ハクソク

世界を動かす技術を、日本語で。

AGENTS.md – コーディングエージェントを指導するためのオープンフォーマット

279日前原文(agents.md)

概要

AGENTS.md は、 README.md を補完する形でエージェント向けの詳細な指示やコンテキストを管理するためのファイル。 人間向け のREADMEを簡潔に保ちつつ、エージェントには必要な情報を提供。 ビルド手順やテスト、コーディング規約 など、READMEには不要な技術的詳細を記載。 プロジェクト全体やサブプロジェクト ごとにAGENTS.mdを配置可能。 標準的なMarkdown形式 で、エージェントにも人間にも分かりやすいドキュメント管理を実現。

AGENTS.mdとは何か・README.mdとの違い

  • README.md は人間向けの概要、クイックスタート、貢献ガイドラインなどを記載
  • AGENTS.md はエージェント向けの詳細なコンテキストや手順、規約の保存場所
  • README.md では冗長になる情報や、エージェントのみが必要とする内容の管理
  • ファイルを分離 することで、人間向けREADMEの簡潔さを維持
  • エージェントが参照しやすい 明確な場所の提供

AGENTS.mdの導入目的

  • エージェント向け指示の一元管理
  • README.mdの簡潔化 と人間中心設計の維持
  • 既存のREADMEやドキュメント を補完する、正確なエージェント向けガイダンスの提供
  • プロプライエタリな形式を避け、誰でも使える汎用的なファイル名とフォーマットを採用
  • AIコーディングエージェントのエコシステム 全体で活用可能

AGENTS.mdのサンプル内容

  • 開発環境Tips

    • pnpm dlx turbo run where <project_name>で目的パッケージへジャンプ
    • pnpm install --filter <project_name>でパッケージをワークスペースに追加しVite, ESLint, TypeScriptで認識
    • pnpm create vite@latest <project_name> -- --template react-tsでReact+ViteのTypeScript対応パッケージ作成
    • 各パッケージのpackage.json内のnameフィールドで名称確認

  • テスト手順

    • .github/workflowsフォルダでCIプラン確認
    • pnpm turbo run test --filter <project_name>でパッケージごとの全チェック実行
    • パッケージルートからpnpm testでテスト可能、マージ前に全テスト合格必須
    • pnpm vitest run -t "<test name>"で特定テストのみ実行
    • テストや型エラーは全て修正し、スイートがグリーンになるまで対応
    • ファイル移動やimport変更後はpnpm lint --filter <project_name>でESLint, TypeScriptルール確認
    • 変更コードには必ずテスト追加や更新

  • PRガイドライン

    • タイトル形式：[<project_name>] <Title>
    • コミット前に必ずpnpm lintとpnpm testを実行

AGENTS.mdの使い方

  • 1. AGENTS.mdの新規作成
    • リポジトリのルートにAGENTS.mdを配置、エージェントによる自動生成も可能
  • 2. 必要事項の記載
    • エージェントがプロジェクトで作業しやすくなる項目をセクションごとに記載
      • プロジェクト概要
      • ビルド・テストコマンド
      • コードスタイル
      • テスト手順
      • セキュリティ考慮点
  • 3. 追加指示の記載
    • コミットメッセージやPRガイドライン、セキュリティ注意点、大規模データセット、デプロイ手順など
  • 4. 大規模モノレポでの活用
    • サブプロジェクトごとにAGENTS.mdを配置可能
    • エージェントはディレクトリツリー上で最も近いAGENTS.mdを自動参照
    • OpenAIのメインリポジトリでは88個のAGENTS.mdを運用中（2024年6月時点）

AGENTS.mdの背景とコミュニティ

  • OpenAI Codex、Amp、Google Jules、Cursor、Factory などAI開発エコシステム全体での協働から誕生
  • オープンフォーマット として進化・維持をコミット
  • どのコーディングエージェントでも活用可能、開発者コミュニティ全体の利便性向上

