更新日 2026.06.16

ChatGPT

Codex AGENTS.mdとは？書き方や置き場所、注意点をわかりやすく解説

Codexにコードを書かせると、毎回プロジェクトのやり方を一から説明したり、想定と違うコードが返ってきて直したりする手間に悩んでいませんか。

その悩みは、AGENTS.md（エージェンツエムディー）というファイルをリポジトリに置くだけで大きく減らせます。

Codexは作業を始める前にこのファイルを必ず読み、書かれたルールに沿って動いてくれるからです。

逆に置かないままだと、毎回同じ指示を出し直す時間のロスが続きます。正しく用意すれば手戻りが減り、開発のスピードがぐっと上がるでしょう。

本記事では、codex agents.mdの概要から置き場所や書く内容、作成方法まで初心者向けに解説します。

最後まで読めば、自分のプロジェクトにAGENTS.mdを置いてCodexを使いこなせるようになります。

（株）SHIFT AI 代表取締役 / GMO AI & Web3株式会社AI活用顧問 / 生成AI活用普及協会（GUGA）協議員 / Microsoft Copilot+ PCのCMに出演 / AI活用コミュニティ SHIFT AI（会員20,000人超）を運営。
『日本をAI先進国に』実現のために活動中。Xアカウントのフォロワー数は15万人超え（5/21時点）。

AIにコードを書かせるスキルは、これからの副業や転職で大きな武器になります。未経験からでも体系的に学びたい方は、SHIFT AIの無料セミナーがおすすめです。

SHIFT AIでは、ChatGPTやGeminiなどの生成AIを活用して、副業で収入を得たり、昇進・転職などに役立つスキルを学んだりするためのセミナーを開催しています。

また、参加者限定で、「今日から使えるプロンプト100選」「新時代のAI×デザイン活用ガイド」「Nano Banana Pro 徹底解説」など、全12個の資料を無料で配布しています。

「これからAIを学び始めたい」「AIを使って副業収入を得たい」「AIで業務を効率化したい」という方は、ぜひ以下のボタンからセミナーに参加してみてください。

スキルゼロから始められる！

無料AIセミナーに参加する

Codex AGENTS.mdとは

AGENTS.mdとは、AIコーディングエージェントに向けた「プロジェクトの説明書」です。人間向けの説明書であるREADMEに対して、AIに読ませることを前提に作られています。

Codexはタスクを始める前にAGENTS.mdを読み込み、そこに書かれたコマンドやルールに従って作業します。

つまり、新しく入ったメンバーに渡す「最初に読んでおいてほしいメモ」のような役割です。

結果として、プロジェクトの決まりごとを毎回説明する手間が消え、規約に沿ったコードが安定して返ってきます。

AGENTS.mdは、Codexを使うなら最初に用意したい土台といえます。

Codexの概要や使い方をまず知りたい方は、以下の記事をご覧ください。

ChatGPTに新機能「Codex」が登場！使い方や料金プランを徹底解説

OpenAIが2025年5月、新たなAIコーディングエージェント「Codex」をChatGPTに統合して発表しました。 Codexとは、ソフトウェア開発に特化したモデル「codex-1」を搭載し、複数のコーディング業務を自律的に並行処理…

Codex AGENTS.mdの置き場所は？

AGENTS.mdの置き場所は、以下の3点を押さえましょう。

それぞれ、詳しく説明していきます。

基本はリポジトリ（プロジェクト）の一番上

AGENTS.mdは、リポジトリの一番上（ルート）に置くのが基本です。ここに置けば、そのプロジェクト全体の作業でCodexが読み込みます。

ルートとは、プロジェクトのフォルダを開いて最初に見える階層のことです。READMEと同じ場所にAGENTS.mdを並べるイメージで問題ありません。

Codexアプリでリポジトリを連携している場合も、このルートのAGENTS.mdが読み込まれます。まずはこの1ファイルから始めれば十分です。

1か所にまとまっているため管理もしやすく、後から内容を追加したいときも迷いません。最初の置き場所として最もおすすめできる方法です。

フォルダごとに分けて置くことも可能

AGENTS.mdは、サブフォルダごとに分けて置くこともできます。フロントエンドとバックエンドでルールが違うような、規模の大きいプロジェクトで便利です。

それぞれのフォルダにAGENTS.mdを置くと、そのフォルダ内の作業をするときだけ追加で読み込まれます。共通ルールはルートに、個別ルールは各フォルダに書き分けられます。

まずはルートの1ファイルで運用し、必要になったらフォルダごとに足す流れがわかりやすいでしょう。

設定が重なったときは作業対象に近いフォルダが優先

ルートとサブフォルダの両方にAGENTS.mdがある場合は、作業対象に近いフォルダの内容が優先されます。

Codexはルートから順に読み込み、より深い階層の指示で上書きしていきます。

たとえばルートで「テストはnpm test」と書き、サブフォルダで別のコマンドを指定すれば、そのフォルダではサブ側が使われます。

この仕組みを知っておくと、「全体のルール」と「ここだけのルール」を自然に両立できます。

1ファイルだけで運用する場合は優先順位を気にする必要はありません。複数置くようになったときに、この考え方を活用してみてください。

Codex AGENTS.mdは何を書けばいい？

AGENTS.mdに書く内容は、大きく分けて次の4つです。

それぞれ詳細に説明していきます。

プロジェクトの概要

最初に、そのプロジェクトが何なのかを一言で書きます。Codexが全体像をつかめると、的外れな提案が減ります。

たとえば「ReactとTypeScriptで作るタスク管理アプリ」のように、使っている技術と目的を添えるだけで十分です。

長く書く必要はありません。新しく参加した人に最初の1〜2行で伝えるつもりで書くと、ちょうどよい分量になります。

