dev-standards

# Engineering standards Shared rules for every code-producing or code-reviewing role (Senior Engineer, Engineer, TechLead, QC). Role skills tell you *what to do and when*; this skill tells you *how good the result must be*. When a rule here conflicts with an approved requirement or ADR, the requirement/ADR wins and the deviation is recorded. ## How to use 1. Before writing code: read the section that matches the task and the matching reference file. 2. While writing: keep to the rules; do not add tooling that is not already part of the project unless an ADR approves it. 3. Before handoff: run the review checklist below and report the result in the handoff note. 4. QC: derive security and performance test cases from the checklists and record evidence. ## Quick rules (details in the references) ### Coding standards — [reference](./references/coding-standards.md) - Python 3.12: type hints on all public functions, `dataclass(frozen=True, slots=True)` for value objects, small functions (about 30 lines or fewer), early returns, no mutable global state. - Format and lint with the tools configured in the project: Ruff in `backend/pyproject.toml` (ADR-005, line length 100); ESLint (`eslint-config-next`) and TypeScript `strict` in `frontend/`. - TypeScript/React: no `any`, explicit types at module boundaries, Server Components by default, `"use client"` only when needed, effects always clean up, Zod at the API boundary, no `dangerouslySetInnerHTML`. - Names describe intent; comments explain *why*, not *what*; no dead code or commented-out code. - Every module cites the requirement/contract IDs it implements (docstring or header comment). ### Code performance — [reference](./references/performance.md) - State the budget first (e.g. `POST /api/run` p95 <= 200 ms for the largest legal program, including the DB write) and measure before optimizing. - Prefer algorithmic fixes: bounded loops, lazy expansion, no repeated work in hot paths, no per-request I/O beyond the single progress upsert. - Frontend: minimal re-renders during animation (memoized board cells), small client bundle (Server Components by default), no layout thrash, timers cleaned up, no blocking work on the main thread. - Record the measurement method and numbers in test results; do not claim "fast" without numbers. ### SQL / database performance — [reference](./references/sql-performance.md) - Persistence is **SQLite** (stdlib `sqlite3`) holding one bounded progress table (ADR-008). Anything beyond it (new tables, history, another engine) needs a requirement and an ADR. - Parameterized queries only, explicit columns, indexes justified by access patterns, `EXPLAIN QUERY PLAN` evidence for non-trivial queries, no N+1, bounded result sets, forward-only reviewed migrations, short transactions. ### Security — [reference](./references/security.md) - Treat all request data as untrusted: strict schema validation, closed vocabularies, explicit size/length limits, reject unknown fields. - No `eval`/`exec`, no shell commands built from input, no string-built SQL, no secrets in code or images, no verbose internals in error responses. - Browser: React text rendering only (no `dangerouslySetInnerHTML`), Zod-validated API responses, security headers and CSP from `next.config.ts`. - Container: non-root user, read-only root filesystem, minimal base image, pinned dependencies, no Docker socket, only needed ports, DB file only on the data volume. - Run dependency audits (`pip-audit`, `npm audit`) when available and record the result. ## Code review checklist - [ ] Matches the contract and requirements; no behavior without a requirement ID. - [ ] Types, naming, function size, and error handling follow the coding standard. - [ ] No rule logic duplicated across layers (simulator is the only source of game rules). - [ ] Inputs validated at the boundary with explicit limits; errors use the single error envelope. - [ ] No security anti-pattern from `references/security.md`. - [ ] Performance budget met or the gap is recorded; no unbounded loops or allocations from user input. - [ ] Tests cover the new behavior including at least one negative/boundary case. - [ ] Changes recorded in `docs/FILE-CHANGELOG.md`. ## References - [Coding standards](./references/coding-standards.md) - [Code performance](./references/performance.md) - [SQL performance](./references/sql-performance.md) - [Security](./references/security.md)