A constitution,
and a way to amend it.
Rules that cannot change are brittle, and rules anyone can change are decoration. This page explains what the constitution binds, and the path a change has to walk before it takes effect.
The twelve articles
CLAUDE.md lands in your repository root at install, and Claude Code reads it at the start of every session, where it binds behaviour for the whole of that session. It runs to 12 Articles.
Which document wins when two disagree, and how an amendment travels.
Decisions stay in the main session. Subagents run recipes that are already decided.
What Claude reads and tells you at the start of every session.
The eleven phases, their order, and the three gates only you can pass.
How the harness loops through phases, and the four ways it stops.
The rules every code change obeys: no stubs, no mocks of your own code, current docs.
What Claude may do with git, which branches are protected, and what is refused outright.
The hook table. Every guard, its event, and the Article it enforces.
How project facts survive across sessions, and why a cited fact is re-checked first.
Several sessions working one body of work, and how a fork reaches a human.
Space reserved for your own rules, which bind alongside the rest.
Which skills the baseline owns, and how a changed one is detected.
Eleven of them ship fixed, while Article XI is yours and is held open for rules applying to your project alone. Anything you put there binds with the same force as the rest, on one condition: it must not contradict the other Articles.
Rules that bind every change
Article VI is the one you will feel most often, because it applies to every line Claude writes.
The first rule is that a declared function is a finished function. If the body is unknown then the function does not get declared at all, and the spec is written first. Alongside it comes a ban on TODO, FIXME, HACK and XXX in source, and on leaving code commented out; deleted code is deleted.
The second rule is about mocks, and it is stricter than most teams write down. Claude may never mock your own modules, your database, or a gRPC channel. Three targets are allowed: a third-party HTTP API that cannot run on your machine, the system clock, and the operating system's randomness. Each one carries a MOCK comment saying why.
Behind that sits an opinion worth stating plainly. An internal module which is hard to test is usually telling you something about the design, and mocking it will hide the message, so the rule points at the design rather than at the test.
YAGNI is the third, and it cuts one way only. It will stop params, flags and abstractions added for a future nobody has asked for, but it carries no authority at all over scope your approved spec has already committed to. A spec row that defers committed work must say why and give a real reason (a dependency, a risk, a cost, or your own instruction), because citing YAGNI there is a blocker at gate A.
The last one is small and saves real time. For any third-party library, Claude must check the current documentation before writing code against it, since recalling an API from training data is how you end up with a signature that was true two versions ago.
The amendment path
docs/init/seed.md is the specification the whole overlay is built from. The constitution sits beneath it, and the hooks and skills sit beneath both, which is why a change has to enter at the top.
docs/init/seed.md the genesis specification ↓ binds CLAUDE.md the in-session constitution ↓ binds .claude/hooks · skills · config the actuators
Amend the seed, then the constitution, then the code which carries it out. Going the other way round is how a rule ends up written in three places and true in only one of them.
Turning a hook off follows the same path with a second lock on it: your explicit approval and a matching seed amendment, both of them, every time. A guard that a session could quietly disable would be a suggestion with extra steps.
When the constitution and the code disagree, the constitution wins and the code is what gets corrected. If instead the seed and the constitution disagree, Claude stops and raises it, because that case is drift: someone edited one of two documents that were supposed to move together.
The size budget
The constitution has a hard ceiling of 40,000 characters, and audit-baseline fails the build above it.
The reason is context. Because CLAUDE.md is loaded into every session, every character in it competes with your codebase for room, and a constitution that grows without limit will slowly crowd out the code it governs.
So the file carries binding rules and nothing else. Amendment history moves next door into .claude/CONSTITUTION.md, along with the account of how each hook enforces its Article and the long reference tables, and Claude opens that file when it needs them. The cap binds the shipped template as well, since the two are byte for byte the same file.
Working under a budget shapes the writing. Rules get tightened where they would otherwise simply be appended to, and a rule that cannot earn its characters was generally carrying nothing.
Skill ownership
If you install into a repository that already has skills of its own, a question shows up at once: which of them does the baseline get to police? Article XII answers it.
A skill belongs to the baseline when its SKILL.md frontmatter says owner: baseline, and everything else on disk is yours. Silence is the default, so a project carrying its own skills installs without you touching a single file to declare them.
For the skills it does own, the shipped manifest records a sha256 hash of every file, and the audit re-derives those hashes from disk on each run. A changed file, or a listed skill that has gone missing, is a hard failure with no opt-out available. That is deliberate, because drift you can silence is drift you will eventually stop noticing.
Your own skills sit outside all of it, left out of the count, the name check and the hash check alike. Maintaining them stays your job, which is the honest division of the work.
The economy of questions
Every question Claude asks costs you attention, and attention is the scarce resource. So the constitution puts a closed list on what may be asked.
Anything that widens what a gate covers: extra paths at commit, a bigger write surface, one more skipped phase.
History rewrites, deletes outside the write set, publishing outward, migrations with no way back.
Changing a default the constitution or project.json declares.
Two acceptance criteria, or an instruction and a memory, that cannot both hold.
Everything outside those four is an ordinary engineering fork. Claude decides it in the main session and writes it into the spec's ## Decisions section along with the reasoning, and you see all of them at gate A before approving anything. The call is still yours, but it arrives as a batch you can read rather than an interruption you have to field.
If you leave a question unanswered it takes the recommended option, records that it did so, and surfaces the assumption at the next consent gate, which is how an unattended run keeps moving. The gates themselves work differently: they block and wait, and no timeout will ever satisfy one.