The AI Constitution
Relevant source files
The following files were used as context for generating this wiki page:The AI Constitution (memory/constitution.md) is a set of immutable principles that govern how specifications are translated into code within the Spec-Driven Development (SDD) framework. It serves as the architectural DNA of the system, ensuring that every generated implementation maintains consistency, simplicity, and quality. The constitution's rules are non-negotiable and are enforced automatically during the development workflow, particularly during the planning phase.
This document acts as a foundational piece that all development must adhere to. It is not just a set of guidelines but a philosophy that shapes how AI agents generate code, transforming them from simple code generators into architectural partners that respect and reinforce the system's design principles.
Sources: spec-driven.md:300-303, README.md:213-214, templates/commands/plan.md:12
Core Principles (Articles)
The constitution defines several articles that shape the development process. These principles are enforced through automated checks in the project's templates.
Sources: spec-driven.md:305-306, memory/constitution.md:6-8
Article I: Library-First Principle
Every feature must be implemented as a standalone, reusable library component before being integrated into an application. This forces a modular design from the start, ensuring that specifications generate self-contained, independently testable, and documented code with clear boundaries.
Sources: spec-driven.md:308-314, memory/constitution.md:9-11, templates/plan-template.md:46-47
Article II: CLI Interface Mandate
Every library must expose its functionality through a Command-Line Interface (CLI). This enforces observability and testability, ensuring all functionality is accessible and verifiable through text-based interfaces.
The CLI must adhere to a specific protocol:
- Accept text as input (via stdin, arguments, or files).
- Produce text as output (via stdout).
- Support JSON format for structured data exchange.
Sources: spec-driven.md:316-323, memory/constitution.md:13-15, templates/plan-template.md:48
Article III: Test-First Imperative (NON-NEGOTIABLE)
All implementation must strictly follow Test-Driven Development (TDD). This is a non-negotiable principle that inverts traditional code generation. No implementation code can be written until tests are written, validated by a user, and confirmed to fail (the "Red" phase of Red-Green-Refactor).
The required order of operations is:
- Write unit tests.
- Get tests approved by the user.
- Confirm the tests fail.
- Write implementation code to make the tests pass.
Sources: spec-driven.md:325-333, memory/constitution.md:17-19, templates/plan-template.md:51-54, templates/tasks-template.md:29-33
Articles VII & VIII: Simplicity and Anti-Abstraction
These articles work together to combat over-engineering and unnecessary complexity.
- Article VII (Simplicity): Mandates starting with the simplest possible solution. An initial implementation is limited to a maximum of three projects, and any "future-proofing" is disallowed.
- Article VIII (Anti-Abstraction): Requires using framework features directly rather than creating wrapper classes. It also promotes a single data model representation, avoiding Data Transfer Objects (DTOs) unless serialization formats differ.
These principles are enforced by "gates" in the implementation plan, forcing the AI to justify any added complexity.
Sources: spec-driven.md:335-345, templates/plan-template.md:37-41
Article IX: Integration-First Testing
This principle prioritizes testing in realistic environments over isolated unit tests. It mandates the use of real dependencies like actual databases and service instances instead of mocks or stubs. Contract tests are required before any implementation begins.
Sources: spec-driven.md:347-353, templates/plan-template.md:53
Other Principles
The constitution template also outlines other key areas, including:
- Observability: Requires structured logging and sufficient error context.
- Versioning: Mandates
MAJOR.MINOR.BUILDversioning and clear procedures for handling breaking changes.
Sources: memory/constitution.md:25-27, templates/plan-template.md:56-63
Constitutional Enforcement
The constitution's principles are not merely suggestions; they are actively enforced during the plan phase of the SDD workflow. The plan-template.md contains a "Constitution Check" section that acts as a series of automated gates.
Sources: spec-driven.md:355-368, templates/plan-template.md:34-35
The diagram below illustrates how the /plan command uses the constitution to validate a feature plan.
Constitution Check Gates
The plan-template.md defines specific checks that map directly to the constitutional articles.
| Gate Category | Check | Corresponding Article(s) |
|---|---|---|
| Simplicity | # of projects ≤ 3 | VII |
| Using framework directly (no wrappers)? | VIII | |
| Single data model (no DTOs)? | VIII | |
| Avoiding patterns (e.g., Repository)? | VIII | |
| Architecture | Every feature as a library? | I |
| CLI per library defined? | II | |
| Testing | RED-GREEN-Refactor cycle enforced? | III |
| Test order: Contract→Integration→E2E→Unit? | III, IX | |
| Real dependencies used (no mocks)? | IX | |
| Observability | Structured logging included? | V (Implied) |
| Versioning | Version number assigned? | VI (Implied) |
Sources: templates/plan-template.md:37-63
Governance and Amendments
The constitution is designed to be stable but can evolve. The amendment process is strictly governed to maintain system integrity. Any modification requires explicit documentation, review, and approval.
A critical part of the amendment process is updating all dependent documents to reflect the changes. The constitution_update_checklist.md file provides a comprehensive list of files that must be reviewed and updated.
Sources: spec-driven.md:370-376, memory/constitution_update_checklist.md:3-5
The following diagram shows the workflow for amending the constitution.
Checklist for Updates
When the constitution is amended, the following key areas and files must be checked for consistency.
| File/Directory | Reason for Update |
|---|---|
/templates/*.md | To ensure all generated specs, plans, and tasks adhere to new principles. |
/templates/commands/*.md | To update the logic of core commands like /plan and /tasks. |
Agent-specific files (CLAUDE.md, etc.) | To update runtime development guidelines for the AI. |
llms.txt (per library) | To update documentation requirements if Article I (Library-First) changes. |
Sources: memory/constitution_update_checklist.md:9-20
Summary
The AI Constitution is the cornerstone of the Spec-Driven Development process in spec-kit. It provides a set of non-negotiable, architecturally significant rules that guide AI-driven code generation. By embedding principles like "Library-First," "Test-First," and "Simplicity" directly into the automated workflow, the constitution ensures that all generated code is modular, testable, maintainable, and consistent. Its enforcement through templates and its structured governance process make it a powerful tool for maintaining high quality and architectural integrity at scale.
Sources: spec-driven.md:300-303, 378-386