# Claude Code First

> An evidence-based specification of how to run a software project with Claude Code as
> its primary author. Each rule cites graded findings from five projects.

Version 0.1.0. The rule registry as data: [rules.toml](spec/rules.toml), [rules.json](spec/rules.json). A plain-language guide for people: [index.html](index.html).

## Rules

- [AP-1 A ceiling on what the surface costs](spec/rules/AP-1.md): MUST, level profile
- [AP-2 Names in agent-facing text are checked against the build](spec/rules/AP-2.md): MUST, level profile
- [AP-3 Tested as installed](spec/rules/AP-3.md): MUST, level profile
- [AP-4 Adoption is proved in a consumer](spec/rules/AP-4.md): MUST, level profile
- [AP-5 A capability for agents with a shell may land as a command](spec/rules/AP-5.md): MAY, level profile
- [AP-6 Canonical tasks benchmarked against the generic path](spec/rules/AP-6.md): SHOULD, level profile
- [AW-1 Figures in prose are generated or checked](spec/rules/AW-1.md): MUST, level 3
- [AW-2 Length limits on planning prose are refused at the write](spec/rules/AW-2.md): MUST, level 1
- [AW-3 A declared house style is checked by a gate](spec/rules/AW-3.md): SHOULD, level 3
- [CD-1 One task per commit](spec/rules/CD-1.md): SHOULD, level 1
- [CD-2 A batch is worked one task at a time](spec/rules/CD-2.md): SHOULD, level 1
- [CD-3 Staging by path](spec/rules/CD-3.md): SHOULD, level 1
- [CD-4 The title states the intent](spec/rules/CD-4.md): SHOULD, level 1
- [CD-5 A filing names something wrong](spec/rules/CD-5.md): MUST NOT, level 1
- [CD-6 Attribution is a stated choice](spec/rules/CD-6.md): SHOULD, level 1
- [CS-1 A session claims its task and its paths](spec/rules/CS-1.md): SHOULD, level 2
- [CS-2 Staging stays inside the claim](spec/rules/CS-2.md): SHOULD, level 2
- [CS-3 A commit-time hook stages only what it wrote](spec/rules/CS-3.md): SHOULD, level 2
- [CS-4 A disturbed gate run is not a verdict on the change](spec/rules/CS-4.md): MUST, level 2
- [CS-5 No measurement on a moving tree](spec/rules/CS-5.md): SHOULD NOT, level 3
- [EP-1 One declared copy answers](spec/rules/EP-1.md): MUST, level 2
- [EP-2 Line terminators are declared and held](spec/rules/EP-2.md): MUST, level 2
- [EP-3 A named encoding at a process boundary](spec/rules/EP-3.md): MUST, level 2
- [EP-4 A leading byte-order mark is expected](spec/rules/EP-4.md): SHOULD, level 2
- [EP-5 Encoding is judged on bytes](spec/rules/EP-5.md): MUST NOT, level 2
- [EP-6 No source edited through a heredoc](spec/rules/EP-6.md): SHOULD NOT, level 2
- [GH-1 A broken rule leaves prose](spec/rules/GH-1.md): MUST, level 2
- [GH-2 A gate behind every guard](spec/rules/GH-2.md): MUST, level 2
- [GH-3 Match every route to the change](spec/rules/GH-3.md): SHOULD, level 2
- [GH-4 A guard that cannot run says so](spec/rules/GH-4.md): MUST, level 2
- [GH-5 The agent configuration under a gate](spec/rules/GH-5.md): MUST, level 2
- [GH-6 A stale copy fails a gate](spec/rules/GH-6.md): SHOULD, level 3
- [HR-1 The agent does not close what needs a person](spec/rules/HR-1.md): MUST NOT, level 1
- [HR-2 A person's bar, not the agent's margin](spec/rules/HR-2.md): SHOULD, level 2
- [IS-1 A gated budget on the every-turn file](spec/rules/IS-1.md): MUST, level 1
- [IS-2 The every-turn file is an index](spec/rules/IS-2.md): SHOULD, level 1
- [IS-3 A skill's description names its occasions](spec/rules/IS-3.md): SHOULD, level 1
- [IS-4 A ceiling for what left the every-turn file](spec/rules/IS-4.md): MUST, level 3
- [IS-5 Lists in the instruction surface are checked](spec/rules/IS-5.md): MUST, level 3
- [IS-6 A budget on served tool schemas](spec/rules/IS-6.md): SHOULD, level 3
- [PG-1 Planning files are governed files](spec/rules/PG-1.md): SHOULD, level 1
- [PG-2 The symptom, not the design](spec/rules/PG-2.md): SHOULD, level 1
- [PG-3 A false premise is recorded, not rewritten](spec/rules/PG-3.md): SHOULD, level 1
- [PG-4 What outlives the task leaves its rationale first](spec/rules/PG-4.md): MUST, level 1
- [PG-5 A block closes on its criteria](spec/rules/PG-5.md): MUST NOT, level 1
- [PG-6 Waiting work is deferred with its reason](spec/rules/PG-6.md): SHOULD, level 1
- [PS-1 Name what stands in for a removed prompt](spec/rules/PS-1.md): MUST, level 1
- [PS-2 A forbidden action is refused, not only forbidden](spec/rules/PS-2.md): SHOULD, level 2
- [PS-3 No credential in the working tree](spec/rules/PS-3.md): SHOULD NOT, level 1
- [VG-1 Gates before done](spec/rules/VG-1.md): MUST NOT, level 2
- [VG-2 No gate through a pipe](spec/rules/VG-2.md): MUST NOT, level 2
- [VG-3 Could not run is not a pass](spec/rules/VG-3.md): MUST, level 2
- [VG-4 A roll call of the tests](spec/rules/VG-4.md): SHOULD, level 3
- [VG-5 CI on every push](spec/rules/VG-5.md): MUST, level 2
- [VG-6 A red about something else is a defect](spec/rules/VG-6.md): MUST, level 2
- [VG-7 An expiring exception for a known red](spec/rules/VG-7.md): SHOULD, level 2
- [VG-8 A closing check](spec/rules/VG-8.md): MUST NOT, level 2
- [VG-9 Measure before building](spec/rules/VG-9.md): SHOULD, level 3

## Findings

- [F1 An every-turn instruction file grows until a gate refuses the next addition, and a budget stated in prose did not stop one](spec/findings/F1.md): R3/S3
- [F2 Moving what only some turns need out of the every-turn file into trigger-loaded files cuts the every-turn cost by a measured amount](spec/findings/F2.md): R3/S3
- [F3 Content moved into on-demand files keeps growing where it lands, and stays bounded only under a ceiling of its own](spec/findings/F3.md): R3/S3
- [F4 Served MCP tool schemas were measured as a fixed cost of every session and held by a failing budget, which forced trims or argued raises](spec/findings/F4.md): R3/S4
- [F5 Agent-written planning prose runs past an instruction to be brief, and only a limit refused at write time bounds it](spec/findings/F5.md): R3/S3
- [F6 Model-written published prose carries the em dash at a density two projects counted as a mark of generated text, and a writing rule without a lint did not keep it out](spec/findings/F6.md): R3/S4
- [F7 A count or list typed into prose goes stale in silence when what it describes changes, and stays true only when it is generated or checked](spec/findings/F7.md): R4/S4
- [F8 Where the consuming agent had a shell, Shio kept new capabilities off its MCP tool list and on its CLI, because the list is paid before any call](spec/findings/F8.md): R2/S2
- [F100 A hook that refuses hand edits of planning files covers only the calls it matches, and widening it cost prompts](spec/findings/F100.md): R1/S2
- [F101 Roadmap lines written under a prose one-sentence rule outgrew it, and a limit applied at the write held them](spec/findings/F101.md): R1/S3
- [F102 Tasks an agent files while working include ones that describe nothing wrong, and filing needed a bar](spec/findings/F102.md): R3/S3
- [F103 A design or diagnosis written before implementation was overturned by implementation, while the symptom the task stated held](spec/findings/F103.md): R3/S3
- [F104 A task recorded as shipped was found not to hold, because the ledger records the shipping session's own claim](spec/findings/F104.md): R3/S3
- [F105 Work that needs a person's judgement or hardware the machine lacks cannot be closed by the agent, and a bar the agent set itself blocked work](spec/findings/F105.md): R3/S2
- [F106 Shipping deletes a task's rationale, and what only the rationale held was lost with it](spec/findings/F106.md): R2/S3
- [F200 A commit tool that stages everything commits whatever else the working tree holds, and an ignore rule closes only the pattern it names](spec/findings/F200.md): R2/S2
- [F201 Agent sessions sharing one checkout commit each other's work unless each commit stages only its own paths](spec/findings/F201.md): R2/S2
- [F202 A gate run in a checkout that something else is writing reports on the moving tree, not on the change](spec/findings/F202.md): R3/S3
- [F203 A written one-task-one-commit rule did not stop commits that ship several tasks, though counted from the ledgers they are a small share](spec/findings/F203.md): R3/S3
- [F204 A commit message generated from the staged diff by another model misdescribes the change, most visibly on documentation commits](spec/findings/F204.md): R2/S2
- [F205 Git metadata does not show which commits an agent composed: the co-author trailer is on a few percent of commits, unevenly](spec/findings/F205.md): R2/S3
- [F206 Commit subjects carry a Conventional Commits type and the task id, which joins the history to the ledger](spec/findings/F206.md): R2/S3
- [F300 A rule stated only in prose, with no check that reads it, was found broken by the repository that wrote it](spec/findings/F300.md): R3/S3
- [F301 A guard hook refuses only the calls that reach it, and its recorded gaps failed silently](spec/findings/F301.md): R3/S3
- [F302 A gate reported a pass over work that did not run or a check that looked at the wrong thing](spec/findings/F302.md): R3/S3
- [F303 A gate that did not run on every push let red suites and drift reach the main branch unremarked](spec/findings/F303.md): R3/S3
- [F304 Gates went red for reasons outside the change, and a red nobody could act on was ignored](spec/findings/F304.md): R3/S3
- [F305 Tasks closed without a check covering the change as committed, and the gap surfaced later as a new task or a red for the next session](spec/findings/F305.md): R3/S3
- [F306 The agent configuration broke silently, and the remedy was to put it under the project's own gate](spec/findings/F306.md): R3/S3
- [F400 Plugin hooks did not reach web sessions, so the guard was carried by a launcher committed to the repository](spec/findings/F400.md): R1/S2
- [F401 A committed settings file lost permission entries during a session, and the loss reached a commit about something else](spec/findings/F401.md): R2/S2
- [F402 Permission prompts were treated as a cost to remove, and a hook that refuses named writes stood in for them](spec/findings/F402.md): R3/S2
- [F403 Where several copies of a shared tool could answer, sessions ran a stale or unintended copy without noticing](spec/findings/F403.md): R3/S3
- [F404 Text crossing a Windows shell, codec or line-ending boundary changed bytes silently, and the remedies were byte-level checks](spec/findings/F404.md): R4/S3
- [F405 An encoding defect was first blamed on the wrong component, and relocating it reversed the fix already chosen](spec/findings/F405.md): R3/S2
- [F406 Projects that ship a surface to other agents put a counted ceiling on what it costs the consuming agent, held by a test](spec/findings/F406.md): R3/S4
- [F407 A surface shipped to agents looked complete from its own repository while an installing consumer met it broken or missing](spec/findings/F407.md): R3/S2
- [F408 Tools built for agents were proved in named consumer repositories, by counted changes there, and the consumer found what the producer's tests did not](spec/findings/F408.md): R3/S3
- [F409 Measured on the same canonical tasks, an agent path shaped to the task cost a fraction of the tokens of the generic interface, and the gap came from fewer reads rather than from the transport](spec/findings/F409.md): R3/S4
- [F410 Measured on one authoring task, editing projected files cost an agent less than writing through the API, and the saving was in what the agent writes, not in what it reads](spec/findings/F410.md): R1/S3