Home / FastAPI AGENTS.md + Cursor rules

AGENTS.md and Cursor rules for FastAPI + SQLAlchemy + Pydantic

AI agents write FastAPI code that runs. The problem is what it quietly gets wrong:

• No ownership check. GET /invoices/{id} fetches any invoice by ID. That is an IDOR, and the most common API bug there is.
• Pydantic v1 habits: class Config, .dict(), @validator in a v2 codebase.
• Legacy SQLAlchemy: session.query(), lazy loads inside async def, N+1 on every list endpoint.
• Schema drift: models changed with no Alembic migration, or an autogenerated one committed without reading it.
• Tests that test nothing: SQLite instead of Postgres, mocked sessions, no 401/404 cases.

Where the rules go

AGENTS.md at the repo root holds the stack, layout, commands and non-negotiables. Codex, Cursor, Windsurf and others read it, and Claude Code picks it up through @AGENTS.md in CLAUDE.md. Path-scoped details go in .cursor/rules/*.mdc with globs, so the Alembic rule loads only when alembic/** or models are in context.

A layout that works

00-core (always on), 10-structure (app/**), 20-api-routes (app/api/**), 30-pydantic-schemas (app/schemas/**), 40-sqlalchemy-models (models, services), 50-alembic-migrations (alembic/**), 60-security (core, deps, auth routes), 70-testing (tests/**).

The three rules that matter most

• Authorization in the query: select(Invoice).where(Invoice.id == id, Invoice.owner_id == user.id), with 404 for other users’ objects.
• Migrations are reviewed code: autogenerate, then read and fix it; every migration has a working downgrade() and is round-trip tested.
• Every endpoint gets four tests: happy path, 422, 401, and 404 for another user, against a real Postgres in a rolled-back transaction.

Free snippet: copy it

---
description: FastAPI routes and dependencies
globs: app/api/**/*.py,app/main.py
alwaysApply: false
---
- Every route: explicit response_model (or return annotation), status_code, and summary. POST create → 201, DELETE → 204 with no body.
- Use Annotated dependencies: SessionDep = Annotated[AsyncSession, Depends(get_session)], CurrentUser = Annotated[User, Depends(get_current_user)].
- Any route touching user data depends on CurrentUser and passes user.id into the service; ownership is filtered in the query. Other users' objects → 404.
- List endpoints are paginated (limit ≤ 100, default 20) and have a stable order_by.
- Don't catch broad Exception in routes. No business logic in routes.
- CORS: explicit allow_origins from Settings; never ["*"] together with allow_credentials=True.

FAQ