The Constitution Pattern

Somewhere in most engineering orgs running more than a couple of AI-assisted specs in parallel, the same small argument keeps breaking out in review. One spec says a failed payment call should raise immediately and halt the workflow. Another, written the same week by a different engineer working with a different session, has the AI retry silently three times before giving up quietly. Neither author is wrong about error handling in the abstract — ask either of them in a hallway and they will describe roughly the same philosophy. The specs disagree anyway, because nothing forced either session to inherit a shared answer. The rule existed only in each engineer’s head, restated imperfectly this time, and not at all the time before.

This is a small failure, and a common one, and it rarely gets diagnosed correctly. Teams tend to read it as a specification-quality problem — someone should have been more careful — and respond by padding the next prompt or the next spec template with more detail. That treats the symptom. The actual defect is structural: two units of work that both depend on the same standing decision had no standing place to find it. The decision had to be re-derived, or re-remembered, independently, by whichever engineer or session happened to be writing that day.

The rule nobody wrote down

It is tempting to treat this as a coordination problem solvable by better prompting — tell each session more, ask each spec-writer to check with the others first. That scales poorly and everyone who has tried it knows it: the number of pairwise conversations needed to keep N specs consistent grows with N, while the number of times a shared principle has to be written down to keep every unit of work informed grows with exactly one, provided it lives somewhere all of them read. The fix was never “communicate harder.” It was giving the shared answer a permanent address.

Where spec-kit starts

GitHub’s spec-kit, open-sourced in September 2025 as one of the toolkits driving the field’s shift away from ad hoc prompting, makes this fix its first move. Before /specify, before /plan, before /tasks, spec-kit’s workflow runs /constitution — a step whose entire job is to write or update one file, constitution.md, that governs decisions across every phase that follows. Nothing in that file is meant to be a technical decision in the ordinary sense. It does not say which test framework to use, which retry library, or how many milliseconds a timeout should be. It says whether testing is required at all, whether errors fail loudly, and what quality bar every change has to clear — the register of decision that, once made, should never need making again.

The mechanics reinforce the intent. spec-kit treats constitution.md as a genuinely versioned artifact: an update bumps a semantic version — major for a principle removed or redefined, minor for a new principle added, patch for wording — and each change is expected to produce a report checking that no downstream spec or plan now contradicts it. The plan and task phases, in turn, are expected to check their own output against whatever the constitution currently says. The toolkit is not asking a team to write its values down once and hope people remember. It is wiring the shared foundation into every later phase of the workflow, with machinery built specifically to notice when a spec drifts from it.

The same shape, a different genre

Readers who have spent time in this Library’s second volume will recognize the shape of the fix even where the vocabulary changes. A CLAUDE.md or AGENTS.md file plays close to the identical constitutional role for a coding session that spec-kit’s constitution.md plays for a spec — a claim this chapter makes explicitly, building on the file-based-memory territory Volume II covers in more depth. Anthropic’s own guidance on context engineering describes CLAUDE.md files as being “dropped into context up front” — not retrieved on demand the way a session might grep for a specific file mid-task, but present unconditionally, before the session has done anything else. AGENTS.md, the cross-vendor convention that emerged in mid-2025 and is now read by dozens of coding agents across different vendors, exists for precisely the reason its name suggests: one predictable location, honored regardless of which tool is driving a given session, for the operational rules a human would otherwise have to retype by hand into every chat. AWS’s Kiro takes the same approach under a different name — its foundation “steering” files are, per its own documentation, “included in every interaction by default.” Three vendors, three names, the same load-bearing idea.

The word “constitution” belongs to spec-kit, not to the industry at large — Kiro calls its version steering, Tessl keeps a similar pair of foundational documents inside its own framework folder. But the pattern the word names shows up wherever a tool has independently had to solve the same problem: something is true across the whole project, and the only reliable place to put a truth that applies everywhere is somewhere it only has to be written once.

One instance of a general principle

The constitution pattern earns its own name, but it is really a special case of something broader: anything true across every unit of work in a project belongs in a standing document loaded once, not repeated piecemeal inside each individual unit. Restating it piecemeal is wasteful in exactly the way this Library’s first volume already quantified — every sentence of a spec or a prompt spent re-explaining a rule that a standing file could carry for free is a sentence of pure overhead, the same Context Debt logic that governs redundant tokens spent restating what context should already hold. But the waste is the smaller cost. The larger one is reliability: a rule that lives only in whichever engineer happens to be writing today’s spec depends on that engineer remembering, every single time, to restate it correctly — and the rule most likely to get dropped is precisely the one someone forgot to restate this time. A standing document does not forget, and it does not get tired of being asked.

DORA’s 2025 AI Capabilities Model gives this intuition some empirical footing one level up, at the organizational rather than the project scale. Among the seven capabilities DORA finds amplify AI’s positive effect on delivery, one is a clear, explicitly communicated AI stance — a written policy rather than a tacit understanding everyone is assumed to share. Ambiguity itself functions as a risk factor in DORA’s framing; a written rule that resolves it does double duty as documentation and as a control. The constitution pattern is that same finding, applied one level down, from an organization’s policy toward AI to a single project’s standing principles.

What makes a good constitution

Not every document that calls itself a constitution earns the name. Three properties separate one that actually changes what a session does from one that decorates a repository without changing anything.

The enforcement property is the one teams skip most often, because its absence is the least visible failure mode. An unenforced constitution degrades the way any unenforced rule degrades: quietly, and only in the specs where it happened to matter. spec-kit’s own answer — a required constitution check at the plan and task phases, wired into the same workflow that reads the file in the first place — is a specific instance of a general fix: a constitution is worth having only if something downstream is actually checked against it, not merely handed it.

A constitution is not a style guide restated with more confidence. It is the one place a project writes down what it will not renegotiate, spec by spec.

The shape spec-kit’s constitution, CLAUDE.md, and Kiro’s steering files converge on independently

What this should look like in practice

One piece is worth flagging before it gets developed on its own terms later in this volume. A single constitution.md at a project’s root, or a single CLAUDE.md sitting at a repository’s root, is the simplest version of the pattern — one document, one scope, every unit of work inside the project inherits it. Organizations outgrow the simple version quickly: an org-wide baseline that every project inherits, a project-level file that may only tighten it and never loosen it, and directory-level rules narrower still. That layered shape — org, project, directory, each layer able to add constraints but not remove the ones above it — is the subject of this volume’s later chapter on Intent Files. It is named here only so the single-file version of the pattern is not mistaken for the whole of it.