SpecDDUse spec sections
Guides for writing each .sdd section well: what the section is for, the valid syntax, when to include it, when to
omit it, and how to avoid turning local specs into vague docs or broad inventories.
- How to write the Spec section
Use the Spec section as the required first line of a complete .sdd file: name the local subject clearly and put behavior in later sections.
Read guide - How to use the Platform section
Use Platform sparingly for useful technical context such as JavaScript/ES6 or Python/Django/5.2; keep detailed conventions in bootstrap.project.md.
Read guide - How to write the Purpose section
Use Purpose to explain why a subject exists in one or two stable lines, then put behavior, ownership, and tasks in their own sections.
Read guide - How to use the Structure section
Use Structure for local layout and immediate child roles, with explicit paths and short descriptions; keep detailed behavior in nearer specs.
Read guide - How to use the Owns section
Use Owns to define what a spec governs; when Can modify is absent, Owns also acts as the modification boundary.
Read guide - How to use the Can modify section
Use Can modify when writable scope should be explicit, narrower, or different from ownership, especially for safe bounded agent work.
Read guide - How to use the Can read section
Use Can read for context that helps implementation or review while keeping writable authority in Owns or Can modify.
Read guide - How to use the References section
Use References for explicit horizontal context outside the inherited chain; references help readers find contracts but do not grant write authority.
Read guide - How to write Must rules
Use Must for required behavior and responsibilities: make each rule local, observable, durable, and reviewable.
Read guide - How to write Must not rules
Use Must not to protect local boundaries and non-goals that contributors or agents might plausibly cross.
Read guide - How to use the Forbids section
Use Forbids for hard dependency and access boundaries, and remember that Depends on, Must, and Tasks do not override it.
Read guide - How to use the Depends on section
Use Depends on to name allowed collaborators and dependencies, while preserving inherited Must not and Forbids boundaries.
Read guide - How to use the Exposes section
Use Exposes to make the public surface of a spec visible without using it as related-spec authority.
Read guide - How to use the Accepts section
Use Accepts to make input expectations explicit so implementation, tests, and review share the same contract.
Read guide - How to use the Returns section
Use Returns for observable outputs so reviewers can compare implementation, tests, and user-visible results against one contract.
Read guide - How to use the Raises section
Use Raises to make failure contracts explicit, then pair them with Handles, Scenario, or Done when when behavior must be verified.
Read guide - How to use the Handles section
Use Handles for required cases and conditions such as missing input, save failure, retries, events, or branch states.
Read guide - How to write Tasks
Use Tasks as a local implementation checklist with valid states: open, done, skipped, blocked, and needs decision.
Read guide - How to write Done when
Use Done when to prevent under-implementation and over-implementation by making completion concrete and checkable.
Read guide - How to write Scenario blocks
Use Scenario blocks for concrete behavior examples that can guide implementation, review, and tests.
Read guide - How to use the Example section
Use Example sparingly for concrete values or transformations that make a spec easier to implement and review.
Read guide - How to use metadata or frontmatter in SpecDD files
SpecDD .sdd files do not use YAML frontmatter for contract metadata; start complete specs with Spec and put real contract data in normal sections.
Read guide - How to write comments in .sdd files
Use whole-line # comments sparingly in .sdd files; comments are ignored and do not create contract meaning.
Read guide - How to use paths in SpecDD sections
Use explicit path prefixes in SpecDD so humans, agents, and tools can distinguish real file references from prose.
Read guide - How to use globs in SpecDD
Use SpecDD globs when a section needs a deliberate file set, but keep authority and recursive expansion narrow enough to review.
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 - 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