「AGENTS.md」がコード品質の新しい基準に——AIエージェント時代のプロンプト設計が、人間のコードレビューを置き換える理由

「AIとの対話方法」がコード品質を決定する時代へ

ソフトウェア開発の現場で、生成AIの活用が当たり前になりつつあります。ChatGPTやClaude、GitHub Copilotといったツールが、開発スピードを劇的に加速させたことは否定できません。しかし同時に、多くのエンジニアが直面している問題があります——それは「AIが生成したコードの品質低下」です。

なぜこのような問題が発生するのか。その答えは、従来の開発手法とAI時代の開発手法の本質的な違いにあります。人間のコードレビューは、暗黙のルールや文脈を理解した上で行われていました。しかし、AIエージェントには、そうした「暗黙の了解」が通じません。求められるのは、より明確で、より詳細な「指示書」なのです。エンジニアのファビアン・サングラール氏が提唱する「AGENTS.md」というアプローチは、この問題への革新的な解答になり得ます。

AGENTS.mdとは——コーディングルールの「外部メモリ化」

AGENTS.mdの考え方はシンプルながら強力です。プロジェクトのルートディレクトリに「AGENTS.md」というマークダウンファイルを配置し、そこにAIエージェント向けのコーディングルール、アーキテクチャ原則、命名規則、テスト戦略など、プロジェクト固有のガイドラインをすべてまとめるというものです。

従来であれば、こうした情報は以下のように分散していました：

チームの頭の中にある暗黙知
散在するドキュメント
古くなったWiki
Slackの過去ログ
コードレビューのコメント

この分散状態こそが、AIエージェントに間違ったシグナルを送り、品質低下を招く根本原因です。AGENTS.mdは、こうした情報を一元化し、AIが常にアクセスできる「外部メモリ」として機能します。大規模言語モデル（LLM）にとって、文脈情報は生成品質を左右する最重要要素です。AGENTS.mdがあれば、AIは常にプロジェクトの「ルールブック」を参照しながら、コード生成を行えるようになるのです。

品質低下の「シグナル」を見逃さない——フィードバックループの最適化

AGENTS.mdのもう一つの重要な役割は、品質低下を検出したときの対応プロセスです。サングラール氏のアプローチでは、生成されたコードの品質が低下したら、単にAIに「もう一度やり直せ」と指示するのではなく、AGENTS.mdの読み直しを指示します。

これは一見すると小さな工夫に見えますが、実は開発プロセスの哲学を根本的に変えるものです：

従来のアプローチ：「AIの出力が悪い」→「AIに直してもらう」
AGENTS.mdアプローチ：「AIの出力が悪い」→「ルール定義が不十分？」→「AGENTS.mdを改善」→「AIに再度実行」

この思考の転換により、品質問題は「AIの能力不足」ではなく、「指示書の不完全さ」の問題として認識されます。つまり、問題解決の主導権を人間が握ることになるのです。コード生成の失敗から学び、ルール定義を反復的に改善することで、AIエージェントは確実に「訓練」されていきます。

プロンプト設計から「ルール設計」へ——開発パラダイムシフトの本質

AGENTS.mdの登場は、エンジニアのスキルセットそのものを進化させることを迫ります。従来、「プロンプト設計」とは、チャットのたびに上手な質問を工夫することでした。しかし、AIエージェント時代には、これが「ルール設計」へと昇華します。

AGENTS.mdに記述すべき内容の例：

アーキテクチャの設計原則と禁止パターン
言語・フレームワーク固有のベストプラクティス
テストカバレッジの最小要件
変数・関数の命名規則とその理由
セキュリティ上の注意点
パフォーマンス最適化のポイント
依存関係管理のルール
ドキュメンテーションの基準

このプロセスを通じて、エンジニアは自分たちのプロジェクトの「本質的な価値観」を言語化することになります。AIに指示を出す過程で、人間同士のコミュニケーションも必然的に明確化されるのです。これは、チーム内の技術的な一貫性を飛躍的に高めることにつながります。

スケーラビリティの新しい形——AGENTS.mdが実現する「品質の民主化」

AGENTS.mdのもう一つの価値は、スケーラビリティです。新しくジョインしたエンジニア、経験の浅い開発者、あるいは外部の契約開発者——こうしたメンバーでさえ、AGENTS.mdさえ読めば、プロジェクトの「ルール」を即座に理解し、その水準のコードを生成するようAIに指示できます。

従来のコードレビュープロセスは、シニアエンジニアのキャパシティに大きく依存していました。しかし、AGENTS.mdが十分に充実していれば、AIエージェントが「初級レベルのコードレビュアー」として機能するようになります。人間のレビュアーは、より高次な判断——ビジネスロジック、全体設計、予期しない副作用の検出などに集中できるようになるのです。