Claude Code First, specification version 0.1.0. The plain-language guide

Claude Code First

Specification version 0.1.0.

Rules

Rule	Keyword	Level	Statement
AP-1	MUST	profile	Each surface a product serves to agents, its tool schemas, skill descriptions and bodies, and command responses, MUST carry a token ceiling that a gate enforces, raised only with its reason written beside the number or in the commit that raises it.
AP-2	MUST	profile	Every command, tool or configuration key that a product's agent-facing text names MUST be checked by a gate against the product's own catalogue of names.
AP-3	MUST	profile	A product's agent surface MUST be exercised from its published artefact, loaded the way an installing consumer loads it, and not only from the source checkout.
AP-4	MUST	profile	A claim that a consumer has adopted the product MUST be proved by a counted change in a named consumer repository, such as the lines of its own replacement deleted or its checks passing on the product.
AP-5	MAY	profile	Where the agents that consume a capability have a shell, a product MAY offer it as a command-line verb rather than as an MCP tool, keeping MCP tools for clients without a shell and for input that is a structured document a served schema validates.
AP-6	SHOULD	profile	A product whose surface agents consume SHOULD benchmark named canonical tasks through that surface and through the generic interface the same tasks would otherwise use, with a gate that fails when a task's calls or tokens pass their ceiling or its ratio to the generic path falls below its floor.
AW-1	MUST	3	A count, version or enumeration that prose states about the present state of the project MUST be generated from its source or checked against that source by a gate.
AW-2	MUST	1	Prose an agent writes into a planning file MUST be held to a length limit that the write path refuses, not only to an instruction to be brief.
AW-3	SHOULD	3	A rule on the style of prose that a project declares SHOULD be checked by a gate that reads the prose it governs.
CD-1	SHOULD	1	A commit that ships work SHOULD ship one task, and carry that task's code, its tests and its ledger entry together.
CD-2	SHOULD	1	When a session is asked to work several tasks, it SHOULD commit each task, after its gate has passed on the tree that commit holds, before it starts the next.
CD-3	SHOULD	1	A commit SHOULD stage its own paths by name, unless a single session owns the checkout and the tree was checked for other changes first.
CD-4	SHOULD	1	The agent that did the work SHOULD write the commit's title, stating the intent of the change and the id of the task it ships, rather than leave the title to a model that sees only the staged diff.
CD-5	MUST NOT	1	A session MUST NOT file a task that names nothing wrong or missing.
CD-6	SHOULD	1	A project SHOULD state, where its agent reads its commit rules, whether commits carry attribution to the agent.
CS-1	SHOULD	2	A session working in a checkout that other sessions share SHOULD hold a claim naming its task and the paths its commit will own.
CS-2	SHOULD	2	In a checkout that other sessions share, nothing that stages for a commit, whether the agent, a hook or a stage line a tool prints, SHOULD stage a path outside the session's claim.
CS-3	SHOULD	2	A hook that writes into a file while a commit is made SHOULD compute its change against the committed file and stage only that change.
CS-4	MUST	2	A gate whose run was disturbed by other work in the checkout, whether another session's edits or another run of the same gate, MUST report the verdict could not run, not passed or failed.
CS-5	SHOULD NOT	3	A count or timing that a rule, a decision or a finding will cite SHOULD NOT be taken while another session has uncommitted work in the checkout.
EP-1	MUST	2	Where more than one copy of a shared tool could answer a session, the project MUST declare in committed files which copy answers and at which version.
EP-2	MUST	2	A repository's line terminators MUST be declared in a committed `.gitattributes` file and held by a gate that fails on a file that departs from them.
EP-3	MUST	2	A program in the project that reads text from another process MUST decode it with a named encoding rather than the locale's default.
EP-4	SHOULD	2	A tool that reads text piped to it on Windows SHOULD strip or refuse a leading byte-order mark rather than keep it as content.
EP-5	MUST NOT	2	An encoding defect MUST NOT be filed or fixed until its bytes have been checked at each boundary the text crossed, the agent's own tools included.
EP-6	SHOULD NOT	2	An agent SHOULD NOT write or edit source files through a shell heredoc.
GH-1	MUST	2	A rule that the project has seen broken MUST be enforced by a guard or a gate that reads what the rule governs, not left in prose alone.
GH-2	MUST	2	Every rule a guard enforces MUST also be checked by a gate that runs in CI.
GH-3	SHOULD	2	A guard SHOULD be matched on every tool through which the agent can make the change it refuses, the shell included.
GH-4	MUST	2	A guard that is wired but cannot run, such as one whose build or engine is missing, MUST say in the session that it is not guarding.
GH-5	MUST	2	The committed agent configuration, including the wiring of every guard, MUST be checked by a gate that fails when an entry is lost.
GH-6	SHOULD	3	Where a session can reach more than one copy of a tool or skill that a guard or a gate depends on, a gate SHOULD fail when the copy that answers is stale against its source or is not the intended one.
HR-1	MUST NOT	1	An agent MUST NOT record as shipped a task whose acceptance needs a person's judgement or hardware the machine lacks, until the person or the hardware has answered.
HR-2	SHOULD	2	Where a bar that no measurement fixes decides acceptance, the agent SHOULD apply a bar a person set, stored where the check reads it, and not a margin of its own choosing.
IS-1	MUST	1	Where a project has an every-turn file, it MUST carry a size budget that a gate enforces.
IS-2	SHOULD	1	Where a project has an every-turn file, it SHOULD hold only what a turn touching no specific area needs, and point to trigger-loaded skill bodies or files read on demand for the rest.
IS-3	SHOULD	1	A trigger-loaded skill SHOULD have a description that names the occasions and words on which it is to load.
IS-4	MUST	3	Every trigger-loaded skill body, and every file the every-turn file or a skill sends the agent to read, MUST carry a size ceiling of its own that a gate enforces.
IS-5	MUST	3	A list of commands, paths, identifiers or configuration keys that the every-turn file or a trigger-loaded skill gives the agent MUST be generated from its source or checked against that source by a gate.
IS-6	SHOULD	3	A project that serves MCP tools to its own agent SHOULD hold the serialized size of their schemas under a ceiling that a gate enforces.
PG-1	SHOULD	1	Each planning file an agent writes SHOULD be a governed file.
PG-2	SHOULD	1	A task line SHOULD state the observed symptom and leave the design to its rationale section.
PG-3	SHOULD	1	When a task's premise or design is found false, the finding SHOULD be recorded, by retiring the task with its reason or in its ledger entry, rather than rewritten in place.
PG-4	MUST	1	Where shipping deletes a rationale section, what in it outlives the task MUST first be moved into the code it explains, the ledger entry or a decision record.
PG-5	MUST NOT	1	A block MUST NOT be declared closed because nothing under it is open.
PG-6	SHOULD	1	A task that waits on a person's judgement or on hardware the machine lacks SHOULD be recorded as a deferral with its reason, not left open.
PS-1	MUST	1	A project that removes permission prompts, by a committed allow rule or by a local bypass, MUST name in its committed files the guard or gate that stands in for them.
PS-2	SHOULD	2	An action a project forbids its agent to take SHOULD be refused by a committed deny or ask rule or by a guard, and not stated only in prose.
PS-3	SHOULD NOT	1	A credential SHOULD NOT be stored in a repository's working tree, ignored or not.
VG-1	MUST NOT	2	Work MUST NOT be called done until every gate that covers it has run and passed on the change as it will be committed, unless a red-suite exception covers the red.
VG-2	MUST NOT	2	A gate MUST NOT be run, in any file that tells an agent how to run it, through a pipe or filter that can replace its exit status or discard its output.
VG-3	MUST	2	A gate MUST report a check that did not execute with the third verdict, could not run, and never count it as passed.
VG-4	SHOULD	3	A test gate SHOULD compare the tests its runner discovered with the tests that reported a result, and report any difference as could not run.
VG-5	MUST	2	A gate that decides whether work is done MUST run in CI on every push to the branches work lands on.
VG-6	MUST	2	A gate that goes red for a cause outside the change MUST be filed as a defect of the gate and fixed, by narrowing what it concludes or where it runs, rather than rerun until it passes.
VG-7	SHOULD	2	A gate that is to stay red while other work continues SHOULD be covered by a red-suite exception that a check turns red once it expires.
VG-8	MUST NOT	2	A task that changes behaviour MUST NOT be recorded as shipped until a check that a gate runs covers that behaviour as committed.
VG-9	SHOULD	3	A change made to improve a measurable quantity SHOULD be preceded by a measurement of that quantity, and kept only if a second measurement shows the gain.