AIエージェントのために書いたら、最高の開発ドキュメントができた

みなさん、こんにちは！
現役IT執行役員のグイグイです⚡

今回は現在私が関わっているプロジェクトでの気づきを書いてみます。

AIエージェント向けに本気でinstructionsを書いたら、結果として、人間向けにも最高の開発ドキュメントができた。

最初からそれを狙っていたわけではない。
むしろ逆だ。

AIに変なコードを書かせないために書いた。
AIに現場のルールを守らせるために書いた。
チーム開発の中で、本番品質で使えるようにするために書いた。

でも、書いていくうちに気づいた。

これ、今まで作ってきたどの「開発手順書」よりも、よほど実用的で、よほど伝わる。

たぶんこれは、AI導入のかなり本質的な副産物だと思う。

私は今、エンタープライズのJavaシステム開発に、AIエージェントを導入しようとしている。

しかも、ただのサンプル開発ではない。
PCI DSS 4.0準拠が求められる、大規模なバッチシステムだ。
Spring Boot 3.x、Spring Batch、MyBatis、AWS構成。
14〜15名のチームで進める、エンタープライズ開発である。

要するに、
「AIにちょっとコードを書かせて遊んでみました」
みたいな話ではない。

現場で使う。
本番品質で使う。
チーム開発の中に組み込む。

そのための準備として、この2週間ほど、AIエージェント向けの各種ファイルを整備してきた。

• .copilot-instructions.md

• batch.instructions.md

• dao.instructions.md

• test.instructions.md

• AGENTS.md

どれも、GitHub Copilot Enterpriseのエージェントが、こちらの期待から外れないようにするための指示書だ。

AIエージェントは便利だ。
でも、雑に使うと普通に危ない。

特にエンタープライズ開発では、「なんとなく動くコード」では困る。

保守できること。
レビューできること。
再現性があること。
チーム全体で品質を揃えられること。

そこまで考えると、AIに渡す指示はかなり重要になる。
だから、かなり本気で書いた。

そして、その結果わかった。
AI向けに書いたinstructionsは、従来の人間向け手順書より、ずっと良いドキュメントになりやすい。

従来の開発手順書は、暗黙知に頼りすぎていた

私は17年ほどJava開発の現場にいる。
その間、「開発手順書」や「コーディング規約」は何度も書いてきた。

だいたいExcelで。

はい、出ました。
日本のエンタープライズ開発名物、Excel手順書である。

もちろん、Excelが悪いわけではない。
問題は中身だ。

たとえば、こういうルールはよく書かれる。

「DBアクセスはMyBatisを使うこと」
「SELECT * は禁止」
「ログはSLF4Jで出力すること」
「例外は握りつぶさないこと」

たしかに、書いてある。
でも、だいたいそこまでだ。

なぜ禁止なのか。
どう代替するのか。
どんな場合なら例外を認めるのか。
なぜその設計にしているのか。

本当に大事なのはその先なのに、そこが抜けやすい。

しかも、これは単に書き手が雑だから、という話でもない。

コーディング規約を整備する役は、たいていチームの中でいちばん経験があって、いちばん判断できる人に回ってくる。
でも、そういう人ほど忙しい。レビューも来るし、設計も見るし、障害も拾うし、調整ごとも振られる。

だから、限られた時間で書くことになる。
すると、どうしても結論だけが先に置かれる。

「これを使うこと」
「これは禁止」

そこまでは書ける。
でも、「なぜそうなのか」まで書く時間がない。

頭の中にはある。
過去にやられた経験もある。
地雷も知っている。
でも、それを全部文章に展開する前に、次の仕事が来る。

書いた本人の頭の中にはある。
経験者同士なら、なんとなく伝わる。
レビューで補正もできる。

でもそれはつまり、読む側の補完力に頼っているということだ。

従来の開発手順書の正体を、少し厳しめに言うならこうなる。

書いた人の暗黙知を前提にした、穴だらけのドキュメント。

人間同士なら、空気で埋めていた。
経験で埋めていた。
レビューで拾っていた。

でも、それはドキュメントが優れていたわけではない。
人間側が頑張っていただけだ。

AIは忖度しない

AIエージェントに指示を出すと、この問題が一気に表面化する。

AIは、曖昧さを「いい感じ」に補完してくれない。

たとえば「SELECT * は禁止」とだけ書いても、次の実装で平然と SELECT * を出してくることがある。

AIからすると当然だ。
なぜダメなのか。
どう書けばいいのか。
代替パターンは何なのか。

その情報が渡されていないのだから、守りようがない。

人間なら、レビューで怒られた経験とか、過去の性能障害とか、現場の空気で察する。
AIは察しない。

いや、正確に言うと、察した"風"のコードは出してくる。
これが一番危ない。

だから、instructionsにはこう書く必要がある。

ここまで書いて、初めてAIは安定して正しい方向に寄ってくる。

単なる禁止では足りない。
理由が要る。代替が要る。具体例が要る。

これはAIのために書いているようでいて、実は人間にとっても圧倒的に親切だ。

新人が読んでもわかる。
中堅が読んでも意図を揃えられる。
レビュー観点としても使える。

