# AGENTS.md (Python)

## Stack
- Python 3.13, async/await, type hints everywhere
- Package manager: uv (never raw pip)
- Testing: pytest + pytest-asyncio
- Linting/formatting: ruff
- Type checking: mypy --strict

## Commands
```bash
uv sync                                      # install deps
uv run pytest tests/test_foo.py -v           # test single file
uv run pytest tests/ -v                      # test all
uvx ruff check src/foo.py --fix              # lint single file
uvx ruff check src/ tests/                   # lint all
uvx ruff format src/ tests/                  # format
uv run mypy src/ --strict                    # typecheck
```

## Project setup
```bash
uv init                                      # new project
uv add <package>                             # add dependency
uv python pin 3.13                           # pin version
uv run python src/main.py                    # run script
```

## Do
- Type hints on all signatures and return types
- async/await for all I/O
- Pydantic models for data structures
- `logging` or framework logger, never `print()`
- Config from env vars or config file, never hardcoded
- Small functions (< 30 lines), small files (< 200 lines)
- Structured logs with context: `logger.info("fetch_done", extra={"channel": name, "count": n})`

## Don't
- No `pip install` — always `uv add` or `uv sync`
- No sync I/O when async is available
- No `# type: ignore` without comment why
- No wildcard imports (`from x import *`)
- No abbreviations in variable names
- No `print()` in production code
- No silent `except: pass`

## Testing
- Test file mirrors source: `src/foo.py` → `tests/test_foo.py`
- Mock external services (APIs, databases, webhooks)
- Write tests before or alongside implementation, not after
- e2e test required before PR: must cover Phase Checkpoint criteria
- No PR without passing `uv run pytest tests/ -v`