50 lines
2.4 KiB
Markdown
50 lines
2.4 KiB
Markdown
# Token conservation
|
||
|
||
Status: parked
|
||
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.
|
||
|
||
## 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.
|