git:20260614.355a60d to git:20261015.66fa304

## Project Specifications

- **Programming Language**: Python >= 3.10

- **Package Manager**: uv

- **Linter & Formatter**: ruff

## Golden Rule

**Explicit intent and maintainability over brevity.** All code must be immediately understandable to another developer (or yourself in future).

## Naming Conventions

- **Variables, functions**: `snake_case` — descriptive and explicit about scope and purpose

- **Boolean variables**: Use `is_`, `has_`, `can_` prefixes (`is_authenticated`, `has_permission`)

- **Collections**: Use plural nouns (`users`, `orders`, `transactions`)

- **Temporary variables**: Acceptable in comprehensions/loops (`for item in items`)

- **Classes**: `PascalCase` — single noun or noun phrase

- **Constants**: `UPPER_CASE` — module-level immutable values

- **Private members**: `_leading_underscore` — single underscore for internal use only

- **Dunder names**: `__double_underscore__` — reserved for Python magic; avoid unless implementing protocols

- **Acronyms**: Treat as words (`HttpRequest` not `HTTPRequest`, `api_client` not `API_client`)

## File Organization

- One class per file unless classes are tightly coupled

- Imports grouped: Standard library → Third-party → Local application (alphabetical within groups)

- No circular imports: refactor if detected

- Module docstring: brief one-liner describing purpose

- Constants at module top, below imports

## Python Modern Syntax

Prefer Python 3.10+ features: `X | None` over `Optional[X]`, built-in generics (`list[int]`, `dict[str, Any]`), `match/case`, f-strings, `Path` over `os.path`, `@dataclass` for simple containers (Pydantic `BaseModel` when validation needed).

## Tech Stack

| Layer | Technology | Notes |

|-------|-----------|-------|

| Database | PostgreSQL | Default relational database |

| Cache | Redis | Optional, via `redis-py` |

| ORM | SQLAlchemy 2.0 | Async support via `asyncpg` |

| Data Validation | Pydantic | Also used for settings via `pydantic-settings` |

| Task Queue | Celery / ARQ | Celery (sync) or ARQ (async) |

| API | FastAPI | Async, OpenAPI, Pydantic validation |

| CLI | Typer | Command-line interfaces |

| Terminal/Logging | Rich | Rich output and logging |

| Testing | pytest | See `.claude/rules/testing.md` |

| Containers | Docker + docker-compose | Local dev and deployment |

| CI/CD | GitHub Actions | Default pipeline |

Adapt this stack to your project needs. Remove or replace layers that don't apply.

Use each tool per its design intent. Don't force workarounds.

## Common Commands

```bash

# Dependencies

uv sync # Install/sync default deps (dev group)

uv sync --group agents # Also install agent tooling (mypy, bandit, ...)

uv add <package> # Add a dependency

uv add --dev <package> # Add a dev dependency

uv remove <package> # Remove a dependency

# Testing

uv run pytest # Run all tests

uv run pytest tests/test_mod.py -v # Run specific file, verbose

uv run pytest -k "test_name" -v # Run tests matching pattern

uv run pytest --cov=src # Run with coverage report

# Linting & Formatting

uv run ruff check . # Lint

uv run ruff check . --fix # Lint + auto-fix

uv run ruff format . # Format

```

## Verification

```bash

uv run ruff check . && uv run ruff format --check . && uv run pytest -x

```

After dependency changes:

```bash

uv sync && uv run pytest

```

## Detailed Rules

Coding standards are organized in `.claude/rules/` by topic:

- @.claude/rules/api-patterns.md

- @.claude/rules/architecture.md

- @.claude/rules/compaction.md

- @.claude/rules/documentation.md

- @.claude/rules/exception-handling.md

- @.claude/rules/git-workflow.md

- @.claude/rules/project-structure.md

- @.claude/rules/python-idioms.md

- @.claude/rules/security.md

- @.claude/rules/testing.md