code-gen

name	code-gen
description	Code generation quality principles — TDD, typing, error handling, logging, API integration, LLM integration.

Code Generation Skill

Reference skill for generator teammates. Read this before writing any code.

---

Core Quality Principles

1. Small Modules — One File, One Responsibility

• Each file must have a single, clearly named responsibility.
• Warning threshold: 200 lines — add a comment noting the file is growing large.
• Block threshold: 300 lines — do not submit. Split before opening a PR.
• If you hit 300 lines, decompose into sub-modules and re-export from an index file.

2. Static Typing — Annotate Everything

• Every function parameter, return value, and variable must have an explicit type.
• TypeScript: Zero any. Use unknown + type guard if the shape is truly unknown.
• Python: Full type hints on all functions. Use TypeVar, Generic, Protocol where appropriate.
• Type aliases for domain concepts (UserId = str, type OrderId = string).

3. Functions Under 30 Lines

• If a function body exceeds 30 lines, decompose it into named sub-functions (the pre-write-gate hook enforces this limit deterministically).
• Each sub-function should be testable in isolation.
• Use descriptive names that read as a sentence: validateOrderItems, buildPaymentPayload.
• Avoid deeply nested control flow — extract branches into named helpers.

4. Single Owner for State Mutations

• Every state-creating operation (DB insert, file write, queue publish) must have exactly ONE call site.
• If a route handler creates a record, the service it calls must receive the ID — not create a second record.
• Anti-pattern: Route creates Task, then calls service.start(query) which also creates a Task → duplicate records.
• Correct pattern: Route creates Task with ID, then calls service.start(task_id) which operates on the existing record.
• When a background task or async flow needs a resource, pass the ID, don't re-create it.
• Test this explicitly: after calling the endpoint, assert the exact count of records created (e.g., assert db.query(Task).count() == 1).

5. Explicit Error Handling

• Define typed error classes per domain (e.g., class OrderNotFoundError extends AppError).
• Never use bare except Exception or catch (e: any).
• All error paths must be covered by tests.
• Propagate errors up with context; do not swallow silently.
• In TypeScript: use Result<T, E> or typed throws with JSDoc @throws.

6. No Dead Code

• Every line of code must trace to a user story or a technical requirement.
• Do not leave commented-out code in PRs.
• Remove unused imports, variables, and parameters immediately.
• If code is speculative ("might need later"), do not include it.

7. Self-Documenting — Names Over Comments

• Variable and function names should make comments unnecessary.
• Types act as documentation — a well-typed function signature is its own doc.
• Use comments only for non-obvious decisions (algorithm choice, regulatory constraints).
• Avoid // TODO in submitted code — file a story instead.
• No stub-to-green. Do not clear compile/lint by shipping todo!(), unimplemented!(), NotImplementedError, empty pass/... bodies, or throw new Error("TODO") on production paths. Implement the behaviour, or defer with an explicit story and // harness:stub-ok story=E#-S# on the same line (the stub-smell-gate enforces markers at commit on standard+ tiers).
• Paragraph rule (Bun). If you need a paragraph-long comment to justify a workaround, the code is wrong — fix the code; do not document the hack.

8. Deep Modules — Simple Interface, Useful Behavior

• Prefer modules with small, stable interfaces that hide meaningful complexity.
• A module interface includes its types, invariants, error modes, ordering requirements, and configuration — not just the function signature.
• Apply the deletion test before adding a module: if deleting it removes complexity entirely, it was probably shallow ceremony; if deleting it spreads complexity across callers, it is earning its keep.
• Do not create pass-through services, repositories, hooks, helpers, or adapters just to satisfy a pattern.
• One implementation behind an interface is not proof an abstraction is needed. Introduce interfaces/adapters when there are two real implementations, a test boundary around an external dependency, or a clear domain seam.

9. Public Interface as Test Surface

• Tests should verify observable behavior through public interfaces: API endpoints, CLI commands, UI flows, exported module functions, or documented domain services.
• Do not test private helpers, implementation details, internal call order, or mock interactions unless that is the public contract.
• If a helper is complex enough to need direct tests, consider making it a named domain module with a clear public interface.
• A good test should survive internal refactors when behavior is unchanged.

