SpecDDSpec-writing technique
Cross-cutting SpecDD writing techniques that apply across levels and sections: write small local specs, choose the right level, name and place specs predictably, avoid duplication, review drafts, and capture edge cases, compatibility, performance, and observability without over-specifying.
- How to write good specs
Good SpecDD specs are short, local, behavior-focused contracts that define ownership, constraints, tasks, and done criteria without broad vague prose.
Read guide - How to keep specs small and maintainable
Prefer many small SpecDD specs over one large one; keep each local, concise, and useful for the next implementation or review.
Read guide - How to choose the right spec level
Pick the smallest SpecDD level that owns the decision: root for inherited project context, module for area boundaries, and focused specs for local behavior.
Read guide - How to start from a minimum viable spec
Begin with the smallest useful SpecDD spec and grow it only when implementation, review, or agent behavior shows a real gap.
Read guide - How to name SpecDD files
Name .sdd files so humans, agents, and tools can find the right local spec: root by content root, local by same basename, suffixes only when useful.
Read guide - How to place .sdd files in a repository
Put specs near the files or areas they describe: root specs at the content root, directory specs in or beside directories, and local specs beside source files.
Read guide - How to split a large spec
Break overgrown specs into local contracts without losing inherited context or write authority.
Read guide - How to avoid duplicating parent constraints in child specs
Write inherited constraints once in the parent spec, then let child specs add or narrow local behavior without copying shared rules.
Read guide - How to be explicit in a spec
Explicit specs reduce hidden assumptions by saying what must happen, what must not happen, what may be touched, and how completion will be checked.
Read guide - How to convert a feature idea into a spec
Convert feature ideas into implementation-neutral specs that preserve intent, expose ambiguity, and give humans and agents a durable source of truth.
Read guide - How to use specs as a source of truth
Make specs the reviewed, versioned source of truth by putting intended behavior in the repository, keeping it synced with code, and reviewing changes against it.
Read guide - How to review a draft spec before using it
A draft spec should become authority only after review confirms the intended behavior, ownership, boundaries, ambiguity, and testability.
Read guide - How to write specs for edge cases
Capture important edge cases in specs with explicit behavior, scenarios, handlers, errors, boundaries, and completion criteria without listing every impossible case.
Read guide - How to write specs for backwards compatibility
Use specs to preserve backwards compatibility by naming stable contracts, allowed changes, forbidden breakage, versioning, deprecation, and test expectations.
Read guide - How to write specs for performance constraints
Use specs to capture real performance constraints as measurable, reviewable behavior while avoiding brittle premature implementation rules.
Read guide - How to write specs for observability
Use specs to define useful observability behavior, including what to log, measure, trace, alert on, audit, and never record.
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-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