claude-mods/rules/agentic-quality.md

Agentic Quality — code, comments, and structure that survive the session

Companion to the repo-doctor skill (the auditor that scores a repo against this doctrine, plus the deep references on commenting, entry docs, and monorepo structure). This file is the directive — how to write code, comments, docs, and directory structure in every repo, on every task, so the work stays navigable by the next agent session.

The rule

Every artifact you produce must pass the cold-agent test: a fresh session with zero conversation context must be able to find it, understand why it is the way it is, and modify it without breaking an invisible constraint. Session context dies at the end of every conversation — the repo is the only channel to your future self. Anything that lives only in the chat (a constraint you discovered, a format you invented, a reason you chose the weird option) is lost unless it lands in the code, a comment, or a doc in the same piece of work.

Three non-negotiables:

1. The WHY gets written down at the site of the WHAT. A non-obvious constraint, invariant, or format is documented where it lives — not in the commit message, not in the chat, not "later".
2. Deliberate weirdness carries a guard comment. Anything that looks refactorable but isn't — a single-file app, a reused buffer, a monster file with a single-writer rule, an odd key format — gets an explicit "why this shape" comment. The #1 agent-specific failure mode is a future agent "improving" away a constraint it couldn't see.
3. Done includes the doc touch. A feature is not finished until the entry doc, index, or design doc it invalidates is updated — in the same commit or the one beside it. Staleness is measured in commits-since-doc-touched, never days.

Why this matters

A 2026-07 audit of 10 active repos on this machine found the single best (GlyphWeb, 4.8/5) and one of the weakest (Simulacra, 3.2/5) were built by the same developer with the same tooling in the same month. The difference was never effort — it was whether the conventions below were applied as-you-go vs deferred. The recurring failures, every one of them expensive for agents: 9,560-line files navigable only by grep; docs lagging 100+ commits behind code; idempotency-key formats with zero explanation two ADRs away from their construction site; agents refactoring single-file apps into modules and breaking file:// preview because nobody wrote down why it was one file. Enforcement beats intention, and written doctrine is the first enforcement layer.

Comment doctrine — what goes in the code

Layer	Directive
Contract block (top of file)	Every substantive source file opens with 3–12 lines: what this module is, the invariants it enforces or relies on ("crash-safe + idempotent", "the ONLY module that touches D1", "no Math.random — deterministic replay"), and cross-refs to the doc/ADR that owns the reasoning.
WHY-only inline	Inline comments state constraints, invariants, units, ranges, and reasons — never narrate what the next line does. // order-independent so retries hash to the same key earns its place; // loop over the items never does.
Guard comments	Anything deliberately "wrong-looking" gets 2–5 lines starting with the constraint: why the file is one file, why the buffer is reused, why the allocation is hoisted, why the dependency is pinned. Name what breaks if it's "fixed".
Formats at the construction site	Wire formats, cache keys, hash inputs, magic strings: document the format grammar and the reason for each component where the string is built, even if an ADR also covers it.
Section markers	Files over ~400 lines get // === SECTION === markers and, over ~800, a top-of-file section map so an agent can jump instead of scroll.
Citations	Domain knowledge embedded in code (standards, papers, OSM way IDs, RFC numbers, spec sections) is cited inline — that's what makes domain code modifiable by a non-domain agent.
Docstrings/JSDoc	Public functions get them when the signature alone under-specifies: side effects, error behaviour, units, ordering guarantees. Private helpers with honest names don't need ceremony.

What NOT to write: comments explaining what the code obviously does, comments addressed to the current reviewer ("fixed per feedback"), commented-out code, TODO without an owner-context ("TODO(cache): invalidate on rename — see #42" is fine; bare "TODO fix" is noise).

Entry docs — AGENTS.md is the front door

• One AGENTS.md per repo, and it is the single source of truth. It carries: what the repo is (2–4 lines), run/test/check commands (exact, tested), a structure map (folder → what lives there), conventions, and — mandatory — a Landmines section: the specific things that break non-obviously (coupled golden fixtures, generated files you must not hand-edit, ordering-sensitive registries). Landmines are the highest-value lines in the file.
• Keep it lean. An agent re-reads this every session; every line is a recurring token cost. Target under ~150 lines; push walkthroughs and rationale into docs/ and link them. Setup guides for humans go in README or CONTRIBUTING, not AGENTS.md.
• CLAUDE.md: only as a one-line pointer to AGENTS.md (tool compatibility), or when there are genuinely Claude-specific deltas — and then it holds only the deltas, never a copy. If both exist, a change to a shared rule updates both in one commit.
• Nested AGENTS.md only where a subsystem has its own contract (a design-system package, an engine with determinism laws, a per-tool CLI). Nested files carry deltas and their own landmines; the root file links each one in an ownership table. Never blanket-nest — duplicated rules rot into contradictions.

