# Instruction-File Style

The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an agent definition, skill prose. Prose style only: frontmatter is metadata, not style. Docs-tree documents follow the skill's templates and [`style-guide.md`](style-guide.md) instead.

## The test for every line

An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and unscoped rules load on **every turn of every session** — the most expensive prose in a repo per word; a `paths:`-scoped rule loads on those same terms from its first matching file read on; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.

**Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.

## Coherence

A rewrite is not only a trim — read the file as one artifact and fix what disagrees or is missing:

- **Two statements of one fact agree, or become one.** A defaults block vs. the worked example beside it, a table row vs. a bullet — reconcile against the code the rule governs and keep one canonical statement; a silent disagreement is worse than either version alone, because each reader picks a different one.
- **Every cross-reference resolves** — the cited `§`, sibling file, or command exists and still says what the citation claims. Section numbers are a public surface other files cite: append, never reshuffle.
- **The body delivers what the scope line promises, and nothing it disclaims.** A topic named then left to guesswork is a hole; material the scope routes elsewhere is a leak.
- **Report what you cannot fix.** A defect outside the file — a stale sibling, an unshipped copy — is named in the handback, never fixed by widening the edit.

## Two genres, one style

Policy files (`CLAUDE.md`, rules) are declarative — assertion bullets and tables, no second person. Agent and skill bodies are procedures — second person, numbered steps, one observable action per step. The genre sets the shape; everything below applies to both.

## Routing

- **Link, don't copy — one canonical source per topic.** `CLAUDE.md` is a **router, not a manual**: per workflow, when to enter, what to dispatch, where the output lands — mechanics live in the agent or skill file, which loads only when it runs.
- **A rule never references a sibling rule.** Rules co-load, so pointing at one from another routes a reader to text already in front of them — noise that also drifts the moment either file moves. State what the rule owns, self-contained; the only outward links a rule carries are to skills and agents, whose bodies do *not* co-load. Routing downward from `CLAUDE.md` to a rule is fine — that is the router doing its job.
- **Cut generic engineering advice.** Agents already know how to code; keep only what is true of *this* stack and not derivable by looking at it.
- **Keep load-bearing rules even when project-specific.** Genericizing is for reference material, not guardrails — deleting a hard rule removes a constraint the agent will otherwise violate.

## Voice

- **Assertion — reason, in one breath.** "**Never name a deployed-value file `.env`** — the dev server auto-loads a root `.env` as local vars, so a prod-valued `.env` silently becomes the local environment." The reason is the rule's armor: an agent that knows the failure mode won't "improve" the rule away; a bare imperative invites second-guessing.
- **A reason appears once — at the rule it armors.** "One breath" caps a reason's length, not its multiplicity: the same rationale in the scope line, a section intro, and a bullet is the restatement trimming exists to remove. A convention whose only reason is consistency states that once, in the scope line.
- **One example, carrying every point it can — never a second example of the same point.** An example calibrates a rule an agent would otherwise read loosely; a second one demonstrating the same rule is restatement in costume. Prefer one worked case rich enough for several rules to cite over a fresh citation per bullet.
- **Grade the bindingness with words.** Bold **never / always / only / must** for hard constraints; "prefer", "default", "acceptable when" for defaults — and every escape hatch states its trigger and its price.
- **Absolute present tense.** Describe the current design as if it had always been the plan — no "previously", no version narration, no stale-reference tripwires, no progress markers. When something moves or is removed, fix every reference and state only the present fact; the journey lives in git history and `docs/history/`. (Docs-tree tense rules: [`style-guide.md`](style-guide.md) § The Two Natures.)

## Negative space

- **Name the rejected alternative.** A package table carries a **Don't use** column because an agent that knows the popular alternative reaches for it unless the file closes the door by name.
- **Pre-empt the workaround.** Where a failure predictably triggers improvisation, spell out the forbidden moves and the exact stop-and-report. The umbrella: **no silent fallback** — fail loudly rather than route around.

## Material & mechanics

- **Tables for enumerable facts, prose for judgment.** One row per item kills the urge to explain; anything that needs a *because* lives in prose around the table, never inside a cell.
- **No ASCII diagrams.** A box-and-arrow diagram costs many tokens for what a sentence or a small table carries.
- Inline-code every identifier, filename, command, and config key.
- ❌ / ✅ only inside banned/blessed lists, not as general decoration.
- `>` blockquotes set off interruptions — cross-pointers, callouts, agent guards — not the main line.