実録
AGENTS.md の書き方を実例で解説(実際に使っている AGENTS.md と CLAUDE.md を公開)
AGENTS.md の書き方を、Claude Code と Codex を併用しているリポジトリで実際に使っているファイルの実例で説明します。見出しの構成、行動規範、役割分担、検証コマンドの書き方と、各項目を入れた理由、書いていないこと、長さの目安をまとめました。
用途と守らせたいルールを選ぶと、AGENTS.md と CLAUDE.md の雛形ができます。登録は不要で、選んだ内容は外部に送りません。
# 作業ルール(すべての AI ツール共通) ## このフォルダについて (ここを書き換える)このリポジトリが何のためのものかを 1〜2 行で書く。 例: 社内の見積もり作成ツール。TypeScript と React で作っている。 ## 作業のルール - 報告は日本語で書き、結論を最初に書く。 - 大きな変更や方針の変更は、作業の前に内容を説明し、了承を得てから進める。 - 変更は小さく分け、1 つずつ確認してから次に進む。 - 変更したら下の「確認の方法」を実行し、結果をそのまま報告する。確認していないことは、確認していないと書く。 - 分からないことは推測で埋めず、分からないと書いて質問する。 - 既存のファイルの書き方、命名、文体に合わせる。 ## やってはいけないこと - パスワード、API キー、個人情報を、ファイルにも報告にも書かない。 - 確認なしにファイルを削除したり、元に戻せない上書きをしたりしない。 - 確認なしに外部へ送信・公開しない(メールの送信、投稿、公開の操作など)。 - 指示なしに git の commit と push をしない。 - 確認なしに新しいパッケージやツールを追加しない。 ## 確認の方法 (ここを書き換える)実際に使っているコマンドを書く。 - テスト: `npm test` - 型チェック: `npm run check` - 1 つのテストだけ実行する方法: (例: `npm test -- path/to/file.test.ts`) ## 気をつける点 (ここを書き換える)同じ注意を 2 回したことがあれば、ここに 1 行で足す。
@AGENTS.md # Claude Code だけに当てはまること 共通のルールは AGENTS.md にある。ここには Claude Code だけに関係することを書く。 (ここを書き換える)なければ、この見出しから下は消してよい。 - 例: 手順の長い作業は、スキルにまとめてから使う。
@AGENTS.md は消さないでください。この行が AGENTS.md を読み込む指定です。以下は 2026-11-21 に各ツールの公式ドキュメントで確認した内容です。ツールの更新で動作が変わることがあるため、うまく読み込まれないときは公式ドキュメントを確認してください。
どちらも、AI のコーディングツールが作業の最初に読む「作業ルールのメモ」です。中身は普通の Markdown で、決まった項目はありません。
Claude Code は、作業フォルダか、その上の階層に CLAUDE.md があると、AGENTS.md を自動では読みません。AGENTS.md だけがある場合は読みますが、この動作には Claude Code の 2.1.277 以降が必要です。
そのため、Claude Code と Codex などを併用するときは、公式ドキュメントが勧める次の形にします。
@AGENTS.md と書いて読み込む(公式の例では 1 行目)。同じルールを両方のファイルに書くと、片方だけ直したときに内容が食い違います。共通のルールは AGENTS.md の 1 か所にまとめてください。
Claude Code の公式ドキュメントは、CLAUDE.md を 1 ファイル 200 行未満にすることを目安にしています。長いファイルは読み込みの負担が増え、指示が守られにくくなるためです。Codex は、読み込む AGENTS.md の合計が初期設定で 32 KiB までです。
書く内容は「AI がフォルダを読んでも分からないこと」に絞ります。確認に使うコマンド、間違えやすい決まり、理由が書かれていない判断などです。フォルダの構成の説明は、AI が自分で読めるので書かなくてかまいません。
/memory で読み込まれているファイルを確認して編集できます。/init は、フォルダの内容をもとに CLAUDE.md の下書きや改善案を作ります。確認日: 2026-11-21
実録
AGENTS.md の書き方を、Claude Code と Codex を併用しているリポジトリで実際に使っているファイルの実例で説明します。見出しの構成、行動規範、役割分担、検証コマンドの書き方と、各項目を入れた理由、書いていないこと、長さの目安をまとめました。
実録
CLAUDE.md は Claude Code が読むファイル、AGENTS.md は複数の AI ツールに共通のファイルです。Claude Code が AGENTS.md を自動で読む条件、併用する 3 つの方法と、共通ルールを 1 か所にまとめた運用例を説明します。