SpecDDAdopt SpecDD on existing projects
Guides for bringing SpecDD into existing repositories without a big-bang rewrite: choose a useful first area, map code into local specs, draft and review specs from current behavior, migrate large docs into source-adjacent contracts, and expand only where the added context helps real work.
- How to plan a SpecDD adoption for an existing repo
Start existing-repo SpecDD adoption with one active area where missing context already hurts, then grow coverage from reviewed local specs.
Read guide - How to introduce SpecDD to a skeptical team
Win skeptical teams with a narrow SpecDD pilot: show how local specs reduce ambiguity without replacing tickets, tests, docs, or human review.
Read guide - How to introduce SpecDD without slowing delivery
Adopt SpecDD in the path of delivery: start with one active change, keep specs small, avoid full coverage mandates, and use review evidence to expand.
Read guide - How to run a SpecDD pilot
Test SpecDD adoption with a focused pilot: pick one team and one active module, define success signals, run real work, and review the results.
Read guide - How to map an existing codebase into specs
Turn a live codebase into a SpecDD map gradually: identify roots, parent specs, local specs, read context, and adoption order.
Read guide - How to generate draft specs from existing code
Use agents to draft specs from existing code, but keep generated specs as drafts until humans review behavior, authority, assumptions, and boundaries.
Read guide - How to spec a legacy module safely
Use SpecDD around legacy code without freezing old bugs: draft current behavior, review intent, mark uncertainty, and add small local tasks.
Read guide - How to adopt SpecDD one folder at a time
Grow SpecDD coverage folder by folder: add context where work is happening, avoid full-tree rewrites, and keep parent and child specs at the right level.
Read guide - How to migrate from ARCHITECTURE.md or a big requirements doc to local specs
Break large architecture and requirements docs into local SpecDD contracts while keeping background, rationale, and broad product context in ordinary docs.
Read guide - How to measure whether SpecDD is helping
Evaluate SpecDD adoption with practical signals from real work, not spec counts: fewer corrections, clearer review, better boundaries, and less drift.
Read guide
More How-To categories
- Getting started
Start with spec-driven development, write your first local SpecDD spec, and run a small end-to-end change with human-and-agent-friendly guardrails.
11 guides - Install and setup
Install the SpecDD CLI, prepare Node.js when needed, initialize or update projects, and verify the framework files are wired correctly.
9 guides - Set up your agent
Set up Claude Code, Codex, GitHub Copilot, Cursor, Windsurf, Gemini CLI, OpenCode, Junie, Cline, Antigravity, and universal Agent Skills for SpecDD.
15 guides - Editor setup
Install SpecDD editor support, validate .sdd files, resolve path warnings, and use completions and section hints while writing specs.
4 guides - Agent workflows
Use SpecDD with agents by keeping prompts short, plans spec-bound, file changes authorized, context durable, and reviews tied to local .sdd contracts.
15 guides - Write specs by level
Write SpecDD specs at the right level: root specs for project context, module specs for area boundaries, and focused specs for local behavior and contracts.
14 guides - Use spec sections
Use SpecDD sections correctly: write only sections that add local value, keep authority clear, and express behavior, boundaries, tasks, scenarios, paths, and examples.
25 guides - Spec-writing technique
Improve SpecDD craft with techniques for small specs, right-level placement, naming, splitting, explicit rules, draft review, edge cases, and compatibility.
16 guides - Spec-driven workflows
Use SpecDD workflows to draft, review, implement, synchronize, and evolve local specs without losing source-of-truth context.
11 guides - Work with SpecDD skills
Use SpecDD skills deliberately: choose the right skill for the phase, keep authority clear, chain skills safely, and verify each result against local specs.
17 guides - Software design practices
Use SpecDD to make software design decisions operational: responsibility, boundaries, layers, cohesion, debt prevention, public APIs, and dependency direction.
20 guides - Testing and quality
Turn SpecDD specs into practical quality work: TDD and BDD loops, acceptance criteria, coverage tracing, CI checks, regression tests, and testability review.
11 guides - Code review and governance
Use SpecDD in code review and governance by checking local authority, behavior, boundaries, spec updates, agent output, and high-risk contract changes.
9 guides - Refactoring and maintenance
Use SpecDD to keep maintenance safe: preserve specified behavior, maintain authority while moving code, keep specs current, and delete obsolete contracts carefully.
9 guides - Security and risk
Use SpecDD to make security and risk constraints local, explicit, reviewable, and hard for humans or agents to weaken accidentally.
13 guides - Teams and process
Use SpecDD as a team process by keeping durable behavior in specs, project planning in tickets, conventions in bootstrap.project.md, and reviews lightweight but consistent.
13 guides - Troubleshooting
Fix common SpecDD problems: agent setup, .sdd highlighting, CLI and Node errors, ambiguous specs, unresolved paths, vague specs, stale criteria, and skill installs.
12 guides