Enforced by linter, pre-commit hooks, review. Original: ~/.claude/backups/CODING_STANDARDS.md.
Index
- Structure, Folders, Pipelines: file/function size, one responsibility, stages
- Naming: functions, booleans, abbreviations
- Constants and reuse: one definition per repeated value
- CSS units: rem only, spacing tokens
- Shared UI styling: one shared style per kind of UI thing
- Comments, File headers, Context docs, ADRs: what to write where
- Interfaces, Errors: signatures, typed errors
- Tests, Linter: TDD, naming, ESLint rules
- Commits, Version control: messages, branches, merges
- Security: SQL, shell, secrets, authz, deps
- Per-file / Per-merge checklists
Structure
- One responsibility per file (summary has no "and"). Class: 1 job, >5–7 public methods → split.
- Function ≤30 lines (hard 50). File ≤200 (soft 400, >600 = problem). No god files.
Naming
- Functions: say what they do incl. side effects. No
process,handle,update,check,run.- e.g.
validateAndNormalizeUserInput,onPaymentWebhookReceived,syncUserProfileToDatabase,isEmailFormatValid
- e.g.
- Files: name by contents, never
utils.js. Organise by domain:payments/formatCurrency.js. - Variables: no single letters (except
i/j/math). Booleansis/has/can. Full nouns. Spell out abbreviations (URL/ID/API ok).
Constants and reuse (same fact = one definition)
- A value that means the same thing in 2+ places gets one named constant. Applies to status/kind strings, units (
DAY_MS), limits (bytes, lengths), storage keys, header values, regexes. - Not a "wrong abstraction": a constant is one fact written once. "Prefer duplication" (see Folders) covers behaviour, not values.
- Same number, different meaning (e.g. two
200s) = two names, never merged. - Where: nearest feature
constantsfile; used in 2+ features →shared/. Build-less frontend that can't import the backend: one copy per side, a comment naming the mirror, a test that both agree. - Enum-like values: export an object (
STATUS.SENT), build validation Sets from it, and test it against the DBCHECKlist. - Never rename a stored value (DB, localStorage, API) while centralising it.
- New code: before typing a literal, grep for an existing constant. Writing a second definition = defect.
- Add a test that fails if the raw literal returns (e.g. scan source for
86400000). - Exempt: 0, 1, -1, HTTP status codes, array indexes, one-use CSS/UI copy.
CSS units (decided 2026-10-18)
- rem everywhere: spacing, font sizes, widths/heights, radii, media queries. Why: scales with the user's text-size setting; one unit = no px/rem mix.
- Spacing goes through a rem scale of tokens (
--space-1…N, e.g. 0.25 / 0.5 / 1 / 1.5 / 2rem). Raw gap/margin/padding numbers = defect. - px exempt only for: borders, outlines, hairlines (1–2px), box-shadow/blur radii.
- Enforce with a test that scans CSS for px outside the exemptions.
Shared UI styling (decided 2026-10-18, permanent)
- Each kind of UI thing (button, dropdown, row, card, link, tab, menu, input, dialog) has ONE shared style, defined once, used everywhere. Why: fixing the look in one place fixes it on every page; one-offs drift and clash.
- New element of a known kind → use the shared class/rule. Never a one-off style for one screen.
- Style by element, role or shared class (
select,.btn-dark,.menu-item), not per-page selectors that repeat the look. - Variants change tokens only (custom properties like
--c,--space-N), never redeclare the whole look. - Looks wrong in one place → fix the shared rule. Element missing the look → give it the shared class; don't copy the styles onto it.
- OS-drawn widgets (dropdown lists, date pickers): style the element once globally (e.g.
appearance: base-select) instead of per-site rebuilds; note which browsers fall back to native. - Before writing a style: grep for the shared rule for that kind. A second definition of the same look = defect.
- Add a test that the shared rule exists and covers the kind (e.g. every
<select>matches it).
Comments
- WHY, not WHAT. Categories: WHY, CONTRACT (pre/postconditions), CONSTRAINT (external limits), TODO/FIXME (with context).
- No commented-out code (git has history). No stale comments.
Interfaces
- Typed signatures: Python hints, TS types, JS JSDoc.
- One return shape, success or error.
- Pure transforms separate from side-effect functions.
- Handle errors at module boundary. Internals stay internal.
Pipelines
- Each stage independently invokable (
fetch,match,notify); no skip flags. - DB is the contract between stages; stages never call each other.
run= thin orchestrator only.- Stages idempotent (upsert, not insert). Each commits its output; a later crash keeps earlier work.
- Why: isolated tests, debuggable, skip costly stages, one reason to change.
Errors
- Typed, named errors (
ValidationError,RateLimitError). No raw strings. - Handle where context can decide. Never swallow silently. Never leak stack traces/DB errors to client.
Tests
- Write first for AI-assisted code. Names describe behavior (
test_rejects_email_without_at_symbol), not function names. - One behavior per test; "and" in name → split. Assert observable behavior, not internals. No shared mutable state.
- Types: unit, integration, snapshot, TS type-check in CI.
Linter (JS: ESLint flat config, js.configs.recommended)
- Rules:
max-lines400,max-lines-per-function50 (both skip blanks/comments),max-depth4,no-unused-vars(args^_),no-undef,eqeqeq. - Runs inside the test suite (e.g.
tests/lint.test.js) sonpm testfails on lint. No formatter rules. Lint owned code only. - Existing offenders: one
KNOWN EXCEPTIONSblock, each line with a ticket number. Never add a file to pass a change. Noeslint-disable.
Commits (PLAIN-LANGUAGE-COMMIT-01)
- Plain, human-readable, intent (what + why, not how). Imperative present tense. Subject ≤50 chars. Body = why.
- No jargon, no ticket-number-only, no "wip"/"fix stuff"/"updates".
- Good:
skip archived contacts when building the billing run. - AI code: message is your reasoning; note what you changed.
Version control
- Feature branches only, prefixes
feature/ fix/ refactor/ chore/. Short-lived; merge, delete. git merge --no-ff. Commit incrementally; each commit one working, tested unit. Tests before implementation.- Never commit "just running" state. Tag before big AI refactors.
Folders
- Feature/domain slices (
auth/,payments/,users/,shared/), not technical layers. shared/= no domain dependency, kept small; prefer duplication to wrong abstraction.- Layer-sliced legacy → add
context.md/AGENTS.mdmapping domains to files.
File headers (every non-trivial file)
- Lines: purpose (1 sentence);
Depends on:;Called by:;IMPORTANT:constraints;Never:prohibitions.
ADRs (docs/decisions/NNN-title.md, 10–20 lines)
- Fields: Status, Context, Decision, Consequences, Alternatives rejected (most important: stops re-litigation).
Context docs
- Per project:
AGENTS.mdat root (<500 words: purpose, stack, folders, patterns, never-do, key decisions + ADR links),docs/decisions/,.ai/(session state, logs). - Session start: read AGENTS.md → one-pass check of today's files (single responsibility? independent modules? skip flags/god files?). Once per session, one sentence, no ceremony. Then relevant ADRs, file headers, task with constraints.
Security
- Parameterised SQL only. No user input in shell.
- No hardcoded secrets (env/secrets manager). Escape HTML output.
- Check ownership, not just auth. Rate-limit login/reset/destructive endpoints.
- No internal errors to client. Audit new deps (
npm audit/pip-audit). - Never let AI write unreviewed: auth/sessions, crypto, access control, payment flows beyond SDK.
Per-file checklist (before commit)
- Header present; function ≤30 lines; file ≤200;
npm testincl. lint passes, no new exceptions. - Descriptive names; WHY comments; no dead code; no hardcoded secrets/magic strings or repeated literals (see Constants and reuse).
- Explicit error handling. AI code: every import/method verified to exist.
Per-merge checklist (PR or local merge)
- Branch prefix; commits pass PLAIN-LANGUAGE-COMMIT-01; tests first/alongside, behavior-named.
- AGENTS.md and ADR updated if architecture changed.
- Security check if touching input/auth/storage/external services; deps audited.
- AI code: can explain every non-trivial block.