[SDD Plugin] Full Structure and Usage of SDD Plugin

Overview

SDD (Spec-Driven Development) Plugin is a Claude Code plugin that helps you develop systematically by collaborating with AI through a structured, GitHub Issue-based development process. In this post, we’ll go through the SDD Plugin’s 4-stage process, commands, GitHub integration, and usage all at once.

The background behind creating this plugin is covered in The Pitfalls of AI Coding and a Path Forward, the development journey in From Prototype to Completion, and the engineering principles in Analyzed Through 4 AI Engineering Paradigms.

The completed plugin is publicly available on GitHub. Check it out if you’re interested.

• GitHub: https://github.com/dev-yakuza/deku-claude-plugins

What Is the SDD Process?

SDD (Spec-Driven Development) is a specification-centered development methodology. The idea is to go through thorough analysis and design before writing code, and use TDD (Test-Driven Development) for implementation. This way, even AI-generated code is grounded in clear requirements and design, leading to better maintainability and extensibility.

4-Stage Process

1. Requirements Analysis (What/Why) → 2. Design (How) → 3. Implementation (TDD) → 4. Testing (E2E/QA)

Stage 1: Requirements Analysis (What / Why)

This stage focuses solely on what to build and why it’s needed. Technical implementation details (How) are intentionally not discussed here.

• Classify request type (New Feature / Enhancement / Bug Fix / Refactoring)
• Derive feature list
• Determine priorities

The key here is separating What/Why from How. AI tends to jump to technical solutions quickly, so we deliberately block technical discussions at this stage.

Stage 2: Design (How)

Based on the requirements from Stage 1, this stage designs how to implement them.

• Explore existing codebase (using a dedicated exploration agent)
• Identify impact scope
• Design file structure and data models
• Identify constraints and risks
• Split into PR units (large features get split into multiple PRs)

For large features, this stage automatically creates Child Issues to manage each PR independently.

Stage 3: Implementation (TDD)

The Red → Green → Refactor cycle is repeated for each PR.

3-0. PR Kickoff: Test plan + implementation plan
3-1. Red: Write failing tests
3-2. Green: Minimal implementation to pass tests
3-3. Refactor: Improve code
3-4. Create PR and code review
→ Repeat for next PR

Each step goes through dual verification: AI self-review + independent agent review (up to 3 rounds) + user confirmation.

Stage 4: Testing (E2E / QA)

Since unit/UI tests are already done in Stage 3, this stage focuses on E2E tests and QA.

4-0. Test Setup: Detect and configure existing test environment
4-1. E2E Tests: AI writes and runs E2E test code
4-2. QA Checklist: Generate checklist for manual testing
4-3. Manual QA: User tests based on the checklist
4-4. Results Review: Failed items go back to Stage 3 for TDD fix

For Parent Issues (with multiple Child Issues), E2E tests for the entire feature are run only after all Child Issues are completed.

Common Pattern Across All Stages

Every stage follows the same pattern.

① Input → ② AI Work → ③ AI Self-Review → ④ Independent Agent Review → ⑤ User Confirmation → Next Stage

Command List

SDD Plugin is used by appending commands after /sdd. Commands are split into core process commands and utility commands.

Usage

Let’s walk through the actual flow of using SDD Plugin step by step.

1. Installation

First, install the plugin in Claude Code.

claude plugin add dev-yakuza/deku-claude-plugins

2. Repository Initialization

Once installed, run initialization in your project repository. Specifying a language sets up Issue templates in that language.

/sdd init ko        # Initialize with Korean templates

Running this command sets up the following:

• Copies language-specific Issue templates to .github/ISSUE_TEMPLATE/
• Saves language setting to .github/.sdd-lang
• Creates GitHub labels (sdd:analyze, sdd:design, sdd:implement, sdd:test, sdd:done)

3. Create an Issue

Create an Issue on GitHub using the SDD template. Choose from 4 template types:

• New Feature
• Enhancement
• Bug Fix
• Refactoring