FAQ

  • 必須フィールドはなし
    • 標準Markdownのみで構成、任意の見出しを利用可能
  • 指示が競合した場合
    • 編集対象ファイルに最も近いAGENTS.mdが優先、明示的なユーザーチャット指示があればそれが最優先
  • エージェントはAGENTS.md内のテストコマンド等を自動実行するか
    • コマンドが記載されていれば、エージェントは関連チェックを実行し、失敗時は修正を試みる
  • 後から内容を更新可能か
    • AGENTS.mdは 生きたドキュメント として随時更新推奨
  • 既存ドキュメントの移行方法
    • 既存ファイルをAGENTS.mdへリネームし、シンボリックリンクで互換性維持
      • コマンド例：mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Hackerたちの意見

README.mdとAGENTS.mdを分けるのがいいアイデアだとはまだ納得できてないな。

└

この時点で、README.mdは「マーケティング/ランディングページのマークダウン」になって、AGENTS.mdやCLAUDE.mdは実際のコードやアーキテクチャ、使い方の概要を得るために訪れるものになるね。

└

その通り。READMEは人間向け、AGENTSなどはLLM向けだよ。ツールの使い方やインストール方法はREADMEに書いて、コンパイルやテスト、アーキテクチャの決定、コーディングスタンダード、リポジトリの構造などはエージェントのドキュメントに書くべきだね。

└

この例を読んでて、同じことを思ったよ。AGENTS.mdの内容は、いいREADME.mdに全部入ってるべきだね。

└

たぶんね。クロードには好きなことをClaudeファイルに入れさせて、時々それがめちゃくちゃじゃないか確認してる。人間向けに書いた高品質なREADMEにはすごく気を使ってるから。Claudeファイルには人間には明らかなことが書いてあって、READMEに詰め込むのは変だけど、Claudeが正しく動くためには必要な情報が入ってるんだ。

└

考慮すべき理由の一つは、LLMとのコンテキストの使い方について。一般的に、少ない方が良いし、README.mdファイルはテキストが多すぎることがあって、その中には毎回のコンテキストウィンドウに入れたくないものもある。私のプロジェクトでは、AGENT.mdやそれに似たファイルが、テストやビルドコマンドなどのフィードバックループに関する簡潔で具体的なコマンドを含んでいる。確かに同じコマンドがREADME.mdにもあるけど、毎回LLMに送るコンテキストウィンドウに入れたくない余計なテキストが多いことがあるんだよね。

└

これについても議論してるんだ: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa... （その投稿から引用）エージェントを分けておくべき理由: * 書き方。エージェントのドキュメントでは、すべて大文字を使うのが特定の指示を強調するのに効果的かもしれない。でも、内部のエンジニアドキュメントでは、失礼に感じられたり、気が散るかもしれない。 * 簡潔さと完全性。エージェントのドキュメントでは、内容を厳選する必要がある。情報を詰め込みすぎると、APIのクォータをすぐに使い切っちゃって、LLMの出力品質が下がる可能性がある。内部のエンジニアドキュメントでは、理想的には100%の完全性を目指すんだ。つまり、重要な設計決定、APIリファレンス、ワークフローなどはどこかに文書化されているべきなんだ。 * 知識のニーズの違い。LLMが必要とする情報は、人間のエンジニアが必要とする情報とは違う。例えば、Gemini 2.5 ProはPigweedのC++スタイルガイドをかなりよく理解している。Gemini APIを使って「Pigweed C++ガイドを全部 recite して」と指示したら、完全には recite しなかったけど、すべてのポイントの詳細な要約をくれた。だから、Gemini 2.5 Pro APIはスタイルガイドでトレーニングされているか、必要に応じてスタイルガイドを取得できるんだ。だから、AGENTS.mdのコンテキストとしてフルスタイルガイドを含める必要はないよ。（このアイデアはKeir Mierleに感謝。）反対の理由: * 重複。概念的には、エージェントのドキュメントは内部エンジニアドキュメントのサブセットなんだ。基本的な目標は同じで、チームにとって重要なワークフローや知識を文書化している。でも、今はその情報を2つの異なるドキュメントセットで維持しなきゃいけないんだ。

