Skip to main content

​
Core Principles

Spec-Driven Development is built on six foundational principles that guide the entire methodology:

​
1. Specifications as the Lingua Franca

Principle

The specification becomes the primary artifact. Code becomes its expression in a particular language and framework. Maintaining software means evolving specifications.
This principle inverts the traditional power structure. Instead of code being the source of truth with specs as afterthoughts, specifications drive everything. The team communicates in requirements, user stories, and acceptance criteria—not implementation details. In practice:
  • Code reviews focus on whether implementation matches the spec
  • Debugging starts by verifying the specification is correct
  • Refactoring means restructuring specifications for clarity
  • The lingua franca of development moves to a higher level

​
2. Executable Specifications

Principle

Specifications must be precise, complete, and unambiguous enough to generate working systems. This eliminates the gap between intent and implementation.
Vague specifications produce vague code. SDD demands precision—not in implementation details, but in what the system should do and why. What makes specifications executable:
  • Clear acceptance criteria (Given/When/Then scenarios)
  • Unambiguous requirements with no [NEEDS CLARIFICATION] markers
  • Measurable success criteria
  • Well-defined entities and their relationships
  • Explicit edge case handling
Executable doesn’t mean “written in a programming language.” It means precise enough that AI can reliably translate intent into working code.

​
3. Continuous Refinement

Principle

Consistency validation happens continuously, not as a one-time gate. AI analyzes specifications for ambiguity, contradictions, and gaps as an ongoing process.
Traditional development has quality gates—discrete checkpoints where work is reviewed. SDD makes quality continuous:
  • /speckit.analyze checks consistency across artifacts
  • /speckit.clarify structures ongoing requirement refinement
  • /speckit.checklist generates custom validation rules
  • Constitution compliance verified at every phase
Why continuous? Because understanding evolves. Early clarifications reveal new edge cases. Implementation challenges expose specification gaps. User feedback highlights missing requirements.

​
4. Research-Driven Context

Principle

Research agents gather critical context throughout the specification process, investigating technical options, performance implications, and organizational constraints.
Specifications don’t exist in a vacuum. They must account for:
  • Library compatibility and maturity
  • Performance benchmarks for technology choices
  • Security implications of architectural decisions
  • Platform capabilities and limitations
  • Company database standards
  • Authentication and authorization requirements
  • Deployment policies and infrastructure constraints
  • Compliance and regulatory requirements
Research happens automatically during /speckit.plan and is documented in research.md, ensuring every technical decision has documented rationale.

​
5. Bidirectional Feedback

Principle

Production reality informs specification evolution. Metrics, incidents, and operational learnings become inputs for specification refinement.
The feedback loop doesn’t end at deployment:
  • Performance bottlenecks → become non-functional requirements
  • Security vulnerabilities → become constraints affecting future generations
  • User behavior patterns → inform UX specifications
  • Production incidents → update specifications for next regeneration
This isn’t just hotfixes—it’s systematic evolution. Production learnings flow back into specifications, improving every future generation.

​
6. Branching for Exploration

Principle

Generate multiple implementation approaches from the same specification to explore different optimization targets—performance, maintainability, user experience, cost.
The same specification can generate different implementations:
  • Performance-optimized branch using async processing and caching
  • Simplicity-optimized branch with minimal dependencies
  • Cost-optimized branch using serverless architecture
  • UX-optimized branch prioritizing user experience over performance
This enables creative exploration and parallel implementation experiments without rewriting specifications.

​
The Constitutional Foundation

At the heart of SDD lies a constitution—a set of immutable principles that govern how specifications become code. The constitution acts as the architectural DNA of the system.

​
Why a Constitution?

Without governing principles, AI generation produces:
  • Inconsistent architectural patterns
  • Over-engineered solutions
  • Untestable code
  • Technical debt from day one
The constitution provides systematic constraints that channel AI capabilities toward consistently high-quality, maintainable implementations.

​
Nine Articles of Development

While each project creates its own constitution, successful SDD constitutions typically include:
Every feature must begin as a standalone library—no exceptions. This forces modular design from the start.Why it matters:
  • Prevents monolithic applications
  • Enforces clear boundaries and minimal dependencies
  • Makes features reusable across projects
  • Enables independent testing and versioning
When the LLM generates an implementation plan, it must structure features as libraries with clear boundaries.
Every library must expose its functionality through a command-line interface.Requirements:
  • Accept text as input (stdin, arguments, or files)
  • Produce text as output (stdout)
  • Support JSON format for structured data exchange
Why it matters:
  • Enforces observability—everything is inspectable
  • Enables testability through text-based interfaces
  • Prevents hiding functionality in opaque classes
  • Makes debugging straightforward
No code before tests. This is the most transformative article.Process:
  1. Unit tests are written
  2. Tests are validated and approved by the user
  3. Tests are confirmed to FAIL (Red phase)
  4. Only then is implementation code written
Why it matters:
  • Completely inverts traditional AI code generation
  • Ensures behavior is defined before implementation
  • Creates living documentation through tests
  • Prevents “generate code and hope it works” approaches
