AIにリポジトリの働き方を伝えるためのAGENTS.md

仕事でAIを使い始めた頃は、ほとんどの指示をプロンプトに書いていました。小さな作業ならそれで十分です。しかし、複数のリポジトリやプロジェクトデータ、ソースコード、顧客向けの文章が関わると、プロンプトはすぐに長くなり、大事な条件も抜けやすくなりました。

もう一つ困ったのは、プロンプトがその会話の中にしか残らないことです。次のタスクでは、どのデータが正なのか、どこで確認が必要なのか、日本語の文章をどうレビューするのか、完了前に何をテストするのかを、また最初から説明しなければなりません。

そこで使い始めたのが AGENTS.md です。

リポジトリの小さな仕事ルール

私は AGENTS.md を巨大なプロンプトにはしていません。リポジトリの簡単な作業ガイドに近いものとして扱っています。ルートには、変更範囲を広げないこと、更新前に最新データを確認すること、完了を伝える前に結果を検証することなど、共通のルールだけを書きます。

特定のフォルダに別の進め方が必要なら、その近くにもう一つ AGENTS.md を置きます。管理データのフォルダでは編集前の再取得を求め、ソースコードのフォルダでは参照先の確認や関連テストを求める、といった使い分けです。作業対象に最も近いルールを優先します。

この形なら、同じ説明を何度も繰り返さずに、必要な場所だけ具体的にできます。

書いていること、書かないこと

残すのは、長く使えて確認できるルールです。

• そのフォルダに置くもの
• 正とするデータやシステム
• 事前確認が必要な場面
• 選ぶべきツールや進め方
• 完了前に必要な確認結果

一時的なタスク履歴、秘密情報、特定PCだけのパスは別の場所に置きます。何でも書こうとすると、すぐに古くなり、読まれない文書になってしまうからです。

「注意して作業する」のような曖昧な表現も避けています。「タスクを更新する前に最新のWBSを取得する」のように、次の行動が決まる書き方のほうが実際に役立ちます。

使ってみて変わったこと

この形にしてから、同じ前提を何度も説明する時間が減りました。それ以上に、AIが何も知らずにリポジトリへ入ってくるツールではなく、最初に作業ガイドを読んだ新しいメンバーに近い動きをするようになりました。

AGENTS.md がAIそのものを賢くするわけではありません。AIがどこで、どのように力を使うかを明確にするものです。実際のプロジェクトでは、長いプロンプトを追加するより、この違いのほうが大きいと感じています。