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;
runonly calls stages; stages idempotent (upsert); failed stage never undoes earlier ones.
Naming
- Functions state side effects (
syncUserProfileToDatabase, notupdate). Booleansis/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-Nrem 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-lines400,max-lines-per-function50,max-depth4,no-unused-vars^_,no-undef,eqeqeq). Noeslint-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-auditfor 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 testincl. 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.