10. Performance & Latency — Don't Ship the Slow Pattern

Readability comes first, but readable code is not allowed to be needlessly slow. The evaluator runs a runtime latency ratchet on read endpoints (p95 regression vs a baseline) plus an advisory budget check from project-manifest.json → execution.latency_budget_ms (default read 300ms / write 800ms, override per-endpoint in the sprint contract). Code to that budget. These are criteria, not "make it fast" — each is a specific pattern to avoid unless you can name why it's unavoidable here:

• No N+1 queries. Loading a list and then querying per-row inside a loop is the single most common latency killer. Fetch the set in one query — use a join, an IN (...)/WHERE id = ANY(...), or the ORM's eager-load (selectinload/joinedload). If you write a query inside a for loop over rows, stop and batch it.
• Bound every result set. Any endpoint or query that returns a collection must paginate or LIMIT. Never SELECT * an unbounded table into memory. Default to a capped page size; accept limit/offset (or cursor) params.
• Index the columns you filter, sort, or join on. If a query has a WHERE/ORDER BY/JOIN on a column, that column needs an index (declare it in the model/migration). A full table scan that passes tests at 10 rows is a timeout at 10⁶.
• Run independent awaits concurrently. Two awaits with no data dependency are a sequential stall — gather them (asyncio.gather, Promise.all). Sequential awaits are only correct when the second genuinely needs the first's result.
• Never block the event loop on a hot path. No synchronous CPU-bound work, blocking SDK call, or sync DB driver inside an async request handler — it stalls every concurrent request. Use async clients, or push blocking work to asyncio.to_thread/a worker (see the async-bridging rule and the thread-pool gotcha below). Sync postgresql:// in an async app is both a correctness and a latency bug.
• Don't re-compute or re-fetch what doesn't change per request. Hoist constant work (compiled regexes, loaded config, opened clients, expensive lookups) out of the request path to startup/module scope. Cache genuinely expensive, repeated, read-mostly results — but only with an explicit invalidation story; a cache without invalidation is a correctness bug, so don't add one speculatively.
• Stream or page large payloads. Don't build a giant string/list in memory to return it; stream, or return a bounded page.

When clarity and speed genuinely conflict on a hot path, keep the readable version and leave a one-line comment naming the trade-off — that signals to the evaluator and reviewer it was a deliberate choice, not an oversight.

---

Code Patterns

Test Structure: Arrange → Act → Assert

// Arrange
const order = buildOrder({ status: "pending" });
// Act
const result = processOrder(order);
// Assert
expect(result.status).toBe("confirmed");

Typed Error Classes

class DomainError extends Error {
  constructor(message: string, public readonly code: string) {
    super(message);
    this.name = this.constructor.name;
  }
}
class OrderNotFoundError extends DomainError {
  constructor(orderId: OrderId) {
    super(`Order ${orderId} not found`, "ORDER_NOT_FOUND");
  }
}

Naming Conventions

• Files: kebab-case.ts for TypeScript, snake_case.py for Python.
• Functions/methods: camelCase (TS), snake_case (Python).
• Types/classes: PascalCase in both languages.
• Constants: UPPER_SNAKE_CASE.
• Booleans: prefix with is, has, can, should.

Database Session Lifecycle (Python/FastAPI)

• Use async_sessionmaker with FastAPI Depends() for dependency injection — never create sessions manually per request.
• Engine and session factory created once in lifespan, stored on app.state, disposed on shutdown.
• Sessions auto-close via async with — never leave sessions open.
• Tests override the session dependency to use a test DB, not the dev DB.

# CORRECT — lifespan manages engine lifecycle
@asynccontextmanager
async def lifespan(app: FastAPI):
    engine = create_async_engine(settings.DATABASE_URL)
    app.state.session_factory = async_sessionmaker(engine)
    yield
    await engine.dispose()

# CORRECT — session via dependency injection
async def get_db(request: Request) -> AsyncGenerator[AsyncSession, None]:
    async with request.app.state.session_factory() as session:
        yield session

