Use when designing or editing aggregates and their repositories in a FastAPI + SQLAlchemy backend: files in `app/models/` and `app/repos/`. Triggers on edits to those directories; on imports from `sqlalchemy.ext.asyncio`, `sqlalchemy.orm`; on user mentions of "aggregate", "repository", "consistency boundary", "ORM model with behavior", "use case loading". Encodes: SA model with behavior (no separate domain layer by default), repos return SA models, YAGNI on repo surface, typed `*Exception` raised from repo, no commit in repo, one repo per aggregate root, named query methods over generic filter objects. Do NOT use for: projects that have an explicit `domain/` directory with pure domain classes — use `python-pure-domain-layer` instead.
Use when wrapping an external HTTP API (CRM, payment gateway, notification service, LLM provider, etc.) into a typed Python client class. Triggers on edits to `app/clients/`; on imports of `httpx`, `tenacity`; on user questions about HTTP clients, retries, mocking external APIs, `MockTransport`, client lifecycle. Encodes: `BaseHTTPClient` with `httpx.AsyncClient` + tenacity retry, per-client `init_X_client` / `cleanup_X_client` async functions, schemas know the wire shape via `from_X` / `to_X`, `httpx.MockTransport` for tests (no aiohttp dep), YAGNI on method surface. Do NOT use for: database access (use python-aggregate-and-repo); internal service-to-service in-process calls (just call the service).
Use when scaffolding or modifying the structure of a FastAPI + SQLAlchemy backend service: `setup.py`, `config.py`, the `db/`, `deps/`, `common/`, `api/` directories, the FastAPI app factory, lifespan, middleware, exception handlers. Triggers on edits to those files; on a new repo that's becoming a FastAPI service; on user questions about app structure, dependency injection setup, lifespan, middleware, exception handling, project layout. Encodes: layered `app/` package, lifespan over event handlers, providers in `app/deps/`, exception handlers grouped by HTTP status, manual `app.state.*` setup in tests. Do NOT use for: scripts, CLIs, libraries, or codebases that aren't FastAPI services.
Use ONLY when the project has an explicit `app/domain/` directory, or the user explicitly asks for "DDD aggregate", "pure domain model", "framework-free invariants", "Cosmic Python style", "separate domain and ORM". Triggers on edits to `app/domain/`; on user mentions of Cosmic Python, ports and adapters, imperative SA mapping, `from_domain` / `to_domain`. Encodes: separate domain classes (frozen dataclass VOs, mutable aggregate roots), SA models that translate to/from domain via `from_domain` / `to_domain` methods, pulling domain events on the aggregate, sync-only domain code. Do NOT use for: default FastAPI + SA services — use `python-aggregate-and-repo` instead. The pure-domain pattern is an opt-in for invariant-dense systems (finance, fulfillment, complex state machines).
Use when designing or editing services and schemas in a FastAPI + SQLAlchemy backend: files in `app/services/` and `app/schemas/`. Triggers on edits to those directories; on definitions of `class *Service`, `class *Command`, `class *Get`; on user mentions of "use case", "service layer", "Pydantic schema", "command", "response shape", "from_model", "to_new_X", "cohesion", "domain service", "policy", "god service", "business rule extraction". Encodes: class-when-state vs function-when-stateless, service returns Pydantic schema (not SA model), top-level service owns the transaction with `AsyncSession.begin()`, composable collaborators do not commit, pure domain services/policies for business rules that do not belong to one aggregate, schema naming (*Get / *Create / *Update / *Command), cohesion methods (`from_<source>` classmethod inbound, `to_<target>` method outbound), Pydantic v2 `from_attributes=True`, no `utils.py` / no free transform functions. Do NOT use for: repos (use python-aggregate-and-repo), routes
Use when setting up logging or writing log calls in a Python service. Triggers on `import logging`, `import structlog`, edits to `app/common/logging.py` or `app/api/middleware/`, on user questions about logging, JSON logs, correlation IDs, structured logging, log levels. Encodes: structlog as the canonical logger, contextvar-based correlation_id propagation, env-driven console-vs-JSON renderer, stdlib bridge so library logs flow through structlog, key=value fields not f-strings. Do NOT use for: print-debugging in scripts; CLI output (use rich or stdout directly).
Use when writing or organizing tests for a FastAPI + SQLAlchemy backend service. Triggers on edits to `tests/`, `conftest.py`, files in `tests/fixtures/`, `tests/doubles/`, `tests/unit/`, `tests/integration/`, `tests/api/`; on imports of `pytest_asyncio`, `httpx.ASGITransport`, `httpx.MockTransport`; on user questions about test fixtures, real-DB tests, external doubles, test layout, pytest setup. Encodes: real Postgres (no testcontainers), session- scoped DB + app, function-scoped session + client, ASGITransport, manual app.state setup in fixtures, httpx.MockTransport for external clients, no unittest.mock / pytest-mock, no factory libs, unit/integration/api split. Do NOT use for: testing libraries, scripts, or non-FastAPI Python.
Use when writing or modifying typed Python code (any project — libraries, services, scripts). Triggers on `.py` files with type annotations; on imports from `typing`, `typing_extensions`, `collections.abc`; on user questions about type hints, Protocol, generics, NewType, PEP 695. Encodes: Protocol over ABC for ports, `Self` for classmethod constructors, `NewType` for ID safety, PEP 695 type aliases and generics, `Annotated` for FastAPI/Pydantic metadata, alternative constructors via `@classmethod from_X(cls, ...) -> Self`, avoiding `Any`, narrowing patterns. Do NOT use for: untyped Python codebases that aren't ready to adopt type hints.