Agent Skills: spec-driven-development

You are beginning a spec-driven development cycle for the requested feature or component. Follow each step in order. Do not proceed to the next step without completing the current one.

Prerequisites — Template Files

Before starting, check that the following template files exist in the skill directory (.claude/skills/sdd/):

• spec_template.md
• plan_template.md

If either file is missing, download it from:

https://raw.githubusercontent.com/yoooonghyun/agent-skills/main/.claude/skills/sdd/<filename>

Use the WebFetch tool to retrieve the raw content and write it to the correct path before proceeding.

Step 1 — Specify

Understand the requested feature or component from the user's description and any relevant existing code or docs. If the request leaves a required behavior genuinely ambiguous — something that cannot be inferred from context — ask for clarification before writing the spec. Do not ask about things that can be determined by reading the codebase.

Create a versioned specification document at:

.sdd/specs/<feature>-v<N>.md

Increment N if a spec for this feature already exists. Use ./spec_template.md as the base.

Fill in all sections: user scenarios with acceptance criteria, functional requirements, edge cases, and success criteria. Base the spec on the user's request; do not add behavior the user did not ask for.

Do not proceed if any required behavior is still unresolved. State the blocker and stop.

Step 2 — Plan

Based on the spec document from Step 1, create a versioned implementation plan at:

.sdd/plans/<feature>-v<N>.md

Use the same version number as the corresponding spec document. Use ./plan_template.md as the base.

Fill in the summary, technical context, and implementation checklist. The checklist is the living record of progress — update it during every subsequent step. Present the plan and get confirmation before moving to the next step.

Step 3 — Interface

Define public contracts (types, interfaces, function signatures, API schemas, etc.) based on the spec document. Use the conventions of the project's language and ecosystem. Rules:

• Every field or parameter must trace back to a requirement in the spec document
• Do not add properties or behaviors not present in the spec
• Use the appropriate type constructs for the language (e.g., union types, enums, ADTs, schemas)

Step 4 — Create Testing

Write tests against the interface before writing any implementation. Tests must cover:

• A spec-compliant happy path
• Missing optional fields (must not error)
• An invalid or missing required field (must log a warning and return a safe fallback)

Do not write implementation code in this step.

Step 5 — Implement

Write the implementation to pass the tests. Rules:

• Any behavior not covered by the spec must not be added
• Reuse shared utilities instead of inlining logic in components
• If a required behavior cannot be expressed by the spec, stop and raise it as a spec-level change

Step 6 — Update Docs

After implementation is complete:

• Update the versioned plan document with any deviations made during implementation
• If .sdd/design.md does not exist, create it by analyzing the current project structure, architecture, key design decisions, and conventions. It should serve as a high-level design reference for the project.
• If new patterns or decisions were introduced, reflect them in .sdd/design.md