Table of Contents
Overview
SDD (Spec-Driven Development) Plugin is a Claude Code plugin that helps you collaborate systematically with AI through a GitHub Issue-based 4-stage process (Analyze → Design → Implement → Test). In this post, I’ll share how this plugin was built — what was considered at each phase and what mistakes were made along the way.
The full structure and usage of SDD Plugin is covered in SDD Plugin: Full Structure and Usage, the background in The Pitfalls of AI Coding and a Path Forward, and the engineering principles in Analyzed Through 4 AI Engineering Paradigms.
File Structure
Let’s first look at the completed plugin’s file structure. This will help you understand how this structure came to be as we walk through the development process.
sdd-plugin/
├── README.md
├── .claude-plugin/
│ └── marketplace.json # Marketplace metadata
└── plugins/sdd-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
└── skills/sdd/
├── SKILL.md # Core: Command routing + common definitions
├── commands/ # Detailed process for each command
│ ├── analyze.md
│ ├── design.md
│ ├── implement.md
│ ├── test.md
│ ├── resume.md
│ ├── status.md
│ ├── review.md
│ ├── ai-review.md
│ ├── init.md
│ ├── rollback.md
│ └── help.md
└── templates/ # Language-specific templates
├── en/ # English
├── ko/ # Korean
└── ja/ # JapaneseThe most important file is SKILL.md. This file defines “when a command comes in, which file to read and how to behave” for Claude Code. Instead of writing logic in a typical programming language, the process is described in Markdown and the AI follows it.
Phase 1: Building the Foundation
The very first step was creating the basic structure for the Claude Code plugin.
What Was Built
plugin.json: Metadata like plugin name, version, and authorSKILL.md: Command routing and common definitions (labels, markers, language settings, etc.)- 4 English Issue templates (Bug Fix, New Feature, Enhancement, Refactoring)
- Analysis/Design output templates
What I Struggled With
At first, I put the entire process into a single SKILL.md file. But it quickly grew to hundreds of lines, and I realized it was inefficient for Claude Code to load the entire file into context every time.
So I changed SKILL.md to only serve as a router, splitting the detailed process for each command into separate files in the commands/ directory. When you run /sdd analyze, SKILL.md directs Claude to read commands/analyze.md.
Phase 2: Multilingual Support
I added Japanese and Korean support so the plugin could be used by global teams.
What Was Built
- Language-specific Issue templates (Korean, Japanese)
- Language-specific output templates
- Language setting storage (running
/sdd init kosaves the setting to.github/.sdd-lang)
Localization, Not Just Translation
Rather than simple translation, I chose terminology that fits each language’s development culture. For example, the Japanese Issue templates use terms like バグ修正, 新機能, 機能改善, and リファクタリング.
Instead of using translation keys, I decided to manage complete template files separately for each language. This means more files, but it allows natural expressions for each language and makes it easy to add language-specific explanations.
Phase 3: Issue Template Improvements
I improved the GitHub Issue templates based on real-world usage.
What Changed
Initially, the Issue templates were too freeform — just a title and body. This meant different people wrote different things, and the AI often missed information it needed for analysis.
So I restructured the templates to require Background (Why), Feature Description (What), and Definition of Done (DoD) in a structured format.
name: 'New Feature'
description: 'Request a new feature'
labels: ['sdd:analyze']
body:
- type: textarea
id: background
attributes:
label: 'Background'
description: 'Why is this feature needed?'
value: |
- Problem / Motivation:
- User feedback: (if any)
- type: textarea
id: description
attributes:
label: 'Feature Description'
description: 'What needs to be built?'
value: |
- One-liner:
- Detailed description:
- Target screens:
- References:
- type: textarea
id: done
attributes:
label: 'Definition of Done'
description: 'When is this feature considered complete?'
value: |
- [ ] Criteria 1:
- [ ] Criteria 2:This ensures all necessary information is captured when the Issue is created, and the AI receives structured input for analysis.
Phase 4: Adding the Resume Command
The biggest pain point in real usage was how hard it was to continue work when a conversation broke. The implement stage in particular spans multiple PRs, making conversation breaks highly likely.
The Solution
To solve this, I added the /sdd resume command.
/sdd resume 123 # Auto-detects the current stage of Issue #123 and continuesThe resume command works with the following logic:
- Determine current stage from Issue labels (
sdd:analyze,sdd:design, etc.) - Check for existing outputs (analysis results, design results) in Issue comments
- Check related PR status
- For Parent Issues, check progress of Child Issues
- Report the interruption point to the user, get confirmation, then continue
Since all outputs are stored on GitHub with markers, context can be fully restored from GitHub even if the conversation starts completely fresh. This was the biggest advantage of the “GitHub Native” design.
Trying It Out
I created a simple project and tested the entire process end to end.
# 1. Initialize
/sdd init ko
# 2. Create Issue (using GitHub template)
# 3. Analyze
/sdd analyze 1
# 4. Design (continues after analysis is complete)
/sdd design 1
# 5. Implement (TDD)
/sdd implement 1
# 6. Test
/sdd test 1Going from Issue creation through Analyze → Design → Implement → Test provided a consistent process throughout development. Each stage’s output remained in Issue comments, making it possible to trace back and understand why certain decisions were made.
What especially impressed me was how the testing stage had the AI write E2E test code and even create a QA checklist. The manual QA items were specific enough to use directly for testing.
Conclusion
In this post, I walked through the SDD Plugin development process phase by phase.
Looking back, the two most important decisions were:
- Splitting SKILL.md into a router — Context efficiency improved significantly.
- Storing all outputs on GitHub — The resume feature became naturally possible.
If you’re curious about what AI engineering principles were applied to this plugin, check out AI Engineering Applied to SDD Plugin — Analyzed Through 4 Paradigms.
Was my blog helpful? Please leave a comment at the bottom. it will be a great help to me!
App promotion
Deku.Deku created the applications with Flutter.If you have interested, please try to download them for free.