└

私たちはこれが役立つと思ってる: * エージェントはまだまだ不十分だから、コンテキスト管理や足元をすくうのを避けるための助けが必要なんだ。例えば、< 500locのai/readme.mdを作って、必須事項や他のリンク、使い方のメタ情報を載せてる。 * IaaCと似ていて、私たちが読むのと同じように準備が整ってないものを分けるのが役立つし、多くのマークダウンは自然言語で書かれたスクリプトみたいなものだから、例えばplan.md.templateとか。

└

かなり前のことだけど、多くのプロジェクトにはREADMEとBUILD/README.build/DEVELOPMENTファイルがあったよね… AGENTS.mdはこの最後のファイルに近いと思う。

これがフォーマットや標準だって、どういうこと？ただの名前空間の中のマークダウンじゃん。

└

このページは「LLMエージェントがリポジトリの指示を見るためのファイル名はAGENTS.mdです。それだけが標準です」と言うだけで100語以内に収まるよ。本当に問題だよ！今、すべてのエージェントが変なファイル名を使ってる。デイビッド・クロウショーのsketch.devが大好きだけど、理解できない理由で「dear_llm.md」って名前を選んでるんだよね。

└

標準は、シンプルで広く採用されることでその価値が生まれるんだよね。例えば、.gitignoreやCONTRIBUTING.md、LICENSEファイルなんかは、みんながその場所と目的に同意してるから機能するんだ。

└

いろんなコーディングエージェントが「ルール」を別々の場所に置いてるんだよね：.cursorとかCLAUDE.mdとか。意味がわからないし、標準化が必要だと思う。これが広まるといいな。

それに、僕が使ってるエージェント（Claude Code、Gemini、Aider）はみんな独自のカスタムファイル名を使ってる。標準化されるといいんだけど。今はrulerを使って、必要な悪としてすべての標準のファイルを自動生成してるけど、この問題がすぐに解決するとは思えない。特に、これらのコーディングエージェントはMCP設定を使うスタイルも違うしね。 https://github.com/intellectronica/ruler

└

JulesはAGENTS.mdを使ってるから、Googleもそれを標準として受け入れてるってことだね。もしGemini Code Assistが続くなら（Julesがそれを引き継ぐのかはわからないけど）、おそらくAGENTS.mdもサポートするだろう。その間に、Gemini Code Assistを任意のファイル名で設定できるよ。Aiderのドキュメントには特定のファイル名の参照が見当たらないけど、リンクしてくれる？Anthropicがここでの主要な抵抗勢力みたいだね。

└

理由はわかるけど…ルーラーは必要ないような気がする。

AIの約束って、正確なフォーマットにこだわらなくてもいいってことじゃない？自分たちにとって一番わかりやすい形式で書けばいいし、機械がその不一致を解決するのが役目だよね。

└

ファイル名だけが標準化されてるんだよね。内容はそうじゃない、それが正解。サイトからの引用: > 必要なフィールドはありますか？ > いいえ。AGENTS.mdはただの標準Markdownだよ。好きな見出しを使って、エージェントは提供されたテキストをそのまま解析するだけ。

└

いや、構造やフォーマットは大事だよ。たとえそれが正確なコードの構文じゃなくてもね。

今は、エージェントが人間以上の特別なガイダンスを必要とする移行期にいると思う。すぐにそんなことはなくなると思うけど。自分たちのプロジェクトのドキュメントを充実させることに集中すべきだと思う（例えば、このAGENTS.mdの内容は、私たちのドキュメントのどこかにあるべきだよね）。でも、常に人間向けに書くべきだよ。LLMの特徴は、私たちの書いたものを読んで理解できることだから、そのレベルで設計しよう。

