[SDD Plugin] SDD Pluginの全体構造と使い方

概要

SDD（Spec-Driven Development）PluginはClaude Code用プラグインで、GitHub Issueベースの構造化された開発プロセスを通じて、AIと協力して体系的に開発できるようにサポートします。この記事では、SDD Pluginの4段階プロセス、コマンド、GitHub連携、使い方まで一通り見ていきましょう。

このプラグインを作った背景はAIコーディングの落とし穴と解決の方向性で、開発過程はプロトタイプから完成までで、適用したエンジニアリング原理はAIエンジニアリング4つのパラダイムで分析で扱っています。

完成したプラグインはGitHubで公開しています。興味のある方は以下のリンクをご覧ください。

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

SDDプロセスとは

SDD（Spec-Driven Development）は仕様（Spec）中心の開発方法論です。コードを書く前に十分な分析と設計を行い、実装はTDD（Test-Driven Development）方式で進めます。こうすることで、AIが書いたコードであっても明確な要件と設計に基づいているため、保守性と拡張性が向上します。

4段階プロセス

1. 要件分析（What/Why） → 2. 設計（How） → 3. 実装（TDD） → 4. テスト（E2E/QA）

Stage 1: 要件分析（What / Why）

何を作るのか、なぜ必要なのかにだけ集中します。技術的な実装方法（How）はこの段階では議論しません。

リクエスト種別の分類（新機能 / 機能改善 / バグ修正 / リファクタリング）
機能リストの導出
優先度の決定

この段階の核心はWhat/WhyとHowを分離することです。AIはHowの答えをすぐ出そうとする傾向があるので、意図的に技術的な議論をブロックします。

Stage 2: 設計（How）

Stage 1で整理した要件をもとに、どうやって実装するか設計します。

既存コードベースの探索（専用探索エージェントを活用）
影響範囲の把握
ファイル構造とデータモデルの設計
制約事項とリスクの特定
PR単位の分離（大きな機能は複数PRに分割）

大規模な機能の場合、この段階で自動的にChild Issueを作成して、各PRを独立して管理します。

Stage 3: 実装（TDD）

PR単位でRed → Green → Refactorサイクルを繰り返します。

3-0. PRキックオフ: テスト計画 + 実装計画の策定
3-1. Red: 失敗するテストを作成
3-2. Green: テストを通過する最小限の実装
3-3. Refactor: コード改善
3-4. PR作成とコードレビュー
→ 次のPRで繰り返し

各ステップでAI自己レビュー + 独立エージェントレビュー（最大3ラウンド） + ユーザー確認という二重検証を行います。

Stage 4: テスト（E2E / QA）

Stage 3でUnit/UIテストはすでに完了しているので、この段階ではE2EテストとQAに集中します。

4-0. テストセットアップ: 既存テスト環境の検出と設定
4-1. E2Eテスト: AIがE2Eテストコードを作成して実行
4-2. QAチェックリスト: 手動テスト用チェックリストの作成
4-3. 手動QA: ユーザーがチェックリストに基づいて直接テスト
4-4. 結果レビュー: 失敗項目はStage 3に戻ってTDD修正

Parent Issue（複数のChild Issueがある場合）では、すべてのChild Issueが完了した後に機能全体のE2Eテストを実施します。

各段階の共通パターン

すべての段階は同じパターンに従います。

① インプット → ② AI作業 → ③ AI自己レビュー → ④ 独立エージェントレビュー → ⑤ ユーザー確認 → 次の段階

コマンド一覧

SDD Pluginは/sddの後にコマンドを付けて使います。4段階プロセスを実行するコアコマンドと、作業を補助するユーティリティコマンドに分かれます。

コマンド	説明
`/sdd init [lang]`	リポジトリ初期化（Issueテンプレート、ラベル作成）
`/sdd analyze <issue>`	Stage 1: 要件分析（What/Why）
`/sdd design <issue>`	Stage 2: 設計（How）
`/sdd implement <issue>`	Stage 3: TDD実装（Red → Green → Refactor）
`/sdd test <issue>`	Stage 4: E2E/QAテスト
`/sdd resume <issue>`	現在の段階を自動検出して続行
`/sdd status <issue>`	進捗状況の確認
`/sdd review <issue>`	現段階の成果物に対するAIレビュー
`/sdd rollback <issue>`	前の段階に戻す
`/sdd help`	使い方の案内