instructionsが必要なのは、「不正解を防ぐため」だけではない

ここで、もう一つ大きな理由がある。

実際の開発現場で厄介なのは、「明らかなダメ実装」よりも、むしろその逆だ。

どちらでも動く。どちらでも間違いではない。いくつも正しいやり方がある。
でも、プロジェクトとしては、そのうちの一つに揃えたい。

こういう場面が、実はものすごく多い。

例外ハンドリングの粒度。
ログ出力の方針。
テストメソッド名の付け方。
単体テストでどこまでモックを許すか。

どれも、唯一絶対の正解があるわけではない。
でも、チーム開発では「揃っていること」自体に大きな価値がある。

人間同士なら、レビューや会話の中でだんだん揃っていく。
「この案件ではこっちで行こう」が、空気として共有されていく。

でもAIは、その空気を読まない。

その時々でもっともらしい選択肢を出してくる。
どれも一応それっぽい。どれも完全に間違いではない。
だからこそ、地味に危ない。

昨日はAパターンで実装していたのに、今日はBパターンで返してくる。
プロジェクト全体で見ると、設計もレビューも保守も少しずつブレていく。

つまり、instructionsは単なる制約集ではない。
チームの判断基準を固定するための文書でもある。

AIにルールを守らせるというより、AIを通して、チームの基準そのものが可視化される。

AIにやられると、ルールが強くなる

instructionsを書いていて面白かったのは、AIがやらかしたことが、そのままルールとして明文化されていくことだ。

たとえば、JUnitの @ParameterizedTest。
パラメータ化テスト自体は便利だ。複数の入力パターンを一つのテストメソッドで回せる。

でもAIは、これを変な方向に使うことがある。

意味の薄い入力パターンを大量に増やして、
「テストケースをたくさん書きました」
という顔をしてくる。

いや、違う。欲しいのは件数ではない。検証の意味だ。

実際にやられた。
なので、instructionsにこう書いた。

この一文には、現場で踏んだ地雷がそのまま入っている。

他にもあった。

• モックが設定通りに動くことだけを確認するテスト

• DAOテストと称して、実DBを使わないモックテスト

• 異常系のふりをして、実際には何も保証していないテスト

全部、AIに実際にやられた。
そして、そのたびにinstructionsへ書き足していった。

良いドキュメントは、机上の理想論だけでは強くならない。
現場で一度やられた経験が入るから、ルールに重みが出る。

AIエージェントを使うと、その痛い目が短期間で可視化される。
そして、それをすぐルール化できる。

ある意味、AIはドキュメントの穴をあぶり出す装置でもある。

AI導入の本当のROIは、速度だけではない

AI駆動開発のメリットとして語られがちなのは、実装速度やコード生成、テスト作成の話だ。

もちろん、それもある。実際、かなり助かる。

でも今回、私が一番大きいと感じた価値は別のところにあった。

AIを正しく動かすために、こちら側の暗黙知を言語化せざるを得なくなること。

何を大事にしているのか。
なぜその設計にしているのか。
どこを間違えると危ないのか。
複数ある正解の中で、このプロジェクトでは何を正とするのか。

それを全部、言葉にしないとAIは安定して働かない。

この圧力が、結果として組織のドキュメント品質を引き上げる。

私はこれを、AI導入の「隠れたROI」だと思っている。

AIはコードを書いてくれる。
でも、それ以上に、人間側が今まで雑に済ませていた部分を、ちゃんと明文化させる。

AIのために書いたものが、人間を育てる

このinstructionsを見た同僚が、こう言った。

「これ、新人研修で使えますね。」

たしかに、その通りだと思った。

でも少し面白い。
これは最初から新人研修用に作った資料ではない。
AIエージェントに正しく動いてもらうために書いたものだ。

しかも、AIに丸投げして作ったわけでもない。

AIと壁打ちしながら、現場の前提を整理し、実装ルールを言語化し、実際にAIがやらかしたパターンを潰しながら、一つひとつ仕上げていった。

AIのために書いた。
AIと一緒に書いた。
でも、結果として人間にも効くドキュメントになった。

AI導入というと、どうしても「人間の仕事がAIに置き換わる」みたいな話になりやすい。

でも、現場で使っている感覚は少し違う。

AIをちゃんと使おうとすると、人間側の思考が整理される。
暗黙知が言語化される。
チームの判断基準が明確になる。

つまり、AIが人間の仕事を奪うというより、
人間がこれまで曖昧に済ませていた部分を、もう曖昧なままでは通してくれなくなる。

今回の一番大きな発見は、そこだった。

AIエージェントのために書いたドキュメントが、結果としてプロジェクトの最高の開発ドキュメントになっていた。
AIのために書いたものが、人間を育てるものになっていた。

これからの開発ドキュメントは、人間だけに読ませる前提で書くより、AIにも読ませる前提で書いたほうが圧倒的に良くなる。

これは単なる効率化の話ではない。
開発現場に溜まった暗黙知を、チームの資産に変える話だ。

#AI駆動開発
#AIコーディング
#生成AI
#エンタープライズ開発
#AI駆動開発
#GitHub Copilot
#エンジニア
#プログラミング
#生成AI
#AI活用