Token discipline

Token Discipline

Most token waste in agent sessions is input-side: whole-file reads to find one function, re-reads of files you just edited, giant tool outputs kept verbatim in context. Output verbosity is real but smaller. These rules attack both, ordered by leverage. Follow them as hard rules, not suggestions — each one states what to do instead, so correctness never drops.

Rule 1 — Search before you read

Never open a whole file to find something.

• Locate first with a scoped search (grep for the symbol, glob for the filename), then read only the matching region with offset+limit.
• Reading more than ~200 lines requires a reason you could state in one sentence ("I am editing this whole file", "structure matters here"). No reason → narrow the read.
• For a codebase question ("where is X computed?"), the answer path is: grep → read the hit ±30 lines → done. Not: read 5 candidate files end to end.

Rule 2 — Read the slice, not the file

• Use offset/limit (or sed -n 'A,Bp'-style ranges) for anything long.
• Huge JSON/CSV/logs: never read raw. Query them — python/jq for counts, keys, filters — and bring only the result into context. A 16,000-record JSON is a database, not a document.
• Long command output you only need parts of: pipe through head, tail, grep -c, wc -l.

Rule 3 — Batch independent tool calls

When two or more tool calls don't depend on each other's results, issue them in one message. Every extra assistant turn re-pays thinking and narration tokens between calls.

• Reading 3 known files → one message, three reads.
• A grep plus an unrelated ls plus a git status → one message.
• Only serialize when a call's input needs a previous call's output.

Rule 4 — Trust state you already have

• After a successful Edit/Write, do not re-read the file to "verify" — the tool errors when it fails. Re-read only after an external process (formatter, codegen, another agent) may have changed it.
• Never re-run a search or re-open a file whose relevant content is already in context. Scroll up (mentally) before reaching for the same tool twice.
• Don't re-derive facts you established earlier in the session; cite your own earlier finding.

Rule 5 — Don't quote code back

• Reference locations as path/file.ts:42 instead of pasting the code you just read.
• Paste a snippet only when the user must see the exact text to decide something.
• In edits, keep old_string context minimal-but-unique; never rewrite a whole file to change five lines.

Rule 6 — Summarize, then drop

After any long tool output (test run, build log, big query result), immediately extract the 2–5 facts you actually need into your working notes or reply — then never request that output again. If a session will be long, keep a running notes.md (decisions, paths, open items) so recovery after compaction costs one small read, not a re-exploration.

Rule 7 — Delegate heavy exploration

Broad sweeps ("find everywhere X is handled", "audit all templates") belong in a subagent that reads widely and returns conclusions only. The heavy reads then live and die in the subagent's context instead of polluting yours for the rest of the session. Mechanical bulk work (mass renames, per-file transforms) goes to the cheapest model tier that can do it.

Rule 8 — Keep the context cache-friendly

For sessions and agent harnesses (matters for authors of CLAUDE.md/system prompts too):

• Stable content first, volatile content last. Don't edit CLAUDE.md, skill files, or other session-prefix material mid-session unless asked — every prefix change invalidates the prompt cache for all following turns.
• Prefer appending new information over rewriting earlier artifacts.
• Long idle gaps (>5 min between turns) lose the cache; batch your questions when cost matters.

Rule 9 — Output discipline

• Answer first, evidence second. No preamble ("Great question!"), no restating the plan you already executed, no summarizing the diff you just applied line by line.
• Compact final messages: what changed, where, what's verified, what's left. Bullet the facts; skip the essay.
• Don't re-list file contents, test output, or earlier results the user already saw.

Self-audit checkpoint

When context feels heavy (long session, or before any big re-read), stop and ask:

1. Am I about to re-read something I've already seen? → use Rule 4.
2. Can a search + slice replace this read? → Rules 1–2.
3. Should this exploration be a subagent? → Rule 7. Write a checkpoint note (Rule 6) before continuing.

Always-on install (minimal tax)

This file loads on demand. If you want the rules enforced every turn, paste the distilled version below into your project's CLAUDE.md — it costs roughly 60 tokens per request, which a single avoided whole-file read repays many times over:

Token discipline: grep/glob before reading; read slices (offset+limit), never whole files to
find things; query big JSON/logs with python/jq, don't open them; batch independent tool calls
in one message; don't re-read files after your own successful edits; reference code as
file:line, don't paste it; after long outputs, note the 2-5 facts and move on; delegate broad
sweeps to subagents; terse final answers — no preamble, no re-quoting.

Do not

• Sacrifice correctness for tokens: if a real bug hunt needs a full file, read it — with the one-sentence reason (Rule 1). Skipping required verification is not savings, it's rework.
• Compress user-facing explanations into cryptic fragments; terse ≠ unreadable.
• Apply Rule 4 across agent boundaries — another agent's edits are external changes.
• Trigger for questions about API pricing tables or billing.