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 50 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.
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.
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
- 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.
- 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
- 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%.
- Only mock external boundaries: databases, third-party APIs, file I/O, clocks, payment processors, queues.
- Never mock business logic — if you mock a service to test another service, you are hiding bugs and testing wiring instead of behavior.
- 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.
- 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.
- Realistic test data — use domain-representative values (real-looking emails, valid UUIDs, plausible amounts). Never
"foo", 123, or "test".
- Test names describe behavior:
"returns 404 when order does not exist", not "test order".
- 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:
- Retry once with an explicit correction prompt: "Your response did not match the required schema. Required: {schema}. Please respond again."
- 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.
1---2name: code-gen-43description: Code generation quality principles — TDD, typing, error handling, logging, API integration, LLM integration.4metadata:5 source: https://skillmd.com/skills/cwijayasundara/code-gen-46---78# Code Generation Skill910Reference skill for generator teammates. Read this before writing any code.1112---1314## Core Quality Principles1516### 1. Small Modules — One File, One Responsibility17- Each file must have a single, clearly named responsibility.18- **Warning threshold:** 200 lines — add a comment noting the file is growing large.19- **Block threshold:** 300 lines — do not submit. Split before opening a PR.20- If you hit 300 lines, decompose into sub-modules and re-export from an index file.2122### 2. Static Typing — Annotate Everything23- Every function parameter, return value, and variable must have an explicit type.24- **TypeScript:** Zero `any`. Use `unknown` + type guard if the shape is truly unknown.25- **Python:** Full type hints on all functions. Use `TypeVar`, `Generic`, `Protocol` where appropriate.26- Type aliases for domain concepts (`UserId = str`, `type OrderId = string`).2728### 3. Functions Under 50 Lines29- If a function body exceeds 30 lines, decompose it into named sub-functions (the `pre-write-gate` hook enforces this limit deterministically).30- Each sub-function should be testable in isolation.31- Use descriptive names that read as a sentence: `validateOrderItems`, `buildPaymentPayload`.32- Avoid deeply nested control flow — extract branches into named helpers.3334### 4. Single Owner for State Mutations35- Every state-creating operation (DB insert, file write, queue publish) must have exactly ONE call site.36- If a route handler creates a record, the service it calls must receive the ID — not create a second record.37- **Anti-pattern:** Route creates Task, then calls `service.start(query)` which also creates a Task → duplicate records.38- **Correct pattern:** Route creates Task with ID, then calls `service.start(task_id)` which operates on the existing record.39- When a background task or async flow needs a resource, pass the ID, don't re-create it.40- Test this explicitly: after calling the endpoint, assert the exact count of records created (e.g., `assert db.query(Task).count() == 1`).4142### 5. Explicit Error Handling43- Define typed error classes per domain (e.g., `class OrderNotFoundError extends AppError`).44- Never use bare `except Exception` or `catch (e: any)`.45- All error paths must be covered by tests.46- Propagate errors up with context; do not swallow silently.47- In TypeScript: use `Result<T, E>` or typed throws with JSDoc `@throws`.4849### 6. No Dead Code50- Every line of code must trace to a user story or a technical requirement.51- Do not leave commented-out code in PRs.52- Remove unused imports, variables, and parameters immediately.53- If code is speculative ("might need later"), do not include it.5455### 7. Self-Documenting — Names Over Comments56- Variable and function names should make comments unnecessary.57- Types act as documentation — a well-typed function signature is its own doc.58- Use comments only for non-obvious decisions (algorithm choice, regulatory constraints).59- Avoid `// TODO` in submitted code — file a story instead.6061### 8. Deep Modules — Simple Interface, Useful Behavior62- Prefer modules with small, stable interfaces that hide meaningful complexity.63- A module interface includes its types, invariants, error modes, ordering requirements, and configuration — not just the function signature.64- 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.65- Do not create pass-through services, repositories, hooks, helpers, or adapters just to satisfy a pattern.66- 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.6768### 9. Public Interface as Test Surface69- Tests should verify observable behavior through public interfaces: API endpoints, CLI commands, UI flows, exported module functions, or documented domain services.70- Do not test private helpers, implementation details, internal call order, or mock interactions unless that is the public contract.71- If a helper is complex enough to need direct tests, consider making it a named domain module with a clear public interface.72- A good test should survive internal refactors when behavior is unchanged.7374---7576## Code Patterns7778### Test Structure: Arrange → Act → Assert79```80// Arrange81const order = buildOrder({ status: "pending" });82// Act83const result = processOrder(order);84// Assert85expect(result.status).toBe("confirmed");86```8788### Typed Error Classes89```typescript90class DomainError extends Error {91 constructor(message: string, public readonly code: string) {92 super(message);93 this.name = this.constructor.name;94 }95}96class OrderNotFoundError extends DomainError {97 constructor(orderId: OrderId) {98 super(`Order ${orderId} not found`, "ORDER_NOT_FOUND");99 }100}101```102103### Naming Conventions104- **Files:** `kebab-case.ts` for TypeScript, `snake_case.py` for Python.105- **Functions/methods:** `camelCase` (TS), `snake_case` (Python).106- **Types/classes:** `PascalCase` in both languages.107- **Constants:** `UPPER_SNAKE_CASE`.108- **Booleans:** prefix with `is`, `has`, `can`, `should`.109110### Database Session Lifecycle (Python/FastAPI)111- Use `async_sessionmaker` with FastAPI `Depends()` for dependency injection — never create sessions manually per request.112- Engine and session factory created once in `lifespan`, stored on `app.state`, disposed on shutdown.113- Sessions auto-close via `async with` — never leave sessions open.114- Tests override the session dependency to use a test DB, not the dev DB.115116```python117# CORRECT — lifespan manages engine lifecycle118@asynccontextmanager119async def lifespan(app: FastAPI):120 engine = create_async_engine(settings.DATABASE_URL)121 app.state.session_factory = async_sessionmaker(engine)122 yield123 await engine.dispose()124125# CORRECT — session via dependency injection126async def get_db(request: Request) -> AsyncGenerator[AsyncSession, None]:127 async with request.app.state.session_factory() as session:128 yield session129130DbSession = Annotated[AsyncSession, Depends(get_db)]131```132133### Background Tasks Must Be Tracked134- Every background task must have a corresponding DB record with a status field (`pending`, `running`, `completed`, `failed`).135- The route creates the record (status=`pending`), then starts the background task with the record's ID.136- The background task updates the record on completion or failure — never fire-and-forget.137- Wrap the entire background task body in try/except: on failure, update the record to `failed` with error details and log the exception.138139```python140# CORRECT — tracked background task141@router.post("/tasks")142async def create_task(request: TaskRequest, db: DbSession, background_tasks: BackgroundTasks):143 task = Task(query=request.query, status="pending")144 db.add(task)145 await db.commit()146 background_tasks.add_task(run_task, task.id) # pass ID, not the object147 return {"task_id": task.id, "status": "pending"}148149async def run_task(task_id: UUID) -> None:150 async with get_session() as db:151 task = await db.get(Task, task_id)152 try:153 task.status = "running"154 await db.commit()155 result = await do_work(task.query)156 task.status = "completed"157 task.result = result158 except Exception as e:159 logger.exception("Task failed", extra={"task_id": str(task_id)})160 task.status = "failed"161 task.error = str(e)162 finally:163 await db.commit()164```165166### CORS Must Be Environment-Configured167- Never use `allow_origins=["*"]` with `allow_credentials=True` — this is a security vulnerability.168- Read allowed origins from an environment variable, default to `localhost` only.169170```python171# CORRECT — env-configured CORS172allowed_origins = settings.ALLOWED_ORIGINS.split(",") # from .env173app.add_middleware(174 CORSMiddleware,175 allow_origins=allowed_origins,176 allow_credentials=True,177 allow_methods=["GET", "POST", "PUT", "DELETE"],178 allow_headers=["*"],179)180```181182### Health Check Must Verify Dependencies183- Health endpoint must test critical dependencies (DB, cache, external APIs), not just return `{"status": "ok"}`.184- Return 503 if any dependency is unreachable.185186```python187@router.get("/health")188async def health(db: DbSession) -> dict:189 try:190 await db.execute(text("SELECT 1"))191 return {"status": "ok", "db": "connected"}192 except Exception:193 raise HTTPException(status_code=503, detail="Database unreachable")194```195196### Request ID Middleware197- Add middleware that generates a unique `request_id` per request and includes it in all log entries and error responses.198- This enables tracing a single user request across all service logs.199200```python201@app.middleware("http")202async def add_request_id(request: Request, call_next):203 request_id = str(uuid4())204 request.state.request_id = request_id205 response = await call_next(request)206 response.headers["X-Request-ID"] = request_id207 return response208```209210---211212## Testing Rules — TDD Mandatory213214**"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 Krenzel2152161. **Tracer-bullet TDD: one behavior at a time.**217 - Do not write all tests first, then all implementation.218 - Write one failing behavior test through the public interface.219 - Implement the minimum code to pass that test.220 - Repeat for the next behavior.221 - This prevents imagined tests for imagined architecture.2222. **Tests FIRST, then code (TDD):**223 - Write a failing test that defines expected behavior224 - Run it — verify it fails for the right reason225 - Write the minimum code to make it pass226 - Run it — verify it passes227 - Refactor if needed, re-run tests228 - Commit2293. **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%.2304. **Only mock external boundaries:** databases, third-party APIs, file I/O, clocks, payment processors, queues.2315. **Never mock business logic** — if you mock a service to test another service, you are hiding bugs and testing wiring instead of behavior.2326. **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`.2337. **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.2348. **Realistic test data** — use domain-representative values (real-looking emails, valid UUIDs, plausible amounts). Never `"foo"`, `123`, or `"test"`.2359. Test names describe behavior: `"returns 404 when order does not exist"`, not `"test order"`.23610. **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.237238---239240## LLM Integration — Structured Output Mandatory241242When generated code calls any LLM (Claude, GPT, or other), follow these rules:243244### 1. Always Use Structured Output245246Use `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.247248### 2. Define a Response Schema249250Every LLM call must have a typed model for the expected response:251252```python253from pydantic import BaseModel254from typing import Literal255256class ClassificationResult(BaseModel):257 category: str258 confidence: Literal["high", "medium", "low"]259 reasoning: str260```261262```typescript263interface ClassificationResult {264 category: string;265 confidence: "high" | "medium" | "low";266 reasoning: string;267}268```269270### 3. Validate Before Using271272Parse the LLM response through the schema. If validation fails:2731. Retry once with an explicit correction prompt: "Your response did not match the required schema. Required: {schema}. Please respond again."2742. If second attempt fails, raise a typed error — do not fall back to a default value.275276### 4. No Silent Fallbacks277278Never write:279```python280# WRONG — hides bugs that compound281try:282 result = await call_llm(prompt)283 parsed = ResponseModel.model_validate_json(result)284except Exception:285 parsed = ResponseModel(category="unknown", confidence="low", reasoning="")286```287288Instead:289```python290# CORRECT — caller decides how to handle failure291class LLMResponseError(Exception):292 def __init__(self, raw_response: str, validation_error: str):293 self.raw_response = raw_response294 self.validation_error = validation_error295 super().__init__(f"LLM response validation failed: {validation_error}")296297try:298 result = await call_llm(prompt)299 parsed = ResponseModel.model_validate_json(result)300except ValidationError as e:301 raise LLMResponseError(raw_response=result, validation_error=str(e))302```303304### 5. Log Raw Responses305306Always log the raw LLM response at DEBUG level before parsing:307308```python309logger.debug(310 "LLM response received",311 extra={312 "provider": self._provider_name,313 "model": self._model,314 "prompt_tokens": response.usage.input_tokens,315 "completion_tokens": response.usage.output_tokens,316 "raw_content": response.content[:1000],317 "latency_ms": round(elapsed_ms, 2),318 },319)320```321322---323324### 6. Prompt Caching (Anthropic API)325326When 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).327328- **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.329- **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.330- **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.331- **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.332- **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).333334```python335# CORRECT — stable prefix cached, moving tail auto-cached336resp = client.messages.create(337 model="claude-...",338 system=[339 {340 "type": "text",341 "text": LONG_STATIC_INSTRUCTIONS, # unchanging across calls342 "cache_control": {"type": "ephemeral"}, # breakpoint at end of stable prefix343 }344 ],345 messages=conversation, # moving tail: no cache_control needed346)347# resp.usage.cache_creation_input_tokens / resp.usage.cache_read_input_tokens348```349350---351352### 7. Batch API for Bulk, Non-Interactive Work (Anthropic API)353354When 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).355356- **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.357- **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.358- **Combine with caching:** put the shared instructions/schema in the cached prefix (section 6) so every item in the batch reuses it.359- This is Anthropic-API-specific. For OpenAI/other providers, use their equivalent batch endpoint or skip.360361```python362# CORRECT — bulk classification as one batch job, not N synchronous calls363batch = client.messages.batches.create(364 requests=[365 {"custom_id": item.id, "params": {"model": "claude-...", "max_tokens": 256,366 "system": SHARED_PREFIX, "messages": [{"role": "user", "content": item.text}]}}367 for item in backlog # many independent items, no inter-item dependency368 ]369)370# poll batch.id, then retrieve results — do NOT block a user request on this371```372373### 8. Output Budgeting374375Output 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:376377- **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.378- **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.379- **Don't request reasoning you discard.** Only enable extended thinking when the task needs it; for mechanical/structured tasks, leave it off.380381---382383## External API Integration384385When 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.386387### Service Wrapper Pattern (Mandatory)388389Every external API gets a dedicated wrapper class. This is the ONLY file that imports the SDK or makes HTTP calls to that service.390391```392Business Logic (process_service.py)393 ↓ calls typed methods394API Wrapper (external_client.py) ← only file that imports SDK / makes HTTP calls395 ↓ calls396External API397```398399Rules:400- One wrapper class per external API401- Wrapper exposes project-internal typed models, not SDK types402- Business logic never sees SDK response objects — only your domain types403- The wrapper is the mock boundary in tests404405### Error Taxonomy (Mandatory)406407Every wrapper classifies errors into typed categories:408409```python410class ApiTransientError(Exception):411 """Retryable: 429, 502, 503, timeout, connection reset."""412 pass413414class ApiPermanentError(Exception):415 """Not retryable: 400, 401, 403, 404, schema mismatch."""416 pass417418class ApiRateLimitError(ApiTransientError):419 """Rate limited with backoff hint."""420 def __init__(self, message: str, retry_after: float | None = None):421 super().__init__(message)422 self.retry_after = retry_after423```424425- Business logic catches `ApiTransientError` to retry/degrade, `ApiPermanentError` to fail fast426- No bare `except Exception` in any API-calling code427- All exceptions carry HTTP status code and response body for debugging428429### Retry and Rate Limiting430431- Retry config lives in `config.yml` under `external_apis.{service_name}.retry`, not hardcoded432- Wrapper applies exponential backoff internally — business logic is unaware of retries433- Respect `Retry-After` headers when present434- Log every retry attempt at WARNING level435436### Async Bridging437438When an SDK is synchronous but the backend is async:439- Use `asyncio.to_thread()` only inside the wrapper class440- Never bridge in business logic441- Prefer async SDKs or HTTP clients when available442443### Secrets444445- API keys in `.env` only, loaded via config layer446- Wrapper reads from injected config, never from `os.environ` directly447- `.env.example` committed with placeholder values448449---450451## Production Standards452453These standards apply to ALL generated code, not just API wrappers or LLM calls.454455### Structured Logging456457All generated services must use structured logging with `extra` dicts:458459```python460import logging461462logger = logging.getLogger(__name__)463464# CORRECT — structured fields for JSON log formatters465logger.info("Document processed", extra={466 "document_id": doc.id,467 "processing_time_ms": round(elapsed_ms, 2),468 "output_size_bytes": len(result),469})470471# WRONG — data interpolated into message string472logger.info(f"Document {doc.id} processed in {elapsed_ms}ms")473```474475```typescript476// CORRECT — structured logger477logger.info("Document processed", {478 documentId: doc.id,479 processingTimeMs: Math.round(elapsedMs),480 outputSizeBytes: result.length,481});482483// WRONG — template literal message484logger.info(`Document ${doc.id} processed in ${elapsedMs}ms`);485```486487Rules:488- Use `logging.getLogger(__name__)` (Python) or scoped logger (TypeScript) at module level489- INFO for business events (request received, document processed, job completed)490- WARNING for recoverable issues (retry triggered, fallback used, slow response)491- ERROR for failures requiring attention (unhandled exception, data corruption, external service down)492- DEBUG for troubleshooting data (raw payloads, intermediate state, timing breakdowns)493- Never log secrets, tokens, passwords, or PII494- Log at service boundaries: incoming requests, outgoing calls, business decisions495496### Exception Handling497498```python499# CORRECT — typed exception with context500class DocumentProcessingError(Exception):501 def __init__(self, document_id: str, stage: str, cause: Exception):502 self.document_id = document_id503 self.stage = stage504 self.cause = cause505 super().__init__(f"Failed at {stage} for document {document_id}: {cause}")506507# WRONG — bare except swallowing the error508try:509 result = process(doc)510except Exception:511 result = default_value512```513514Rules:515- Define typed exception classes per domain (not per function)516- Every exception carries enough context to debug without the stack trace517- Never catch `Exception` or `BaseException` unless re-raising or logging at a top-level boundary518- No silent fallbacks — if an operation fails, the caller must know519- API route handlers catch domain exceptions and map to HTTP error responses520521### Structured Error Responses522523The 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:524525```json526{527 "error": {528 "code": "DOCUMENT_NOT_FOUND",529 "message": "Document with ID abc123 does not exist",530 "details": {}531 }532}533```534535Rules:536- `code` is a machine-readable UPPER_SNAKE_CASE string enum537- `message` is human-readable538- `details` is optional structured context539- HTTP status mapping: 400 validation, 404 not found, 409 conflict, 422 processing error, 500 internal540541### Request/Response Validation542543- All API inputs validated via Pydantic models (Python) or Zod schemas (TypeScript)544- Validation errors return 400 with field-level messages545- All API outputs serialized through response models — never return raw dicts or ORM objects546547### Configuration548549- All configurable values in `config.yml` or environment variables550- No magic numbers or hardcoded strings in business logic551- Config loaded once at startup, injected into services via constructor552- Defaults provided for all non-secret config values553554---555556## Parallel Execution557558- **File ownership:** consult `component-map.md` before touching any file.559- **Plan approval required** before starting parallel work.560- **Shared interfaces:** message teammates before changing a type or API contract that crosses boundaries.561- **Task sizing:** aim for 5–6 discrete tasks per teammate per sprint cycle.562- **Conflicts:** if two teammates need the same file, one blocks; do not merge partial changes.563564---565566## Gotchas (Things That Cause Review Failures)567568- Importing upward across layers (UI importing from repository layer)569- Functions exceeding 30 lines without decomposition570- Untyped values — `any`, missing return types, unannotated parameters571- Broad exception catches without re-raise or typed handling572- Mocking business logic in unit tests573- Generic test data (`"test"`, `0`, `null` as stand-ins for real domain values)574- Commented-out code in the submitted diff575- Missing error-path test coverage576- Teammates editing the same file in the same sprint without coordination577- **Free-text LLM parsing** — Never use regex to parse LLM output. Use structured output (tool_use / JSON mode).578- **Silent fallback on LLM error** — `except Exception: return default` hides compounding bugs. Raise typed errors.579- **Missing raw response logging** — Always log raw LLM response at DEBUG before parsing. This is the debugging ground truth.580- **Direct SDK imports outside wrapper** — All SDK imports must be inside the wrapper class file. Business logic imports your wrapper, not the SDK.581- **Bare except on API calls** — Catch `ApiTransientError` and `ApiPermanentError` specifically. Never `except Exception`.582- **Hardcoded retry config** — Retry attempts, backoff, and timeout belong in `config.yml`, not in code.583- **Missing structured logging in API wrapper** — Every request/response/error must be logged with structured fields (service, operation, attempt, latency_ms).584- **f-string log messages** — Use `extra` dict for structured fields, not string interpolation. Structured logs are searchable; f-strings are not.585- **Missing logging at service boundaries** — Every incoming request and outgoing call must be logged with timing and status.586- **Raw dict API responses** — Always serialize through a response model. Raw dicts bypass validation and leak internal structure.587- **Magic numbers** — All thresholds, limits, timeouts, and configuration belong in `config.yml`.588- **.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.589- **Sync DB driver in async app** — `postgresql://` uses psycopg2 (sync). Async SQLAlchemy needs `postgresql+asyncpg://`. Always match the driver scheme to the engine type.590- **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.591- **Manual session creation** — Never create DB sessions manually per request. Use `Depends(get_db)` with `async_sessionmaker`. Manual sessions leak connections.592- **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.593- **CORS allow_origins=["*"]** — Never use wildcard origins with `allow_credentials=True`. Read origins from env var, default to localhost.594- **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.595- **Engine not disposed on shutdown** — Always `await engine.dispose()` in the lifespan's teardown. Leaked connections exhaust the pool.596- **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.597- **Deprecated startup/shutdown events** — Use `@asynccontextmanager` lifespan, not `@app.on_event("startup")`. The event-based API is deprecated in FastAPI.598- **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.