AGENTS.md template for Python FastAPI services using uv, Ruff and pytest
An AGENTS.md for FastAPI backends managed with uv: exact commands for tests, lint, format and type checks, plus conventions for Pydantic models, dependencies, async database access, Alembic migrations and error handling.
File in Engineering by AISkillHub Library
What it does
This template gives coding agents what they need to work in a FastAPI service without guessing: which tool runs what, how the code is organized, and which mistakes to avoid. It assumes `uv` for environments and dependencies, Ruff for linting and formatting, pytest for tests, and optionally mypy or pyright and Alembic.
**What it covers** - Commands: `uv sync`, `uv run pytest`, `uv run ruff check`, `uv run ruff format`, the type checker, running the app, and Alembic revision and upgrade commands. - API conventions: separate Pydantic request and response models, `response_model` on routes, dependencies via `Depends` for auth and database sessions, correct status codes, `HTTPException` with safe messages. - Async rules: no blocking I/O in `async def` routes; use async database drivers or plain `def` routes for blocking calls. - Database: Alembic autogenerate output must be reviewed (renames show up as drop and add), migrations are never edited after merge. - Testing: pytest fixtures, dependency overrides with `app.dependency_overrides`, no real network calls. - Guardrails: no new dependencies, no edits to `.env`, no migrations against shared databases without asking.
**Variables to fill** - `{{service_name}}`, `{{service_purpose}}`. - `{{package_dir}}`: the import package, for example `src/app` or `app`. - `{{app_module}}`: the ASGI app path, for example `app.main:app`. - `{{type_checker_cmd}}`: for example `uv run mypy src` or `uv run pyright`, or delete the line. - `{{db}}`: for example "Postgres via SQLAlchemy 2.0 async", or delete the database section.
**Using it with Claude Code** Create a `CLAUDE.md` containing `@AGENTS.md` so Claude Code imports the same instructions.
How to use it
1. Copy the file below to `AGENTS.md` at the root of your service. 2. Replace every `{{...}}` variable (listed in the description) and remove sections that do not apply (for example Database if the service has none). 3. Confirm each command works in your project, especially the type checker and app module path. 4. For Claude Code, add a `CLAUDE.md` containing `@AGENTS.md`. 5. Commit both files.
Files
Save each file at the path shown, relative to your project root.