Combat over-engineering through concrete constraints.Simplicity Gate (Article VII):
  • Maximum 3 projects for initial implementation
  • Additional projects require documented justification
  • No future-proofing or speculative features
Anti-Abstraction Gate (Article VIII):
  • Use framework features directly rather than wrapping them
  • Single model representation (no parallel abstractions)
  • Justify every layer of complexity
Why it matters: When an LLM might naturally create elaborate abstractions, these articles force it to start simple and justify complexity.
Prioritize real-world testing over isolated unit tests.Requirements:
  • Use realistic environments (real databases, not mocks)
  • Actual service instances over stubs
  • Contract tests mandatory before implementation
Why it matters: Ensures generated code works in practice, not just in theory. Integration tests catch issues that unit tests miss.

​
Constitutional Enforcement

The implementation plan template operationalizes constitutional principles through Phase -1 Gates: 
### Phase -1: Pre-Implementation Gates

#### Simplicity Gate (Article VII)
- [ ] Using ≤3 projects?
- [ ] No future-proofing?

#### Anti-Abstraction Gate (Article VIII)
- [ ] Using framework directly?
- [ ] Single model representation?

#### Integration-First Gate (Article IX)
- [ ] Contracts defined?
- [ ] Contract tests written?
These gates act as compile-time checks for architectural principles. The LLM cannot proceed without either passing the gates or documenting justified exceptions in the “Complexity Tracking” section.

​
Constitutional Evolution

While principles are immutable, their application can evolve:
Modifications to the constitution require:
  • Explicit documentation of the rationale for change
  • Review and approval by project maintainers
  • Backwards compatibility assessment
This allows the methodology to learn and improve while maintaining stability.

​
Template-Driven Quality

The true power of SDD lies in how templates guide LLM behavior toward higher-quality specifications.

​
How Templates Constrain LLMs

Preventing Premature Implementation

Templates explicitly instruct:
  • ✅ Focus on WHAT users need and WHY
  • ❌ Avoid HOW to implement
This keeps specs stable even as implementation technologies change.

Forcing Explicit Uncertainty

Templates mandate [NEEDS CLARIFICATION] markers:
  • Don’t guess authentication method
  • Don’t assume data retention period
  • Mark all ambiguities explicitly
Prevents plausible but potentially incorrect assumptions.

Structured Thinking Through Checklists

Templates include comprehensive checklists:
  • No [NEEDS CLARIFICATION] markers remain
  • Requirements are testable and unambiguous
  • Success criteria are measurable
Forces LLM to self-review systematically.

Constitutional Compliance Gates

Templates enforce architectural principles:
  • Simplicity gates prevent over-engineering
  • Anti-abstraction gates require justification
  • Test-first gates ensure quality
Creates accountability for architectural decisions.

Hierarchical Detail Management

Templates enforce proper information architecture:
  • Main documents stay high-level and readable
  • Detailed specs go in implementation-details/
  • Code samples extracted to separate files
Prevents specifications becoming unreadable code dumps.

Test-First Thinking

Templates enforce test-first development:
  1. Create contracts/ with API specifications
  2. Create test files (contract → integration → e2e → unit)
  3. Create source files to make tests pass
Ensures testability is considered before implementation.

​
The Compound Effect

These constraints work together to produce specifications that are:
  • Complete - Checklists ensure nothing is forgotten
  • Unambiguous - Forced clarification markers highlight uncertainties
  • Testable - Test-first thinking baked into the process
  • Maintainable - Proper abstraction levels and information hierarchy
  • Implementable - Clear phases with concrete deliverables
The templates transform the LLM from a creative writer into a disciplined specification engineer, channeling its capabilities toward producing consistently high-quality, executable specifications that truly drive development.

​
Beyond Rules: A Development Philosophy

The constitution isn’t just a rulebook—it’s a philosophy that shapes how LLMs think about code generation:
1

Observability Over Opacity

Everything must be inspectable through CLI interfaces. No hidden functionality, no opaque abstractions.
2

Simplicity Over Cleverness

Start simple, add complexity only when proven necessary. Three projects max. Direct framework usage. Justify every abstraction.
3

Integration Over Isolation

Test in real environments, not artificial ones. Real databases, actual services, contract tests mandatory.
4

Modularity Over Monoliths

Every feature is a library with clear boundaries. Reusable, independently testable, properly versioned.

​
The Power of Immutable Principles

The constitution’s power lies in its immutability. While implementation details evolve, core principles remain constant. This provides:
  1. Consistency Across Time - Code generated today follows the same principles as code generated next year
  2. Consistency Across LLMs - Different AI models produce architecturally compatible code
  3. Architectural Integrity - Every feature reinforces rather than undermines the system design
  4. Quality Guarantees - Test-first, library-first, and simplicity principles ensure maintainable code
By embedding these principles into the specification and planning process, SDD ensures that generated code isn’t just functional—it’s maintainable, testable, and architecturally sound.
The constitution transforms AI from a code generator into an architectural partner that respects and reinforces system design principles.

​
Next Steps

Understand the Workflow

Learn the step-by-step process of practicing Spec-Driven Development

Get Started

Begin implementing SDD in your projects

Build docs developers (and LLMs) love

Get started for freeTalk to us