Book-Reader-Assist/library/Spec Driven Development/Chapter-09-speckit-constitution-the-rules-before-the-first-move/Chapter-09-source-text.md

Spec Driven Development — Chapter-09: 4 - speckit constitution: the rules before the first move

• Source: /library/Spec Driven Development/source-file.pdf
• PDF pages: 76–92
• Pages without text: none

---

4 - speckit constitution: the rules before the first move The rules before the first move In the previous chapter you got the ground ready: the tool installed, the To-Do project initialized, the spec-kit scaffolding in view. Coming back to the construction metaphor that opens this material, it is like having the lot cleared, the hoarding up, and the mixer running. What is missing is the first work order. And here comes the surprise that tends to unsettle anyone arriving from improvisation: the first command in the flow writes no feature at all. It doesn't draw the list screen, it doesn't create the add-task button, it doesn't touch the database. The first command writes the rules of the project. Remember the constitution.md file, sitting empty inside .specify/memory , that Chapter 3 left waiting? That is what steps in now. Before you specify what the To-Do does, spec-kit asks you to say under which principles it will be built. That raises a fair question, and it is the question that runs through the whole chapter: why is the first thing the tool asks for the rules, and not the specification? Why spend energy on government before you even know what the first feature is? Hold on to the question. The answer starts with a word you already use outside programming without noticing.

What a project constitution is You live alongside constitutions your whole life, even without calling them that. A country has a constitution: the text that stands above any ordinary law and that every new law has to respect in order to hold. A condo has bylaws: you can decorate your apartment however you like, but you can't change the façade or do noisy construction on a Sunday, because there are general rules that apply to every unit. A city has a building code: each building project is different, but all of them obey the same limits on height, setback, and safety. Notice the shared pattern. In each case there is a set of general, lasting rules, decided once and rarely touched, that frame every specific decision that comes later. You don't re-argue the building code with each floor that goes up. It sits there, in the background, governing. A software project constitution is exactly that. It is the project's governance layer: the set of non-negotiable principles that every spec, every plan, every task list, and every line of implementation has to respect. Governance, here, is the level of the rules that sit above the day-to-day decisions and that decide what is acceptable across all of them. Now the hook's question answers itself. The rules of the game have to exist before the first move. If you were to specify the To- Do's first feature without having fixed the principles, each spec would invent its own rules, and the project would turn into a patchwork of local decisions. The constitution comes before specify because it is what defines the limits within which every spec will be written. It is worth carefully separating the constitution from the other artifacts in the flow, because they are easy to confuse. The constitution is the general, lasting rules of the whole project. The

spec is the what of a specific feature. The plan is the how and the technology. The tasks are the execution steps. The constitution is the only one that cuts across everything and that rarely changes: specs come and go with each feature, but the constitution governs all of them, from the start of the project to the end. What goes in and what stays out Once you know what the constitution is, the next practical doubt is what to write inside it. A good constitution usually holds four kinds of content. First, the principles, each with its rationale. A principle without the why is an arbitrary order, easy to ignore when the deadline bites. With the rationale, it becomes an argument: you know which problem the rule avoids and so you respect it even under pressure. “Every operation that can fail returns an explicit result” is a principle; “because that way the error path becomes part of the contract, and not a surprise at runtime” is the rationale that holds it up. Second, the engineering and quality standards: the technical practices the project demands of itself, such as SOLID, the five design principles that keep classes and modules cohesive, decoupled, and easy to change, Clean Architecture, and the TDD you already know from Chapter 1. Third, the workflow: how the team (or you alone with the AI) carries each change through. Fourth, the governance proper: how the constitution is versioned and by what criterion it is amended, the subject that closes the chapter. Just as important as what goes in is what stays out. These do not belong in the constitution: the programming language, the framework, the library, the state management pattern, the

