SpecDDGetting started
Introductory guides for readers new to SpecDD or spec-driven development.
- How to start with spec-driven development
Start spec-driven development with one small change: write intent before implementation, keep the spec near the work, implement, test, and review.
Read guide - How to use spec-driven development with humans and agents
Use spec-driven development with humans and agents by keeping durable rules in local specs, asking for the actual task, and reviewing the result against the contract.
Read guide - How to move from vibe coding to spec-driven development
Move from vibe coding to spec-driven development by turning rough prompts into local specs before real implementation, then using those specs for planning, boundaries, and review.
Read guide - How to use SpecDD in 10 minutes
Set up SpecDD quickly by installing the CLI, running init, adding a root spec and one local spec, then asking an agent to complete a bounded change.
Read guide - How to write your first .sdd spec
Write a first SpecDD .sdd spec by choosing a local target and adding purpose, ownership, required behavior, boundaries, completion criteria, and one scenario.
Read guide - How to run your first spec-driven change end to end
Run a complete spec-driven change by defining behavior, adding a task and scenario, implementing a small slice, checking it, and reviewing against the spec.
Read guide - How to choose your first SpecDD use case
Choose a first SpecDD use case by looking for a small active change where local intent, boundaries, review, or agent scope control will pay off quickly.
Read guide - How to know when you do not need a spec
Decide when to skip a SpecDD spec by separating trivial, temporary, or obvious work from changes that need durable intent, boundaries, or verification.
Read guide - How to use basic SpecDD levels
Use basic SpecDD levels to decide where intent belongs: root specs for project context, module specs for areas, and focused specs for local behavior.
Read guide - How to link existing docs and content with SpecDD
Connect existing project docs and content to SpecDD without copying them into specs by mapping shared locations in bootstrap.project.md and using explicit local spec references.
Read guide - How to enforce and document local code style and conventions
Use bootstrap.project.md for code style enforcement, concrete commands, generated-file policy, dependency rules, and links to existing style docs.
Read guide
More How-To categories
- 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 - 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