Project constitution
The constitution solves a different problem from that of the spec—which says what is built—and from that of the boundaries—which say what the agent may do. The constitution says which project we are in and what rules govern work on it. In the first edition of the SDD map it was half a sentence; today it is the first step of the method in the reference implementations and is taught as the first competency in the area.
The underlying problem it solves is the agent's lack of memory. Each session starts from scratch and, without a document that pins down the context, structural decisions get made all over again in every conversation, with different results. The constitution is what reduces "cognitive debt": the effort of explaining the same thing over and over.
What it contains
Thoughtworks teams working with SDD on existing codebases have documented what a constitution that actually works contains:
- Project scope. What the system is and what it is not, so that the agent does not expand it on its own.
- Domain context. The business vocabulary and the rules a newcomer would need to know.
- Technology versions. Languages, frameworks, and libraries with their versions, so that no others are introduced.
- Coding standards. Naming, testing, and style conventions.
- Repository structure. The chosen architecture (for example, hexagonal or layered) and where everything goes.
To that list are added the project boundaries: the general rules about what the agent always does, asks about first, or never does (the Always / Ask First / Never system).
Why it should be short
A constitution that tries to contain everything falls into the curse of instructions: past a certain point, more context degrades the model's ability to retrieve what matters. The rule for dividing things up is simple: what applies to a single increment goes in its spec; what applies to all of them goes in the constitution. Mixing them bloats the constitution and leaves the spec out of date. Moreover, when the constitution exists, each spec can be shorter, because it does not repeat what has already been decided.
Where it lives and how it is maintained
In GitHub Spec Kit, the constitution is created with the first command in the workflow and lives in the repository, versioned along with the code. In the rest of the ecosystem, the usual vehicle is an instructions file for agents at the root of the project, with AGENTS.md as the most widespread format. What matters is not the name of the file, but that it sits where the agent will read it at the start and where the team will review it whenever a structural decision changes.
It is maintained like any architectural decision: it changes rarely, it changes deliberately, and every change is reviewed, because it affects everything built afterward. An increment that needs to break a rule of the constitution is a sign that the rule—or the increment—deserves a conversation.
Common mistake
Putting into the constitution what belongs to a single increment. The constitution bloats, the spec goes stale, and the agent receives rules that don't apply to its task. The opposite is just as damaging: having no constitution and relying on the conversation's memory means every session decides the architecture all over again, and structural drift appears within weeks. And writing it once and never looking at it again is worse than not having one, because a constitution that contradicts the team's current decisions is the one the agent will follow.
Resources
📊 Guía didáctica SDD [SDD Teaching Guide, in Spanish]Resources · Scrum Manager
🏦 SDD en equipos ágiles [SDD in Agile Teams, in Spanish]Skill Arena · Scrum Manager
References
- Böckeler, Birgitta. (2025). "Understanding Spec-Driven Development." Thoughtworks / martinfowler.com.
- GitHub. (2026). Spec Kit (project documentation).
- DeepLearning.AI. (2026). Spec-Driven Development with Coding Agents (course).
See also
Want to grow your agility? You can search for course and exam calls, or go at your own pace by becoming a member of the Agile Club. This membership includes exclusive resources, e-learning classrooms, and access to Skill Arena: a space to practice and measure your agile skills at your own pace.