AIにコードを書かせる前に、何を決めておくか ～AIエージェント開発で見えてきた「インストラクション設計」の話～

皆さんこんにちは。
現役執行IT役員のグイグイです⚡

最近、現場でAIエージェントを使った開発を進めています。

いわゆる「AIにコードを書かせる」という話ではあるのですが、実際にやってみると、単にAIへ実装を投げるだけでは足りないなと感じています。

AIに雑に投げるのと、プロジェクトの前提をちゃんと渡した上で実装させるのでは、出てくるものがかなり違います。

Xなどを見ていると、たまにこういう話を見かけます。

「AIのコードは雑」
「性能を考えていない」
「セキュリティが甘い」
「結局、人間が直すことになる」

もちろん、そういうケースがあること自体はわかります。

ただ、自分が現場で見ている範囲では、それはAIの能力不足というより、AIに渡している前提が足りていないケースも多いんじゃないかと思っています。

今回は、そのあたりについて、実際に現場でAIエージェント開発を進めながら考えていることを書いてみます。

AIが迷わないための前提を作る

自分の現場では、AIエージェントに実装させる前に、インストラクションファイルをかなりしっかり作っています。

ここで言うインストラクションファイルは、単なるコーディング規約ではありません。

たとえば、こういうものを入れています。

・プロジェクトの背景
・なぜこのシステムを作るのか
・技術スタック
・その技術スタックでの実装パターン
・使用する開発言語とFWのベストプラクティス
・セキュリティ要件
・性能要件
・ログの出し方
・ログレベルの使い分け
・ログに出してはいけない情報
・DBアクセス方針
・例外処理方針
・冪等性の考え方
・テスト方針
・コーディング規約
・プロジェクト固有の共通設計

このあたりを、AIが参照できる形で言語化しておきます。

要は、AIに「いい感じに作って」と投げるのではなく、AIが判断に迷わないように、先に開発上の判断基準を渡しておく感じです。

ここをやらずにAIに実装させると、その場その場ではそれっぽいコードが出てきます。

ただ、システム全体で見たときに、微妙に考え方が揃っていないものが積み上がっていく可能性があります。

これが、エンタープライズ開発ではけっこう怖いところです。

正しい実装は、1つではない

ここで大事なのは、正しい実装方法は1つではないということです。

たとえばJavaの例外処理ひとつ取っても、いくつか王道のパターンがあります。

独自例外を作って、業務例外・システム例外・致命的な例外を分けるのか。

フレームワーク標準の例外体系に寄せるのか。

どの層で例外を変換するのか。

どこまで上位に伝播させるのか。

このあたりは、どれか1つだけが絶対に正しいという話ではありません。

ログの出し方も同じです。

INFO、WARN、ERROR、FATALをどう使い分けるのか。

どの情報をログに出すのか。

業務ログとシステムログを分けるのか。

msgIdを付けるのか。

MDCを使うのか。

個人情報や機微情報をどう扱うのか。

nullの扱いもそうです。

nullを許容するのか。

空文字や空Listに寄せるのか。

Optionalを使うのか。

入力時点で弾くのか。

Service層で吸収するのか。

このあたりも、プログラム単体で見れば、どれもそれなりに成立します。

ただ、プロジェクト全体でバラバラに混ざると、一気に扱いづらくなります。

単体では動く。

でも、システム全体で見ると一貫性がない。

これは実務ではかなり厄介です。

「決めの問題」をAIに渡す

現場ではよく「それは決めの問題ですね」という会話をします。

技術的に絶対の正解があるわけではない。
でも、プロジェクトとしてはどれかに決めないといけない。

例外処理も、ログ設計も、nullの扱いも、DBアクセス方針も、冪等性の考え方も、テストの書き方もそうです。

どれも単体で見れば、複数の正解があります。

でも、システム全体として品質を保つには、プロジェクトとしての正解を1つに寄せる必要があります。

ここを決めずにAIエージェントへ実装させると、AIはその都度もっともらしい正解を選びます。

あるクラスでは独自例外を使う。

別のクラスでは標準例外をそのまま投げる。

ある処理ではWARNで出す。

別の処理ではERRORで出す。

あるDAOではnullを返す。

別のDAOでは空Listを返す。

それぞれ単体では間違っていない。

でも、積み重なるとシステム全体としてブレる。

だから、AIエージェントに開発させるなら、「一般的なベストプラクティス」を渡すだけでは足りないと思っています。

数ある正解の中から、このプロジェクトではどれを採用するのか。

その「決めの問題」まで、インストラクションとして落とし込んでおく必要があります。

変なコードが出るときは、前提が漏れていることが多い

少なくとも自分が見ている範囲では、この前提をきちんと渡した状態でAIエージェントに実装させると、「これはちょっと雑すぎるな」と思うようなコードは、そこまで出てきません。

もちろん、完璧ではありません。

ただ、変なコードが出てきたときは、AIが単純にダメというより、

「あ、このルールをまだ伝えていなかったな」

「あ、この共通設計をインストラクションに入れていなかったな」

「あ、この判断基準が曖昧だったな」

と気づくことの方が多いです。

これは人間の開発者に対する指示とかなり似ています。

背景も設計方針も制約も渡さずに「この機能を作って」と言えば、人によって実装はブレます。

でも、設計思想、禁止事項、共通部品、ログ方針、例外処理方針、テスト方針まで渡せば、成果物は安定します。

AIも同じです。

