[SDD Plugin] 開発過程 — プロトタイプから完成まで

概要

SDD（Spec-Driven Development）PluginはClaude Code用プラグインで、GitHub Issueベースの4段階プロセス（分析→設計→実装→テスト）を通じてAIと体系的に協力して開発できるようにサポートします。この記事では、このプラグインがどんな過程で作られたか、各Phaseで何を悩み、どんな試行錯誤があったかを共有します。

SDD Pluginの全体構造と使い方はSDD Pluginの全体構造と使い方で、作った背景はAIコーディングの落とし穴と解決の方向性で、適用したエンジニアリング原理はAIエンジニアリング4つのパラダイムで分析で扱っています。

ファイル構造

まず完成したプラグインのファイル構造を見てみましょう。開発過程を追いながらこの構造がどう作られたか理解するのに役立ちます。

sdd-plugin/
├── README.md
├── .claude-plugin/
│   └── marketplace.json               # マーケットプレイスメタデータ
└── plugins/sdd-plugin/
    ├── .claude-plugin/
    │   └── plugin.json                # プラグインメタデータ
    └── skills/sdd/
        ├── SKILL.md                   # コア: コマンドルーティング + 共通定義
        ├── commands/                  # 各コマンドの詳細プロセス
        │   ├── analyze.md
        │   ├── design.md
        │   ├── implement.md
        │   ├── test.md
        │   ├── resume.md
        │   ├── status.md
        │   ├── review.md
        │   ├── ai-review.md
        │   ├── init.md
        │   ├── rollback.md
        │   └── help.md
        └── templates/                 # 言語別テンプレート
            ├── en/                    # 英語
            ├── ko/                    # 韓国語
            └── ja/                    # 日本語

最も重要なファイルはSKILL.mdです。このファイルがClaude Codeに対して「どのコマンドが来たらどのファイルを読んでどう動作するか」を定義します。一般的なプログラミング言語でロジックを書くのではなく、Markdownでプロセスを記述するとAIがそれに従う構造です。

Phase 1: 基盤構築

最初に行ったのはClaude Codeプラグインの基本構造を作ることでした。

作ったもの

plugin.json: プラグイン名、バージョン、作者などのメタデータ
SKILL.md: コマンドルーティングと共通定義（ラベル、マーカー、言語設定など）
英語Issueテンプレート4種（バグ修正、新機能、機能改善、リファクタリング）
分析/設計成果物テンプレート

この段階で悩んだこと

最初はすべてのプロセスをSKILL.md一つに入れていました。しかしファイルがあっという間に数百行になり、Claude Codeが毎回全内容をコンテキストにロードするのは非効率だと気づきました。

そこでSKILL.mdはルーターの役割だけにして、各コマンドの詳細プロセスはcommands/ディレクトリの別ファイルに分離しました。/sdd analyzeを実行するとSKILL.mdがcommands/analyze.mdを読むよう案内する仕組みです。

Phase 2: 多言語対応

グローバルチームで使えるように日本語と韓国語のサポートを追加しました。

作ったもの

言語別Issueテンプレート（韓国語、日本語）
言語別成果物テンプレート
言語設定の保存（/sdd init jaで初期化すると.github/.sdd-langに保存）

翻訳ではなくローカライズ

単純な翻訳ではなく、各言語圏の開発文化に合わせて用語を選びました。例えば日本語のIssueテンプレートではバグ修正、新機能、機能改善、リファクタリングという用語を使っています。

翻訳キーを使う代わりに、言語ごとに完全なテンプレートを別ファイルで管理することにしました。ファイルは少し増えますが、各言語に合った自然な表現が使え、特定の言語にだけ必要な説明を追加するのも簡単です。

Phase 3: Issueテンプレート改善

実際に使ってみながらGitHub Issueテンプレートを改善しました。

改善ポイント

最初はIssueテンプレートが自由すぎました。タイトルと本文だけのシンプルな形だったので、人によって書く内容が異なり、AIが分析する時に必要な情報が抜けることが多かったです。

そこでリクエスト背景（Why）、機能説明（What）、**完了基準（DoD）**を構造化して入力するようにテンプレートを改善しました。

name: '新機能'
description: '新機能をリクエストします'
labels: ['sdd:analyze']
body:
  - type: textarea
    id: background
    attributes:
      label: 'リクエスト背景'
      description: 'この機能はなぜ必要ですか？'
      value: |
        - 問題 / 動機:
        - ユーザーフィードバック: (あれば)

  - type: textarea
    id: description
    attributes:
      label: '機能説明'
      description: '何を作る必要がありますか？'
      value: |
        - 一行要約:
        - 詳細説明:
        - 対象画面:
        - 参考資料:

  - type: textarea
    id: done
    attributes:
      label: '完了基準（Definition of Done）'
      description: 'この機能が完了とみなされる基準は？'
      value: |
        - [ ] 基準1:
        - [ ] 基準2:

こうすることでIssue作成時点で必要な情報が漏れなく入り、AIが分析する際も構造化されたインプットを受け取れます。

Phase 4: resumeコマンド追加

実際に使ってみて最も不便だったのは、会話が途切れた時に続きから作業するのが難しいということでした。特にimplement段階は複数のPRにまたがるため、会話が途切れる可能性が高いです。

解決方法

この問題を解決するために/sdd resumeコマンドを追加しました。

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

resumeコマンドは以下のロジックで動作します。

Issueラベル（sdd:analyze、sdd:designなど）で現在の段階を判断
Issue commentで既存の成果物（分析結果、設計結果）を確認
関連PRの状態を確認
Parent Issueの場合、Child Issueの進捗状況を確認
中断した地点をユーザーに報告し、確認を得てから続行

すべての成果物がGitHubにマーカーと一緒に保存されているため、会話が完全に新しく始まってもGitHubからコンテキストを復元できます。これが「GitHubネイティブ」設計の最大のメリットでした。

実際に使ってみる

簡単なプロジェクトを作って全プロセスをテストしてみました。

# 1. 初期化
/sdd init ja

# 2. Issue作成（GitHubでテンプレートを使用）

# 3. 分析
/sdd analyze 1

# 4. 設計（分析完了後に続行）
/sdd design 1

# 5. 実装（TDD）
/sdd implement 1

# 6. テスト
/sdd test 1