SpecDDSpec-driven workflows
Workflow guides for using SpecDD as a practical development loop: write or review the spec first, implement one bounded piece of work, keep specs and code aligned, and resolve ambiguity before it turns into code.
- How to run the spec-first loop
Use the SpecDD spec-first loop to turn intent into a reviewed local contract, implement one bounded change, verify it, and update tasks only after the result matches the spec.
Read guide - How to draft specs automatically with AI, then review
Use AI-generated SpecDD drafts as a starting point, then review ownership, behavior, assumptions, write authority, and completion criteria.
Read guide - How to implement one spec at a time
Keep SpecDD implementation focused by selecting one local spec, staying inside its write authority, completing one task or behavior, and reviewing the result before moving on.
Read guide - How to keep specs in sync with code changes
Prevent stale SpecDD contracts by deciding when code changes affect the spec, updating the local .sdd file in the same changeset, and reviewing code, tests, and specs together.
Read guide - How to recover from spec-code drift
Fix spec-code drift by identifying the disagreement, choosing the intended source of truth, and realigning specs, code, tasks, and checks together.
Read guide - How to configure team rules in bootstrap.project.md
Use .specdd/bootstrap.project.md for shared project conventions that humans and agents should apply across the repository without mixing them into local .sdd contracts.
Read guide - How to configure personal preferences in bootstrap.local.md
Use .specdd/bootstrap.local.md for local operator or machine preferences while keeping shared team rules in bootstrap.project.md and durable behavior in .sdd specs.
Read guide - How to resolve conflicts between specs
Handle conflicting SpecDD rules by finding the governing chain, preferring stricter constraints, treating tasks as non-authority, and fixing the owning spec.
Read guide - How to reference another area's spec safely
Use explicit SpecDD references for outside context without granting edit permission, inheriting sibling specs accidentally, or blurring local ownership boundaries.
Read guide - How to change a spec safely after code already exists
Update a SpecDD spec after code exists without codifying bugs, creating drift, or changing write authority accidentally.
Read guide - How to deprecate behavior with SpecDD
Use SpecDD to make deprecation explicit with Must, Must not, Tasks, Done when, and Scenarios so old behavior is migrated safely instead of disappearing accidentally.
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 - 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 - Adopt SpecDD on existing projects
Adopt SpecDD gradually in live codebases by starting with active areas, reviewing generated specs, expanding folder by folder, and measuring practical review and delivery signals.
10 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