AGENTS.md · FastAPIAGENTS.md and CLAUDE.md examples for FastAPI
Of 225 actively developed open-source products built with FastAPI, 128 (57%) keep instruction files for coding agents: AGENTS.md in 93, CLAUDE.md in 80. The typical file is 930 words, and most cover commands to build, run and test (77%) and pointers to other docs (76%).
Real files to read
From the best-known open-source FastAPI products whose file is a real one (not a pointer to another), 200 to 4,000 words, covering at least three of the usual topics and naming FastAPI. Each opens on GitHub.
| Project | File | Stars | Words | Covers |
|---|---|---|---|---|
| Significant-Gravitas/AutoGPT | AGENTS.md | 187,527 | 943 | CommandsTestingDoc pointersStructureCode styleGit |
| bytedance/deer-flow | AGENTS.md | 83,703 | 1,785 | CommandsTestingDoc pointersCode style |
| lfnovo/open-notebook | AGENTS.md | 40,079 | 501 | CommandsTestingDoc pointersGit |
| MODSetter/SurfSense | AGENTS.md | 16,374 | 1,263 | CommandsTestingDoc pointersStructureGit |
| yusufkaraaslan/Skill_Seekers | AGENTS.md | 15,133 | 1,917 | CommandsTestingStructureCode styleGit |
| Chainlit/chainlit | AGENTS.md | 12,510 | 1,387 | CommandsTestingDoc pointersStructureCode styleGit |
| dataelement/bisheng | AGENTS.md | 12,032 | 2,476 | CommandsTestingDoc pointersStructure |
| MemTensor/MemOS | AGENTS.md | 11,816 | 1,362 | CommandsTestingDoc pointersStructureCode styleGit |
| plastic-labs/honcho | CLAUDE.md | 7,576 | 3,230 | CommandsTestingDoc pointersStructureCode style |
| xerrors/Yuxi | AGENTS.md | 7,363 | 331 | CommandsTestingDoc pointers |
| feast-dev/feast | AGENTS.md | 7,323 | 671 | CommandsTestingDoc pointersStructureCode styleGit |
| dramaclaw/dramaclaw | AGENTS.md | 6,851 | 1,210 | CommandsTestingDoc pointersStructureCode styleGit |
What FastAPI projects put in them
Share of the 111 files that cover each topic, against all 641 files we read.
How they talk to the agent: 83% say “never” or “do not” somewhere (all files: 80%), 18% shout a rule in capitals like IMPORTANT or MUST (24%), and 18% tell it to ask before some changes (20%).
The tools they name
Package managersuv (51 files), npm (24 files), pnpm (15 files)
Tests and linterspytest (59), Ruff (15), Playwright (12), Vitest (10), ESLint (10), Prettier (5)
Named more than in files generallyPython (79), pytest (59), Docker (43), Pydantic (23), Redis (22), SQLAlchemy (17), Ruff (15)
What they tell the agent
Instructions that recur across files, in our words; open one for the FastAPI projects whose file says it.
About FastAPI
Named as the Python backend or API server framework, usually paired with a separate frontend.15 files
ArcReel/ArcReelChainlit/chainlitDmitryBMsk/llm-council-plusFujiwaraChoki/supoclipKiln-AI/KilnMODSetter/SurfSenseSignificant-Gravitas/AutoGPTagentcontrol/agent-controlaipotheosis-labs/acilemma-work/lemma-platformlfnovo/open-notebookonyx-dot-app/onyx-fosspuppyone-ai/puppyone-cloudtransformerlab/transformerlab-appwecode-ai/Wegent
About Python
Use uv to run Python commands and manage dependencies; never call bare pip, python or pytest.8 files
Annotate Python code with type hints and keep it passing the type checker, often strict mypy.6 files
Lint and format Python with Ruff (or Black in some repos) and make it pass before finishing.4 files
Activate and use the repository's own .venv virtual environment before running Python, tests or tools.2 files
About pytest
Run tests through the project environment, with uv run or the venv, never a bare system pytest.17 files
Chainlit/chainlitCodeBoarding/CodeBoardingKiln-AI/KilnMODSetter/SurfSenseanywhere-labs/Agents-Anywheredapr/dapr-agentsdramaclaw/dramaclawemcie-co/parlantgenerative-computing/melleahijohnnylin/neuronpedialemma-work/lemma-platformlfnovo/open-notebookplastic-labs/honchopuppyone-ai/puppyone-cloudreflex-dev/reflexsuperserve-ai/superservewandb/weaveMark tests by type, such as unit, integration, slow, or e2e, so default runs skip slow or credentialed ones.11 files
Run pytest and see it pass before committing or claiming a task is done.4 files
Run a single test file or test by path while iterating, then the full suite before finishing.7 files
About Docker
Integration and end-to-end tests need a running Docker daemon or services, so start them before running those suites.2 files
Docker Compose runs the local dev services, such as databases and Redis, so start it before running the app.1 files
Do not assume Docker is available; many dev and test paths intentionally run without it, and CI may have none.1 files
Build and publish multi-arch Docker images through CI release workflows rather than by hand.2 files
About Pydantic
Define API request and response schemas as Pydantic models for validation.9 files
Load configuration and settings through Pydantic models, giving typed and validated config.5 files
Keep Pydantic models in a dedicated schemas or models directory.5 files
Prefer Pydantic models over untyped dicts or bare classes for structured data.4 files
About Redis
Named as the queue broker, cache or pub/sub layer, usually next to Postgres and a background worker.8 files
Start Redis through Docker Compose or a test service script before running the app or integration tests.2 files
About SQLAlchemy
Named as the Python ORM, usually with FastAPI or Flask and PostgreSQL.8 files
Keep SQLAlchemy models and database code in dedicated db or models modules, separate from handlers.3 files
Use SQLAlchemy 2.0-style APIs with typed mapped columns and select, not legacy query patterns.2 files
About Ruff
Ruff serves as the Python linter and formatter.5 files
Run Ruff through make or just targets; it is enforced by pre-commit hooks.4 files
Ruff also sorts imports.1 files
Ruff settings live in pyproject.toml.2 files
A starting AGENTS.md for FastAPI
The sections these files cover most, the package manager and checks FastAPI projects name most, and the stack FastAPI makers' products chose most often. Fill in the <placeholders>.
# AGENTS.md <What this product does and who it is for, in a sentence or two.> ## Stack - Backend Framework: FastAPI - Hosting: Vercel - Database: PostgreSQL ## Commands - Install: `uv sync` - Run locally: `<command>` - Test: `uv run pytest` - Lint: `uv run ruff check .` ## Testing Run `uv run pytest` before calling a change done, and add a test with each fix or feature. ## Project structure - `<folder>/`: <what lives there> - More in <docs/…> ## Conventions - <Naming, patterns and style the code does not show> - Commits and pull requests: <your rules> ## Boundaries - Ask before: <changes you want to approve first> - Never: <files or actions that are off-limits> <!-- Started from https://howmakersbuild.com/agents-md/fastapi — point CLAUDE.md here with a line: @AGENTS.md -->
- uv: named in 51 of 111 instruction files from open-source projects built with FastAPI.
- pytest: named in 59 of 111 instruction files from open-source projects built with FastAPI.
- Ruff: named in 15 of 111 instruction files from open-source projects built with FastAPI.
Questions
What should an AGENTS.md for a FastAPI project include?
In 111 files from open-source FastAPI products: commands to build, run and test (77%), pointers to other docs (76%), testing (68%), project structure (59%), git, commits and pull requests (51%), code style (42%). The package manager they name most is uv (51 files).
AGENTS.md or CLAUDE.md?
Among these FastAPI products, 93 keep an AGENTS.md and 80 a CLAUDE.md. Across every product we checked, 320 keep both, and in 170 of those the CLAUDE.md only points to the AGENTS.md (a symlink or a line like @AGENTS.md), so there's one file to maintain. Codex, Cursor, Copilot and others read AGENTS.md; Claude Code reads CLAUDE.md.
How long is a typical FastAPI AGENTS.md?
The median is 930 words in these 111 files; across all 641 files we read, half are between 425 and 1,665 words.
How this is counted: the GitHub repos of open-source products built with FastAPI, pushed to in the 180 days before 2026-10-12. We read each repo's AGENTS.md, CLAUDE.md and other agent files; what's published here is counts and links, not their text. All files, by the numbers.