← Adopt SpecDD on existing projects guides

How to introduce SpecDD to a skeptical team

How-To Adopt SpecDD on existing projects Beginner 1111009HOWTO-1111009

HOWTO-1111009Adopt SpecDD on existing projectsBeginner

This guide shows you how to introduce spec-driven development to a skeptical team without asking them to accept a new process on faith.

Skepticism is useful. It forces the rollout to prove that specs reduce real ambiguity instead of becoming another documentation obligation. The best answer is a small example tied to a real pain point.

Short answer

Start with the team’s concern, not a framework pitch. Explain SpecDD as small source-adjacent contracts that preserve intent, boundaries, tasks, and completion criteria. Show one local example, run one real change, and measure whether it reduced rework, wrong-file edits, review ambiguity, or onboarding friction.

When to use this guide

Use this guide when teammates say:

“We already have tests.”
“We already have tickets.”
“This sounds like more docs.”
“Agents should infer context from the code.”
“We do not have time to spec everything.”
“Architecture docs already exist.”
“Specs will get stale.”

Steps

1. Start from the team’s concern

Ask what problem would make SpecDD worth trying:

repeated review comments
unclear module ownership
wrong-file edits by agents
stale architecture docs
tickets that lose durable behavior after merge
onboarding questions that repeat
tests that prove behavior but do not explain intent

Tie the first example to that problem.

2. Explain what SpecDD does not replace

Use simple distinctions:

tickets still handle planning, priority, and delivery coordination
tests still provide evidence
docs still explain broad concepts, users, and rationale
code still implements behavior
specs preserve local intent, authority, boundaries, tasks, and done criteria

SpecDD should make existing work more reviewable, not replace every artifact.

3. Show one local example

Use a short spec:

Spec: Itinerary

Owns:
  ./itinerary.js
  ./itinerary.test.js

Must:
  Reject itinerary items without a place name.

Must not:
  Change destination search behavior.

Tasks:
  [ ] Add missing-place validation.

Done when:
  Missing-place behavior is covered by a check.

Point out the concrete benefits:

reviewers know which files are in scope
tests map to Done when
agents know what not to touch
the behavior remains visible after the ticket closes

4. Address common objections

For “This is more docs”:

The first spec should replace repeated explanation, not add a parallel essay. If it does not help the next change, it is too broad or unnecessary.

For “We already have tests”:

Tests prove behavior. Specs explain intended behavior, ownership, boundaries, and what work is still open.

For “We already have tickets”:

Tickets coordinate delivery. Specs keep durable implementation rules near the code after the ticket closes.

For “Agents should infer from code”:

Inference is exactly where wrong-file edits and accidental behavior happen. Specs make authority explicit.

For “Specs will get stale”:

Behavior-changing pull requests should update specs in the same changeset, and spec changes should be reviewed like code.

For “We do not have time”:

Do not spec everything. Try one active area where rework already costs time.

5. Run a small pilot

Choose:

one team
one repository or subproject
one active module or workflow
one to three changes
one review checklist

Use a real task:

Plan the Itinerary validation change.

Then review the plan and diff against the local spec.

6. Use evidence to decide

After the pilot, ask:

Did the spec prevent wrong-file edits?
Did review comments become more concrete?
Did the agent need fewer corrections?
Did Done when clarify testing?
Did the spec stay short enough to maintain?
Did anyone use the spec during review?

If the answer is no, adjust or stop. If the answer is yes, expand to the next active area.

Common mistakes

Pitching SpecDD as an agent-only tool.
Starting with a full-repository documentation plan.
Arguing abstract benefits instead of showing one local workflow.
Claiming specs replace tests or tickets.
Ignoring the team’s real delivery pressure.
Treating skepticism as resistance instead of useful review input.

How to verify the introduction

The team introduction worked when:

teammates understand what specs do and do not replace
the first pilot area is small and real
objections are answered with concrete workflow changes
success criteria are written before expansion
the team agrees on whether to continue based on evidence

Quickstart