claude
7f804b84e7
docs/CLAUDE.md defined four tiers and docs/capabilities/ and docs/architecture/ were neither of them. Both are now declared as generated: rebuilt from a source, never corrected in place. A wrong row in either is a bug in the generator or in one of its hand-written inputs, and editing the output makes the next rebuild silently undo the fix. The eval index gains the 2026-08-19 CPT+SFT measurement and the 2026-08-26 baseline, and marks the 2026-08-13 capability audit superseded. The 2026-08-19 file lands with them: it is the direct evidence that the deployed maven-instruct-b2 routes better than Qwen3-1.7B and cannot hold a Russian sentence, which is the first item on the gaps.md priority list. Its header records Vikunja as returning 503. That reading was wrong and the 2026-08-26 baseline says so, but a dated eval is not edited after the day. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.5 KiB
2.5 KiB
docs/
Everything an agent needs that is not a rule and not code. CLAUDE.md at the
root carries the rules and points here. Nothing here restates a rule.
The tier is the path, so staleness is visible from the filename.
| path | holds | lifetime |
|---|---|---|
docs/*.md |
living. One file per subsystem: the reasoning, corrected in place. Each carries Last verified: <date> @ <sha>. |
until it is wrong |
docs/evals/ |
dated measurements, one file per measurement. Never edited after the day. A newer number is a new file. Indexed in docs/evals/CLAUDE.md, which marks each one live or superseded. |
forever |
docs/caveats/ |
known limits, one entry per limit, each with a task id and a revisit trigger. Indexed in docs/caveats/CLAUDE.md. |
until fixed, then deleted |
docs/plans/ |
the plan for one piece of work, frozen once it starts. Indexed in docs/plans/CLAUDE.md. |
until the work lands |
docs/capabilities/ |
generated. The capability ledger and its probe harness, regenerated from docs/spec.md plus a named eval. Never hand-edited, except domains.yaml, probes_field.json and the scripts, which are its sources. Indexed in docs/capabilities/README.md. |
until the spec or the measurement moves |
docs/architecture/ |
generated. The architecture observation and its evidence pack, rebuilt from source by the scripts beside it. Indexed in docs/architecture/README.md. |
until the shape changes |
docs/archive/ |
dead. Read by nobody by default. | forever |
Rules for this directory
- One fact, one home. A measurement is cited from a living doc, never copied into it. The two drift the moment they are both edited.
- A living doc is corrected in place and its
Last verifiedline moves with the correction. Do not append a changelog to it. - A number in prose with no
docs/evals/file behind it is an opinion. - Fixing something deletes its caveat. It does not edit the eval that found it.
- A generated tier is rebuilt, never corrected. A wrong row in
docs/capabilities/ordocs/architecture/is a bug in the generator or in one of its hand-written inputs. Editing the output makes the next rebuild silently undo the fix.
Where a subsystem's reasoning lives
routing.md, language.md, world.md, offload.md, deployment.md,
ecosystem.md, workflow.md, design.md, rearchitecture.md,
determinism.md, protocol.md, handler-wiring.md, operations.md, qa.md.
The root CLAUDE.md says which one to read before touching what.