CLAUDE.md for Python REST API
FastAPI service with typed schemas, tests and migrations.
How to use this
Save it as CLAUDE.md in your repository root and replace the placeholders in angle brackets. Claude reads it before every task, so keep it short — the Playbooks table at the bottom is how you add detail without paying for it on every unrelated request.
The file
# <project name>
<What this service does and who calls it.>
## Commands
- `uv run uvicorn app.main:app --reload` — dev server
- `uv run pytest` — tests
- `uv run alembic upgrade head` — apply migrations
## Architecture
- `app/routers/` — HTTP layer only; no business logic
- `app/services/` — business logic
- `app/models/` — SQLAlchemy models
- `app/schemas/` — Pydantic request and response models
## Conventions
IMPORTANT: routers stay thin. Logic belongs in services so it can be tested directly.
YOU MUST: define an explicit Pydantic response model for every endpoint.
NEVER: build SQL with string interpolation.
- Every schema change ships with a migration in the same commit.
- Secrets come from the environment, never from code or defaults.
## Verification
`uv run pytest` passes and the server starts cleanly.
## Working with Claude Code
- Explore the relevant files before proposing a change.
- For anything non-trivial, plan first (Shift+Tab into plan mode) and let me review.
- Run the verification command below before telling me something works.
- Keep commits small and conventional (`feat:`, `fix:`, `docs:`, `chore:`).
## Playbooks
- Changing the database schema → read `.claude/playbooks/migration.md` first
- Deploying to staging or production → read `.claude/playbooks/deploy.md` first
The playbooks it expects
The routing table points at files that don't exist yet. Create them as you need them — each one holds a procedure too long to sit in CLAUDE.md and too rare to justify the context cost.
.claude/playbooks/migration.mdChanging the database schema.claude/playbooks/deploy.mdDeploying to staging or production
Other starting points
Next.js + Supabase
App Router, TypeScript, Tailwind and Supabase with row-level security.
R Data Analysis
Tidyverse analysis project with reproducible figures and a clear data pipeline.
Python Research Project
Analysis codebase with notebooks for exploration and modules for anything reused.
CLI Tool
A command-line tool where the interface is the contract.
Monorepo
Several packages in one repository, where knowing the boundaries matters most.
Need something else? Build one from scratch with the generator.