devplacepy/quality_project.md

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.