はじめに
ども！今月はがっつりと開発期間をいただいて、社内で活用できるサービスを作成しつつ、AIとの開発検証を進めている龍ちゃんです。作るものが多くてあっちにフラフラこっちにフラフラって感じです。
今回は、「Claude Code革命！3フェーズ開発で効率的な開発：計画→実装→検証術」で提唱した「計画ドキュメント」を用いての開発を3カ月ほど続けたので、そこに対する知見を書いていこうと思います。
結論は「計画ドキュメント」ってめちゃくちゃ大事じゃね？ってお話です。
問題：AIに丸投げすると何が起きるか
技術選定を任せる危険性
開発を進めていく中で、最も課題となったのが「AIに技術選定を委ねてしまう」という問題でした。
CRUDの4つの要素のうち、SWRが最適化されているのは主にRead（データ取得）の部分です。Create、Update、Deleteの3/4については本来の用途から外れているにも関わらず、統一性を重視して全てSWRで実装しようとしていました。
人間の開発者であれば「SWRの実装が複雑になるようであれば、素直にAxiosを使用した方が良い」という判断ができます。しかし、AIにはこうした経験に基づく技術的判断や、ライブラリの適切な使い分けに関する感覚が不足しているようです。
システムプロンプトで「SWRを絶対使うように」って書いていたので、技術選定をしたのは人間なのですがそれに対する課題などの指摘は特にないってのが問題ですね。
AIの限界：誤字脱字と文脈の理解
プロンプトを通じたやり取りで発生する問題も重要な課題でした。
入力に誤字脱字が含まれている場合、AIはそれを修正することなく処理を継続してしまいます。技術用語の誤入力などがあっても、人間であれば文脈から推測して修正できるような内容でも、AIは字面通りに解釈して間違った方向に進んでしまうことがあります。
この結果、想定していたアーキテクチャから逸脱した実装が生成されたり、設計方針に一貫性がなくなったりする問題が発生しました。
具体例として、README.mdに「SWRを必ず使用すること」という記述があったのですが、これが問題の原因となりました。Orvalの設定を適切に調整すれば回避できた問題でしたが、全てのエンドポイントに対してAxiosとSWRの両方のクライアントが生成される状況で、AIは一貫してSWRを選択し続けていました。
根本原因：意思決定の不在
これらの問題の本質は、人間が行うべき意思決定をAIに委ねてしまっている点にあります。
人間の開発者は、明文化されていない暗黙知に基づいて技術的判断を行うことがあります。「この技術領域では一般的にこのようなアプローチを取る」といった、体系化されていない経験則や業界標準に関する知識です。
こうした暗黙知は、各開発者の経験や学習によって蓄積されたものですが、現在のAIには十分に備わっていないと感じています。もちろん、私の技術力が不足しているため、AIの能力を十分に引き出せていない可能性もありますが、この差を埋める仕組みが必要です。
その仕組みこそが、計画ドキュメントによる意思決定の明文化なのです。
解決策：計画ドキュメント = 意思決定の場
人間同士の協働 vs AI協働の違い
人間同士での開発とAI協働での開発では、「暗黙知の共有レベル」に大きな差があります。
人間同士での協働の場合：
- 共通の技術的背景知識を前提とした議論が可能
- 「一般的にはこのようなアプローチを取る」という共通認識
- 文脈を理解した柔軟な修正と提案
- 暗黙の了解による効率的なコミュニケーション
AI協働の場合：
- 明示的に指示された内容のみに基づく判断
- 技術的なベストプラクティスの理解が限定的
- プロンプトの内容に対する忠実な実行
- 全ての判断基準の明文化が必要
つまり、AI協働においては全ての意思決定プロセスを文書化することが不可欠となります。
計画ドキュメントで決めること
計画ドキュメントで明文化すべき要素は、主に以下の4つです：
技術選定：
- 選定理由とともに、採用しない選択肢（禁則事項）についても記載
- ライブラリ間の使い分け基準の明確化
- 例：SWRはデータフェッチ（Read）操作のみに使用し、CUD操作にはAxiosを使用する
アーキテクチャ方針：
- フロントエンド・バックエンド間の責任境界
- エラーハンドリングの統一方針
- 状態管理の方法と各層の責務
API設計：
- エンドポイントの命名規則と構造
- レスポンス形式の統一ルール
- エラーレスポンスの標準フォーマット
実装方針：
- ディレクトリ構成とファイル配置のルール
- コンポーネント設計のガイドライン
- テスト方針とカバレッジ基準
意思決定と実行の分離
効果的なAI協働を実現するには、意思決定フェーズと実行フェーズを明確に分離することが重要です。
- 人間の役割： 何を作るか、どのような方針で開発するかを決定する
- AIの役割： 決定された方針に従って、実際のコードを生成・組み立てる
この役割分担により、AIの長所である「高速で大量のコード生成」を活かしながら、人間の「経験に基づく技術判断」を適切に反映できるようになります。
計画の品質が成果物の品質を決定するのは開発の基本原則ですが、特にAI協働においては「計画ドキュメントがプロジェクトの成否を左右する」と言えるでしょう。
実行の標準化：パーツと自動生成
品質保証としてのパーツ化
実際の開発では、意思決定した内容を「パーツ」として標準化することで品質を保証できます。これはソフトウェア工学における品質管理の考え方と共通しています。
システム開発において、個々のコンポーネントの品質がシステム全体に与える影響は重大です。一つのコンポーネントに不具合があると、それがシステム全体の信頼性を損なう可能性があります。プログラムにおいては多少の技術的負債を抱えても稼働し続けることは可能ですが、基盤となるパーツがすべて品質に問題を抱えている場合は、深刻な影響が生じます。
特にフロントエンドを開発する際は、外部のAPIや自作のAPIをパーツとしてとらえることで、作業領域が明確化されます。
人間の役割：
- 作成すべき機能と要件を明確に定義する
- 使用するパーツの選択と品質基準の設定
- パーツの妥当性と整合性を検証する
パーツ/自動生成の役割：
- 実装方法を標準化し、一貫性を保つ
- コードの品質を一定レベルに維持する
- 再利用性を高め、開発効率を向上させる
AIの役割：
- 定義されたパーツを適切に組み合わせて実装する
- ボイラープレートコードの大量生成を効率化
- 人間が決定した設計方針に従ってコードを構築する
実例：自動生成パイプライン
具体例として、OpenAPIスペックから型定義を自動同期するパイプラインを構築した際の事例をご紹介します。
// DTO定義（人間による意思決定）
interface UserCreateRequest {
name: string;
email: string;
role: 'admin' | 'user';
}
// 型定義とAPI関数は自動生成
const createUser = async (data: UserCreateRequest) => {
return axios.post<UserResponse>('/api/users', data);
};
この実装において重要なポイントは、DTO定義という設計判断は人間が行い、実行部分（型定義生成、API関数生成）は自動化している点です。これにより、設計の一貫性を保ちながら実装効率を大幅に向上させることができました。
参考事例：Shadcn/uiのアプローチ
Shadcn/uiは、UIコンポーネント開発において「パーツ化」の優れた事例を提供しています。
このライブラリが革新的な点は、UIコンポーネントを標準化された「パーツ」として提供し、開発者が「どのコンポーネントを使用するか」という意思決定に集中できる環境を作り出していることです。AIは「パーツを選択して適切に組み合わせる」という作業に集中でき、結果として開発効率と品質の両立を実現しています。
この考え方は、API接続層やビジネスロジック層にも応用可能であり、AI協働開発における有効なパターンとなり得ると考えています。
実践：意思決定を握る3原則
原則1：計画ドキュメントでの明文化
実施内容：
- 技術選定の理由を具体的かつ詳細に文書化
- 実装方針を明確で実行可能なレベルまで記述
- 暗黙知となっている判断基準の言語化
明文化の範囲について： 理論的にはどこまで詳細化しても構いませんが、コンテキスト量の制約があることを考慮する必要があります。特にClaude等のLLMを使用する場合、トークン制限により詳細すぎる文書は処理できなくなる可能性があります。このバランス調整は現在の技術的制約として受け入れる必要があります。
実践的な運用方法： バックエンドとフロントエンドを並行開発する場合、計画ドキュメントに加えて具体的な実装手順をToDo形式で管理することを推奨します。進捗を可視化することで、AIツールが予期せず停止した場合でも、明確な再開ポイントを確保できます。
原則2：パーツによる実行の標準化
実施内容：
- 再利用可能なコンポーネント・関数の設計と整備
- API接続の標準化（型定義、エラーハンドリング含む）
- 開発ツール（Linter、Formatter等）の統一と自動化
品質保証の重要性： 個々のパーツの品質は、システム全体の安定性に直結します。不適切な設計のパーツを多数組み合わせると、保守性や拡張性に深刻な問題が生じる可能性があります。そのため、パーツ設計段階での品質基準の設定と検証が不可欠です。
原則3：検証による継続的改善
実施内容：
- 計画と実装結果の差分分析と記録
- 発見された問題点や改善点の体系的な蓄積
- 得られた知見の次回プロジェクトへの適用
現実的な視点の重要性： 完璧な計画ドキュメントや仕様書を最初から作成することは現実的ではありません。開発過程で「より良いアプローチが明確になる」ことは自然な現象です。
そのような状況では、変更の必要性を適切に判断し、修正された方針で実装を完了させることが重要です。完了後には計画と実装の差分を分析し、その経験を将来のプロジェクトに活かすことで、継続的な改善を図ることができます。
まとめ：意思決定は人間、実行はAI
本記事では、3ヶ月間のAI協働開発を通じて得られた実践的な知見をもとに、効果的な協働体制の構築について詳しく解説してきました。
重要ポイントの整理：
- 技術選定の主導権確保 – AIに技術的判断を委ねることのリスクと、経験に基づく適切な技術選択の重要性
- 計画ドキュメントによる意思決定の明文化 – 暗黙知の言語化と、全ての判断基準の明確化の必要性
- 意思決定と実行の明確な分離 – 人間とAIの適切な役割分担による効率化の実現
- パーツ化による実行の標準化 – 品質保証と再利用性向上のための設計アプローチ
- 継続的改善による知見の蓄積 – 完璧性よりも学習と改善を重視したアプローチ
結論として、現在のAI協働開発においては、人間が意思決定を行い、AIが実行を担当するという役割分担が最も効果的であると考えられます。
AI技術は急速に進歩していますが、現時点では経験に基づく技術的判断や、コンテキストを考慮した柔軟な意思決定において、人間の能力に及ばない側面があります。一方で、大量のコード生成や、定められたパターンに従った実装作業においては、AIの方が高速かつ正確に処理できます。
この技術特性を理解し、適切な役割分担を実装することで、AI協働開発の真価を発揮することが可能になります。
実践への提案
AI協働開発を検討されている方は、まず「計画ドキュメント」の作成から始めることをお勧めします。初期段階では作成コストが高く感じられるかもしれませんが、中長期的には開発効率と成果物の品質において大幅な改善効果が期待できます。
この記事で紹介した3原則と実践的アプローチが、皆さんのAI協働開発プロジェクトの成功に寄与できれば幸いです。