DbSession = Annotated[AsyncSession, Depends(get_db)]

Background Tasks Must Be Tracked

• Every background task must have a corresponding DB record with a status field (pending, running, completed, failed).
• The route creates the record (status=pending), then starts the background task with the record's ID.
• The background task updates the record on completion or failure — never fire-and-forget.
• Wrap the entire background task body in try/except: on failure, update the record to failed with error details and log the exception.

# CORRECT — tracked background task
@router.post("/tasks")
async def create_task(request: TaskRequest, db: DbSession, background_tasks: BackgroundTasks):
    task = Task(query=request.query, status="pending")
    db.add(task)
    await db.commit()
    background_tasks.add_task(run_task, task.id)  # pass ID, not the object
    return {"task_id": task.id, "status": "pending"}

async def run_task(task_id: UUID) -> None:
    async with get_session() as db:
        task = await db.get(Task, task_id)
        try:
            task.status = "running"
            await db.commit()
            result = await do_work(task.query)
            task.status = "completed"
            task.result = result
        except Exception as e:
            logger.exception("Task failed", extra={"task_id": str(task_id)})
            task.status = "failed"
            task.error = str(e)
        finally:
            await db.commit()

CORS Must Be Environment-Configured

• Never use allow_origins=["*"] with allow_credentials=True — this is a security vulnerability.
• Read allowed origins from an environment variable, default to localhost only.

# CORRECT — env-configured CORS
allowed_origins = settings.ALLOWED_ORIGINS.split(",")  # from .env
app.add_middleware(
    CORSMiddleware,
    allow_origins=allowed_origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)

Health Check Must Verify Dependencies

• Health endpoint must test critical dependencies (DB, cache, external APIs), not just return {"status": "ok"}.
• Return 503 if any dependency is unreachable.

@router.get("/health")
async def health(db: DbSession) -> dict:
    try:
        await db.execute(text("SELECT 1"))
        return {"status": "ok", "db": "connected"}
    except Exception:
        raise HTTPException(status_code=503, detail="Database unreachable")

Request ID Middleware

• Add middleware that generates a unique request_id per request and includes it in all log entries and error responses.
• This enables tracing a single user request across all service logs.

@app.middleware("http")
async def add_request_id(request: Request, call_next):
    request_id = str(uuid4())
    request.state.request_id = request_id
    response = await call_next(request)
    response.headers["X-Request-ID"] = request_id
    return response

---

Testing Rules — TDD Mandatory

"Coverage isn't about bug prevention — it's about guaranteeing the agent has double-checked the behavior of every line of code it wrote." — Steve Krenzel

1. Tracer-bullet TDD: one behavior at a time.
   • Do not write all tests first, then all implementation.
   • Write one failing behavior test through the public interface.
   • Implement the minimum code to pass that test.
   • Repeat for the next behavior.
   • This prevents imagined tests for imagined architecture.
2. Tests FIRST, then code (TDD):
   • Write a failing test that defines expected behavior
   • Run it — verify it fails for the right reason
   • Write the minimum code to make it pass
   • Run it — verify it passes
   • Refactor if needed, re-run tests
   • Commit
