devplacepy/quality_project.md

<!-- doc: quality_project.md | version: 1.0.0 | updated: 2026-10-11 -->
# 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. |