database, the infrastructure, and any implementation detail. No “use PostgreSQL,” no “React 19,” no “global state with Redux.” Why this strictness? Because those choices are technology, and technology is a decision for another step, the plan , not for the constitution. It is the principle of technology-agnostic specification, one of the central ideas of SDD: intent and lasting rules stay separate from implementation. A constitution swollen with stack decisions recreates vibe-coding with more ceremony; an empty constitution governs nothing. The balance point is to fix principles and structure, and to leave technology for later. Notice that this section, on its own, already works as a checklist: for any line you think of putting in the constitution, ask whether it is a lasting rule or an implementation choice. If it is implementation, it lives in the plan . Constitution, spec, or plan? The rule that settles the doubt In practice, three questions resolve almost every case. What the app does (the user can mark a task as done, can filter by date) is a functional requirement, and that lives in the spec. How it is built and under which standard (layered architecture, TDD, error as value, and even a general scope limit like “this app is single- user”) are rules that hold for every feature, and that is constitution. With which technology (the language, the framework, the state library, the database) is plan. It is worth undoing here a confusion inherited from systems analysis, because it trips up experienced people. In scope prioritization, the analyst separates out what is “MUST HAVE”: the list of essential features. It is tempting to think the constitution is that document, but it isn't. That list of features is spec. The constitution's “MUST” is of another nature: instead of “this feature must exist,” it says “every feature must obey this.”

One describes the features; the other describes the rules above all of them. That is why a functional requirement, however mandatory, does not go in the constitution. And your preferences? They pass through the same filter. If the preference is a quality standard you want across the whole project (always test first, always isolate data access), it is a principle and goes in the constitution with its rationale. If it is a tool taste (this framework, that database), it is stack and goes to the plan . If it is a whim with no why that survives deadline pressure, it goes nowhere. Running the constitution step on the To-Do With the theory solid, let's run the step for real on the To-Do. In spec-kit, creating or updating the constitution is a step in the flow that starts from a template and writes a real file of the project.1 The mechanism is simple to describe. There is a template with fill-in markers at .specify/templates/constitution-template.md , with fields like the project name and the names and descriptions of the principles. From your answers, the step fills that mold and writes the constitution to .specify/memory/constitution.md , the same file that sat empty waiting for you. At the top of the file the command keeps a Sync Impact Report, a short account of what changed from one version to the next, applies semantic versioning to the version number, and propagates the adjustments to the dependent templates (plan, spec, and tasks), so that none of them ends up talking about a rule the constitution no longer has. I won't transcribe every option of the command here, and for a reason of method: command-line instructions change with each release of the tool. What ages well is the understanding of the

step (template filled, file written, version controlled); the exact detail of the command you always check in the official spec-kit documentation, which is the living source.2 What you write in the command But what, in the end, do you provide in this step? The command doesn't invent your project's rules: you describe them in plain language and the tool organizes them into the constitution's format. The input you hand over is the list of principles you want, each with its rationale, plus what should stay out. So this doesn't stay abstract, here is the text you provide to the constitution step, word for word, to generate a constitution like the To-Do's that you are about to read. Copy it and adapt it to your project, swapping the principles for your own: Create the Constitution for the To-Do project, a personal task-list a pp (single-user). The Constitution must define only permanent engineering and architecture prin ciples. It must not specify technologies, languages, frameworks, librarie s, state management patterns, databases, or implementation details. Those dec isions belong to the Plan, not to the Constitution. Produce a lean, clear, normative constitution, starting at version 1.0.0. The constitution must contain exactly six principles, each made up of:

• a short title;
• objective rules using normative language (“MUST”, “MUST NOT”, “SHOULD”, etc .);
• a brief Rationale explaining which problem the principle avoids. The six principles must address the following themes:

1. Layered Architecture

The application must clearly separate responsibilities into layers, keeping t he direction of dependencies always pointing toward the application domain. B

