プロジェクトの概要
そのプロジェクトは最初からAI駆動開発を前提に設計されていた。
フローはシンプルだった。
- Excelで書かれた設計書をMCPサーバ経由でMarkdownに変換
- 変換されたMDファイルと、スケルトン状態のアーキテクチャをAIに渡す
- プロンプトで「設計書に従って実装してください」と指示する
個人で試したときは正直感動した。設計書を読み込んだAIが、スケルトンの構造を理解した上でコードを書いてくれる。「これが普及したらエンジニアの仕事はどうなるんだ」と思うくらいだった。
実装で起きた問題
AIが設計書を最後まで読んでいなかった
最も発見が遅れた問題がこれだった。
AIはプロンプトで明示的に指示しないと、長いドキュメントを途中で読むのをやめる。設計書が100行あっても、最初の50行だけで判断して実装を始めることがある。しかもエラーも警告も出ない。それっぽいコードが返ってくる。
AIが正しく読んだと思い込んだままレビューに出してしまい、設計書と突き合わせて初めて「後半の仕様が丸ごと実装されていない」と気づく——そういったことが繰り返された。
この問題はプロンプトの書き方次第でほぼ防げる。しかし、そのノウハウを事前に整理してチームに展開できていなかった。
# 設計書を最後まで読ませるプロンプトの例
「設計書を最初から最後まで全て読んだ上で、
読み終えたことを確認してから実装を始めてください」
完成品のどこが抜けているか、全部確認するしかなかった
設計書の読み取りが途中で止まると、実装の抜けがランダムな箇所に発生する。
「どこまで実装できていてどこが抜けているか」を示す手がかりがコードの中にない。結果として、設計書の全項目を1から照合するしかなかった。 AIに任せることで増えたはずの速度が、確認コストで消えた。
AIのコードを読むのは、自分で書くより難しい
これがチーム全体に効いた本質的な問題だった。
コードを読むのは書くより難しい。これは一般論だが、AIが生成したコードはさらに難しい。変数名や構造がある程度一貫していても、「なぜこう書いたか」という文脈が一切ない。
自分自身はさほど苦にならなかったが、レビュースキルが十分でないメンバーにとっては、AIが生成したコードの検証はかなりの苦痛だったようだ。コードを読み解く力がなければAIの出力を正しく検証できない。かといって読もうとすれば時間がかかる。AI活用の前提として、コードレビュースキルの重要性を見くびっていた。
スケジュールの前提を受け入れたまま進んでしまった
AI活用によってスケジュールが短縮される前提で計画が組まれていた。その前提に対して早い段階で疑問を呈せなかったことが、後の歪みにつながった。
AIがうまく動かなかったときの余白がなく、設計書の読み取りミスが発覚するたびにやり直しが発生した。スケジュールは変わらないまま。
「AIがうまくいかなかった場合」のリスクを事前に言語化して共有できていなかった。 その結果、「とりあえずAIが書いたコードで出す」という判断が増え、品質の問題が後工程に積み上がっていった。
なぜ失敗したか
問題を整理すると、一本の構造が見えてくる。
AIが設計書を途中で読むのをやめる
↓
実装に抜けが発生する（しかし気づきにくい）
↓
設計書の全項目を1から確認するしかない
↓
AIのコードを読み解くのに時間がかかる
↓
スケジュールの余白がなくプレッシャーがかかる
↓
確認が甘くなり、抜けが後工程まで残る
AIの問題ではなく、AIの特性を理解しないまま運用設計をしてしまったことが根本だった。
テストで起きた問題
このプロジェクトではUTを2種類に分けていた。
- UT1：コードのC0・C1カバレッジを100%にする
- UT2：業務ロジックが正しいことを検証する
UT1はAIが得意だった
UT1はシンプルだった。「このクラスのC0・C1カバレッジを網羅するテストコードを作成してください」とプロンプトに書くだけで、AIはテストコードを生成してくれる。
クラスが肥大化するにつれて一度のプロンプトでは網羅しきれず、何度も回す必要が出てきた。ただ、これは時間さえかければ解決する問題だった。
UT2はほぼ機能しなかった
問題はUT2だった。業務ロジックの正しさを検証するには、AIに複数の設計書を同時に読ませる必要がある。
- コンポーネント設計書
- DB設計書
- 外部IF設計書
- デシジョンテーブル
- そのコンポーネントで参照している全ての仕様
実装時と同じ問題がここでも発生した。プロンプトの書き方が少しでも甘いと、AIは途中までしか設計書を読まない。 複数のドキュメントを渡すぶん、読み飛ばしのリスクはさらに高くなった。
加えて、AIが生成するSQL（特にINSERT文）の精度が低く、誤りを指摘してAIに修正を投げ直す——というやり取りを何度も繰り返した。最終的には自分で書いた方が早かった、という結論になった。
テストの実装方針をAI任せにしてしまった
AIは自律的にテストの方針を提案してくれる。それ自体はありがたいのだが、方針を自分たちで決めないままAIの提案をそのまま各々が採用してしまい、テストの実装方法がバラバラになった。
モックの使い方、テストデータの管理方法、アサーションの粒度——同じプロジェクトの中で流儀が乱立した。後から統一しようとしても、AIが書いたテストコードを読み解くコストは実装コードと同じだけかかる。
テストの方針はチームで先に決め、AIにはその方針の中で動かす。その設計を怠ったことが失敗だった。CLAUDE.mdにテストの実装方針を明確に記載しておくなど、AIが迷わない環境を整えておく必要があるだろう。
対処したこと
問題が見えてきたあとに、以下のルールを追加した。
- 設計書読み取りの確認をプロンプトに必須化：AIに「全て読んだことを確認してから実装せよ」と明記する
- 実装チェックリストをAIに出力させる：コードと一緒に「実装した項目一覧」を返させ、設計書との照合を機械的にできるようにする
- テストの実装方針をCLAUDE.mdまたはそれに紐づくファイルに明記する：モックの使い方・テストデータの管理方法・アサーションの粒度など、チームとして決めた方針をAIが参照できる形で残しておく
学んだこと
AI駆動開発で本当に難しいのは、AIが失敗したことに気づく仕組みを自分たちで作ることだと思う。
AIは失敗してもエラーを出さない。それっぽい結果を返す。その「それっぽさ」を見破るには、結局のところ設計書を理解していて、コードを読める人間が必要になる。
そしてこのプロジェクト全体を通じて痛感したのは、プロンプトの書き方・設計書のフォーマット・テストの方針・レビューの基準を事前に標準化してチームに展開する、その旗振りを誰かがやらなければならなかったということだ。そしてそれは、プロジェクトに関わった自分たち自身の責任だった。
標準化がなければ、AIは各自がバラバラに使うツールになり、統一コストが積み上がる。「AIを使えばチームが速くなる」ではなく、「AIを正しく使える環境をどう設計するか」——これは巷でよく言われることではあるが、実際に痛い目を見て改めて腹落ちした。
AI活用の方針を吟味し、しっかり旗を振れる力量を自分たち自身が持てていなかった。ツールの問題ではなく、プロセス設計の問題として生産性が落ちた。このプロジェクトがまさにそうだった。
そして最後に、ひとつ面白い気づきがあった。
CLAUDE.mdに実装方針を書く、という行為は一見「AIへの指示書を作る」だけのように見える。しかし実際にやってみると、それはチームの暗黙知を言語化する作業に他ならない。「なんとなくこうしてる」「空気を読めばわかる」——そういった曖昧なまま共有されていたルールを、文字に落とし込む必要が生じる。
AIに伝わらないものは、実は人間にも伝わっていなかっただけだ。
CLAUDE.mdを整備することは、副次的に組織の開発プロセス改善につながる。AIを使うことで、これまで見えていなかったプロセスの抜け穴が浮かび上がってくる——これはAI導入の、思わぬ収穫だと感じた。