# CONVENTIONS

Rules for AI coding assistants working in this project. 

## Code style
- Follow the existing style in whatever file you're reading
- Run the project's linter after every change and fix all issues
- No "clever" one-liners if a longer form is clearer
- No comments that restate the code. Comments explain "why" not "what"

## Naming
- Files and directories: snake_case
- Functions and variables: snake_case
- Classes: PascalCase
- Database tables: snake_case, plural
- No single-letter variable names. Except "i", "j", "k" in loop index

## Patterns
- Every API endpoint validates input before processing.
- Errors use the frameworks standard error mechanism. Dont invent your own.

## What NOT to do
- Do not add new dependencies without explicit instruction. If proposing a dependency describe it in plain text. Do not install it.
- Do not refactor adjacent code "while you're at it". Stay within the scope of the request.
- Do not assume environment variables exist. If a new environment variable is needed state it clearly and add it to '.env.example'
- Do not suppress type checker or linter errors without a comment explaining why.
- Do not commit code that fails lint, type check or tests. 

## Git
- One logical change per commit
- Commit messages are in imperative mood, lowercase and max 72 char title.
- Good: "add email validation to user signup"
- BAD: "added email validation to user signup"
- BAD: "fix stuff"

## Testing
- Test files mirror source structure: "src/users/service.py" -> "tests/users/test_service.py"
- Mock only external IO boundaries. Never mock our own modules, services or utilities.
- Every new endpoint needs at minimum one test for the success case and one test for a validation error case.