むしろ、明文化されたルールに対しては、AIの方が素直に守ってくれる場面もあります。

インストラクションだけでは終わらせない

ただし、インストラクションファイルを作れば終わり、という話でもありません。

AIが書いたコードは、静的なコード解析ツールにも通します。

そこで検出されたものは、必要に応じてAIに修正させる。

それでも拾いきれない部分は、人間が見ます。

つまり、AIに丸投げしているわけではなく、既存の品質管理の仕組みにAIを組み込んでいる感覚です。

ここはかなり大事だと思っています。

AIコーディングというと、どうしても「AIがどこまでコードを書けるか」という話になりがちです。

でも、エンタープライズ開発では、それだけでは足りません。

AIに実装させる。
静的解析を通す。
テストを通す。
品質記録を残す。
人間がレビューする。
プロジェクトの品質基準に合わせる。

この流れの中に、AIをどう組み込むか。

そこまで含めて考えないと、実務では使いにくいと思っています。

インストラクションを書けるのは誰か

ただ、ここで一つ問いが残ります。

そのインストラクションファイルは、誰が作るのか。

結局のところ、AIに前提を渡せる人というのは、その前提をすでに知っている人です。

言語仕様を理解している。

非機能要件、つまり性能・セキュリティ・可用性を理解している。

運用・保守を見据えた設計ができる。

障害が起きにくい構成を知っている。

起きたときにダメージを最小化できる作りを知っている。

問題をすぐ特定できるログ設計ができる。

これらは、教科書に書いてあることというより、現場で培った実践知です。

過去に、ここを抑えておかなかったせいでひどい目にあった。

長年の現場経験の中で、じわじわと身についてきた判断力。

そういうものが土台にあって、はじめてインストラクションに落とし込める。

プログラムの文法や実装パターンは、正直AIに丸投げしていいと思っています。

「このバージョンのこの言語で、最適な実装をしてくれ」という部分は、AIの方が速い。

ただ、「このプロジェクトではどう決めるか」という判断は、別の話です。

AIは言語仕様を知っています。

でも、過去の失敗から来る「傷跡」は持っていない。

だから、エンジニア不要論というのは、自分の中では極論だと思っています。

コードを書く作業は、どんどんAIに移っていく。

でも、AIが迷わないための判断基準を作れるのは、やっぱり経験を積んだエンジニアなんだと思います。

バイブコーディングとは別の話

ここは少し補足しておくと、別にバイブコーディングを否定したいわけではありません。

自分も、個人でちょっとしたアプリやツールを作るときは、かなりバイブコーディング的にやっています。

というより、自分用のツールを作るときは、出来上がったソースコードすらろくに読まないこともあります。

操作してみて、自分の満足いくアウトプットが出るか。

やりたいことができているか。

正直、そこしか見ていないことも多いです。

細かい設計や保守性よりも、まず動くものが手元にあることの方が大事な場面もあります。

そういう意味で、バイブコーディングはかなり便利ですし、自分も普通に使っています。

ただ、金融系や基幹系、セキュリティ要件が重いシステム、品質説明が必要なエンタープライズ開発では、同じやり方をそのまま持ち込むのは難しいです。

そこでは、AIに自由に書かせるのではなく、AIが守るべきルールを先に作る必要があります。

つまり、バイブコーディングが悪いという話ではなく、用途が違うという話です。

個人開発や自分用ツールなら、欲しい結果が出ればそれで十分な場面もある。

でも、エンタープライズ開発でAIを使うなら、インストラクション、共通設計、品質管理、静的解析、人間レビューまで含めて考える必要がある。

この2つは、同じ「AIにコードを書かせる」でも、かなり別物だと思っています。

AIが雑なのか、前提が雑なのか

AIのコードが雑だという話は、半分はわかります。

でも、そのときに見ているものが、

「AIが雑なのか」

「AIに渡している前提が雑なのか」

は分けて考えた方がいいと思っています。

少なくとも自分の現場では、機能要件、セキュリティ要件、性能要件、ログ設計、例外処理、冪等性、DBアクセス方針、テスト方針、コーディング規約あたりをちゃんとインストラクションに落とし込むことで、AIエージェントの出力は安定しています。

AI開発で大事なのは、AIに何を書かせるかだけではありません。

AIが迷わない開発環境を先に作ること。

そして、既存の品質管理の仕組みと組み合わせて、開発プロセスの中にAIを組み込むこと。

たぶん、エンタープライズ開発でAIを使うなら、ここを避けて通れないんだと思っています。

まとめ

今回書いた話は、AIを否定する話ではありません。

むしろ逆です。

AIエージェントは、ちゃんと前提を渡せばかなり頼れる存在になると思っています。

ただし、そのためには、AIが迷わないようにする必要があります。

何を守るのか。
何を禁止するのか。
どの実装方針を採用するのか。
どこまでAIに任せて、どこから人間が見るのか。

このあたりを決めずにAIへ投げると、AIはその場でそれっぽい正解を選びます。

でも、エンタープライズ開発で必要なのは、その場のそれっぽさではなく、システム全体としての一貫性です。

AIにコードを書かせる前に、何を決めておくか。

今の自分の整理では、ここがAIエージェント開発のかなり大きな分かれ目になる気がしています。

#生成AI
#AI活用
#AIエージェント
#AI駆動開発
#システム開発
#エンジニア
#ソフトウェア開発
#プロジェクト管理
#業務改善
#DX