API開発チーム向け AGENTS.md ファイルの書き方

コーディングエージェントはコードを書く前にあなたのリポジトリを読み込み、最初に読み込むファイルがAGENTS.mdです。これは、Codex CLI、Cursor、Aider、OpenHands、その他多くのツールが合意したオープンな規約であり、単一のコンテキストファイルがすべてのエージェントで機能するようにします。API開発チームにとって、このファイルは、実際ローカルサーバーに対して正しいテストを実行するエージェントと、エンドポイントを幻覚させ、壊れたクライアントを出荷するエージェントとの違いとなります。

このガイドでは、AGENTS.mdとは何か、APIチームがなぜこれを本番コードとして扱うべきか、OpenAPIを最初に採用するリポジトリにとって重要なセクション、具体的な例、そしてAPIの進化に合わせてこれを最新の状態に保つ方法について説明します。最後にApidogと組み合わせて、エージェントの契約テストフローが実際の仕様に基づいて行われるようにします。

button

TL;DR

AGENTS.mdは、リポジトリのルートにあるプレーンなMarkdownファイルで、コーディングエージェントにプロジェクト内でコードをナビゲート、ビルド、テスト、出荷する方法を伝えます。
この規約はオープンであり、Codex CLI、Cursor、OpenHands、Aider、Claude Code、その他のエージェントツールでサポートされています。
APIチームにとって最も効果的なセクションは、ビルドコマンド、OpenAPI仕様のパス、モックサーバーのエンドポイント、契約テストコマンド、認証設定、および「触るな」ゾーンです。
短く保ちましょう。200〜400行で十分です。それ以上長いと、エージェントは重要な部分をスキップします。
Apidogコレクションと組み合わせて、エージェントがコンテキスト（AGENTS.md）と実行可能な契約（OpenAPI仕様）の両方を持つようにします。

`AGENTS.md`とは実際何なのか

AGENTS.mdは、リポジトリのルートにコミットするMarkdownファイルです。コーディングエージェントは、コードベースと初めて接触する際にそれを探し、その内容をプロジェクトの仕組みに関する公式のブリーフィングとして扱います。この規約はOpenAIのCodex CLI内で始まり、他のツールが同じファイルを読み込めるようにオープンな標準として公開されました。今年現在、Codex CLI、Cursor、Aider、Claude Code、OpenHands、Sourcegraph Cody、その他いくつかの小規模なエージェントがすべてこれを読み込んでいます。

これを便利にする3つのことがあります：

1つのファイル、すべてのエージェント。コンテキストを一度書けば、チームのツールセット内のすべてのエージェントがそれを認識します。ツールごとの設定のずれはありません。
プレーンなMarkdown。DSLもスキーマもビルドステップもありません。エンジニアは他のドキュメントと同じように編集します。
記述対象のコードの隣に存在する。ビルドスクリプトが変更されたとき、同じPRでファイルも変更されます。差分によって、レビュー担当者とエージェントにその変更が可視化されます。

最も近いものは、AnthropicのClaude Codeが読み込むCLAUDE.mdです。これら2つの形式は大きく重複しており、多くのプロジェクトではCLAUDE.mdにシンボリックリンクされたAGENTS.mdを保持しており、追加の設定なしで両方のツールが機能するようにしています。CodexチームとAnthropicは、今後も形式の互換性を維持することで公に合意しています。

なぜAPI開発チームは特にこれを必要とするのか

APIチームは、厄介な交差点に位置しています。コードは小さく、契約は大きく、どちらかを間違えた場合の影響はすべてのダウンストリームクライアントに可視化されます。仕様がopenapi.yamlにあることを知らないエージェントは、トレーニングデータから覚えているレスポンスの形状から型を書き換えてしまいます。契約テストコマンドを知らないエージェントは、コンパイルは通るものの、クライアントSDKパイプラインを壊すコードをコミットしてしまいます。

APIリポジトリ用に適切に書かれたAGENTS.mdは、以下の4つのことを行います：

仕様を信頼できる唯一の情報源として固定する。すべての変更はOpenAPIまたはGraphQLスキーマから始まり、そこで終わります。エージェントは最初に仕様を更新し、次に型を再生成することを学習します。
ローカルサーバーに名前を付ける。ローカルのモックサーバーまたはライブサーバーを起動するエージェントは、Stack Overflowのスニペットではなく、テストに適したURLを選択します。
意図別にテストコマンドをリストする。「単体テストを実行」は「契約テストを実行」や「ステージング環境に対して統合テストを実行」とは異なります。
禁止されたパスを指摘する。生成されたSDKコード、サードパーティのクライアントラッパー、およびマイグレーションファイルは編集可能に見えることが多いですが、そうではありません。

