目次
概要
Claude CodeのようなAIコーディングツールを実務で使っていると、コードを素早く書けるというメリットの裏に隠れた様々な問題に出会います。この記事ではその問題を整理し、SDD（Spec-Driven Development）Pluginを作ることになった背景を共有します。
この記事はSDD Pluginシリーズの一部です。完成したプラグインの構造と使い方はSDD Pluginの全体構造と使い方で、開発過程はプロトタイプから完成までで、適用したエンジニアリング原理はAIエンジニアリング4つのパラダイムで分析で扱っています。
AIコーディングの落とし穴
Claude Codeを使えば驚くほどのスピードでコードが書けます。「この機能を作って」と一言いえば、あっという間にコードが生成されます。最初は感動しましたが、実務で繰り返し使っているうちに、いくつかの問題が目につくようになりました。
要件分析なしでいきなりコーディング
AIに「この機能を作って」と言うと、AIはすぐにコードを書き始めます。しかし**What（何を）とWhy（なぜ）**が明確でない状態で作られたコードは、望んでいた方向と違うことがあります。そして方向がずれていることに気づいた時には、すでにかなりのコードが書かれた後です。
設計なしの実装
既存のコードベースにはそれなりのアーキテクチャとパターンがあります。しかしAIはそれを無視して独自の方法で実装することが多いです。結果として既存のコードとスタイルが異なるコードが混在し、保守が難しくなります。
テストの不在
素早く作れたもののテストコードがないため、後で修正する際にサイドエフェクトの把握が困難です。AIが作ったコードなので、本人もどんなロジックか正確に把握できていないこともあります。
会話の喪失
Claude Codeの会話が長くなるとコンテキストが圧縮され、会話が途切れると以前のコンテキストが消えてしまいます。どこまで進んだか、どんな決定をしたかを記憶に頼らざるを得ない状況が繰り返されます。
既存の開発プロセスの限界
チームがすでに開発プロセスを持っていても、AIコーディングツールを使う時はそのプロセスに従うのが難しいです。
AIに「このプロセスに従って」と毎回説明するのは非効率で、人によって説明の仕方が違うため一貫性も落ちます。結局プロセスがあってもAIと一緒に働く時は無視されがちです。
Claudeでどこまでできるか
こうした問題を認識した後、まずAIと一緒に開発するプロセスを自分で試してみました。GitHub CLIをインストールして、Claude Codeと一緒に以下のような流れで作業しました。
- タスク分析: GitHub Issueや要件をClaudeに渡して「この内容を分析して問題点とやることを整理して」と依頼
- 作業内容確認: Claudeが分析した内容を確認し、合っていない部分は「ここはこう修正すべきでは？」とフィードバック
- 実装: 分析結果に満足したら実装を指示
- AIコードレビュー: 実装が終わったら「修正内容をレビューして」「リファクタリングできる部分ある？」でコード品質を向上
- セルフコードレビュー: AIレビュー結果を確認し、追加で自分でもレビュー
- コードレビュー対応: 他のメンバーのレビューコメントもClaudeに渡して対応方法を分析
このプロセスを繰り返しながら、いくつかのことがわかりました。
- AIは意外と信頼できる。分析やレビュー結果がかなり正確でした。
- ほぼすべての開発段階でAIを活用できました。
- しかし100%AIに任せるのは無理でした。人がタスクを説明し、結果を確認し、適切に判断するプロセスが必ず必要でした。
コード自動生成ツールからSDDへ
最初はAIとは別に、設計書をもとにBoilerplateコードを自動生成するツールを作っていました。Drawioで画面を描き、スプレッドシートでコンポーネントを定義し、コードジェネレーターで基本コードを作る方式でした。
しかしこのツールを開発しながら、Claude CodeのSkill機能だけでもコード自動生成ツールレベルの結果を出せるという話を聞きました。そこで方向を転換しました。別のツールを作る代わりに、AIが作業しやすい開発プロセス自体を設計しようということでした。
すでにSpec-Driven Development（SDD）というアプローチが存在していました。仕様（Specification）を先に定義して、その仕様をもとにAIが自動で開発する方法論です。
これらのオープンソースを参考にしながら、自分の実務経験に合ったClaude Code用のSDD Pluginを作ることに決めました。
解決の方向性
開発プロセス自体をClaude Codeのプラグインにすれば、以下のメリットがあると判断しました。
- コマンド一つでプロセスを実行できる。毎回AIにプロセスを説明する必要がない。
- すべての成果物がGitHubに保存されるので、会話が途切れても続きから作業できる。
- チーム全体が同じプロセスに従える。プラグインをインストールするだけ。
プロセス設計
1. 開発プロセス分析
具体的なプロセスを設計するために、まず私たちが開発する時に経る段階を分析する必要があると思いました。そこで、一般的な開発プロセスをClaudeに聞いてみました。
- 要件分析（Requirements Analysis）
- 設計（Design）
- 実装（Implementation）
- コードレビュー（Code Review）
- テスト（Testing）
- デプロイ（Merge & Deploy）
- モニタリング（Monitoring）
このうちデプロイとモニタリングはAIと一緒にする作業ではないと判断したため、この2つ以外のプロセスを生成AIと一緒に作業できるようにしたいと思いました。
2. InputとOutputの定義
次に、各プロセスで生成AIが作業しやすいInputとOutputを定義しました。実装段階ではコードの精度と品質のためにTDD（Test Driven Development）で進めることにしました。
- 要件分析（Requirements Analysis）
- Input: 要求定義書
- Output: 要求定義書の分析結果
- 設計（Design）
- Input: 要求定義書の分析結果
- Output: 設計書
- 実装（Implementation: TDD）
- Input: 設計書
- Output: コード
- コードレビュー（Code Review）
- Input: コード
- Output: Pull Request
- テスト（Testing）
- Input: 要求定義書の分析結果、設計書、コード
- Output: E2Eテストコード、QAチェックリスト
3. AIと人の開発プロセス追加
InputからOutputまで行う必要があるAIと人の詳細な開発プロセスを追加しました。
1）要件分析（Requirements Analysis）
| 順序 | 主体 | 作業 |
|---|---|---|
| Input | - | 要求定義書 |
| 1 | AI | 要求定義書分析 |
| 2 | AI(Self) | 分析結果セルフレビュー |
| 3 | AI(Agent) | 分析結果エージェントレビュー |
| 4 | 人 | 分析結果確認 |
| Output | - | 要求定義書の分析結果 |
2）設計（Design）
| 順序 | 主体 | 作業 |
|---|---|---|
| Input | - | 要求定義書の分析結果 |
| 1 | AI | 設計 |
| 2 | AI(Self) | 設計セルフレビュー |
| 3 | AI(Agent) | 設計エージェントレビュー |
| 4 | 人 | 設計確認 |
| Output | - | 設計書 |
3）実装（Implementation: TDD）
| 順序 | 主体 | 作業 |
|---|---|---|
| Input | - | 設計書 |
| テストと実装計画 | ||
| 1 | AI | テストと実装計画作成 |
| 2 | AI(Self) | 計画セルフレビュー |
| 3 | AI(Agent) | 計画エージェントレビュー |
| 4 | 人 | 計画確認 |
| RED：失敗するテスト作成 | ||
| 5 | AI | テストコード作成 |
| 6 | AI(Self) | テストコードセルフレビュー |
| 7 | AI(Agent) | テストコードエージェントレビュー |
| 8 | 人 | テストコード確認 |
| GREEN：テストを通過するコード作成 | ||
| 9 | AI | 実装コード作成 |
| 10 | AI(Self) | コードセルフレビュー |
| 11 | AI(Agent) | コードエージェントレビュー |
| 12 | 人 | コード確認 |
| REFACTOR：リファクタリング | ||
| 13 | AI | リファクタリング実施 |
| 14 | AI(Self) | コードセルフレビュー |
| 15 | AI(Agent) | コードエージェントレビュー |
| 16 | 人 | コード確認 |
| Output | - | コード |
4）コードレビュー（Code Review）
| 順序 | 主体 | 作業 |
|---|---|---|
| Input | - | コード |
| 1 | AI(Self) | コードセルフレビュー |
| 2 | AI(Agent) | コードエージェントレビュー |
| 3 | 人 | コードレビュー |
| 4 | 人 | PR作成＆Merge |
| Output | - | Merged Pull Request |
5）テスト（Testing）
| 順序 | 主体 | 作業 |
|---|---|---|
| Input | - | 要求定義書の分析結果、設計書、コード |
| 1 | AI | 要求定義と設計書、コードを読んでE2Eテストコード作成 |
| 2 | AI | 手動テストチェックリスト作成 |
| 3 | AI | 作成内容レビュー |
| 4 | 人 | 作成内容確認 |
| 5 | 人 | 手動テスト実施 |
| Output | - | E2Eテストコード、QAチェックリスト |
各段階で共通的に適用されたパターンは、AIが作業し、AIがセルフレビューし、別のAIエージェントがレビューし、人が最終確認する多重検証構造です。
① Input → ② AI作業 → ③ AIセルフレビュー → ④ AIエージェントレビュー → ⑤ ユーザー確認 → Output4. InputとOutputの管理
InputとOutputをどう管理するかを悩みました。
Claudeは会話が長くなるとコンテキストを圧縮するため、精度が落ちる問題があります。そのため、各段階の成果物をドキュメントでしっかり管理する必要がありました。
最初はMarkdownファイルでGitリポジトリで管理することも考えましたが、GitHub Issueで管理する方式を選びました。理由は以下の通りです。
- ファイルで管理すると、少しの修正でも毎回コミットが必要になります。
- 一時的な対応やバグ修正など、作業が終わったものもファイルがリポジトリに残り続けます。
- Issueは作業が終わったらクローズできるので、完了した作業と進行中の作業を明確に区別できます。
まとめ
この記事では、AIコーディングツールの落とし穴、既存プロセスの限界、そして実際にAIと協業してみた経験をもとに、SDD Pluginを作ることになった背景を整理しました。
核心は「AIが素早くコードを書くこと」ではなく、**「AIが正しい方向で作業するようにプロセスを設計すること」**でした。
この記事で整理した開発プロセスの分析と設計をもとに、実際にClaude Code用のSDD Pluginを制作しました。次の記事では、完成したプラグインの全体構造と使い方を紹介します。
次の記事: SDD Pluginの全体構造と使い方
私のブログが役に立ちましたか？下にコメントを残してください。それは私にとって大きな大きな力になります！
アプリ広報
Dekuが開発したアプリを使ってみてください。Dekuが開発したアプリはFlutterで開発されています。興味がある方はアプリをダウンロードしてアプリを使ってくれると本当に助かります。
