# Quality Project Playbook: What Belongs in AGENTS.md Generic companion to `quality_software.md` and `quality_versioning.md`. It defines what an agent instruction file must contain so that every agent (and every human) develops the same way and the project stays consistent and current. Naming note: this repo uses `CLAUDE.md` instead of `AGENTS.md`, but the system is what matters, not the filename. Three layers, loaded by scope: - Personal base rules (DevPlace: `~/.claude/CLAUDE.md`). Applies to every project for one operator: safety, proof, craft, ops habits. - Root project file (DevPlace: `CLAUDE.md`, ~440 lines). Applies to the whole repo regardless of area touched. Always loaded, so it stays proportional to global rules only. - Nested subsystem files (DevPlace: ~30 `CLAUDE.md` files next to the code). Loaded only when a file under that directory is read or edited. Deep mechanics, helpers, pitfalls, worked examples. If your tooling reads `AGENTS.md`, use that name with the identical three-layer split. Never merge all three into one file: the root would bloat past usefulness and agents would stop reading it. ## 1. Personal base rules (cross-project, rarely changes) One short file per operator, ported across projects. Contents: - Control over cleverness: hard caps on everything unbounded, floors automated processes may never cross, static ceilings over autotuning, fewer dependencies. - Safety: destructive ops dry-run by default and explicitly confirmed, loud skips over silent corruption, verify-before-write, deletes that reclaim (compaction in the same change). - Proof: measured claims only, real-path testing with failure injection, suite after behavior change, live verification after deploy. - Craft: exact minimal diffs, boring technology, research before load-bearing decisions, docs describing today with gaps marked. - Communication: direct and factual, disagree with data, fixed style bans (DevPlace: no em dashes anywhere). - Operations: commit, deploy, verify in the same session; retention and checks run inside the system on loops. This layer never names project paths or stack details. When it conflicts with a project file, the project file wins. ## 2. Root project file (global rules, always loaded) Ordered contents, each earning its place by applying to every area: 1. Project identity in one paragraph: what it is, stack in one line per layer, ports, key constraints (username rules, password rules, data layout). An agent must orient in 30 seconds. 2. Commands table: install, dev, prod, every test target, load test, lint, clean. Exact commands, no prose alternatives. Which interpreter each target uses. 3. Single-test invocation and the failure-triage order (cheapest-first), so agents debug efficiently instead of re-running the slowest suite. 4. CLI reference for management commands (one line each), so agents use named commands instead of inventing shell one-liners. 5. Runtime data layout: the single data root, the path registry, and the rule that no module computes a path from scratch. 6. Environment variables table: name, default, purpose. Complete; an undocumented env var is a trap. 7. Subsystem map: table of every nested doc with one-line scope, so agents know which file to load (and that it exists). 8. Architecture: request pipeline, routing layout, templates and frontend rules, content pipeline, auth, database, background work. One paragraph each with pointers down, not full detail. 9. Hard rules, each marked as such: soft delete, reportability, production-DB protection, confirmation gates, changelog/doc duties. A hard rule states the rule, the mechanism enforcing it, and what fails if violated (usually a named test). 10. Conventions: naming, validation style, response style, ownership checks, date formats, slug/ID handling, role storage. Each convention shows the one correct shape. 11. Testing: tier definitions, directory mirroring rule, fixture stack, required patterns, full-suite gate. Pitfalls live in the nested test doc; the root states the gate. 12. Feature workflow: the ordered step list (understand, data, server, view, safety, agent+docs, document, validate) with the blocking rule: a failed step blocks the rest. 13. CI/CD: what runs on push/PR, merge gate, DTAP stages, deploy then verify. Size guard: if the root passes ~500 lines, detail has leaked in that belongs in a nested file. Split it out. ## 3. Nested subsystem files (deep detail, loaded on touch) One per directory that owns a mechanic (DevPlace: routers, services, database, static/js, static/css, templates, tests). Contents: - Scope line: which paths it covers, in the first line. - The mechanic: helpers, entrypoints, and patterns with exact symbol names (`conditional_update_farm`, `respond()`, `get_users_by_uids`), never paraphrased APIs. - The closed sets: registries, token scales, breakpoint lists, event catalogues. An agent must be able to check membership. - CORRECT/WRONG pairs for the two or three mistakes every newcomer makes (DevPlace tests doc: scoped vs unscoped selectors, waits vs sleeps). Show code, not advice. - Common pitfalls section: the real bugs this area produced, each with cause and fix. Pitfalls are bug reports that pay rent. - Worked examples: one end-to-end change with the file count it touched, so agents calibrate "one feature = N files". - Backwards-compatibility notes where the area promises them (what may never break, what the migration path is). A nested file never repeats the root. It assumes the root was read and only adds what the root deliberately omitted. ## 4. Severity levels: hard rule, convention, guidance Agents follow what they can rank. Mark every statement: - Hard rule: enforced by code, hook, or failing test. Violation breaks the suite or is denied by tooling. Example: every removal is a soft delete; production DB access needs written confirmation plus a token; new user-visible tables must be classified reportable or private with a reason. - Convention: one correct shape, enforced by review. Example: response helpers, date formats, commit message shape, no second implementation of an existing helper. - Guidance: preferred approach with stated tradeoffs. Example: boring technology, static ceilings over autotuning, research before load-bearing decisions. Write the enforcement next to the rule ("fails in `tests/unit/database/moderation.py`", "denied by the pre-tool hook"). A rule without a named enforcer is a wish. ## 5. Keeping the docs updated (the docs are code) - Same-change rule: the doc update ships in the commit that changes the behavior. Docs describing yesterday are worse than missing docs because agents trust them. - Landing rule: new global rule goes to the root, new mechanic or pitfall to the nested file, new user-visible behavior to README plus the user docs site. The feature workflow names this step so it is never skipped. - Measured, not remembered: counts, diagrams, and claims derive from the running app and schema (DevPlace architecture atlas is generated from the imported app object and live schema, and records where docs and code disagree). - No fiction: docs state what the system does today, gaps listed next to the code that will close them. No roadmap prose, no aspirational architecture. - Versioned per `quality_versioning.md` section 4: header comment, history table, bump in the same commit. All three layers count as markdown and follow the scheme. - Deletion duty: removing a feature removes its doc lines in the same commit. Stale sections are found by searching for the removed symbol, not by rereading. ## 6. Anti-patterns: what does NOT belong - Tutorial prose or onboarding narrative. Agent docs are reference, not a course. One example per pattern, then the rule. - Duplicated detail in two layers. If root and nested both explain it, one will rot. Root states the rule and points down. - Unbounded lists ("all endpoints", "all settings") pasted by hand. Point at the registry, the table, or the command that lists them. - Aspirational rules nobody enforces. Each release, delete one rule the suite does not check and no review ever cites. - Secrets, credentials, customer data, or production hostnames. Env var names yes, values never. - Style debates or option-weighing. Decide with an opinion, state the tradeoff in one line, move on. ## 7. Replication checklist for your hosting site 1. Personal base file: safety, proof, craft, ops. Shared across your projects, project file wins on conflict. 2. Root `AGENTS.md`: identity, commands, triage order, CLI, data layout, env table, subsystem map, architecture pointers, hard rules with enforcers, conventions, testing gate, workflow, CI/CD. Under ~500 lines. 3. Nested files per area: `billing/`, `provisioning/`, `support/`, `status/`, plus `tests/` pitfalls and `templates/` partials. Scope line first, symbols exact, CORRECT/WRONG pairs, pitfalls from real bugs. 4. Severity marks on every statement plus the named enforcement (test path, hook name, review gate). 5. Same-change doc updates, landing rule, measured claims, no fiction, version headers on all three layers, deletion duty. 6. Quarterly audit: run the suite, grep each hard rule for its enforcer, delete one unenforced rule, regenerate the architecture counts. ## Doc history | Version | Date | Change | |---------|------|--------| | 1.0.0 | 2026-10-11 | Created from repo research: three-layer CLAUDE.md system, root/nested/personal contents, severity levels, update duties, anti-patterns. |