このファイルがこれらの4つのことを行うとき、エージェントの出力はREADMEをスキップしたジュニア開発者のように見えるのをやめ、チームメイトのように見え始めます。

APIリポジトリに有効な構造

AGENTS.mdには必須のスキーマはありません。コミュニティは、よく調整されたほとんどすべてのファイルに現れるいくつかのセクションに落ち着きました。APIチームにとって、以下の順序は強力なデフォルトとなります。

1. プロジェクトの概要 (3-5行)

APIが何をするのか、誰がコンシューマーなのか、サーバーがどの言語とフレームワークで動作するのかを記述します。事実に基づいて簡潔に記述します。

# Project: Payments API

Acme製品ラインの内部決済サービス。顧客は
モバイル、ウェブ、パートナーのバックエンド。サーバーはEcho上のGo 1.23、
ストレージにはPostgres 17、冪等性レイヤーにはRedisを使用。

このブロックは、エージェントにデフォルトでどの言語を使用するか、どのイディオムに従うか、誤ったレスポンス形状を出荷した場合にどのクライアントが壊れるかを伝えます。

2. クイックスタートコマンド

エージェントが常に実行する5〜10個のコマンド。常にコマンドを含め、wikiへのリンクは避けてください。

## Commands

| Intent | Command |
|--------|---------|
| 依存関係のインストール | `make deps` |
| サーバーをローカルで実行 | `make dev` (127.0.0.1:8080にバインド) |
| 単体テストの実行 | `make test` |
| ローカルモックに対する契約テストの実行 | `make contract` |
| Lint | `make lint` |
| 仕様からのクライアントの再生成 | `make codegen` |
| マイグレーションの適用 | `make migrate` |

コマンドの動作に環境変数が必要な場合は、その環境変数名を隣に記述します。エージェントは変数のエクスポートは得意ですが、推測は苦手です。

3. OpenAPI / GraphQL仕様セクション

これはAPIリポジトリで最も価値のあるセクションです。エージェントに仕様がどこにあるか、生成されたコードと仕様がどのように関連しているか、編集の流れがどちらの方向かを示します。

## 真実の源

- 仕様は`apis/payments/openapi.yaml`にあります。
- 生成されたクライアントは`gen/clients/{go,ts,python}`に存在し、手動で編集してはなりません。
- 生成パイプラインは`make codegen`です。仕様変更のたびに実行し、
  再生成されたクライアントを同じPRでコミットしてください。
- 仕様変更の流れ：仕様 -> `make codegen` -> サーバーハンドラの更新 ->
  契約テスト -> 出荷。

このブロックだけで、エージェントが生成されたクライアントを編集して型不一致を「修正」し、次のcodegen実行で変更が上書きされ、2日後にビルドが不可解に壊れるという種類のバグが解消されます。

4. モックサーバーとApidogの連携

モックサーバーを実行している場合（そしてそうすべきです）、それらの名前を記述します。URL、読み込む仕様、開始方法をリストします。

## ローカルサーバー

- 実際のサーバー: `make dev` -> `http://127.0.0.1:8080`
- Apidogモックサーバー: `make mock` -> `http://127.0.0.1:4010`
- モックは同じ`openapi.yaml`を読み込み、`apis/payments/apidog/`の
  Apidogコレクションから保存された例を再生します。

ここでApidogがファイル内でその役割を果たします。モックサーバー、仕様、および保存されたリクエスト例は、エージェントが実際のバックエンドで呼び出しを消費することなく実行できる契約を形成します。基盤となるワークフローについては、PostmanなしのAPIテストガイドと組み合わせてください。

5. 認証とシークレット

APIがどのように認証を行い、どの環境変数に何が保持されているかをエージェントに伝えます。実際のシークレットをファイルに決して入れないでください。

## 認証

- 本番環境ではAuth0が発行するOAuth 2クライアントクレデンシャルを使用します。
- ローカル開発では静的な開発トークンを使用します。`.env.local`から`DEV_TOKEN`をエクスポートしてください。
- Apidogコレクションは同じ環境変数名を使用しているため、モックと実際のクライアントは
  同じように動作します。