動かすコマンド

次に、プロジェクトを動かすためのコマンドを書きます。インストール、起動、テストなど、開発でよく使うものをまとめましょう。

Codexはここに書かれたテストコマンドを使って、自分が書いたコードが正しく動くかを確認します。コマンドを伝えておくと、検証まで任せられるようになります。

「インストールは npm install」「テストは npm test」のように、コマンドと用途をセットで書くとわかりやすいでしょう。これだけでCodexの動きが安定します。

コードのルール

コードの書き方のルールも伝えておくことをおすすめします。インデントの幅や命名のしかた、使ってよいライブラリなどです。

ルールを書いておくと、プロジェクトの他のコードと統一感のあるコードが返ってきます。後から自分でフォーマットを直す手間が減るのが利点です。

「インデントはスペース2つ」「新しいライブラリは追加せず既存のものを使う」のように、守ってほしい点を具体的に書くのがコツです。

やってほしくないこと

触ってほしくないファイルや、避けてほしい操作も書いておきます。これは事故を防ぐうえでとくに大切です。

たとえば「設定ファイルは編集しない」「.envファイルは変更しない」と書いておけば、Codexが大事なファイルを勝手に書き換えるのを防げます。

守ってほしいことだけでなく、やめてほしいことも伝える点がポイントです。禁止事項を明示しておくと、安心してCodexに作業を任せられます。

【3ステップ】Codex AGENTS.mdの作り方

AGENTS.mdの作り方は以下の3ステップです。

ステップ1：Codexアプリで対象リポジトリを開く
ステップ2：「AGENTS.mdを作って」と依頼する
ステップ3：差分を確認して反映する

AGENTS.mdの作成は、CodexのアプリでもCLI（ターミナル）でも、できることは変わりません。

本記事では、はじめての方にもわかりやすいよう、アプリだけで完結する手順にしぼって紹介します。

ステップ1：Codexアプリで対象リポジトリを開く

まず、AGENTS.mdを置きたいプロジェクトをCodexで開きます。クラウド版でGitHub連携を使っている場合は、対象のリポジトリを選びます。

デスクトップアプリなどローカルで作業する場合は、AGENTS.mdを置きたいプロジェクトフォルダをCodexで開きます。

【3ステップ】codex agents.mdの作り方/ステップ1：Codexアプリで対象リポジトリを開く

すでにCodexで開発しているプロジェクトがあれば、その状態のままで問題ありません。準備ができたら、次のステップに進みます。

ステップ2：「AGENTS.mdを作って」と依頼する

次に、Codexに「このプロジェクトを調べて、セットアップ方法やテストコマンド、コーディング規約を含むAGENTS.mdを作って」と頼みます。

すると、Codexが中身を調べ、AGENTS.mdの内容を自動で作ってくれます。

【3ステップ】codex agents.mdの作り方/ステップ2：「AGENTS.mdを作って」と依頼する

入れてほしい内容を具体的に伝えるほど、実用的なものができます。

ステップ3：差分を確認して反映する

最後に、Codexが作成したAGENTS.mdの内容（差分）を確認します。気になる点があれば、修正を依頼してから反映しましょう。

GitHub連携を使っている場合は、Codexが変更内容をプルリクエストとして提案できます。内容を確認してマージすれば、AGENTS.mdがリポジトリに追加されます。

ローカルで作業している場合は、アプリ内で差分を確認し、そのまま保存（コミット）すれば反映されます。いずれの場合もCodexアプリ内で作成から反映まで進められます。

反映したAGENTS.mdは、次に始める新しいタスク（セッション）から読み込まれます。編集中のタスクには反映されない点に注意しましょう。

正しく読み込まれているか不安なときは、Codexに「いま読み込んでいるAGENTS.mdの内容を要約して」と聞くと確認できます。これなら初心者でも安心して設定を終えられます。

Codexアプリの使い方に関して詳しく知りたい方は、以下の記事もご覧ください。

Codex AGENTS.mdとCLAUDE.md・README.mdの違い

AGENTS.mdとよく似たファイルに、CLAUDE.mdとREADME.mdがあります。

役割の違いを整理しておくと、迷わず使い分けられます。

CLAUDE.mdとの違い
README.mdとの違い

それぞれの違いに関して、詳しく説明していきます。

CLAUDE.mdとの違い

AGENTS.mdは多くのツールで使える共通の指示書、CLAUDE.mdはClaude Code向けの指示書です。

項目	AGENTS.md	CLAUDE.md
対象ツール	Codexなど多くのAIエージェント共通	主にClaude Code
位置づけ	ツールに依存しない共通の指示書	Claudeに最適化した指示書
使い分け	CodexやCursorを使うなら基本こちら	Claude Codeをメインで使うなら

Codexを使うならAGENTS.mdを用意すれば十分です。複数のツールを併用する場合も、共通フォーマットのAGENTS.mdにまとめておくと管理が楽になります。

CodexとClaude Codeのどちらを使うか迷っている方は、両者の違いを比較した記事もあわせて読むと選びやすくなります。

README.mdとの違い

AGENTS.mdとREADME.mdは、読む相手が違います。README.mdは人間向け、AGENTS.mdはAI向けの説明書です。

項目	AGENTS.md	README.md
読む相手	AI（Codexなど）	人間（開発者）
主な中身	コマンド・規約・禁止事項	プロジェクト紹介・使い方
目的	AIに正しく作業させる	人に内容を伝える

READMEに作業ルールを書いてもCodexが優先して読むとは限りません。AI向けの指示は、AGENTS.mdにまとめるのが確実です。

2つのファイルは役割が違うため、両方そろえておくのが理想です。人間にもAIにも伝わるプロジェクトになり、開発がスムーズに進みます。