The Question
AI-assisted development is here. Whether you use GitHub Copilot, Claude Code, Cursor, or a custom agent pipeline, the fundamental challenge is the same: how do you give the AI enough context to produce correct, consistent, verifiable code?
Two schools of thought have emerged:
Spec-Driven Development — Write comprehensive specification documents that AI agents consume as context. The specifications are text files, templates, and checklists that describe what to build, how to test it, and how to document it. The AI reads the spec, generates code, and the spec validates the output through quality gates.
Typed Specifications — Encode requirements as compiler-enforced types. Features are abstract records. Acceptance criteria are abstract methods. The compiler refuses to build until every requirement is specified, implemented, and tested. AI agents work within the type system, not alongside a document.
Both approaches solve real problems. Both are serious engineering efforts. But they make fundamentally different bets about where truth lives — in documents or in types.
This series is a deep, honest comparison. Ten parts. No straw men. We'll examine a real spec-driven framework (cogeet-io/ai-development-specifications) against a real typed specification system (the approach described in Requirements as Code and Contention over Convention on this site). Where the spec-driven approach is genuinely better, we'll say so. Where typed specifications solve problems that documents cannot, we'll show why.
Part I: The Problem Both Solve
AI agents fail because of context failures, not model failures. Both approaches agree on this diagnosis. Where they diverge is the treatment. Document-based context assembly vs compiler-enforced context through the type system.
Part II: Architecture — Six Pillars vs Six DSLs
The spec-driven framework has six pillars: PRD, Specification, Context Engineering, Testing, Documentation, Coding Practices. The typed approach has six DSLs: DDD, Content, Admin, Pages, Workflow, Requirements. A structural comparison of how each organizes knowledge.
Part III: Requirements — Templates vs Types
The PRD template asks you to fill in fields: features, acceptance criteria, priorities. Typed specifications make features into abstract records and acceptance criteria into abstract methods. What happens when a requirement changes? What happens when someone forgets one?
Part IV: Context Engineering — Assembly vs Generation
The spec-driven approach assembles context from four sources using three strategies (task-driven, progressive disclosure, adaptive). The typed approach generates context at compile time — the metamodel registry, the traceability matrix, the compliance report. One is runtime context selection; the other is compile-time context production.
Part V: Testing — Strategy Documents vs Compiler-Enforced Coverage
The spec-driven testing spec defines 15+ strategies with metrics and thresholds. The typed approach makes tests declare which acceptance criteria they verify — and the compiler warns when coverage is missing. One tells you what to test; the other tells you what you forgot to test.
Part VI: Validation — Quality Gates vs Roslyn Analyzers
Both approaches validate. Spec-driven uses CI/CD quality gates, coverage thresholds, and mutation testing scores. Typed specifications use Roslyn analyzers (REQ1xx-REQ4xx) that fire at compile time. The difference: when do you find out something is wrong?
Part VII: Documentation — Living Docs vs Self-Documenting Types
The spec-driven framework has a full Documentation-as-Code pillar with automated generation and quality measurement. The typed approach says "the type IS the documentation" — Ctrl+Click from test to AC to feature to epic. Two philosophies of what documentation means.
Part VIII: The AI Agent Experience
What does it feel like to be an AI agent working with each approach? With spec-driven, you read a document and generate code that hopefully matches. With typed specifications, you write code within a type system that rejects incorrect implementations. The feedback loop difference is profound.
Part IX: Drift, Scale, and the Long Game
What happens after six months? After two years? After the team doubles? Document-based specs drift from the codebase. Types cannot drift — they ARE the codebase. But types have their own costs: learning curve, tooling investment, language lock-in. An honest assessment.
Part X: The Verdict — When to Use Which
Not every project needs typed specifications. Not every team can adopt them. A decision framework based on project size, team experience, compliance requirements, language ecosystem, and AI integration depth. Plus: can the two approaches be combined?
How to Read This Series
Architects evaluating AI development strategies should read Parts I, II, IX, and X — the problem statement, architecture comparison, long-term analysis, and verdict.
Developers adopting AI-assisted workflows should read Parts I, III, V, and VIII — the problem, how requirements work in each approach, testing differences, and the AI agent experience.
Tech leads frustrated with specification drift should read Parts I, IX, and X — then the domain that hurts most on their team.
Anyone in a hurry should read Part I (the shared problem) and Part X (the verdict).
Prerequisites
- Familiarity with at least one specification or requirements tracking approach (Jira, Confluence, ADRs, RFC documents)
- Basic understanding of AI-assisted development (GitHub Copilot, Claude Code, Cursor, or similar)
- For the typed specification examples: familiarity with C# and .NET (the examples use .NET 8+)
- For the spec-driven examples: ability to read structured text/YAML configuration
Disclosure
This comparison is written by the author of the typed specification approach. That's a bias worth acknowledging. To compensate: every critique of the spec-driven approach is accompanied by the equivalent weakness in the typed approach. Every strength of the typed approach is accompanied by the prerequisite cost. The goal is not to sell one approach — it's to help you make an informed decision.
Related Posts
This series builds on and references:
- Requirements as Code — the nine-part series on typed requirements in C#
- Auto-Documentation from a Typed System — the Document DSL that generates documentation from typed DSLs (the proof that "everything can be a DSL" — including documentation itself)
- Contention over Convention — the philosophical foundation: why types beat conventions
- Don't Put the Burden on Developers — structural fixes, not discipline
- Quality to Its Finest — multi-layer quality gates
- Meta-Metamodeling — M2/M3 theory behind attribute-driven generation
- DDD — Domain-Driven Design with the type system