- トークンはコミットしてはなりません。`.env.local`は`.gitignore`にあります。

6. テスト戦略

テストレイヤーの順位を付けます。エージェントはリストされた順序で実行します。

## テスト

1. 単体テストには`make test`を使用します。高速で、変更のたびに実行されます。
2. モックに対するOpenAPI契約テストには`make contract`を使用します。仕様変更がマージされる前に実行されます。
3. 実際のPostgresを使用したローカルサーバーに対するエンドツーエンドテストには`make integration`を使用します。
   mainブランチにマージする前に実行されます。
4. ステージングのソークテストはGitHub Actions経由で nightlyに実行されます。ローカルコマンドではありません。

7. 触るなリスト

生成されたコード、ベンダー依存関係、およびマイグレーションファイルは、ほとんどの場合ここに含まれます。

## 手動で編集しないでください

- `gen/**` (`make codegen`によって再生成されます)
- `vendor/**` (`go mod vendor`によって管理されます)
- `migrations/*.up.sql` (最初の未適用マイグレーション以降)
- `apis/payments/openapi.yaml` (所有者の承認なしにスキーマフィールド名変更)

8. ハウススタイル

3〜5つのルール。それ以上だとエージェントは間違ったルールを選ぶでしょう。

## 規約

- エラーはRFC 7807 problem JSONを返します。生文字列は使用しません。
- JSONではsnake_case、GoではcamelCase、TSクライアントではPascalCaseを使用します。
  コード生成がマッピングを処理します。
- リソースを作成するすべてのPOSTエンドポイントでは冪等性キーが必須です。
- 新しいエンドポイントには、200と4xxの両方のパスをテストする契約テストが必要です。

具体的な例: 90行で目的を果たすファイル

800行書きたくなる誘惑に抵抗してください。以下のファイルは、実際のAPIサービスを90行のMarkdownでカバーしており、どの主要なエージェントでも生産的に作業するのに十分です。

# Project: Payments API

Acme製品ライン向けの内部決済サービス。Go 1.23、Echo、
Postgres 17、冪等性にはRedisを使用。コンシューマーはモバイル、ウェブ、
およびパートナーバックエンド。

## コマンド

| 意図 | コマンド |
|--------|---------|
| インストール | `make deps` |
| サーバー実行 | `make dev` |
| 単体テスト | `make test` |
| 契約テスト | `make contract` |
| Lint | `make lint` |
| クライアント再生成 | `make codegen` |
| DB移行 | `make migrate` |

## 真実の源

- 仕様: `apis/payments/openapi.yaml`
- 生成されたクライアント: `gen/clients/{go,ts,python}` (編集禁止)
- 編集フロー: 仕様 -> `make codegen` -> ハンドラ -> 契約テスト -> 出荷

## ローカルサーバー

- 実際のサーバー: `make dev` (`http://127.0.0.1:8080`)
- Apidogモック: `make mock` (`http://127.0.0.1:4010`)
- Apidogコレクション: `apis/payments/apidog/`

## 認証

- 本番環境: Auth0 OAuth 2クライアントクレデンシャル。
- ローカル開発: `.env.local`からの静的`DEV_TOKEN`。

## テスト順序

1. `make test`
2. `make contract`
3. `make integration`

## 手動で編集しないでください

- `gen/**`、`vendor/**`
- `migrations/`内の適用済みマイグレーション
- 所有者の承認なしの仕様フィールド名

## 規約

- エラーにはRFC 7807 problem JSONを使用
- snake_case JSON、codegenが言語マッピングを処理
- POST作成には冪等性キーが必須
- すべての新しいエンドポイントには契約テストを同梱

これで十分です。エージェントが同じ誤った選択を二度した場合にのみ、セクションを追加してください。

ファイルを最新の状態に保つ

古いAGENTS.mdは、ファイルがないよりも悪い結果を招きます。エージェントはそれを信じ、もはや機能しないビルドコマンドに基づいてコードを出荷してしまうでしょう。

以下の3つの習慣がファイルを最新の状態に保ちます：