Structure — folders an agent can guess

• Guessability is the metric: an agent should predict where a feature lives from folder names alone. Feature/subsystem folders over kind-folders at scale; src/xero/ beats src/utils2/.
• File-size discipline: at ~400 lines add section markers; at ~800 split by responsibility or write the guard comment justifying why not; a deliberately large file (single-writer rule) REQUIRES a top-of-file section map and a mechanical gate that enforces the invariant that justifies it (the lint:db/"only this module touches the DB" pattern — a 30-line check script makes a 9,000-line file safe).
• Repo root is sacred: no scratch scripts, screenshots, output artifacts, or one-off probes in root. Scratch work goes to the session scratchpad or dev/; captured verification images go to docs/screenshots/; generated artifacts are gitignored or clearly marked generated ("built — don't hand-edit" header).
• Tests live where an agent looks: colocated test//tests/ per package, named for the behaviour they defend. Adversarial tests are named for the adversary (double-bill-nudge.test.ts, not billing2.test.ts) — the name tells the next agent what evil the test blocks.
• Every repo has one check entry point (npm run check, just check, make check) that gates typecheck + lint + tests + the repo's invariant scripts. If it isn't one command, agents won't run it.

Docs discipline — as-you-go, indexed, delegated

• docs/ with more than ~6 files gets an index (00_INDEX.md, or a PLAN.md that serves the role): one line per doc — what it is, why you'd read it. Two rules that keep an index alive: it carries its own maintenance instruction, and volatile lists (ADRs, per-item inventories) are delegated to the filesystem ("see ls docs/adr/") instead of hand-copied.
• Docs pair with features. The commit that changes behaviour touches the doc that described the old behaviour. docs(...) commits interleaved with feat(...) commits is the healthy signature; a docs commit catching up 10 features later is the rot signature.
• Decisions that constrain the future become ADRs (→ adr-ops skill): one decision per record, rejected alternatives included. Everything else is a commit message or a code comment — don't ceremonialise.
• Plans state their liveness. A roadmap/PLAN.md says what's next and marks shipped phases done; history lives in CHANGELOG/git, not in the plan.

Monorepos — structure for many-subsystem repos

The full playbook is repo-doctor's monorepo-structure reference. The directives:

• Root AGENTS.md is a router: repo-wide invariants + an ownership table mapping subsystem → path → its nested AGENTS.md (if it has a contract) → its gate.
• Each package with its own contract gets its own entry doc and its own check; the root check fans out.
• Cross-package invariants get mechanical gates, not prose — "only X imports Y", "no package → app imports", "tokens only, no raw hex" are 20-line scripts, and they're the only reason large shared files/dirs stay safe.
• Extraction signal: when a subsystem grows a roadmap, an asset library, or an audience of its own, it's a product — extract it to its own repo before it distorts the host (the iso-studio/svg-studio rule).

Self-check — before ending any turn that wrote code

• Did I introduce a constraint, format, or non-obvious choice this turn? → Is it written at the site (contract block, guard comment, format comment)?
• Did my change invalidate anything AGENTS.md / the docs index / a design doc says? → Same-commit fix.
• Did I create a file > 400 lines, or push one past 800? → Markers / split / guard.
• Did I leave anything in repo root that isn't permanent? → Move or delete.
• Would repo-doctor flag what I just did? When in doubt, run it.

When to bend the rule

Scratchpad experiments, one-shot probes, and generated/vendored code are exempt — but the moment a scratch artifact is committed to a repo, it either meets the doctrine or carries a header saying what it is and when it can be deleted. Solo creative projects (art, maps, one-off visualisations) may skip entry-doc ceremony, but the comment doctrine still applies — domain-heavy code with cited sources is precisely what keeps creative repos modifiable later.

Cross-reference

• ~/.claude/skills/repo-doctor/SKILL.md — the auditor: scores any repo against this doctrine; references own the depth (comment-doctrine, entry-docs, monorepo-structure, scoring-rubric).
• ~/.claude/skills/adr-ops/SKILL.md — decision records (when-to-write rule lives there).
• ~/.claude/skills/doc-scanner/SKILL.md — reads/synthesizes/generates entry docs; repo-doctor audits them.
• ~/.claude/skills/refactor-ops/SKILL.md — the remediation path for monster files.
• naming-conventions.md — claude-mods component naming; this rule owns cross-repo code/doc quality.