3. 100% meaningful coverage — every branch, every error path. At 100%, any uncovered line is an immediate signal of missing verification. The ratchet gate BLOCKS below 80%.
4. Only mock external boundaries: databases, third-party APIs, file I/O, clocks, payment processors, queues.
5. Never mock business logic — if you mock a service to test another service, you are hiding bugs and testing wiring instead of behavior.
6. Isolate tests from .env files: When testing settings/config that uses pydantic-settings or dotenv, pass _env_file=None (pydantic) or mock dotenv.load_dotenv to prevent the developer's .env from leaking into tests. Tests must be self-contained — they must pass regardless of what's in the local .env.
7. Use async-compatible connection strings: When using async frameworks (SQLAlchemy async, asyncpg), defaults must use the async driver scheme (e.g., postgresql+asyncpg:// not postgresql://). The sync scheme will fail at runtime with a cryptic driver error.
8. Realistic test data — use domain-representative values (real-looking emails, valid UUIDs, plausible amounts). Never "foo", 123, or "test".
9. Test names describe behavior: "returns 404 when order does not exist", not "test order".
10. Integration tests for multi-step flows: When a route triggers a background task or async flow (e.g., POST creates a record then starts processing), write a test that calls the endpoint and asserts the FINAL state — not just that each unit works alone. Assert exact record counts: assert db.query(Task).count() == 1 after one API call.

---

LLM Integration — Structured Output Mandatory

When generated code calls any LLM (Claude, GPT, or other), follow these rules:

1. Always Use Structured Output

Use tool_use / function_calling / response_format: { type: "json_schema", json_schema: ... } for every LLM call. Never parse free-text responses with regex or string splitting.

2. Define a Response Schema

Every LLM call must have a typed model for the expected response:

from pydantic import BaseModel
from typing import Literal

class ClassificationResult(BaseModel):
    category: str
    confidence: Literal["high", "medium", "low"]
    reasoning: str

interface ClassificationResult {
  category: string;
  confidence: "high" | "medium" | "low";
  reasoning: string;
}

3. Validate Before Using

Parse the LLM response through the schema. If validation fails:

1. Retry once with an explicit correction prompt: "Your response did not match the required schema. Required: {schema}. Please respond again."
2. If second attempt fails, raise a typed error — do not fall back to a default value.

4. No Silent Fallbacks

Never write:

# WRONG — hides bugs that compound
try:
    result = await call_llm(prompt)
    parsed = ResponseModel.model_validate_json(result)
except Exception:
    parsed = ResponseModel(category="unknown", confidence="low", reasoning="")

Instead:

# CORRECT — caller decides how to handle failure
class LLMResponseError(Exception):
    def __init__(self, raw_response: str, validation_error: str):
        self.raw_response = raw_response
        self.validation_error = validation_error
        super().__init__(f"LLM response validation failed: {validation_error}")

try:
    result = await call_llm(prompt)
    parsed = ResponseModel.model_validate_json(result)
except ValidationError as e:
    raise LLMResponseError(raw_response=result, validation_error=str(e))

5. Log Raw Responses

Always log the raw LLM response at DEBUG level before parsing:

logger.debug(
    "LLM response received",
    extra={
        "provider": self._provider_name,
        "model": self._model,
        "prompt_tokens": response.usage.input_tokens,
        "completion_tokens": response.usage.output_tokens,
        "raw_content": response.content[:1000],
        "latency_ms": round(elapsed_ms, 2),
    },
)

---

6. Prompt Caching (Anthropic API)

When the generated app calls the Claude API (the anthropic SDK), make it cache-friendly by default. Prompt caching reuses the unchanging prefix of a request, cutting cost and latency on repeated calls. This is an Anthropic-API-specific feature — do not apply it to OpenAI or other providers (OpenAI caches automatically with no breakpoint API).

• Static content first. Order each request so unchanging content comes before variable content: tools, then system, then long-lived context (instructions, docs, examples, schemas), then the moving conversation tail. Caching only helps a prefix that is byte-for-byte identical across calls, so never interleave per-request data (timestamps, user IDs, retrieved snippets) into that prefix.
• One breakpoint on the stable prefix. Put a single cache_control breakpoint ({"type": "ephemeral"}) on the last block of the stable prefix — typically the end of the system prompt or the end of a large tool/context block. Everything up to and including that block becomes the cached prefix.
• Rely on auto-caching for the moving tail. Do not stamp cache_control on every turn. Anthropic automatically extends cache coverage to the longest previously-seen prefix, so the one breakpoint at the end of the stable section is reused by later turns without per-message markers. Reserve extra breakpoints (max 4 total) only for additional large, reused segments.
• Keep the prefix above the cache threshold. Cacheable prefixes have a model-dependent minimum (~1024+ tokens). Tiny system prompts will not cache — do not contort small prompts to force it.
• Verify cache behavior. Confirm the breakpoint lands where intended by inspecting usage: cache_creation_input_tokens on the first call (cache write) and cache_read_input_tokens on later calls (cache hit).

# CORRECT — stable prefix cached, moving tail auto-cached
resp = client.messages.create(
    model="claude-...",
    system=[
        {
            "type": "text",
            "text": LONG_STATIC_INSTRUCTIONS,          # unchanging across calls
            "cache_control": {"type": "ephemeral"},     # breakpoint at end of stable prefix
        }
    ],
    messages=conversation,                              # moving tail: no cache_control needed
)
# resp.usage.cache_creation_input_tokens / resp.usage.cache_read_input_tokens

---

7. Batch API for Bulk, Non-Interactive Work (Anthropic API)

When the generated app does bulk, one-shot LLM work — classify a backlog, summarize a document set, score a corpus, run an offline backfill — use the Anthropic Message Batches API instead of one synchronous call per item. Batch requests are 50% cheaper than standard calls, and the discount stacks with prompt caching (a cached, batched request pays ~50% of the already-90%-discounted cache-read rate).

• Use it only for non-interactive paths. Batch is asynchronous (results land within ~24h, usually much sooner) and is not conversational — there is no mid-request tool loop. Never use it for a live request/response path, an interactive agent loop, or anything a user waits on. Those stay synchronous.
• Right shape: a queue/cron/worker that has many independent prompts ready at once. Wrong shape: a web handler serving one user, or an agent that needs each result to decide its next step.
• Combine with caching: put the shared instructions/schema in the cached prefix (section 6) so every item in the batch reuses it.
• This is Anthropic-API-specific. For OpenAI/other providers, use their equivalent batch endpoint or skip.

# CORRECT — bulk classification as one batch job, not N synchronous calls
batch = client.messages.batches.create(
    requests=[
        {"custom_id": item.id, "params": {"model": "claude-...", "max_tokens": 256,
         "system": SHARED_PREFIX, "messages": [{"role": "user", "content": item.text}]}}
        for item in backlog          # many independent items, no inter-item dependency
    ]
)
# poll batch.id, then retrieve results — do NOT block a user request on this

8. Output Budgeting

Output tokens are billed at the highest rate and are fully re-read as input on the next turn of any conversation, so unbounded output compounds cost. Constrain it in generated LLM calls:

• Always set an explicit max_tokens sized to the expected response — not the model maximum. A classifier returning a small JSON object needs ~256, not 4096.
• Ask for the smallest sufficient output. Prefer structured output (section 1) and IDs/enums over prose; instruct the model to omit restated context and long explanations unless required.
• Don't request reasoning you discard. Only enable extended thinking when the task needs it; for mechanical/structured tasks, leave it off.

---

External API Integration

When generated code calls any external API (third-party services, partner APIs, cloud services), follow these rules. See .claude/skills/code-gen/references/api-integration-patterns.md for full templates.

Service Wrapper Pattern (Mandatory)

Every external API gets a dedicated wrapper class. This is the ONLY file that imports the SDK or makes HTTP calls to that service.

Business Logic (process_service.py)
    ↓ calls typed methods
API Wrapper (external_client.py)    ← only file that imports SDK / makes HTTP calls
    ↓ calls
External API

Rules:

• One wrapper class per external API
• Wrapper exposes project-internal typed models, not SDK types
• Business logic never sees SDK response objects — only your domain types
• The wrapper is the mock boundary in tests

Error Taxonomy (Mandatory)

Every wrapper classifies errors into typed categories:

class ApiTransientError(Exception):
    """Retryable: 429, 502, 503, timeout, connection reset."""
    pass

class ApiPermanentError(Exception):
    """Not retryable: 400, 401, 403, 404, schema mismatch."""
    pass

class ApiRateLimitError(ApiTransientError):
    """Rate limited with backoff hint."""
    def __init__(self, message: str, retry_after: float | None = None):
        super().__init__(message)
        self.retry_after = retry_after

• Business logic catches ApiTransientError to retry/degrade, ApiPermanentError to fail fast
• No bare except Exception in any API-calling code
• All exceptions carry HTTP status code and response body for debugging

Retry and Rate Limiting

• Retry config lives in config.yml under external_apis.{service_name}.retry, not hardcoded
• Wrapper applies exponential backoff internally — business logic is unaware of retries
• Respect Retry-After headers when present
• Log every retry attempt at WARNING level

Async Bridging

When an SDK is synchronous but the backend is async:

• Use asyncio.to_thread() only inside the wrapper class
• Never bridge in business logic
• Prefer async SDKs or HTTP clients when available

Secrets

• API keys in .env only, loaded via config layer
• Wrapper reads from injected config, never from os.environ directly
• .env.example committed with placeholder values

---

Production Standards

These standards apply to ALL generated code, not just API wrappers or LLM calls.

Structured Logging

All generated services must use structured logging with extra dicts:

import logging

logger = logging.getLogger(__name__)

# CORRECT — structured fields for JSON log formatters
logger.info("Document processed", extra={
    "document_id": doc.id,
    "processing_time_ms": round(elapsed_ms, 2),
    "output_size_bytes": len(result),
})

# WRONG — data interpolated into message string
logger.info(f"Document {doc.id} processed in {elapsed_ms}ms")

// CORRECT — structured logger
logger.info("Document processed", {
  documentId: doc.id,
  processingTimeMs: Math.round(elapsedMs),
  outputSizeBytes: result.length,
});

// WRONG — template literal message
logger.info(`Document ${doc.id} processed in ${elapsedMs}ms`);

Rules:

• Use logging.getLogger(__name__) (Python) or scoped logger (TypeScript) at module level
• INFO for business events (request received, document processed, job completed)
• WARNING for recoverable issues (retry triggered, fallback used, slow response)
• ERROR for failures requiring attention (unhandled exception, data corruption, external service down)
• DEBUG for troubleshooting data (raw payloads, intermediate state, timing breakdowns)
• Never log secrets, tokens, passwords, or PII
• Log at service boundaries: incoming requests, outgoing calls, business decisions

Exception Handling

# CORRECT — typed exception with context
class DocumentProcessingError(Exception):
    def __init__(self, document_id: str, stage: str, cause: Exception):
        self.document_id = document_id
        self.stage = stage
        self.cause = cause
        super().__init__(f"Failed at {stage} for document {document_id}: {cause}")

# WRONG — bare except swallowing the error
try:
    result = process(doc)
except Exception:
    result = default_value

Rules:

• Define typed exception classes per domain (not per function)
• Every exception carries enough context to debug without the stack trace
• Never catch Exception or BaseException unless re-raising or logging at a top-level boundary
• No silent fallbacks — if an operation fails, the caller must know
• API route handlers catch domain exceptions and map to HTTP error responses

Structured Error Responses

The canonical error-envelope shape and the layering rules live in .claude/skills/code-gen/references/architecture.md — defer to it if the two ever differ. Repeated here for convenience: all API error responses follow a consistent envelope:

{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "Document with ID abc123 does not exist",
    "details": {}
  }
}