└

コードベースを理解するだけじゃなくて、スタイル的なことも大事だよね。「このアサートライブラリを使ってテストを書く」とか、「コメントは書かない」とか、「構造化ログを使う」とか。コードがあまりない新しいプロジェクトでも、同じくらい役立つよ。

└

今は、エージェントが人間以上の特別なガイダンスを必要とする移行期にいると思う。すぐにそんなことはなくなると思うけど。これは保証されてないよ。完全自動運転の車ができないのと同じように、完全に人間クオリティのコーダーも出てこないだろうね。今はAIコーダーはツールの一つに過ぎないと思う。

└

これ、mcpにも当てはまるよ。

└

同僚たちがよくやってるのは、エージェントにコメントを書かせることだね。そうすれば、全体の流れがわかるから。 :)

└

ビジネスロジックみたいなものには、特別なガイダンスが常に必要だと思う。彼らは、あなたが何を作っているのか、なぜそれを作っているのか、プロジェクトの最終目標が何なのかを正確には理解できないから、教えてあげないといけない。アーキテクチャのことも、人間の好みの問題だからね。自分の頭の中で物事がどこに行くべきか、どうやってやるべきかがマッピングされていれば、変更を読むときにより良い結果が得られる。それが本当のボトルネックになるから。

└

AIが社会にもっと取り入れられるにつれて、機械可読なプラクティスが標準になると思う。いい例が自動運転と地域の法律・コンテキストだね。「赤信号での右折禁止。学校の日は午前7時から9時まで」。だから、必要なのは「今どこにいるのか」「この特定の学校の学校日はいつか」「今は何時か」ってこと。検索でそれを集めようとすることもできるけど、もっと現実的には、自治体が法律を作るときにコンテキストを減らすか、機械可読な情報（例えばQRコード）を看板に載せることになると思う。そうしないと、ルール違反が多くなるだろうね。

└

この一般的な意見には賛成だけど、特定のエージェントファイルを通じて毎回コンテキストに強制的に入れたいものもあるかもしれないね。

└

これは、既存のコードベースがほとんど自己文書化されている場合に当てはまるけど、そんなのは珍しいよね。

└

そうそう！まさにそれが俺の言いたかったことだよ！: https://news.ycombinator.com/item?id=44837875

今のところ、AGENTS.mdはREADME.mdみたいなもので、実際に人を動かすだけの盛り上がりがあるんだよね。他の人のためにドキュメントを書くのが面倒だった人たちが、ロボットのためにはやるっていうのが面白い。この状況、エルゴノミックハンドルのデザインを思い出させるな。少数の人のためにデザインされてるけど、みんなに好まれてる。

└

逆だと思うな。みんなドキュメント読むのが面倒だから、誰も書こうとしなかったんだよ。エージェントがいると、CLAUDE.mdに一度書けば、1週間で何千人ものエージェントが読むことになるんだ。

└

今の違いは、人々がソフトウェア開発の仕事から他の人や自分自身を排除しようとしていることなんだ。だから、ロボットには十分な指示が必要なんだ。動機は大きいよ。ソフトウェア開発から人間の関与をすべて取り除くことがみんなの望みで、しかもそれをすぐに実現したいと思ってるんだ。

これ、.agents¹にindex.mdが必要だったね。小さくて使い捨てのプロジェクトには、モノリシックな.mdファイルでもいいけど、フォルダを使うともっと複雑なプロジェクトでも「ちょうどいい階層」を持たせて構造を提供できる。index.mdが入り口になって、全体的なガイダンスに加えて、組織ガイドも含められる（LLMの助けで簡単にメンテできる）。 index.md ├── auth.md ├── performance.md ├── code_quality ├── data_layer ├── testing └── etc 私の経験では、これが「巨大なファイル」方式よりもずっと良い結果を出すよ。LLMやエージェントが関連するコンテキストを追加できるし、無関係なコンテキストにトークンを無駄にしなくて済むから、ノイズが減って応答の精度が向上する。人間とLLMの両方にとってメンテもしやすいしね。¹ できれば「.agents」よりもいい名前が欲しいな、例えば「.codebots」や「.context」とか。

