AIに「規約を渡したからOK」は甘かった。設計〜テストまでAIを活用して分かった2つの誤解と現場のリアル

はじめに

現在、業務でAIツール（Cursorなど）を活用し、設計規約の作成〜実装計画〜コーディング・テストコード作成までをAI主導で進めています。

AIを使った開発を始めてまだ数ヶ月で不慣れな部分も多いのですが、だからこそ「AIに指示を出す難しさ」や「思わぬ壁」に日々ぶつかっています。

最初は「最初に規約や実装計画をしっかり作って渡しておけば、指示通りに完璧なコードを書いてくれるだろう」と思っていました。しかし実際に運用してみると、規約を無視されたり、ディレクトリ構成が崩れたりと、数々の壁にぶつかりました。

この記事では、AI開発に奮闘する中で学んだ「AIのクセ」と「現場で本当に効果があったプロンプト・指示出しの工夫」を共有します。

誤解1：実装計画に「規約参照」と書いておけばフォルダ構成も守ってくれる

起こったこと

「設計規約」を作成した上で「実装計画」を作成し、その計画書の中に参照資料として規約を記載していました。
そして「実装計画に沿って順番に実装して」とAIに依頼したのですが、いざコードが出力されると、コーディング規約に書かれているはずのディレクトリ・フォルダ構成が全く守られていないという事態が発生しました。

AIは「渡された資料の中にある参照記述」を自動で辿り、それを厳密に遵守しながら実装を進めてくれるわけではない、ということを痛感しました。

🔥 判明した事実：なぜAIは規約を渡しているのに無視してしまうのか？

「なぜ規約通りにできていないのか？」をAIに直接問い詰めたところ、非常に興味深いAI側の本音が返ってきました。

AIからの実際の返答：
「『参照ドキュメントを見ていない』というより、『参照ドキュメントの“実装に必要な部分”は見ているが、細かい業務ルール条項・共通基盤ファイルとの整合性・複数ドキュメント間の整合性までは、実装フェーズでは検証していなかった』というのが実態に近い」

つまり、AIはコードを動かすための最小限の情報だけを拾い上げて実装を優先してしまい、フォルダ構成や共通ルール、他ドキュメントとの整合性といった全体的な規約の検証をスルーしていたのです。

💡 対策：実装指示と「1行ずつの突き合わせチェック指示」をセットで渡す

この「実装優先で全体整合性のチェックを省く」というAIのクセに対処するため、実装を依頼するプロンプト内に 参照ファイルの相対パス指定 と 完成後の1行ずつの突き合わせ検証・修正指示 をセットで含める運用に行き着きました。

AIに自発的に計画書を辿らせたり、一発で完璧なコードを出させようとするのではなく、「実装完了後に、明示指定した規約と1行ずつ突き合わせて確認・修正まで行う」という明確なプロセスを指示に組み込むやり方です。

💡 実際に効果があったプロンプト例

実装計画の〇番の実装をお願いします。
（※実装計画書自体も相対パスで指定して渡しています）

また、実装後は以下の資料と実装コードを1行ずつ突き合わせて確認し、
ルールへの違反や漏れがあれば修正まで行ってください。

- 参照資料：`./docs/rules/coding_rule.md`

このように「実装指示」「参照パスの明示」「1行ずつの突き合わせ確認と修正指示」を1つのプロンプトで完結させることで、AIが全体の整合性を無視してコードだけ出力してしまうのを防ぎ、手戻りを大幅に減らすことができました。

誤解2：AIは丸投げで完璧な成果物を出す「魔法のツール」である

起こったこと

指示が大雑把だと、AIは「それっぽいコード」を書いてくれますが、あとから何回も修正のやり取りが発生し、かえって時間がかかってしまうことがありました。

解決策：AIは「丁寧な指示とチェックが必要な優秀な新人」と捉える

AI開発で重要なのは、前提条件や参照ファイルを過不足なく渡すこと（相対パスの明示）と成果物に対するレビュー（事後検証プロンプト）を徹底することです。丸投げではなく、適切な指示を出す指導者（プロンプター）として接することで、最大のパフォーマンスを発揮してくれます。

まとめ

設計〜テストまでAIを活用する中で得た一番の学びは、「AIの性能だけでなく、人間のプロンプト設計と指示のプロセスが成果を左右する」ということです。

AIは実装を優先して「全体の規約チェック」を省くクセがあることを理解する
参照資料は相対パスで明示し、計画書内に書いてあってもプロンプトで直接指定する
プロンプト内で「資料とコードを1行ずつ突き合わせて確認・修正まで行って」と指示する
AIを「優秀な新人」として前提条件の共有と事後チェックを徹底する

これからCursorや各種AIツールを使って業務効率化を目指す方の参考になれば幸いです！