[SDD Plugin] 適用したエンジニアリング — AIエンジニアリング4つのパラダイムで分析

概要

SDD（Spec-Driven Development）PluginはClaude Code用プラグインで、GitHub Issueベースの4段階プロセス（分析→設計→実装→テスト）を通じてAIと体系的に協力して開発できるようにサポートします。この記事では一歩引いて、このプラグインにどんなAIエンジニアリング原理が適用されているかを分析してみます。

SDD Pluginの全体構造と使い方はSDD Pluginの全体構造と使い方で、作った背景はAIコーディングの落とし穴と解決の方向性で、開発過程はプロトタイプから完成までで扱っています。

AIエンジニアリング4つのパラダイムの詳しい説明はAIエンジニアリング4つのパラダイム — Prompt, Context, Agentic, Harnessをご覧ください。

Prompt Engineering — スコープを制限する指示

SDD Pluginで最も重要なプロンプトエンジニアリングは、What/WhyとHowを分離することでした。

AIは質問を受けるとすぐに技術的な実装方法（How）を語ろうとする傾向があります。しかしWhat/Whyが整理されていない状態でHowを議論すると、方向がずれる可能性があります。

analyze.mdではこれを明示的にブロックします。

Focus ONLY on What and Why. Do NOT discuss How (technical implementation).

この一行がAIの行動を大きく変えます。分析段階では要件の本質にだけ集中し、技術的な議論は設計段階に自然に流れます。

また各段階の成果物テンプレートもプロンプトエンジニアリングの一部です。テンプレートが出力形式を事前に定めているため、AIが一貫した構造で結果を作ります。

## 要約
- リクエスト種別:
- 一行要約:
- リクエスト背景:

## 機能リスト
| # | 機能 | 説明 |

Context Engineering — 必要な情報だけをロードする構造

SDD PluginでContext Engineeringが適用されている場所は大きく2つです。

SKILL.mdのモジュール化

開発過程の記事でも触れましたが、最初はすべてのプロセスをSKILL.md一つに入れていました。しかしこうすると/sdd analyzeを実行する時にtest.mdの内容まで全部コンテキストにロードされてしまいます。

# 変更前: すべてのプロセスが一つのファイルに
SKILL.md（500行） → 全部コンテキストにロード

# 変更後: ルーター + 個別コマンドファイル
SKILL.md（ルーター、約60行） → commands/analyze.mdだけ追加ロード

11個のコマンドがありますが、一度に1つだけコンテキストに入ります。トークン使用量が減り、AIが不要な情報に混乱するのも防げます。

GitHubから必要な成果物だけを取得

設計段階では分析結果が必要で、実装段階では設計結果が必要です。この時Issueのすべてのcommentを取得するのではなく、マーカーを使って必要な成果物だけをフィルタリングします。

# すべてのコメントをコンテキストに入れる代わりに
gh api .../comments --jq '.[].body'

# マーカーが含まれるコメントだけ取得
gh api .../comments --jq '.[] | select(.body | contains("sdd:analyze:output")) | .body'

Issueに一般的な会話コメントが数十個付いていても、成果物マーカーがあるコメントだけ正確に取得できます。

Agentic Engineering — エージェントと反復ループ

SDD Pluginで最も目立つAgentic Engineering技法は、役割別エージェント分離と自己改善ループです。

探索専用エージェント

設計段階で既存コードベースを分析する際、メインエージェントが直接行わず専用探索エージェントに委任します。

Explore the codebase using a dedicated Explore agent (model: "sonnet")

探索作業は速いモデル（Sonnet）で十分なので、コストと速度を最適化できます。メインエージェントは探索結果を受け取って設計に集中します。

AIレビューループ

すべての段階の成果物はai-review.mdに定義された独立レビューループを通ります。

Execute the following loop (maximum 3 rounds):
  1. Self-Review: 自分で成果物をレビュー
  2. AI Review: 独立エージェントが別途レビュー
  3. Evaluate: 合否判定
  → 合格なら終了、不合格なら修正して次のラウンドへ

核心はレビューするエージェントが作業したエージェントと独立しているということです。自分で作った結果を自分でレビューすると見落としがありえますが、別のエージェントがレビューすれば違う観点から問題を発見できます。

レビュー基準も段階ごとに異なります。

段階	レビュー基準
analyze	機能が明確に定義されているか？What/Whyは十分か？漏れた要件はないか？
design	設計が要件と一致するか？実現可能か？アーキテクチャと一貫性があるか？
implement	コード品質は？テストカバレッジは？パターンの一貫性は？PR説明は正確か？
test	テストカバレッジは十分か？エッジケースは扱われているか？リグレッションリスクは？

Harness Engineering — 実行環境の設計

SDD Plugin自体が一つのHarnessと見ることができます。AIが作業するプロセス、順序、制約条件を事前に定義しているのですから。

宣言型プロセス制御

コードでAIを制御するのではなく、Markdownでプロセスを宣言します。SKILL.mdが「このコマンドが来たらこのファイルを読め」と案内し、各commandファイルが「この段階ではこれをして、あれはするな」と制約します。

この方式のメリットはプロセスの修正がとても簡単なことです。Markdownファイルを編集するだけでAIの行動が変わります。コードの修正、ビルド、デプロイのプロセスは不要です。

GitHubベースの状態管理

ラベルで進捗を管理するのもHarness Engineeringです。AIが勝手に段階をスキップしたり、すでに完了した段階を再実行するのをラベルチェックで防止します。

sdd:analyze → sdd:design → sdd:implement → sdd:test → sdd:done

rollbackコマンドも同様です。前の段階にだけ戻れて、先にスキップはできません。AIに自由を与えつつ、プロセスの順序は環境が強制します。

権限設定

Claude Codeのsettings.jsonを通じてAIの権限を制限することもできます。

{
  "permissions": {
    "allow": [
      "Bash(ls:*)", "Bash(wc:*)",
      "Read(/path/to/sdd-plugin/skills/sdd/**)"
    ]
  }
}

読み取り専用のbashコマンドだけ許可し、スキルファイルだけ読み取り可能に制限すれば、安全にプラグインを使用できます。

4つのパラダイムが交わる地点

SDD Pluginを4つのパラダイムで分析すると、それぞれが独立して作用するのではなく互いに噛み合って動作することがわかります。

パラダイム	SDD Pluginでの役割
Prompt	What/WhyとHowの分離、成果物テンプレートで出力形式を制御
Context	SKILL.mdのモジュール化、マーカーベースの成果物フィルタリング
Agentic	探索エージェントへの委任、独立レビューループ（最大3ラウンド）
Harness	宣言型プロセス、ラベルベースの状態管理、権限設定

例えばanalyzeコマンドを実行すると：

Harness: ラベルを確認して正しい段階か検証
Context: Issue bodyから要件を読み、必要な成果物だけコンテキストにロード
Prompt: 「What/Whyだけ分析してください、Howは議論しないでください」でスコープを制限
Agentic: AIが分析を実行し、独立エージェントがレビューするループを実行

4つのレイヤーが一つのコマンドの中で同時に動作します。

まとめ

この記事では、SDD Pluginに適用されたAIエンジニアリング技法を4つのパラダイムで分析しました。

SDD Pluginを作りながら最も強く感じたのは、AIをうまく活用するにはプロンプト一つをうまく書くだけでは不十分ということでした。情報をどう管理するか（Context）、エージェントをどう構成するか（Agentic）、どんな環境で実行するか（Harness）まで一緒に設計してこそ、AIが安定して良い結果を出せるのです。

AIと一緒に開発プロセスを考える方々のお役に立てれば幸いです。