Python FastAPI AGENTS.md Template

# AGENTS.md — Python / FastAPI

## Environment

- Python: [version]
- Dependency manager: [uv/Poetry/pip]
- API: FastAPI + Pydantic
- Database: [SQLAlchemy/SQLModel] + [Alembic]

## Commands

- Install: `uv sync`
- Run API: `uv run fastapi dev app/main.py`
- Lint: `uv run ruff check .`
- Format check: `uv run ruff format --check .`
- Type check: `uv run mypy app`
- Tests: `uv run pytest -q`

## Implementation rules

- Add type hints to public functions and keep mypy clean.
- Validate external input with Pydantic models at the API boundary.
- Keep route functions thin; put business logic in services.
- Use dependency injection for database sessions, auth, and external clients.
- Do not perform blocking I/O inside async functions.
- Return intentional HTTP status codes and stable error shapes.
- Never expose stack traces, credentials, or internal exception details to clients.

## Database changes

- Every schema change needs a reviewed migration.
- Migrations must be safe for existing production data.
- Avoid destructive or irreversible migrations without explicit approval and a rollback plan.
- Keep transactions small and make retry-sensitive writes idempotent.

## Tests

- Cover success, validation, authorization, not-found, and dependency-failure paths.
- Use fixtures/factories; do not depend on test execution order.
- Mock network boundaries, not the business logic being tested.
- For bug fixes, add a regression test that fails before the fix.

## Definition of done

- Ruff, mypy, and relevant pytest suites pass.
- OpenAPI output remains compatible or the breaking change is documented.
- Migrations upgrade cleanly on representative data.