AGENTS.md template for FastAPI

# Project instructions

This repository is a Python FastAPI service. Preserve its existing dependency injection, validation, persistence, and error-handling patterns. Keep API behavior backwards compatible unless the task explicitly changes the contract.

## Start here

- Read the target router, schema, service, model, and tests before editing.
- Use the Python version and dependency manager configured in the repository.
- Prefer focused changes over broad rewrites.
- Preserve user changes and never reveal values from local environment files.

## Commands

- `uv sync`: install locked dependencies.
- `uv run fastapi dev app/main.py`: start the development server.
- `uv run pytest`: run tests.
- `uv run ruff check .`: run lint checks.
- `uv run ruff format --check .`: verify formatting.
- `uv run mypy app`: run static type checks when configured.

Replace these commands if the repository uses pip, Poetry, PDM, Hatch, or different scripts.

## Architecture

- `app/api/` or `app/routers/`: HTTP routing and request/response boundaries.
- `app/schemas/`: Pydantic request, response, and domain schemas.
- `app/services/`: business logic and orchestration.
- `app/models/`: persistence models.
- `tests/`: unit and API integration tests.
- Keep HTTP concerns in routers and business rules in services. Avoid database queries inside response formatting.

## FastAPI and Python rules

- Declare explicit request and response models; do not return undocumented dictionary shapes.
- Keep sync and async boundaries correct. Never call blocking I/O directly from an async route.
- Reuse dependencies for authentication, authorization, sessions, and shared validation.
- Raise established domain or HTTP errors rather than leaking raw exceptions.
- Add type annotations to new public functions and preserve the repository's import and formatting style.

## Data and security

- Validate all client-controlled values and enforce authorization at the server boundary.
- Never include secrets, tokens, password hashes, or internal exception details in responses or logs.
- Do not create, edit, or apply database migrations without explicit approval and a reviewed rollback path.
- Keep transactions scoped; do not commit partial state after an error.

## Testing and validation

- Add or update tests for success, validation failure, authorization failure, and relevant edge cases.
- Prefer dependency overrides and isolated fixtures over live external services.
- Run the focused test module first, then the complete required suite.
- Verify OpenAPI and response-model changes when an endpoint contract changes.

## Definition of done

- The endpoint or service behavior works through its public boundary.
- Tests, lint, formatting, and configured type checks pass.
- API and database compatibility are preserved unless explicitly changed.
- Sensitive data is not exposed in responses, logs, fixtures, or errors.
- The final handoff names the contract changed, checks run, and any migration or deployment risk.