本番コードとして扱う。変更は他のPRと同じレビュープロセスを経ます。レビュー担当者は、コマンドリストが実際のMakefileと一致していることを確認します。
CIに組み込む。コマンドテーブルを解析し、新鮮なチェックアウトで各コマンドを実行する短いスクリプトは、ずれを迅速に検出します。ほとんどのチームはこれを30行のBashで記述します。
同じPRで更新する。新しいテストコマンドを追加するときは、AGENTS.mdを後で更新すると約束しないでください。すぐに更新してください。コストは2分です。スキップした場合のコストは2週間のエージェントの混乱です。

Apidogを`AGENTS.md`の実行時契約として使用する

AGENTS.mdはエージェントにコンテキストを与え、OpenAPI仕様は契約を与えます。Apidogはこの2つを橋渡しします。Apidogは仕様を読み込み、AGENTS.mdにリストされているURLでローカルモックを実行し、保存されたリクエスト例をテストのために再生し、エージェントが実際のバックエンドでクレジットを消費することなく実際のレスポンスを確認できるようにします。

機能するパターンは次のとおりです：

apis/<service>/openapi.yamlとapis/<service>/apidog/（エクスポートされたコレクション）をコミットします。
モックURLとmake mockコマンドをAGENTS.mdにリストします。
エージェントは保存された例に対して高速なテストを行うためにmake contractを実行します。
仕様が変更された場合、エージェントはクライアントを再生成し、契約スイートを実行し、その後初めてライブサーバーに触れます。

実際のAPIを使用したApidogモックワークフローの詳細なウォークスルーについては、DeepSeek V4 APIガイドで、サービスAPIではなくモデルAPIに適用された同じパターンについて説明しています。

APIチームが犯しがちな一般的な間違い

これらのファイルを何十もレビューした結果、同じ5つの問題が繰り返し現れます：

リストする代わりにリンクする。「ビルドコマンドについてはwikiを参照してください。」エージェントはwikiを閲覧しません。コマンドをインラインで記述してください。
マーケティング的な表現。「当社の世界クラスのAPIプラットフォームは…」エージェントは売り込みを必要としません。事実を述べてください。
古くなったコマンド。3月に壊れたコマンドが4月になってもファイルに残っている。これを検出するためにCIを組み込んでください。
仕様セクションが欠落している。最も役立つブロックです。常に含めてください。
「触るな」リストがない。エージェントは生成されたコードを編集します。次のコード生成実行で編集が上書きされます。ビルドが壊れます。繰り返し発生します。

出発点となるベースラインが必要な場合は、上記の例をリポジトリにコピーし、プロジェクトの概要を編集し、コマンドテーブルを調整してください。20分で利用可能なファイルをリリースできます。

FAQ

AGENTS.mdはCLAUDE.mdと同じですか？形式は互換性があります。ほとんどのチームはどちらか一方を真実の源として保持し、もう一方をシンボリックリンクしています。AnthropicとOpenAIは、規約の相互運用性を維持することで公に合意しています。

ファイルをどこに置くべきですか？常にリポジトリのルートに置いてください。一部のエージェントは、サブディレクトリ内のネストされたAGENTS.mdファイルも読み込みます。これはモノレポに役立ちます。最初はルートレベルのファイルを1つ作成し、ルートファイルが長くなりすぎる場合にのみサブディレクトリファイルを追加してください。

どのくらいの長さが適切ですか？200〜400行が最適な範囲です。それ以上だと、エージェントはセクションをスキップし始めます。より詳細な情報が必要な場合は、1行の要約をインラインで記述し、別のドキュメントにリンクしてください。

コードサンプルを含めるべきですか？短いものなら、はい。長いものなら、いいえ。完全な例はテストのために保存してください。エージェントもテストを読みます。GPT-5.5無料Codexガイドでは、Codexが追加のシグナルとして例となるテストをどのように具体的に使用するかについて説明しています。

エージェントは毎回ファイルを再読み込みしますか？ほとんどのエージェントはセッション開始時に読み込み、キャッシュします。一部は大規模なファイル変更後に再読み込みします。大幅な編集を行った場合は、エージェントセッションを再起動するのが最も安全な方法です。

ファイルが機能するかどうかをテストするにはどうすればよいですか？他のコンテキストなしで新しいエージェントセッションを実行し、「POST /paymentsに422レスポンスを追加してください」といった小さなタスクを与え、その動作を観察してください。仕様を読み込み、make codegenを実行し、契約テストを作成すれば、ファイルは正常に機能しています。