usiness logic must remain independent of the user interface and the infrastru cture. Dependency composition must happen only at the edge of the application . The Constitution must define only the architectural principles. It must not i mpose frameworks, specific state management patterns, dependency injection me chanisms, or implementation details.

2. Isolated Business Logic

Every business rule must reside in a layer of its own in the application, ind ependent of the user interface and the infrastructure. The interface only collects user input and presents results. No business deci sion must exist in the UI.

3. Error as Value

Predictable failures must be represented by explicit success or error results , never by exceptions propagated across layers. Exceptions must remain confined to the boundaries with infrastructure.

4. Test-Driven Development

Every new behavior must be specified by automated tests before or during its implementation. Development must follow a flow that encourages small iterations, continuous v alidation, and safe refactoring.

5. Simplicity

The project must stay deliberately simple. Being a personal, single-user app, any feature not needed for the scope must be avoided (YAGNI). The code must prioritize readability, low coupling, and e ase of maintenance.

6. Technology Agnosticism

The Constitution must never impose a language, framework, library, database, interface architecture, state management pattern, or any specific technology. Those choices belong exclusively to the Plan. After the principles, you must include the following sections:

Engineering Standards

Consolidate the general principles used by the project, including:

• SOLID;
• Clean Architecture;
• Test-Driven Development;
• Error as Value;
• Separation of Concerns.

Workflow

Briefly describe the expected development flow:

1. Constitution
2. Spec
3. Plan
4. Tasks
5. Implementation
6. Tests
7. Review

Governance

Include:

• semantic versioning;
• a process for creating amendments;
• a compatibility rule between versions;
• an obligation to review the Constitution whenever a permanent architectural change occurs. The result must be a professional, objective, and lasting document, focused o n engineering principles, avoiding implementation decisions or details specif ic to any technology. Write each rule the way you would explain it to a colleague joining the project tomorrow: the rule, the why behind it, and the limit of what it does not cover. The clearer the request, the less the tool has to guess and the better the first result comes out.

One note before you read the result, and it holds for everything you build from here on: version the project with git from the start. The constitution is the first of several files the flow will write into the repository, and all of them are text that evolves. Without version control you lose the history of each amendment and the why behind it, which is exactly what makes these artifacts living and auditable. Initialize git in the To-Do project before moving on, and commit the constitution as soon as it is born. Each project has exactly one constitution, in its own .specify , and it is that one you look after from now on. The step ran and the file was born. Let's read it. The To-Do's constitution, principle by principle The constitution that was born for the To-Do is lean and complete: six principles, enough to govern a real app without turning into a treatise. I'll comment on each one in excerpts, with the why of its being there. The whole file, with the supporting sections and the version header, is reproduced in this chapter's appendix; here you get the commented cuts, not the file dumped all at once. The first principle is the structural heart and deserves the most care. Note the word MUST, placed by spec-kit: it means DEVE (and MUST NOT, NÃO DEVE). AI agents generally have no trouble with mixed languages in the same document: I. Layered Architecture. The application MUST clearly separate responsibilities into layers, keeping the direction of dependencies always pointing toward the application domain. Business logic MUST remain independent of the

user interface and the infrastructure. Dependency composition MUST happen only at the edge of the application. This constitution MUST NOT impose frameworks, specific state management patterns, dependency injection mechanisms, or implementation details. It defines only the architectural principles. Several new terms here, and each is worth a definition. Layered architecture is organizing the code into bands with distinct responsibilities, instead of everything mixed together. The domain is where the business rule lives, the heart of the application. The direction of dependency is the rule of who may know whom: the arrows always point inward, toward the domain, and never the other way. The outer layers (the interface, the infrastructure) know the inner ones; the domain ignores whoever is outside. Dependency composition is the moment the concrete pieces get wired to one another; keeping it “at the edge” means assembling everything at a single entry point of the application, leaving the core free of details. That is the essence of Clean Architecture: the business rule at the center, frameworks and details at the edge. A concrete way to embody this, which you will see in the next chapters, is to separate the screen (view), the band that holds the screen's state, the use cases that run the rules, and data access isolated in a repository. But notice: the constitution does not descend to that level. It fixes the principle (layers, direction toward the domain, composition at the edge) and stops there. And there is a deliberate detail in that “stops there.” The principle says, in so many words, that the constitution does not impose a state management pattern or a dependency injection mechanism. It doesn't order “use the Redux pattern.” How you

