AGENTS.md Template for Python

# Python Repository Instructions

## Runtime
- Supported Python: `[version from pyproject.toml]`
- Environment and dependency manager: `[uv/Poetry/pip/other]`
- Package layout: `[src layout/flat layout]`

## Commands
- Create/sync environment: `[exact command]`
- Run application: `[exact command]`
- Focused test: `[exact pytest command with path]`
- Full tests: `[exact command]`
- Lint: `[exact command]`
- Format check: `[exact command]`
- Type-check: `[exact command]`
- Build package: `[exact command or remove]`

## Python Rules
- Use the Python version and dependency manager declared by the repository.
- Follow the existing package layout and import style; do not modify sys.path to hide packaging errors.
- Add type hints to changed public interfaces and keep return types explicit.
- Raise or translate specific exceptions; do not catch broad Exception unless adding context and preserving failure semantics.
- Use timezone-aware datetimes and avoid mutable default arguments.
- Do not edit generated lockfiles manually.

## Data and Migrations
- Treat schema and data migrations as separate, reviewable changes.
- Do not generate, apply, or roll back migrations without explicit task scope.
- Never use production credentials or production data in local tests.

## Testing
- Put tests in the repository's existing test tree and mirror its naming conventions.
- Cover the success path, invalid input, and the most important exception path.
- Prefer deterministic fixtures; freeze time and mock only external boundaries when needed.
- Run focused pytest during iteration, then lint, types, and the required full suite.

# Python Repository Instructions

## Commands
- Install: `[uv sync | poetry install | pip install -e .]`
- Test: `[uv run pytest | poetry run pytest | pytest]`
- Lint: `[ruff check .]`
- Format check: `[ruff format --check .]`
- Type-check: `[mypy src | pyright]`

## Rules
- Preserve the existing package and dependency manager.
- Add type hints to changed public interfaces.
- Test success, invalid input, and important exception paths.
- Do not create or run migrations without explicit approval.