Templates have structured fields for Background (Why), Feature Description (What), and Definition of Done (DoD), ensuring the AI receives all information needed for analysis without gaps.

4. Run the Development Process

Once the Issue is ready, run each stage in order. Just pass the Issue number.

# Stage 1: Requirements Analysis
/sdd analyze 123

# Stage 2: Design
/sdd design 123

# Stage 3: Implementation (TDD)
/sdd implement 123

# Stage 4: Testing
/sdd test 123

At each stage, the AI performs the work, self-reviews, then asks for your confirmation. Once you approve, the output is saved as an Issue comment and the process moves to the next stage.

5. Resume Work

If your Claude Code conversation breaks or you start a new session, the resume command checks the Issue’s labels and outputs to pick up exactly where you left off.

/sdd resume 123     # Auto-detects current stage and continues

6. Check Progress

Use this when you want to see how far an Issue has progressed.

/sdd status 123

It shows the completion status and current progress of each stage in a format like this:

Issue #123: User Profile Page Development
Stage: implement
- [x] Analyze: Done
- [x] Design: Done
- [ ] Implement: PR #1 in progress
- [ ] Test: Not started

GitHub Integration

All data in SDD Plugin is stored on GitHub. No separate database or file management is needed.

Data Storage Locations

Here’s where each stage’s output is stored:

Progress Tracking via Labels

You can instantly see which stage an Issue is at by its label. This makes it easy to manage overall work status just by filtering labels in GitHub’s Issue list.

When a stage is completed, the previous label is automatically removed and the next one is added.

Output Markers

You might wonder: “How does the next stage find the previous stage’s results?” Output stored in Issue comments includes HTML comment markers that allow precise identification of the needed artifacts.

<!-- sdd:analyze:output -->
Analysis results here...
<!-- /sdd:analyze:output -->

These markers allow the next stage to automatically read the previous stage’s output, and the resume command also uses them to determine progress.

Multi-PR Workflow

Large features are hard to handle in a single PR. SDD Plugin solves this with a Parent/Child Issue structure.

Parent Issue #10: User Profile Feature
├── Child Issue #11: Profile API Integration (PR #1)
├── Child Issue #12: Profile UI Implementation (PR #2)
└── Child Issue #13: Profile Image Upload (PR #3)

1. During Design, if multiple PRs are needed, Child Issues are automatically created.
2. During Implementation, each Child Issue goes through its own independent TDD cycle.
3. During Testing, after all Child Issues are complete, the Parent Issue runs E2E tests for the entire feature.

Key Design Decisions

A few important design decisions were made while building this plugin.

1. GitHub Native

It uses only GitHub’s built-in features with no separate database. Requirements in Issue body, outputs in Issue comments, progress in Issue labels, implementation in PRs. This means even if a conversation breaks, all context can be restored from GitHub.

2. Declarative Process

The process is described in Markdown, not code logic. A single SKILL.md file controls the AI’s behavior. Want to modify the process? Just edit the Markdown file.

3. Multilingual Support

Instead of translation keys, complete templates are managed separately for each language. This allows natural expressions tailored to each locale, not just direct translations. Currently supports Korean, English, and Japanese.

Conclusion

In this post, we covered SDD Plugin’s 4-stage process, commands, GitHub integration, and usage.

The core idea is to organize What/Why first (Analyze), design the How (Design), implement with TDD (Implement), and verify with E2E/QA (Test). The entire process is naturally connected to GitHub Issues, so you can always resume work even if a conversation breaks.

If you’re curious about how this plugin was built, check out SDD Plugin Development — From Prototype to Completion.

Github Sponsor Buy me a coffee

Was my blog helpful? Please leave a comment at the bottom. it will be a great help to me!

App promotion

You can use the applications that are created by this blog writer Deku.
Deku created the applications with Flutter.

If you have interested, please try to download them for free.

word learning app for kids

BlaBoo

Korean TOPIK vocabulary app

TOPIK words

Japanese vocabulary app

Japanese words

Chinese HSK vocabulary app

HSK words