Rules:

• code is a machine-readable UPPER_SNAKE_CASE string enum
• message is human-readable
• details is optional structured context
• HTTP status mapping: 400 validation, 404 not found, 409 conflict, 422 processing error, 500 internal

Request/Response Validation

• All API inputs validated via Pydantic models (Python) or Zod schemas (TypeScript)
• Validation errors return 400 with field-level messages
• All API outputs serialized through response models — never return raw dicts or ORM objects

Configuration

• All configurable values in config.yml or environment variables
• No magic numbers or hardcoded strings in business logic
• Config loaded once at startup, injected into services via constructor
• Defaults provided for all non-secret config values

---

Parallel Execution

• File ownership: consult component-map.md before touching any file.
• Plan approval required before starting parallel work.
• Shared interfaces: message teammates before changing a type or API contract that crosses boundaries.
• Task sizing: aim for 5–6 discrete tasks per teammate per sprint cycle.
• Conflicts: if two teammates need the same file, one blocks; do not merge partial changes.

---

Gotchas (Things That Cause Review Failures)

• Importing upward across layers (UI importing from repository layer)
• Functions exceeding 30 lines without decomposition
• Untyped values — any, missing return types, unannotated parameters
• Broad exception catches without re-raise or typed handling
• Mocking business logic in unit tests
• Generic test data ("test", 0, null as stand-ins for real domain values)
• Commented-out code in the submitted diff
• Missing error-path test coverage
• Teammates editing the same file in the same sprint without coordination
• Free-text LLM parsing — Never use regex to parse LLM output. Use structured output (tool_use / JSON mode).
• Silent fallback on LLM error — except Exception: return default hides compounding bugs. Raise typed errors.
• Missing raw response logging — Always log raw LLM response at DEBUG before parsing. This is the debugging ground truth.
• Direct SDK imports outside wrapper — All SDK imports must be inside the wrapper class file. Business logic imports your wrapper, not the SDK.
• Bare except on API calls — Catch ApiTransientError and ApiPermanentError specifically. Never except Exception.
• Hardcoded retry config — Retry attempts, backoff, and timeout belong in config.yml, not in code.
• Missing structured logging in API wrapper — Every request/response/error must be logged with structured fields (service, operation, attempt, latency_ms).
• f-string log messages — Use extra dict for structured fields, not string interpolation. Structured logs are searchable; f-strings are not.
• Missing logging at service boundaries — Every incoming request and outgoing call must be logged with timing and status.
• Raw dict API responses — Always serialize through a response model. Raw dicts bypass validation and leak internal structure.
• Magic numbers — All thresholds, limits, timeouts, and configuration belong in config.yml.
• .env leaking into tests — Tests that validate "missing config raises error" will pass in CI but fail locally if .env has the value. Always pass _env_file=None in pydantic-settings tests.
• Sync DB driver in async app — postgresql:// uses psycopg2 (sync). Async SQLAlchemy needs postgresql+asyncpg://. Always match the driver scheme to the engine type.
• Duplicate record creation — Route creates a record, then calls a service that creates the same record again. Pass the ID, don't re-create. Test with assert count == 1 after one API call.
• Manual session creation — Never create DB sessions manually per request. Use Depends(get_db) with async_sessionmaker. Manual sessions leak connections.
• Fire-and-forget background tasks — Every background task must update a DB record on completion or failure. No background_tasks.add_task(fn) without status tracking.
• CORS allow_origins=["*"] — Never use wildcard origins with allow_credentials=True. Read origins from env var, default to localhost.
• Health check returns OK without checking DB — Health endpoint must SELECT 1 against the database. A healthy HTTP server with a dead DB is not healthy.
• Engine not disposed on shutdown — Always await engine.dispose() in the lifespan's teardown. Leaked connections exhaust the pool.
• No request ID tracing — Add middleware that generates a UUID per request, injects into logs and response headers. Without it, errors can't be traced to requests.
• Deprecated startup/shutdown events — Use @asynccontextmanager lifespan, not @app.on_event("startup"). The event-based API is deprecated in FastAPI.
• Thread pool exhaustion — asyncio.to_thread() uses a default pool of ~5 workers. Under concurrent load, blocking SDK calls exhaust the pool. Set loop.set_default_executor(ThreadPoolExecutor(max_workers=20)) or use async clients.
• N+1 queries — Loading rows then querying per-row in a loop. Batch into one query (join / IN / eager-load). This is the most common cause of an endpoint that passes tests but fails the evaluator's latency ratchet.
• Unbounded result set — Returning a whole table/collection with no LIMIT/pagination. Always cap and paginate list responses; never load an unbounded table into memory.
• Missing index on a filtered column — A WHERE/ORDER BY/JOIN column with no index is a full scan; fine at 10 rows, a timeout at scale. Declare the index in the model/migration.
• Sequential independent awaits — Two awaits with no data dependency run back-to-back instead of via asyncio.gather/Promise.all. Gather independent I/O.
• Per-request re-computation — Recompiling regexes, reloading config, or re-opening clients inside the handler instead of hoisting to startup/module scope.