manage state follows whatever is idiomatic in the stack you choose, and that is decided later, in the plan . It could be Redux or Zustand in React, BLoC in Flutter, NgRx in Angular: the constitution doesn't choose for you. What it guarantees is the structure; how the state is embodied is free. Which of those patterns to adopt, and what each one charges in return, belongs to FOCUS Architecture (2026, https://books.kodel.com.br/en/books/focus/), the second volume in this trilogy, which answers where each rule lives and why dependencies point inward. You do not need it here: in the To-Do that choice shows up in the first cycle's plan , and all the constitution demands is that business rules not live in the screen. The other five principles complete the mold: II. Isolated Business Logic. Every business rule MUST reside in a layer of its own in the application, independent of the user interface and the infrastructure. The interface MUST only collect user input and present results. No business decision MUST exist in the UI. Concentrating the rule in one place makes it testable without the screen and predictable for humans and for the AI. III. Error as Value. Predictable failures MUST be represented by explicit success or error results, and MUST NOT be propagated as exceptions across layers. Exceptions MUST remain confined to the boundaries with infrastructure. This is error handling as value (sometimes called the Result type): the failure becomes part of the function's contract, and the caller is forced to handle it, instead of being surprised at runtime.

IV. Test-Driven Development. Every new behavior MUST be specified by automated tests before or during its implementation. Development SHOULD follow a flow of small iterations, with continuous validation and safe refactoring. It is the TDD from Chapter 1, now raised to a rule of the To-Do: specifying behavior by test stops being an option and becomes law. V. Simplicity. The project MUST stay deliberately simple. Being a personal, single-user app, any feature not needed for the scope MUST be avoided (YAGNI). The code SHOULD prioritize readability, low coupling, and ease of maintenance. The app exists to teach the method; needless complexity only steals the focus. VI. Technology Agnosticism. This constitution MUST NOT impose a language, framework, library, database, interface architecture, state management pattern, or any specific technology. Those choices MUST belong exclusively to the plan . It is the technology-agnostic specification from the previous section, now written as a rule of the To-Do. The five engineering standards the project consolidates (SOLID, Clean Architecture, TDD, error as value, and separation of concerns) appear gathered in a supporting section of the file,

