bdeshiandClaude Opus 5
ec6e9838f0
docs/content-model.md opens with "Engine specification". It is also where the rule lives that a leading underscore makes a file unaddressable — and the human who owns this site did not know that rule, because nothing in this repository is addressed to an author. Twelve documents named docs/ while being exclusively about building the parser is a signpost pointing at the wrong room. Naming the directory for its audience makes the gap visible instead of hiding it. docs/ is now reserved and deliberately absent: an empty docs/ is an honest statement that end-user documentation does not exist, where docs/ full of parser specs was a claim that it did. HARNESS.md stays at the root. Root holds the three entry points — README.md for a human, CLAUDE.md for an agent, HARNESS.md for whoever maintains the machine — and harness/README.md is the map of the directory, so moving the guide inside would have collided with it for nothing. Mechanical and wide: 100 path references across 24 files. Every verify.sh gate that names a doc by path, the directory lists the dangling-path and ADR-number gates scan, surface.sh's output target, the Makefile, CLAUDE.md's read order, the skill, four commands, and two Go package comments. A first pass with a shell loop silently edited only four files and the rest still said docs/; the fix was to write the file list out and check the remaining count was zero rather than trust the loop's exit status. No rule, threshold, gate or obligation moved — this is a rename, and the gates demonstrated it twice: they stayed green on the new paths, and the ADR-number gate caught ADR-0082 before the entry existed. Deferred, both on the human's call: the end-user documentation site itself, which wants its own decision about where it lives and whether its claims are gated; and moving examples/ under docs/, since demo-site is a live site root that verify.sh, the coverage test and make demo all point at, and moving it would couple a rename to a design nobody has made. 31 files, +146/-106. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
4.2 KiB
Token conservation
Status: adopted → harness/context-economy.md + ADR-0053 (2026-08-01). All six mechanisms landed, plus
the compressed-form, machine-discovery and quiet-output disciplines the human added. The open question
below is the only part still undecided; it is also recorded in state.md "Open questions".
Raised: 2026-07-28
Why it came up
Development pace is limited by session and usage limits, not by typing speed. Cutting token cost per feature buys more features per session. The goal is explicitly conserve tokens without lowering output quality — not "be terse and worse".
What is already established
Do not re-derive these.
- Turn count dominates, not file size. The whole context is re-sent on every tool call, so a six-call verification sequence costs roughly 6× the context. Batching is the biggest lever.
CLAUDE.mdis the most expensive file per byte in the repo — it is re-sent every turn.- Agent prose is a large, entirely self-inflicted cost. The target is density, not brevity: same information, fewer words. Length follows content; padding, restatement, hedging and rhetorical closers do not.
- Two accepted rules cost tokens on purpose and are worth keeping: hard rule 8 (docs ship with the change) and the topic-ownership read floor. The ownership table is what keeps the floor cheap — it sends you to one doc instead of a grep sweep.
The six mechanisms, ranked by saving
- Batch tool calls — one Bash call per phase, not per command.
- Prose density in reports and replies — cut restatement and flourish, keep every finding, number and caveat. Biggest win, costs nothing. Not a length cap: truncating information is not a saving.
- Line ceiling on
CLAUDE.mdinbudgets.env, gated like any other budget. - Targeted reads —
grep -nplusRead offset/limit; whole-file reads only for the doc that owns a rule being asserted. - Evidence proportional to risk — one case for a behaviour change, a full matrix only for a gate or a security boundary.
- Never re-read after
Edit; runverify.shonce per feature, at the end.
Open question — needs the human
Subagents for fan-out search. Dispatching "find every place X appears" to a subagent keeps its file dumps out of the main context: you pay for the conclusion, not the search. A real multiplier on exploration-heavy work. Currently disallowed unless explicitly requested, so it is a policy call, not a judgment call. Deferred again on 2026-08-01, with the case laid out:
For. The criterion is read volume ÷ conclusion length. /audit, /refresh-docs and /invariants
all read thousands of lines to produce a verdict of twenty, so their ratio is ~100:1 and the reading
is pure waste in the main window. Several passes could run at once. A subagent that goes down a wrong
path costs nothing here, which makes speculative exploration cheap for the first time.
Against. Four real costs. (1) The subagent reads under its own judgment, not the read-order
discipline in CLAUDE.md §1 — the thing that keeps this project's read set small is exactly what a
delegated agent is worst at honouring. (2) A verdict without its evidence cannot be audited: "no
abstraction has earned extraction" is only trustworthy if the counters were read correctly, and the
report is all that comes back. (3) Findings arrive as prose to be re-verified, and re-verification of
a wrong report costs more than the original read would have. (4) Total tokens go up, not down — the
saving is entirely in this window, which matters for session length and not at all for usage limits.
Where it is clearly right. Read-only sweeps whose output is a list of locations, where being wrong is visible immediately: "every doc mentioning the old form after a rename", "which files import X".
Where it is clearly wrong. Anything that decides something — a verdict, an earn-it call, an invariant, whether a warning is a defect. Those need the evidence in the window where the decision gets made.
Cheapest next step
Apply 1–6 as one batched change: CLAUDE.md (efficiency rule), SKILL.md (report cap, evidence
proportionality), budgets.env + verify.sh (CLAUDE.md line ceiling). Trips the HARNESS.md
coupling gate by design. Estimated one feature-sized change.