SpecDDWrite specs by level
Guides for choosing and writing the right kind of .sdd file: root project specs, directory and module specs, feature
specs, and focused local specs for services, models, adapters, APIs, components, jobs, events, policies, packages,
libraries, and repositories.
- How to write a root project spec
Use the root project spec for inherited project context: purpose, major structure, broad Must rules, and top-level Must not boundaries.
Read guide - How to write a module spec
Use module specs for inherited local context: area purpose, immediate structure, owned responsibilities, allowed dependencies, and boundaries.
Read guide - How to write a feature spec
Use feature specs for capabilities people can observe: inputs, outcomes, scenarios, non-goals, and checks that guide implementation.
Read guide - How to write a service spec
Use service specs for local orchestration behavior: what the service owns, depends on, must do, must not do, and how changes are checked.
Read guide - How to write a model spec
Use model specs to protect domain invariants: what state is valid, what the model exposes, and what responsibilities stay outside it.
Read guide - How to write an adapter spec
Use adapter specs to keep external-system behavior isolated: persistence, retrieval, translation, failure reporting, and dependency boundaries.
Read guide - How to write an API spec
Use API specs to define inbound interface contracts: exposed endpoints or commands, accepted inputs, returned outputs, errors, and boundary rules.
Read guide - How to write a component spec
Use component specs for UI behavior: accepted props, visible output, interaction scenarios, state handling, and boundaries that keep components focused.
Read guide - How to write a job spec
Use job specs for background work: triggers, inputs, idempotency, side effects, failure handling, retry boundaries, and completion evidence.
Read guide - How to write an event spec
Use event specs to make message contracts explicit: event name, payload, producers, consumers, handled cases, and forbidden side effects.
Read guide - How to write a policy spec
Use policy specs for rules that decide whether something is allowed, denied, eligible, visible, or blocked.
Read guide - How to write a package spec
Use package specs to define a package's local contract: what it owns, exposes, depends on, must preserve, and must not reach across.
Read guide - How to write a library spec
Use library specs to protect public API behavior, compatibility expectations, examples, and implementation boundaries.
Read guide - How to write a repository spec
Use repository specs for repository-level architecture and boundaries, while keeping commands and conventions in bootstrap.project.md.
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 - 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