Create implementation-ready product specifications before coding.
Constitution-Driven Development is a methodology for building durable product context that enables developers and AI agents to make autonomous decisions consistent with your vision.
Instead of rushing to code with ambiguous requirements, CDD creates a "constitution"—a set of principles, specifications, and examples—that answers the hard questions before implementation begins.
- Developers spend 30-50% of time asking clarifying questions
- Ambiguous specs lead to rework and misaligned implementations
- AI agents silently reinterpret your product
- Documentation becomes stale immediately
CDD structures discovery and specification so that:
✓ Developers implement independently with <5 clarifying questions
✓ AI agents understand your intent and make aligned decisions
✓ Implementation discovers better models, not silently rewrites yours
✓ Specifications stay alive, updated as decisions change
- Reduced implementation time (clear requirements)
- Reduced rework (questions answered upfront)
- Better autonomous decision-making (explicit principles)
- Easier handoffs (canonical documentation)
| Mode | Scope | Use When |
|---|---|---|
| Feature | Single feature or component | Focused work, quick iterations |
| Product | Complete product/subsystem | Normal products, clear vision |
| Platform | Enterprise-scale systems | Complex, long-lived systems |
- Inspect - Review existing context
- Discovery - Understand the user problem
- Doctrine - Define guiding principles
- Domain Model - Model what you're building
- Scenarios - Make it concrete with examples
- Specifications - Write behavioral rules
- Architecture - Design how it fits together
- Vertical Slice - Pick something small to build
- Audit - Keep your constitution alive
Full methodology: SKILL.md
Everything you document is one of four types:
Doctrine
Durable principles that guide decisions forever.
- Vision & mission
- Core principles (3-5 that matter)
- Non-goals (what you won't do)
Specification
Concrete rules for behavior.
- Lifecycle rules (state machines)
- Calculation rules (algorithms)
- Validation rules (constraints)
- UX flows (user behavior)
Reference
Worked scenarios that make specs real.
- Happy path (normal case)
- Variants (common alternatives)
- Edge cases (important failures)
Decision
Consequential choices plus rationale.
- What was decided
- Why (alternatives considered)
- Implications
- When to revisit
Product requirement:
"Users need to know what's happening nearby."
Questions multiply:
- What counts as "nearby"? (500m? 5km? User's choice?)
- What's a "story"? (Only incidents? Weather too? Traffic?)
- When should we send notifications?
- Should stories expire? When?
- What if we're wrong about something?
- What if multiple stories describe the same event?
- How do users control what they see?
- ...50+ more questions
Result: Developers guess. Implementations diverge. Rework.
Doctrine (Principles):
- Locality-first: Users always know their physical context
- Transparency: Show confidence in our understanding
- User control: Users decide what matters to them
- No guessing: Never show unverified claims as fact
Domain Model:
- Signal: Raw observation (P2000 report, weather API, user report)
- Story: Coherent interpretation of signals
- Confidence: How sure we are (0-100%, based on signal count/freshness)
- Scope: Geographic area affected (neighborhood, street, building)
Decision: Signal Confidence
- Why: Users need to know what we're certain about vs. guessing
- If high confidence (>80%): Show story prominently, cite sources
- If low confidence (<50%): Show as "possible" or preview, ask user to verify
- Alternative: Just show everything equally (rejected: erodes trust)
Example Scenario:
- 2 nearby P2000 reports of fire on Main St → Confidence 85%
- User sees: "Fire reported on Main St (2 sources, 5 min ago)"
- User can: Verify from news, mark as resolved, set boundary
Result: Developers understand the why, make aligned decisions independently.
---
## Templates
Start with a template for your mode:
- **Feature Mode:** [one-file-constitution.md](templates/one-file-constitution.md) — Single file, focused scope
- **Product Mode:** [specification.md](templates/specification.md) — Standard specification template
---
## 8 Operating Rules
Non-negotiable principles:
1. **Don't code immediately.** Build understanding first.
2. **Ask only consequential questions.** Skip nice-to-know.
3. **Prefer durable context over exhaustive requirements.** Quality > quantity.
4. **Constitution before specification; specification before implementation.** This order.
5. **Use worked examples aggressively.** Every important spec needs concrete examples.
6. **Separate fact, decision, hypothesis, and open question.** Label each.
7. **Stop documenting when the first vertical slice is safe to build.** Don't over-document.
8. **Keep the constitution alive.** Update or it dies.
---
## Quality Checklist
Every specification should pass:
- [ ] No vague language ("might", "usually", "typically")
- [ ] Examples with concrete data (not abstractions)
- [ ] 5-10 edge cases documented
- [ ] Acceptance criteria are measurable
- [ ] Integration points are clear
- [ ] Failure modes are considered
- [ ] Developer can implement without asking
---
## Getting Started
### For a New Project
```bash
1. Clone or fork this repo
2. Choose your mode (Feature/Product/Platform)
3. Copy relevant template to your project
4. Follow 9 phases in SKILL.md
5. Build
1. Read SKILL.md (methodology)
2. Read CONTRIBUTING.md (how to improve it)
3. Try it on a small project first
4. Share learnings back to the community- SKILL.md — Full methodology (8 operating rules, 9 phases, artifact types)
- CONTRIBUTING.md — How to contribute improvements
- CHANGELOG.md — Version history
- templates/ — Starter templates for each mode
- examples/ — Real products built with CDD
- audit/ — Constitution audit checklist
Q: Isn't this just waterfall documentation?
A: No. CDD stops documenting when the first vertical slice is safe to build. It doesn't specify everything, just enough to minimize consequential ambiguity.
Q: How long does CDD take?
A: Depends on scope. Feature Mode: days. Product Mode: weeks. Platform Mode: weeks to months. Always faster than ambiguous requirements → rework cycles.
Q: Can I use CDD with AI coding agents?
A: Yes, that's a core use case. CDD creates the context that enables agents to make autonomous decisions aligned with your intent.
Q: What if the constitution and code diverge?
A: Update one to match the other deliberately. Phase 9 (Audit) catches this.
Q: Can I skip phases?
A: Yes, if prior work already covers them (Phase 0). But don't skip doctrine or domain model; they're foundational.
The constitution is not the product.
Its purpose is to make the product easier to build correctly, easier to change deliberately, and harder for autonomous agents to silently reinterpret.
If the constitution is getting in the way of building, update it. If implementation discovers a better way, change the doc and the code together.
The constitution serves you, not the reverse.
We welcome contributions! See CONTRIBUTING.md for how to help.
Ideas for contribution:
- Share your experience using CDD
- Add examples from your projects
- Suggest improvements to phases
- Improve templates
- Fix documentation
MIT — Use freely in any project, commercial or personal.
- Anthropic's Constitution-Driven Development — Operating rules, artifact types, audit methodology
- Real product experience — Proven on Vicinity v1.0.1 and other projects
- Best practices from leading product and engineering teams
- Learning? Start with SKILL.md
- Stuck? Check examples/ for similar products
- Questions? Open an issue
- Improving? Submit a PR (see CONTRIBUTING.md)
- Read: SKILL.md (full methodology)
- Choose: Your mode (Feature/Product/Platform)
- Copy: Relevant template
- Follow: 9 phases
- Build: Your constitution
- Share: Back to community (optional)
Ready to build with clarity?
Start with SKILL.md.