使い方

実際にSDD Pluginを使う流れを順番に見ていきましょう。

1. インストール

まずClaude Codeでプラグインをインストールします。

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

2. リポジトリの初期化

インストールが完了したら、プロジェクトリポジトリで初期化を実行します。言語を指定すると、その言語のIssueテンプレートが設定されます。

/sdd init ja        # 日本語テンプレートで初期化

このコマンドを実行すると、以下が設定されます。

.github/ISSUE_TEMPLATE/に日本語Issueテンプレートをコピー
.github/.sdd-langに言語設定を保存
GitHubラベルの作成（sdd:analyze、sdd:design、sdd:implement、sdd:test、sdd:done）

3. Issueの作成

GitHubでSDDテンプレートを使ってIssueを作成します。4つのテンプレートから適切なものを選びます。

新機能
機能改善
バグ修正
リファクタリング

テンプレートにはリクエスト背景（Why）、機能説明（What）、**完了基準（DoD）**が構造化されているので、AIが分析に必要な情報を漏れなく受け取ることができます。

4. 開発プロセスの実行

Issueが準備できたら、各段階を順番に実行します。Issue番号を渡すだけです。

# Stage 1: 要件分析
/sdd analyze 123

# Stage 2: 設計
/sdd design 123

# Stage 3: 実装（TDD）
/sdd implement 123

# Stage 4: テスト
/sdd test 123

各段階でAIが作業を行い、自己レビュー後にユーザーに確認を求めます。ユーザーが承認すると、成果物がIssue commentに保存され、次の段階に進みます。

5. 作業の再開

Claude Codeの会話が途切れたり新しいセッションを始めた場合、resumeコマンドを使うとIssueのラベルと成果物を確認して、中断した地点から続けて作業できます。

/sdd resume 123     # 自動で現在の段階を検出して続行

6. 進捗状況の確認

現在のIssueがどの段階まで進んでいるか確認したい時に使います。

/sdd status 123

各段階の完了状況と現在の進捗を以下のような形式で表示します。

Issue #123: ユーザープロフィールページ開発
Stage: implement
- [x] Analyze: 完了
- [x] Design: 完了
- [ ] Implement: PR #1 進行中
- [ ] Test: 未着手

GitHub連携

SDD PluginのすべてのデータはGitHubに保存されます。別途データベースやファイル管理は不要です。

データの保存場所

各段階の成果物がどこに保存されるか整理すると以下の通りです。

データ	保存場所
要件（入力）	Issue body
分析成果物	Issue comment
設計成果物	Issue comment
現在の段階	Issue label
実装結果	Pull Request
テスト結果	Issue comment

ラベルで進捗を追跡

Issueに付くラベルで現在どの段階にあるか一目で把握できます。GitHubのIssue一覧でラベルフィルタリングするだけで全体の作業状況を管理できるので便利です。

ラベル	段階
`sdd:analyze`	要件分析中
`sdd:design`	設計中
`sdd:implement`	実装中
`sdd:test`	テスト中
`sdd:done`	完了
`sdd:child`	Child Issue

各段階が完了すると、自動的に前のラベルが削除され次のラベルが追加されます。

成果物マーカー

「次の段階で前の段階の結果をどうやって見つけるのか？」と気になるかもしれません。Issue commentに保存される成果物にはHTMLコメントマーカーが含まれており、このマーカーを通じて必要な成果物を正確に特定します。

<!-- sdd:analyze:output -->
分析結果の内容...
<!-- /sdd:analyze:output -->

このマーカーにより、次の段階で前の段階の成果物を自動的に読み込むことができ、resumeコマンドもこのマーカーを確認して進捗状況を判断します。

Multi-PRワークフロー

大規模な機能は一つのPRで処理するのが難しいです。SDD PluginはParent/Child Issue構造でこれを解決します。

Parent Issue #10: ユーザープロフィール機能
├── Child Issue #11: プロフィールAPI連携（PR #1）
├── Child Issue #12: プロフィールUI実装（PR #2）
└── Child Issue #13: プロフィール画像アップロード（PR #3）