Standards

Standards summary

Short form of ~/.claude/CODING_STANDARDS.md + ~/.claude/AI_Assisted_Dev_Architecture.md. Hard rules. Open a full doc only for the section the task touches. Project AGENTS.md/CLAUDE.md wins where more specific. Originals: ~/.claude/backups/.

Index (use only what the task needs)

  • Size and structure: file/function limits, folders, pipelines
  • Naming: functions, booleans, abbreviations
  • Constants and reuse: one named constant per repeated value
  • CSS units: rem only, spacing scale tokens
  • Shared UI styling: one shared style per kind of UI thing, reused everywhere
  • Comments and headers: WHY comments, file header fields
  • Interfaces and errors: signatures, typed errors
  • Tests: TDD, naming, JS lint-in-tests
  • Git: branches, merges, commit messages
  • Scope and hallucination: stay in scope, verify imports, plan first
  • Security: SQL, shell, secrets, authz, deps
  • Session start: what to read first
  • Before committing / merging: checklists

Size and structure

  • One responsibility per file (one sentence, no "and"). No god files, no utils.js.
  • Function <30 lines (hard 50). File <200 (soft 400, >600 = problem). Class >5–7 public methods → split.
  • Feature/domain folders, not layers. shared/ = no domain knowledge. Prefer duplication to wrong abstraction.
  • Pipelines: each stage own command; data store is the contract; no skip flags; run only calls stages; stages idempotent (upsert); failed stage never undoes earlier ones.

Naming

  • Functions state side effects (syncUserProfileToDatabase, not update). Booleans is/has/can. Full nouns (URL/ID/API ok). Single letters only for loop counters/math.

Constants and reuse

  • Same value, same meaning, 2+ places → one named constant (status/kind strings, DAY_MS, limits, storage keys, header values, regexes). Grep for an existing one before typing a literal.
  • Same number, different meaning → separate names. Enum-likes: export an object, build Sets from it, test vs DB CHECK.
  • Build-less frontend: one copy per side + mirror comment + agreement test. Never rename stored values (DB, localStorage, API).
  • Add a test that fails if the raw literal returns. Exempt: 0/1/-1, HTTP codes, indexes, one-use UI copy.
  • Constants ≠ "wrong abstraction": duplication rule covers behaviour, not values.

CSS units

  • rem for spacing, font sizes, widths, radii, media queries. Never px.
  • Spacing only via a --space-N rem scale token; no raw gap/margin/padding numbers.
  • px allowed only: borders/outlines/hairlines (1–2px), box-shadow/blur.
  • Add a test that fails on px outside those.

Shared UI styling (permanent)

  • One shared style per kind (button, dropdown, row, card, link, tab, menu, input), defined once, used everywhere. No one-off styles per screen.
  • Style by element/role/shared class; variants change tokens only (--c, --space-N).
  • Wrong in one place → fix the shared rule. Element missing it → add the shared class, never copy styles.
  • OS-drawn widgets (dropdown lists): style globally once (appearance: base-select); note native fallbacks.
  • Grep for the shared rule before styling. Second definition of a look = defect. Test that the shared rule covers the kind.

Comments and headers

  • Comments = WHY (also CONTRACT, CONSTRAINT, TODO with context), never WHAT. No commented-out code, no stale comments.
  • Every non-trivial file header: purpose (1 sentence), Depends on:, Called by:, IMPORTANT:, Never:.

Interfaces and errors

  • Explicit signatures. One return shape. Pure transforms separate from side effects.
  • Typed named errors, handled at module boundaries. Never swallow. Never send stack traces/DB errors to clients.

Tests

  • Tests first; commit with/before implementation. Behaviour-named (rejects email without @), one behaviour each, no "and", no implementation asserts, no shared mutable state.
  • JS: ESLint inside npm test (max-lines 400, max-lines-per-function 50, max-depth 4, no-unused-vars ^_, no-undef, eqeqeq). No eslint-disable. Never add KNOWN EXCEPTIONS to pass new code; split it.

Git

  • Branch per task (feature/ fix/ refactor/ chore/), short-lived, git merge --no-ff, delete after merge. Tag before big refactor.
  • Commits: plain language, imperative, subject ≤50 chars, body = why. Never "wip"/"fix stuff"/ticket-only. Only working, tested units.

Scope and hallucination

  • Change only what the task names. No renames/reformat/"improvements" nearby; note or ticket other problems.
  • Verify every new import, external method, internal function exists (grep/docs). Run the code. Name library versions. Reuse helpers.
  • Plan before non-trivial work. Restart rather than iterate on a wrong approach. Chunks each end tested.

Security

  • Parameterized SQL only. No user input in shell. Escape HTML. No hardcoded secrets.
  • Check ownership, not just authn. Rate-limit login/reset/destructive endpoints. No Access-Control-Allow-Origin: * on authed APIs. Validate uploads (type, size, content).
  • npm audit / pip-audit for new deps.
  • Auth/session, crypto, permissions, payments: proven libraries; flag for human review.

Session start

  • Read: project AGENTS.md, ADRs for the task, headers of files to touch.
  • Once per session, one sentence: do touched files break one-responsibility / no-god-file / stage rules?
  • Minimal context: read needed functions, not trees.

Before committing (per file)

  • Header · fn ≤30 (50 max) · file ≤200 (400 soft) · names say what they do · WHY comments only · no dead code · no secrets/magic strings/repeated literals · explicit errors · npm test incl. lint passes · every import/call verified.

Before merging (per branch)

  • Prefixed branch · plain-language commits · tests first, behaviour-named · AGENTS.md/ADR updated if architecture changed · security checklist if touching input/auth/storage/external services · new deps audited · can explain every non-trivial block.