└

同じような設定を使ってて、今のところ結構いい結果が出てるよ。index.md内の各ファイルに短い説明を追加して、特定の動作を求めるディレクトリごとにrules.mdファイルを作る実験をしてる。例えば、realtime-service.tsやqueue-service.tsみたいな異なるサービスがあるディレクトリがあったとする。そのレベルにrules.mdファイルを置くことで、プロンプトを使うときにそのファイルを参照するだけで素早くスキャフォールディングできるんだ。ただ、名前はあんまり良くないかも。

└

.well-known/

└

このアイデアいいね。今の設定で、このディレクトリの内容をエージェントのプロンプトに追加するミドルウェアってある？

└

私は自分のllmの指示を、主にヘッダー付きのセクションと5つほどの箇条書きで構成された、約100行の簡潔なファイルに保つようにしてる。アーキテクチャ、テストモッキング、大きな変更へのアプローチなどの基本的な期待をカバーしてる。いくつかのプロジェクトにはそれでは足りないかもしれないけど、私のプロジェクトのほとんどにはこれで十分だと思ってる。

└

隠す必要はないよね。なんで人は重要なファイルやディレクトリを隠したがるんだろう？特にドキュメントに関しては。伝統なのかな、でもそれはすべてを不透明にするアンチパターンだよね。もしかしてrobot_docs？

今、5000以上のリポジトリを管理・インデックスするコーディングエージェントを開発中だよ。エージェントの状態は、隠れた.agentディレクトリにローカルで保存されていて、異なるエージェントの役割や具体的な指示用の設定フォルダが含まれてる。それから「agents」フォルダがあって、複数のファイルがあるんだけど、エージェントは自分の役割が定義されているファイルだけを読むんだ。プロジェクトディレクトリ内には、コーディングエージェントの状態が保存されるドットフォルダがある。プロセスは/initコマンドで始まり、リポジトリ全体の深い分析をトリガーする。生のコードをインデックスするだけじゃなくて、エージェントはそのアーキテクチャやロジックの高レベルな要約を生成するんだ。これらの要約はエディタにトグル可能な「ゴーストコメント」として表示される。これはメタデータ層で、ソースコードの一部ではないから、実際のコードにはコミットされない。洗練されたマッピングシステムが、各要約の注釈を関連するコードの行に正確にリンクさせる。このアーキテクチャは、初期に直面した問題の解決策なんだ。ソースコードに直接RAGを実行しても、必要な結果が得られなかったからね。今のシステムはハイブリッド検索モデルを使ってる。ASTを使って高速でリテラルなリテラル検索を行い、RAGは高レベルな要約に対するセマンティック検索に使う。これが大きな違いを生むんだ。「このアプリの認証はどうなってるの？」って聞くと、単純なリテラル検索だとloginって単語が含まれる関数や、その呼び出し階層に出てくる関数・クラスしか見つからない。でも、私たちのセマンティック検索は、物語のような要約をクエリするから、認証フロー全体を理解できる。異なるファイルからプロットポイントを組み合わせて、全体像を把握できるんだ。まるで魔法みたいだよ。

└

もっと教えて！

私はAIに反対してるわけじゃないよ、明らかにね。でも、これは基準としては全然不十分だし、「コンテキスト管理」という分野での革新がまったくないんだよね。

AGENTS.mdはいいけど、このパターンが続いてくれるといいな。もう一つの方法は、README.mdを使って人間用とエージェント用のセクションを分けることだね。エージェントのコンテンツウィンドウがリポジトリ内のすべてのコンテキストを読み込めるようになると、あんまり関係なくなると思う。