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>
72 lines
4.2 KiB
Markdown
72 lines
4.2 KiB
Markdown
# 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.md` is 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
|
||
|
||
1. Batch tool calls — one Bash call per phase, not per command.
|
||
2. 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.
|
||
3. Line ceiling on `CLAUDE.md` in `budgets.env`, gated like any other budget.
|
||
4. Targeted reads — `grep -n` plus `Read offset/limit`; whole-file reads only for the doc that
|
||
owns a rule being asserted.
|
||
5. Evidence proportional to risk — one case for a behaviour change, a full matrix only for a gate
|
||
or a security boundary.
|
||
6. Never re-read after `Edit`; run `verify.sh` once 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.
|