Spec Kit constitution: what goes in it, with an example

Published 25 October 2026

A Spec Kit constitution is the file of rules that every feature in a project must follow: .specify/memory/constitution.md, written once with /speckit-constitution and read again by the commands that plan, check and build each feature. Below are what goes in one, a template to copy, a filled-in example, what each command does with it, how it differs from AGENTS.md and CLAUDE.md, and how it goes out of date — Spec Kit’s own included.

The constitution that’s created as the first step is valuable in its own right. Something that can be used for onboarding both engineers and LLMs.

— one commenter on Hacker News, after trying Spec Kit on a feature that spans several repositories, 2025

What a constitution is

Spec Kit describes it as “a set of immutable principles that govern how specifications become code” (spec-driven.md). Birgitta Böckeler, reviewing Spec Kit for martinfowler.com, put it more plainly: “It’s basically a very powerful rules file that is heavily used by the workflow” (martinfowler.com, 2025).

Three things about it matter in practice:

• One per project. It holds what applies to every feature; a feature’s own requirements go in its spec. In a monorepo, each project with its own .specify/ has its own constitution, and “Spec Kit does not provide a built-in base/inheritance mechanism” (monorepo guide).
• The agent writes it. /speckit-constitution fills Spec Kit’s template from what you type after the command; anything you leave out, it infers “from existing repo context (README, docs, prior constitution versions if embedded)”.
• The commands read it; a plain session does not. The Spec Kit commands load the file when they run. Spec Kit “never touches your agent context file”, in the words of its optional agent-context extension, and that extension adds a pointer to the current plan, not to the constitution. A chat outside the Spec Kit commands does not see the constitution unless AGENTS.md or CLAUDE.md points to it.

It is not the constitution Anthropic published for Claude in January 2026, which is “a crucial part of our model training process” (Anthropic). One commenter put the difference in a line: “the constitution goes into the training data, while CLAUDE.md goes into the prompt” (Hacker News, 2026). A Spec Kit constitution goes into the prompt.

What goes in a constitution

Spec Kit’s constitution template has five parts:

The command asks for principles that are “declarative, testable, and free of vague language”, and versions the file like software: MAJOR when a principle is removed or redefined, MINOR when one is added or widened, PATCH for wording.

What belongs: rules that hold for every feature, and that a reviewer or a test can check.

What does not:

• One feature’s requirements. They go in that feature’s spec.
• Rules for one module or one phase. Spec Kit’s lead maintainer, closing a request to split a large constitution: “a constitution only becomes ‘too big’ if module/phase rules are pushed into it” (issue #1950).
• Rules nobody has agreed to. Spec Kit’s guide for existing projects asks for principles “already true for the repository or that the team has explicitly agreed to adopt”, and warns: “Do not invent standards merely to fill the constitution template. The constitution governs later planning and analysis, so unrealistic rules create noise instead of useful constraints” (existing projects).

Constitution template

Copy it, fill in the brackets, and give it to /speckit-constitution as its input; the command keeps Spec Kit’s headings, sets the version and dates, and writes .specify/memory/constitution.md.

# [Project] Constitution

## Core Principles

### I. [Principle name]
[One sentence: what must always hold.]
- [A rule with MUST that a reviewer or
  a test can check]
- [   ]
Rationale: [why the rule exists, and
what goes wrong without it]

### II. [Name] (NON-NEGOTIABLE)
[   ]

### III. [Principle name]
[   ]

## Additional Constraints
- Stack: [languages, frameworks and
  versions the project is fixed on]
- Security: [what must never happen]
- Performance: [limits, with numbers]

## Development Workflow
- Review: [who reviews what, before
  merge]
- Quality gates: [the checks that must
  pass: tests, lint, CI]

## Governance
- Authority: [what this file overrides,
  and how a conflict is resolved]
- Amendments: [who proposes, who
  approves, where the reason is kept]
- Versioning: MAJOR = a principle
  removed or redefined; MINOR = one
  added or widened; PATCH = wording
- Review: [when the file is checked
  against the code and CI]

**Version**: [x.y.z]
**Ratified**: [YYYY-MM-DD]
**Last Amended**: [YYYY-MM-DD]

Spec Kit writes the version and the two dates on one line; they are split here to fit a phone.

Constitution example

For the customer portal used across this site: a client’s customers see their invoices and pay them by card, and the supplier’s developers build it with an AI coding agent.

# Customer Portal Constitution

## Core Principles

### I. No card data (NON-NEGOTIABLE)
Customers pay on the payment provider's
hosted page.
- Card numbers MUST NOT be sent to,
  logged by or stored on our servers.
- Payment code MUST use the provider's
  hosted page or its client library.
Rationale: card data stays with the
provider, and so does most of the
PCI DSS work (decision D-4).

### II. Test-backed change
- A change in behaviour MUST come with
  a test that fails without it.
- The test suite MUST pass in CI before
  merge.
Rationale: the agent's work is checked
by its tests before anyone reads it.

### III. The /api/v1 contract holds
- /api/v1 responses MUST NOT lose or
  rename a field.
- A breaking change MUST go to /api/v2.
Rationale: the client's accounting
system reads /api/v1.

### IV. Money is exact
- Amounts MUST be integers in minor
  units (cents) with a currency code.
- Amounts MUST be rounded only for
  display.
Rationale: an invoice one cent off is
a support call.

### V. Every page is accessible
- Pages MUST meet WCAG 2.2 level AA.
Rationale: the client's contract
requires it.

## Additional Constraints
- Stack: Python 3.12, PostgreSQL 16. A
  new runtime dependency needs the tech
  lead's approval.
- Personal data MUST be stored in the
  EU.
- The invoice list MUST load in under
  2 seconds with 10,000 invoices.

## Development Workflow
- Every pull request is reviewed by a
  developer who did not write it.
- A change to what customers see needs
  its spec agreed by the client's
  finance lead first.

## Governance
- Authority: this file overrides other
  guidelines. A conflict is fixed in
  the spec, plan or tasks, never by
  weakening a principle.
- Amendments: proposed in a pull
  request, approved by the tech lead,
  and by the finance lead when a
  principle affects customers. The
  commit says why and who agreed.
- Versioning: MAJOR = a principle
  removed or redefined; MINOR = one
  added or widened; PATCH = wording.
- Review: checked against the code and
  CI every quarter, and whenever the
  stack changes.

**Version**: 1.1.0
**Ratified**: 2026-01-12
**Last Amended**: 2026-09-30

What is not in it: the payment reminder, the invoice list, any single feature. Those are specs. The reason behind principle I is in the project’s decision log, where the constitution points to it.

How Spec Kit uses the constitution

The plan’s gate is strict on paper: the plan template says it “Must pass before Phase 0 research”, and a violation can stay only with a written justification in the plan’s complexity table. The analysis is stricter: “Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle” (analyze command).

Two changes in 2026 shaped how it works today. Until version 0.8.6 in May, /speckit-implement did not read the constitution at all; the issue that fixed it: “code generation during /speckit.implement is completely unaware of project principles, non-negotiable rules, and governance constraints” (issue #2459). And since 0.14.4 in July, /speckit-constitution changes only the constitution. Before, it also rewrote the plan, spec and tasks templates; now every command reads the current file when it runs, because “Propagation duplicated the single source of truth” (upgrade guide). Teams that want the old behaviour can add the constitution-sync preset.

Constitution vs AGENTS.md and CLAUDE.md

Both hold rules, so the same rule can end up in both and then drift apart. Keep commands, layout and conventions in AGENTS.md or CLAUDE.md, keep the rules that must hold in the constitution, and add one line to AGENTS.md or CLAUDE.md that names the constitution’s path, so that a session outside the Spec Kit commands knows it exists. Claude Code can instead import the whole file with @.specify/memory/constitution.md in CLAUDE.md, but imports “don’t reduce its context cost”, and Anthropic’s advice is to “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence” (Claude Code docs). Which tools read which file: AGENTS.md vs CLAUDE.md vs spec.md.

Other tools keep the same kind of file under other names:

• Kiro: steering files in .kiro/steering/ — product.md, tech.md and structure.md to start with. Each is included in every interaction by default, or only for matching files, on request, or when relevant (Kiro docs).
• OpenSpec: the context: field of openspec/config.yaml, “injected into every planning request”, and rules: for each kind of document (OpenSpec docs).

How the three tools compare overall: Spec Kit vs OpenSpec vs BMAD.

Does a constitution work? What the research says

No study we found measures what a constitution adds on its own. What there is:

One direct test, on one project. A preprint tested a security constitution on a banking demo application; its author notes: “Small sample size (n=1 project) limits statistical power” (Marri, 2026, preprint). A peer-reviewed study adds that the test ran “on a single project with the same developer implementing both conditions sequentially” (Hill, ESEM 2026).

Rules files are followed, but do not reliably raise success. The most careful test of AGENTS.md-style files found that “instructions in the context files are well followed by coding agents”, yet that the files do “not generally improve task success rates, while increasing inference cost by over 20% on average”; files written by developers did slightly better than generated ones (Gloaguen et al., 2026, preprint). /speckit-constitution drafts the file from a few lines of input, which puts it closer to the generated kind unless someone rewrites it.

An agent can follow it too eagerly. Böckeler, in the same review: “I also saw the agent go way overboard because it was too eagerly following instructions (e.g. one of the constitution articles).”

Long constitutions lose rules. One user’s write-up: “When given comprehensive documents (like our 1000+ line Constitution), AI assistants lose context and violate principles” (issue #206). Another user: “the AI agent ignored quite a few of the guidelines in the constitution because it was big” (issue #1950). A third describes why: “The constitution is a large document read once at plan time and then gone from context” (issue #2219).

It is read, not enforced. The author of Consort, a competing framework, describes Spec Kit’s constitution as “honored as prose rather than checked mechanically” (Hartman, 2026, preprint). One satisfied user pairs it with something that is checked: “Pro tip, tell spec-kit to do TDD in your constitution and the tests will keep it on the rails as you progress” (Hacker News, 2026). Another commenter, who uses the constitution to set the order of work, is less sure: “That might very well be useless superstition since it is soo easy to fool yourself” (Hacker News, 2026).

What the evidence supports: a short constitution, written or rewritten by a person, of rules that a test, a CI step or a reviewer can check — with those checks in place.

How a constitution goes stale

Spec Kit’s quickstart says to “Establish a constitution once per project”. Once is also where a constitution can stay, while the code around it moves.

Spec Kit’s own constitution shows how. The Spec Kit repository has one, ratified on 19 June 2026 and not amended since. On 23 October 2026:

• It says CI runs the tests “across a matrix of ubuntu + windows × Python 3.11, 3.12, and 3.13”. The test workflow in the same repository runs Ubuntu, Windows and macOS on Python 3.13 and 3.14.
• It says “Any amendment MUST propagate to dependent templates and command guidance in the same change”. Since July, Spec Kit’s own /speckit-constitution no longer does that, by design.
• It still opens with the review notes the command adds at the top of the file, although since September the command says they are “expected to be removed before the amended constitution file is committed”.

The principles still hold; the facts around them moved, and nothing compared the two. Spec Kit’s commands check specs, plans, tasks and code against the constitution, not the constitution against the repository. Community extensions such as MemoryLint, which “audits agent memory files for boundary, reality, conflict, and redundancy drift”, try to fill the gap.

Some are never filled in. One user reported a 454-line constitution, then corrected it: “I never properly filled out the constitution.md file. It stayed as the default template with placeholders” (issue #860). Nothing warns about that: /speckit-converge will “skip constitution checks gracefully rather than failing” when the file is still the template.

Rules turn up later. One user: “i found my self coming back to the constitution to update it with the core concepts i noticed by building features, but i forgot to list them when starting the project” (issue #366). Amending it is expected; the questions are who approves each amendment and where its reason is kept. The same pattern in other project files: spec drift.

How to write and keep a constitution

1. Start from rules that are already true — the README, the CI configuration, the contribution guide, the decision log — as Spec Kit’s guide for existing projects advises.

2. Keep only rules for every feature. Module and phase rules go elsewhere; a feature’s requirements go in its spec.

3. Make each rule checkable: MUST, something a reviewer or a test can see, and a one-line rationale.

4. Read and rewrite what the agent drafts. Keep the rules you would defend in a review; delete the rest.

5. Back the important rules with checks — a test, a CI step, a hook. The constitution is read as prose.

6. Make sure it is filled in. No [PRINCIPLE_1_NAME] or other bracketed placeholder left.

7. Name who approves an amendment, and keep why. The version line records when; git records what changed; the commit message or the pull request should say why and who agreed:

   docs: amend constitution to v1.1.0
   
   MINOR: principle V added
   (accessibility).
   Why: WCAG 2.2 AA is now in the
   client's contract.
   Agreed by: tech lead and the
   client's finance lead, 30 Sep 2026.
   

8. Check it against the repository on a schedule, and whenever the stack or CI changes: versions, tools, commands, workflow.

9. Point to it from AGENTS.md or CLAUDE.md, so a session outside the Spec Kit commands knows it exists.

Where Specroot fits

This is the problem Specroot works on: the rules every change must follow and the requirements of each change, kept current, with who agreed each amendment and why. Specroot for teams using AI coding agents.