AGENTS.md の書き方を実例で解説(実際に使っている AGENTS.md と CLAUDE.md を公開)
公開: 著者: 問い合わせ設計室 運営事務局

AGENTS.md は、AI のコーディングツールに作業のルールを伝える Markdown のファイルです。この記事では、実際に使っている AGENTS.md と CLAUDE.md の構成と、各項目を入れた理由、書き方の具体例が分かります。
結論から書くと、書くのは「AI がフォルダを読んでも分からないこと」です。完了の条件、確認を求める場面、検証コマンド、触ってはいけない場所を先に書きます。機能の一覧や作業の履歴は書きません。
題材は、運営している占い SaaS「Stellica」のリポジトリです。Claude Code と Codex を併用していて、共通のルールを AGENTS.md の 1 か所に書き、CLAUDE.md はそれを読み込む短いファイルにしています。
載せているのは、どの現場でも使える部分の抜粋です。プロダクトに固有の仕様、ファイルの場所、外部サービスの設定に関わる行は外し、一部は言い回しを一般的な形に直しています。全文の転載ではありません。
ファイルの内容は 2026 年 11 月 21 日時点のものです。公式の仕様に関する記述も、同じ日に各ツールの公式ドキュメントで確認しました。
AGENTS.md の基本
AGENTS.md には決まった項目がなく、普通の Markdown で好きな見出しを使えます。置き場所と読まれ方は、ツールごとに少し違います。
| 公式の説明 | |
|---|---|
| 項目 | 必須の項目はない。好きな見出しを使ってよい |
| 置き場所 | リポジトリの最上位。フォルダごとにも置け、編集するファイルにいちばん近いものが優先される |
| Codex の読み方 | 最上位から作業フォルダまでをたどり、フォルダごとに 1 つずつ読んでつなげる。合計 32 KiB まで(初期設定) |
| Claude Code の読み方 | 作業フォルダとその上の階層に CLAUDE.md がないときだけ、自動で読む(v2.1.277 以降) |
Claude Code と Codex を併用するときは、CLAUDE.md から AGENTS.md を読み込む指定が要ります。条件の詳しい説明は、CLAUDE.md と AGENTS.md の違いに書きました。
全体の形
リポジトリの最上位に、AGENTS.md と CLAUDE.md の 2 つを置いています。ルールを直すときは、AGENTS.md だけを直します。
| ファイル | 行数 | 役割 |
|---|---|---|
| AGENTS.md | 195 行 | Claude Code と Codex に共通のルール。ルールを直すときはここだけを直す |
| CLAUDE.md | 37 行 | AGENTS.md を読み込む指定と、Claude Code だけに関係する運用 |
CLAUDE.md の書き出しは次のとおりです。
**プロジェクト規約の正本は `AGENTS.md`**。ルールの追加・変更は AGENTS.md に対して行う。
本ファイルには Claude 固有の運用だけを書く。
@AGENTS.md
@AGENTS.md の行が、AGENTS.md を読み込む指定です。初期設定の Claude Code は、作業フォルダかその上の階層に CLAUDE.md があると、AGENTS.md を自動では読みません。そのため、CLAUDE.md を置いて併用するときは、この 1 行が必要になります。この形は、Claude Code の公式ドキュメントに載っているものです。
AGENTS.md の見出しと、入れた理由
見出しは 10 個で、守ってほしい度合いが高く、どの作業にも関係するものを先に置いています。
| 見出し | 書いてあること | 入れた理由 |
|---|---|---|
| 行動規範 | どの作業にも当てはまる 7 つの決まり | 作業の終わり方と、確認を求める場面をそろえるため |
| 役割分担 | どのツールが何を担当するか | 2 つのツールが同じファイルを読むため |
| 通常の開発と、厳格に管理する作業の境界 | 重い手順を使う作業の一覧 | 手順を全部の作業にかけると進まなくなるため |
| 検証コマンド | テスト、型チェック、ビルドのコマンド | AI がフォルダを読んでも「どれを通せば完了か」は分からないため |
| ツール別のメモ | ツールごとの読み込み方と使い分け | 共通のファイルの中で、片方だけに関係することを分けるため |
| プロジェクトの概要 | 何のサービスかを 3 行ほど | 用語の前提をそろえるため |
| 触ってはいけない場所 | 変更の前に確認が要る場所、本番で実行してはいけないもの | 事故になったときに戻せないため |
| 資料の場所 | 仕様ごとの「正しい資料はどれか」の表 | 一覧をこのファイルに持つと古くなるため |
| コーディング規約 | 言語ごとの決まり、画面の決まり | 同じ指摘を繰り返さないため |
| Git の決まり | commit、push、ほかの作業中の変更の扱い | 複数の作業が同じリポジトリで並行するため |
以下、他の現場でもそのまま使える項目を抜粋します。
行動規範の 7 項目
ファイルの先頭には、どの作業にも当てはまる 7 つの決まりを置いています。作業の終わり方と、確認を求める場面をそろえるためのものです。見出しは原文のまま、説明は短くしています。
## 行動規範(全エージェント共通・最優先)
1. 完了を製品成果で機械的に判定する: 着手前に「完了」を 1 行で定義する
(例: このテストが通る / このコマンドが正常に終わる / この見出しが本文に入る)。
2. 可逆な判断は自律的に進める: 差分から戻せる範囲は、仮定を明示して進める。
成果物・公開仕様・データ・費用・リスクが実質的に変わる選択だけを確認する。
3. ついで改善を禁止する: 依頼されていない変更を実装しない。
隣の改善点を見つけたら、実装せずに提案として列挙する。
4. 検証は影響範囲に比例させる: 最短の対象テストから始め、
変更の広さに応じて型チェック・全体のテスト・ビルドを追加する。
5. 同じエラーでは再診断する: 同じ原因に対して違う直し方が 2 回失敗したら、
直し方を増やさず、原因を調べ直す。
6. 完了前に統合差分をレビューする: 差分全体を、初めて読むつもりで 1 回見直す。
7. 進捗報告で作業を分断しない: 長い作業だけ
「完了したこと / 次にやること / 気になっていること」を短く共有する。
それぞれ、入れた理由があります。
| 項目 | 入れた理由 |
|---|---|
| 1 | 作業が終わらなくなるのを防ぐため。完了の条件を先に決めないと、AI は「念のため」の確認を足し続ける |
| 2 | 確認の回数を減らすため。質問してよい条件のほうを書いた |
| 3 | 差分を読める大きさに保つため。頼んでいない修正が混ざると、確認する側の負担が増える |
| 4 | 小さな修正のたびに全部のテストとビルドを回すと、時間がかかるため |
| 5 | 同じ失敗の繰り返しを止めるため |
| 6 | 作業した本人の見直しを 1 回で終えるため |
| 7 | 報告のたびに作業が止まるのを防ぐため |
補足が 3 つあります。
- 1 の原文には、考えられる不安がなくなることを完了の条件にしない、とも書いています。
- 2 は、何でも質問されると作業が止まり、何も質問されないと費用やデータに関わる判断まで進んでしまう、という両方を避けるための書き方です。
- 6 について、別の担当によるレビューを使う条件(高リスクの変更など)も、原文では決めています。
ツールごとの役割分担
Claude Code と Codex で担当を分け、その分け方を共通のファイルに書いています。2026 年 11 月からの分け方は次のとおりです。
## 役割分担
- Claude Code: 企画・作業分解・作業指示書の作成・成果物の確認・テキスト全般
(画面の文言・記事・仕様書・コミットメッセージ・PR の説明)。アプリのコードは書かない
- Codex: コードの実装・修正・テスト・調査。作業指示書に従って作業する
実装を担当する Codex には、作業指示書を受け取ったときの決まりも書いています。
1. 指示された範囲だけを最小限に変える。指示書の「変更対象ファイル」以外を編集しない。
ほかに必要な変更が見つかったら、実装せず結果報告に書く
2. 仕様に迷ったら実装せず質問を返す。成果物が変わる解釈が 2 つ以上あるときは、
その時点で止め、選択肢と推奨を返す。変数名や内部構造など、
成果物が変わらない実装上の判断は自分で決めてよい
3. 画面の文言・記事・ドキュメントの文章は書かない。指示書に指定された文言をそのまま使う。
指定がなければ `TODO(copy)` を置き、報告する
4. commit / push / merge はしない。作業ブランチで変更を残して終える
5. 結果報告の形式: やったこと / 変更ファイル / 実行したテストと結果 / 未解決・質問
役割分担を共通のファイルに書くのは、どちらのツールも同じファイルを読むからです。片方のファイルにだけ書くと、もう片方は自分が何を担当しないのかを知らないまま作業します。
2 では、質問を返す条件と一緒に「自分で決めてよい範囲」も書いています。質問を返す条件だけを書くと、変数名のような細かいことまで質問が返ってくるおそれがあるためです。
通常の開発と、厳格に管理する作業の境界
承認の記録や、独立したレビューといった重い手順は、対象の作業を一覧にして、それ以外では使わないと書いています。一覧は、一般的な言い方に直すと次のとおりです。
- データベースの権限設定とスキーマの変更、本番のデータベース
- 課金、返金、決済の通知の処理
- 本番への反映、本番で動く定期実行、外部への書き込み、有料 API の大量実行
- 認証とアクセス制御、個人データの扱い、秘密情報と本番の設定
- サービスの中核になる計算ロジック
この一覧を入れた理由は、安全のための手順が通常の作業にも広がっていったからです。厳しい手順を全部の作業に求めると、小さな修正にも時間がかかります。反対に、何も書かなければ、課金やデータベースの変更も通常の修正と同じ扱いになります。境界を一覧で書いておくと、AI はどちらの進め方をするかを自分で判断できます。
同じ章に、検証のための仕組みを増やしすぎない決まりも書いています。
- 既存のテスト、CLI、サービスの標準機能を優先する。独自の仕組みは、
既存の手段では受入条件を証明できない具体的な欠落がある場合だけ作る。
- 検証補助の実装量が、対象の製品変更を上回り始めたら、追加実装を停止する。
- 製品の受入条件を満たした時点で「完了」とする。理論上のリスクへの追加の対策は、
完了を止める理由にせず、別の改善候補として報告する。
AI に「しっかり確認して」と頼むと、確認のためのスクリプトや記録の仕組みを作り始め、そちらが本体より大きくなることがあります。この項目は 2026 年 8 月に足しました。
検証コマンド
テスト、型チェック、ビルドのコマンドを、コードブロックでそのまま書いています。コマンドの一覧だけでなく、「どれが必須で、どれが広い変更のときだけか」を書くのが要点です。
実際のコマンドはプロジェクトに固有なので、ここでは形だけを示します。
## 検証コマンド(変更範囲に応じて選ぶ)
まず対象のテストを実行し、変更の広さに応じて次を追加する。
画面側を変えたときの型チェックは必須。全体のテストとビルドは、広い変更かリリースのときに行う。
(ここに、テスト・型チェック・lint・ビルドのコマンドをコードブロックで書く)
一覧だけだと、毎回すべてを実行するか、どれも実行しないかのどちらかになりがちです。
触ってはいけない場所
事故になると戻せない場所を、短い一覧にしています。どの行も「何を、どうしてはいけないか」と「代わりにどうするか」を 1 行で書きます。
中身はプロダクトに固有なので、書き方の型だけを挙げます。
- 変更の前に、決まったコマンドで現状を確認する場所(例: データベースの権限設定)
- 本番で実行してはいけないスクリプト(「開発用のデータベースでだけ実行する」と書く)
- 計算結果を変えたら、既知のデータで検証する処理
- 設定値を読む場所を 1 か所に限る決まり(「このファイル以外から環境変数を読まない」)
「注意する」とだけ書いた行は、AI が何をすればよいか判断できません。
資料の場所は表にして、一覧は持たない
仕様や設計の資料は、内容を AGENTS.md に写さず、「この話題の正しい資料はこれ」という表だけを置いています。表の上には次の 1 行があります。
常時コンテキストには変わりにくい規約だけを置く。実装状況や完了履歴は必要時に正本を読む。
表の最後の行は、ページや API や実装ファイルの場所についてです。ここには場所を書かず、「古い一覧を信用せず、検索して見つける」と書いています。
機能の一覧や完了した作業の履歴は、このファイルに書いても更新が追いつかず、古くなります。古い一覧を AI が信じて作業するよりも、その場で検索させるほうが確実です。
コーディング規約と Git の決まり
コーディング規約は言語ごとに 4 行から 6 行で、理由を括弧で添えている行があります。他の現場でも使えるものを抜粋します。
- 型の指定は必須
- `any` 型の使用禁止(`unknown` を使って型ガードする)
- 自動生成のファイルは、生成コマンドで作り直す。手動で編集しない
- パッケージを入れたら、必ず依存関係の一覧にも追加する
(デプロイ先は一覧からインストールするため、漏れるとデプロイに失敗する)
- 片側だけのカラー線を、装飾や選択表示に使わない
- 画面に出る文言に絵文字を入れない
理由があると、AI は似た場面にも当てはめて判断できます。
Git の決まりは、複数の作業が同じリポジトリで並行することを前提にしています。
- commit、push、PR は、ユーザーが明示または事前承認した場合だけ実行する
- ほかの作業中の変更(未コミットのファイル)を stage、stash、revert、削除しない。
対象のパスの status / diff だけ確認する
- commit が承認された場合は、動作に必要な一式に限定してコミットする
- 新規ファイルを報告から漏らさない。ただし、消えるのを防ぐためという理由で、
無断で commit / push しない
CLAUDE.md に書いていること
@AGENTS.md の下には、Claude Code だけに関係することを書いています。
| 項目 | 書いてあること |
|---|---|
| 自分の役割 | 企画、作業の分解、Codex への指示、成果物の確認、文章全般。編集してよいのは設定ファイルとドキュメントだけ |
| 作業の流れ | 企画、承認、指示書の作成、受け渡し、結果の受け取り、確認、報告の順。承認されるまで実装には渡さない |
| 禁止事項 | 同じファイルを 2 つのツールで同時に編集しない。秘密情報を指示書やログに書かない。承認なしに main へ merge や push をしない |
| スキルの使い分け | どのスキルを自動で使ってよく、どれは明示されたときだけ使うか |
役割分担は AGENTS.md にも書いてありますが、CLAUDE.md には「Claude Code 自身がどう動くか」の手順を書いています。Codex が読む必要のない内容だからです。
書いていないこと
次の内容は、AGENTS.md にも CLAUDE.md にも書いていません。
| 書いていないこと | 理由と、代わりの置き場所 |
|---|---|
| フォルダの構成の説明 | AI が自分で読める |
| 完了した機能の一覧と作業の履歴 | 別の記録にあり、すぐ古くなる |
| 手順の長い作業 | 記事の制作や公開前の点検はスキルに分け、「その作業はこのスキルが正しい資料」とだけ書く |
| 鍵やトークンなどの秘密情報 | 「値を文書や出力に書かない」という決まりのほうを書く |
手順の長い作業をスキルに分けることは、Claude Code の公式ドキュメントも勧めています。
長さの目安に対して
長さの目安は、Claude Code が 1 ファイル 200 行未満、Codex が合計 32 KiB までです。いまの構成は、どちらにも収まっています。
| 公式の目安と上限 | このリポジトリ | |
|---|---|---|
| Claude Code | CLAUDE.md は 1 ファイル 200 行未満が目安 | AGENTS.md が 195 行、CLAUDE.md が 37 行 |
| Codex | 読み込む AGENTS.md の合計が 32 KiB まで(初期設定) | AGENTS.md が約 18 KiB |
Claude Code について、注意点が 1 つあります。@ で読み込んだファイルは、読み込む側と一緒に読まれるので、分けても負担は減りません。Claude Code が毎回読むのは、合わせた 232 行です。
2026 年 7 月の初めには、AGENTS.md だけで 478 行ありました。そこから数回の見直しで 195 行まで減らしています。減らした経緯はCLAUDE.md と AGENTS.md の違いに書きました。
「30 行まで」「500 行まで」といった目安を挙げている記事もあります。どちらの数字も、2026 年 11 月 21 日の時点で、公式ドキュメントでは確認できませんでした。AGENTS.md の公式サイトには、長さの目安は書かれていません。
自分のファイルを書くときの順番
これから書く人は、検証コマンド、承認なしにやってはいけないこと、触ってはいけない場所の 3 つから始めるのがおすすめです。残りは、使いながら足します。
- 検証コマンドと、「どれを通せば完了か」を書く。
- 承認なしにやってはいけないこと(commit、push、本番への反映、外部への送信)を書く。
- 触ってはいけない場所を、代わりの手順と一緒に書く。
- 同じ注意を 2 回したら、その内容を 1 行で足す。
- 行が増えてきたら、一覧と履歴を削り、長い手順をスキルに分ける。
最初の雛形は、AGENTS.md・CLAUDE.md ジェネレーターで作れます。用途と守らせたいルールを選ぶと、併用の形(CLAUDE.md の 1 行目に @AGENTS.md)で出力されます。
よくある質問
AGENTS.md には何を書く?
AI がフォルダを読んでも分からないことを書きます。検証コマンドと完了の条件、承認なしにやってはいけないこと、触ってはいけない場所が、最初に書く 3 つです。必須の項目はなく、見出しは自由に決められます。
AGENTS.md は何行までにすべき?
AGENTS.md の公式サイトには、長さの目安は書かれていません。Claude Code は CLAUDE.md を 1 ファイル 200 行未満にすることを目安にしています。Codex は、読み込む合計が初期設定で 32 KiB までです。
AGENTS.md はどこに置く?
リポジトリの最上位に置きます。フォルダごとに置くこともでき、その場合は、編集するファイルにいちばん近いものが優先されます。
AGENTS.md は日本語で書いてよい?
公式サイトの説明は「普通の Markdown」というだけで、言語の決まりは見つかりませんでした。このリポジトリでは日本語で書いています。
Claude Code でも AGENTS.md は使える?
使えます。v2.1.277 以降の Claude Code は、CLAUDE.md がなければ AGENTS.md を自動で読みます。CLAUDE.md も置く場合は、CLAUDE.md に @AGENTS.md と書いて読み込みます。
まとめ
- AGENTS.md に決まった項目はありません。書くのは「AI がフォルダを読んでも分からないこと」です。
- 先頭には、完了の条件と、確認を求める場面を決める行動規範を置いています。
- 重い手順を使う作業は一覧にして、それ以外の作業には広げません。
- 決まりには理由と「代わりにどうするか」を添えます。「注意する」だけの行は役に立ちません。
- 機能の一覧と履歴は書かず、長い手順はスキルに分けて、1 ファイル 200 行未満を保ちます。
この運用で進めている記事制作と検索対策の記録は、新規ドメインを約 8 か月で月間 約 9,000 クリックにした施策の全記録にまとめています。自社のルールの文書化を含めて、AI エージェントの導入を相談したい場合は、AI エージェント導入・伴走支援をご覧ください。
出典
いずれも 2026 年 11 月 21 日に確認しました。
- Claude Code 公式ドキュメント: メモリ(CLAUDE.md と AGENTS.md)
- Claude Code 公式ドキュメント: ベストプラクティス
- AGENTS.md の公式サイト
- OpenAI Codex の AGENTS.md ガイド(developers.openai.com/codex/guides/agents-md から転送されます)