sdd-spec-writer — Claude Code subagent: specs before code
Turns a task description into an executable spec: inputs, outputs, side effects and test cases. Useful before building a feature that needs a clear contract.
npx claude-code-templates@latest --agent development-team/sdd-spec-writerWhat sdd-spec-writer does
This subagent follows the Spec-Driven Development method. You hand it a task description; it writes a .spec.md file such as create-order.spec.md. The document covers metadata (agent or human as implementer, complexity, languages), the objective, context, an implementation contract, files to touch, required tests, acceptance criteria and verification commands.
The .spec.md extension matters. Quality gate hooks plan-gate and scope-guard look for active specs by that filename pattern, so a differently named file stays invisible to them.
A separate section decides who should do the work. Agents get application and infrastructure layers, plus repeatable patterns like CRUD and validation, as long as complexity stays at or below 8 hours. Code review always goes to a human, along with subjective UI/UX calls and architecture decisions that aren't documented yet. Supported languages: C#/.NET, TypeScript, Python, Go, Rust, Java, PHP, Ruby, Kotlin, Swift.
What it helps with
- turn a feature description into a contract with exact types
- pin down side effects before implementation starts
- decide whether an agent or a human should build it
- write test cases with concrete data
- get acceptance criteria that automated tests can check
Example prompts for the agent
- Write a spec for the create-order task in
create-order.spec.md - Draft the contract for the cancel-order endpoint: inputs, outputs, side effects
- Break the migration task into a spec with test cases and verification commands
How to install sdd-spec-writer
1claude-code-templates
npx claude-code-templates@latest --agent development-team/sdd-spec-writer2Manually: put the files in place
.claude/agents/sdd-spec-writer.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/sdd-spec-writer.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/sdd-spec-writer.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about sdd-spec-writer
How do I install sdd-spec-writer in Claude Code?
Run npx claude-code-templates@latest --agent development-team/sdd-spec-writer. The agent file then sits at .claude/agents/sdd-spec-writer.md.
What does sdd-spec-writer do?
It builds an executable specification from a task description: a typed contract, file list, tests and acceptance criteria. The spec acts as an unambiguous agreement for a developer or an AI agent.
Why must the spec file use .spec.md?
The plan-gate and scope-guard hooks detect an active spec by that filename pattern. Any other extension and they won't pick it up.