without repeating the text of the principles. And a necessary bit of honesty: going deep on this layered architecture is not the focus of this chapter. It is the subject of FOCUS Architecture (https://books.kodel.com.br/en/books/focus/), where the same separation appears drawn layer by layer. You do not need it to go on from here: what is enough now is to understand that the constitution fixes the structure, and the detail of how to draw each layer is left for later. Checking and improving the result Once the file is generated, don't accept it in the dark: read it as a reviewer, because the result is yours and may come out different from what I showed here. Three checks are enough. The first is coverage: is each principle you asked for present, with a clear name and a rationale that truly justifies the rule, instead of repeating it in other words? The second is leakage: did any line fix a technology by accident? Look for names of languages, frameworks, libraries, or databases; they can appear only as an example of “follows the stack,” never as a requirement. In the architecture principle, confirm that it fixes the layers and the direction of dependency, but does not tie down a state pattern. The third is form: is the version header there, starting at 1.0.0, and does the Sync Impact Report record what was born? If something came out vague, missing, or wrong, you have two ways out. You can run the step again with a sharper request (a more concrete rationale, the principle that was missing) or edit the file by hand and bump the version according to the size of the change. The tool gives the first shape; the owner of the constitution is you. Why the stack stays out

Maybe you felt a tension reading the first principle. If the constitution fixes the architecture, isn't it, deep down, fixing technology? And doesn't that contradict the very principle of technology agnosticism that the To-Do's constitution just declared? There is no contradiction, and untying that knot is the point of this section. Architecture and stack are things of different natures. Architecture is a structural, lasting principle: the idea of separating view, state, use cases, and data access, and of making the dependencies point inward, holds regardless of any tool. It is governance. Stack is an implementation choice: which language, which framework, which state library, which database. It is a plan decision, and it is your choice. The proof is in portability. The same To-Do constitution serves a React app, a desktop in Delphi, a system in Java or C#. What changes from one to another is only the embodiment of the architecture: the separation into layers exists in all of them, but the way to write a data repository in Java is not the way to write it in Dart, and the way to manage state in React is not the way you do it in Flutter. The structure is the same; the clothes it wears are the stack's. Hence the postponement being deliberate. Fixing the stack in the constitution would jump the gun on a decision the method tells you to make later, with the right information in hand, in the plan . The constitution locks down the intent (how the project is organized and what it demands of quality); the plan locks down the implementation (with what this will be built). That separation between intent and implementation is exactly what gives SDD its strength: you decide each thing at the right moment, without tying down too early what can still change.

Living artifact and the bridge to the first spec One last idea is missing so the constitution doesn't look like a foundation stone you lay and forget. It is a living artifact, in the same spirit as the spec from Chapter 2. It was born at version 1.0.0 and evolves by semantic versioning: an amendment that removes or redefines a principle in an incompatible way bumps the major version, a new principle bumps the middle one, a simple clarification bumps the minor one. Every amendment enters with a criterion and with its rationale, recorded in the Sync Impact Report. The constitution changes little, but when it changes, it changes in a controlled and traceable way. And it is not forgotten after being written: further along the flow it comes back to demand conformance, in a check called the constitution check that the next chapter presents at the right point in the cycle. Clear the context at the end of each step A habit worth adopting from now on, and one many people forget. When you finish each step of the flow ( constitution , specify and clarify , plan and check , tasks and analyze , implement ), run a /clear to reset the agent's context before moving on to the next. It seems counterintuitive to throw away everything the agent “learned” in the conversation, but that is exactly the point of SDD: what rules is the generated documentation, never what stayed in the conversation's memory. The constitution, the spec, the plan, and the tasks are the source of truth; the next step reads those files and works from them, not from a chat history that kept piling up. Clearing the context brings two gains. The first is quality: the agent restarts each step looking at the artifact, without dragging along assumptions, dead ends, and misunderstandings from the

previous step. The second is cost: huge contexts burn a lot of tokens on every interaction, and carrying the whole conversation from one end of the flow to the other is expensive for no reason. If the documentation is good, it is enough. And if it isn't enough, the problem is in the documentation, not in the lost context, and that is where you should go back to fix it. The To-Do's rules are set; the ground, which was already prepared, now also has its laws. The constitution, however, sits above the flow: it is written once and governs everything, but it is not part of the cycle that repeats with each feature. Before running the first specify , it is worth climbing to a high point and seeing this whole cycle from above: what path a feature travels, from the git branch to the integrated code. That is the map the next chapter draws, so that only then do we come down to the ground and write the To-Do's first spec.

Footnotes GitHub Spec Kit, official repository and documentation, flow constitution → specify → (clarify) → plan → tasks → (analyze/checklist) → implement and specify init : https://github.com/github/spec-kit · https://github.github.io/spec-kit/ (checked on 2026-06-25, specify CLI v0.11.8). GitHub Spec Kit, official repository and documentation, flow constitution → specify → (clarify) → plan → tasks → (analyze/checklist) → implement and specify init : https://github.com/github/spec-kit · https://github.github.io/spec-kit/ (checked on 2026-06-25, specify CLI v0.11.8).