この記事には広告（アフィリエイトリンク）が含まれます。Amazonのアソシエイトとして、PROBEFOLIOは適格販売により収入を得ています。

CodexなどのAIに開発を頼んだら、コードは直ったのに、必要なテストが実行されていなかった。毎回こちらから同じ注意をするのは大変です。人に仕事を引き継ぐときと同じように、最初に読んでほしい案内をプロジェクトへ置けます。

AGENTS.mdは、その案内に使う文章ファイルです。「画面のコードはここ」「変更後はこの検査」「終わったら結果も報告する」と書きます。会社全体のルールと部署ごとのルールがあるように、共通の案内と、作業する場所に合わせた案内を分ける使い方もあります。

ただし、ファイル名が同じでも読み方はツールによって異なります。この記事ではCodexの読み込み方を具体例に、置き場所と短い書き方、適用の確認を説明します。CLAUDE.mdやSKILL.mdとの違いも、何を繰り返し伝えたいかから整理していきましょう。

この記事の目次
01

AIが作業前に読む、プロジェクトの案内

AGENTS.mdは普通のMarkdown文書です。先頭へ特別な設定データを置くことは必須ではありません。対応するツールが読んで、作業の前提に使います。READMEにある情報を全部複製するより、実行時に迷う点への入口をまとめるのが使いやすい形です。

たとえば「ソースはsrc」「検査はnpm test」「自動生成物は元ファイルを直す」「公開は指示された範囲で行う」と書けば、毎回同じ説明を繰り返す量を減らせます。人が読んでも意味が分かる言葉で書きましょう。

02

Codexでは、共通から作業場所へ向かって読む

2026年9月14日に確認した公式資料では、Codexは共通の設定場所と、プロジェクトのルートから現在の作業場所へ至る経路の指示を扱います。近い場所の指示が先の指示を上書きする関係があります。AGENTS.override.mdがある場合や、設定した別名がある場合も扱いが変わります。

このため、どこから作業を始めるかが重要です。「下のフォルダーに書けば、どこで起動しても全部読まれる」と考えないでください。初めはプロジェクトの一番上へ一枚置き、個別ルールが必要になったときだけ分けます。

全体の案内と、画面を直す人への案内

  1. プロジェクト全体：AGENTS.md

    このサービスの目的、全体の構成、共通の確認事項を書く。

  2. 画面のフォルダー：AGENTS.md

    その配下を編集する際の追加ルールを書く。例：スマートフォン表示も確かめる。

  3. 今回のチャットで伝える依頼

    ログイン画面の説明文を直す。今回の変更点と、期待する見え方を伝える。

フォルダーごとの案内を説明する例です。Codexでの詳しい読み込み順は本文の手順で確認します。

毎回守ってほしいことは案内ファイルへ、今日だけの修正はチャットへ、と分けると更新しやすくなります。画面のフォルダーに置く案内は、関係のない場所まで同じルールを広げないためにも使えます。

ただし、下のフォルダーに置けば必ず全部の設定を上書きする、という意味ではありません。使うツールの読み込み順と対象範囲を確認し、実際の作業前にどの案内が適用されるか確かめてください。

03

まず書くのは、構成・検査・完了条件

下の例は、npm testとnpm run lintが存在する架空のプロジェクト向けです。実際には設定ファイルを確認し、使っているパッケージ管理ツールと一致させてください。コマンドを推測で書かないことが大切です。

「最高の品質で」という指示より、「変更した動作のテストを実行し、失敗したら理由と未確認範囲を報告する」の方が結果を確認できます。外部サービスの名前や秘密の値を列挙せず、必要なら設定方法を記した資料へ案内します。

04

適用されているか、作業の前に確かめる

新しく作業を始める際に、「読み込んだ指示ファイルと、このプロジェクトのテストコマンドを挙げて」と依頼します。想定したAGENTS.mdが含まれるか、コマンドがファイルの内容と一致するかを確認します。必要な場合は、ツールが表示する指示の読み込み記録も見ます。

公式の読み込みにはサイズ上限などの設定もあります。ファイルが長すぎるときは、同じ内容を別の場所へ重複して書くのではなく、入口を短くして詳細を参照資料へ分けます。古い運用手順へリンクし続けていないかも確認してください。

この記事のテンプレートは説明用です。別のCodexプロセスへこの例を実行させた検証ではありません。実際の適用は自分の作業環境で、表示と結果を照合してください。

05

CLAUDE.md・SKILL.mdとは役割が違う

CLAUDE.mdはClaude Codeで使われる指示ファイルです。AGENTS.mdをどのように扱うかはツールによって違い、名前を置き換えれば必ず動くとは限りません。共通のルールを一つの文書にまとめる場合も、各ツールからの参照方法を確認します。

SKILL.mdは、繰り返し使う手順をまとめるためのファイルです。名前と説明などのメタデータを持ち、必要な作業で読み込む形に向きます。「このプロジェクト全体の約束」と「記事監査をするときの具体的手順」を分けると、いつも長い説明を読む必要を減らせます。

指示ファイルを整えた後に、Codexでの開発やチームでの使い方まで学ぶなら、AGENTS.mdを扱う章がある書籍を比較できます。下の本はCodex向けです。別のAIツールでも同じ読み込み規則になるとは限りません。

どこに書くか迷ったら
内容置く候補注意点
全体の構成と検査AGENTS.md対応ツールと適用範囲を確認
Claude Code固有の設定CLAUDE.md他ツールにも同じとは限らない
繰り返す詳細手順SKILL.mdと参照資料利用条件が伝わる説明を付ける
今回だけの作業その依頼文恒久ルールへ残しすぎない
秘密の値専用の秘密管理指示文へ直接書かない
06

一枚を保ち、失敗例から育てる

更新する理由は、文章量を増やすことではありません。「いつも違う検査を走らせる」「公開先を取り違えやすい」といった繰り返す問題を、短い指示と確認方法へ変えます。古いルールを残したまま新しいルールを追加しないことも大切です。

詳細な手順を切り出すならSKILL.mdの作り方へ。Claude Code側の運用はCLAUDE.mdの読み込み確認で、ファイルごとの違いを確認できます。

QUICK ANSWERS

よくある疑問を、ここで。

使い始める前に、気になるところから。

AGENTS.mdにもYAMLの設定欄が必要ですか？

普通のMarkdown文書として書けます。SKILL.mdのname・descriptionのような必須メタデータとは区別してください。

この記事の内容をもとにした、編集部からの提案です。
すべてのAI開発ツールで使えますか？

対応や読み込み規則はツールによります。採用しているツールの公式資料でファイル名と探索範囲を確認します。

この記事の内容をもとにした、編集部からの提案です。
書いたルールは絶対に守られますか？

文書の指示だけで実行を保証するものではありません。権限設定、テスト、実行結果の確認も必要です。

この記事の内容をもとにした、編集部からの提案です。

この記事を共有する

X（旧Twitter）（新しいタブで開きます）LINE（新しいタブで開きます）はてなブックマーク（新しいタブで開きます）

商品情報の提供：Supported by Rakuten Developers

SOURCES & EDITORIAL NOTE

出典と、この記事について

公式資料や、記事で参照した発表・報道をまとめています。仕様や料金は、利用する前に最新の案内をご確認ください。

確認した内容と条件は本文に記載しています。結果や使い勝手は、資料や環境によって異なります。編集方針を読む