Skip to main content
Spec 1.0: This page reflects the current stable portable core release.

​
Is this a replacement for tests?

No. Tests are still one of the main ways to prove behavior. Spec Led Development gives the repo a current-truth contract and a verification loop around that contract.

​
Is this a code generator?

No. Agents can use the spec as an implementation target, but the method is not a code generation product.

​
Is this a heavyweight requirements process?

No. The goal is the opposite:
  • keep the authored model small
  • keep it close to the repo
  • keep it easy to maintain

​
Is this only for AI workflows?

No. The method is useful without agents. AI just makes the old drift problem show up faster and more often.

​
Does every file need a spec?

No. Start with the parts of the system where shared understanding matters most. The goal is meaningful subject coverage, not a mechanical file inventory.

​
Do I need ADRs on day one?

No. Start with current-truth subject specs. Add ADRs when you have a cross-cutting decision that should stay consistent over time.

​
Is this only for greenfield projects?

No. It works well for brownfield adoption because you can start from current behavior and tighten the loop one subject at a time.

​
Is this tied to one language?

No. The method is language-agnostic. The tooling is implementation-specific.

​
Is this just TDD with a new name?

No. TDD focuses on executable behavior through tests. Spec Led Development adds a repo-level current-truth contract so code, tests, docs, review, and CI can point at the same target.

​
Is the spec just the pull request description?

No. They do different jobs. The pull request description explains the change:
  • scope
  • risk
  • rollout
  • reviewer notes
The spec states the durable current truth that the repository should keep after the change is merged. Keeping the spec in the same pull request is still useful because it gives reviewers a stable statement of intent before they inspect the code.

​
How does this help code review?

It gives reviewers a clearer sequence:
  1. is the spec change correct?
  2. does the implementation match it?
  3. do the checks actually prove it?
That is easier and safer than reconstructing intent from code alone.

​
What is the real goal?

The goal is not more documentation. The goal is to keep intent, implementation, and verification aligned as the code changes.

​
Where should roadmap and phase docs go?

Keep them outside .spec/specs/. Good options include:
  • docs/roadmap.md
  • docs/phases.md
  • .spec/notes/roadmap.md
The boundary is simple:
  • .spec/specs/ is current truth
  • .spec/decisions/ is durable cross-cutting decisions
  • roadmap and planning docs are supporting context

​
Do supporting docs replace the spec?

No. Supporting docs may help humans and agents plan work, but the spec is still the contract the repo verifies.

​
Could reusable specs become more valuable over time?

Yes, probably. If teams can keep specs small, current, and verifiable, those specs may become useful shared assets over time. That is a long-term possibility, not the main promise of the 1.0 release.