CodexのAGENTS.mdとは？CLAUDE.md相当の指示ファイルでAIに前提を渡す方法

Claude Codeを使っている開発者の話を見ていると、よく CLAUDE.md というファイルが出てきます。

これは簡単に言うと、Claude Codeに対して「このプロジェクトではこう動いてください」と伝えるための説明書です。たとえば、使うコマンド、守る設計ルール、触ってはいけない領域、テストのやり方などをあらかじめ書いておきます。

では、OpenAIのCodexにも同じような仕組みはあるのでしょうか。

結論から言うと、あります。Codexでは基本的に AGENTS.md を使います。

この記事では、Codexの AGENTS.md を、非エンジニアの事業担当者・マーケティング担当者・Web担当者にもわかるように整理します。コードの細かい話ではなく、「AIに仕事の前提をどう渡すか」という観点で解説します。

CodexがAGENTS.mdを全体ルール、プロジェクトルール、作業場所ルールの順に読む仕組み — Codexは、全体ルールから作業場所に近いルールまで、段階的に指示を読み込みます。

AGENTS.mdとは何か

AGENTS.md は、AIコーディングエージェント向けの説明書です。

人間向けの README.md が「このプロジェクトは何か」「どう動かすか」を説明するファイルだとすると、AGENTS.md は AI向けのREADME と考えるとわかりやすいです。

たとえば、以下のような内容を書いておきます。

このプロジェクトの目的
使っている技術やサービス
開発・確認に使うコマンド
デザインや文章のトーン
変更してよい範囲、変更してはいけない範囲
公開前に必ず確認すること

毎回チャットで「このサイトはNext.jsで、CMSはmicroCMSで、記事本文にはh1を入れないで、画像はアップロードしてから使って……」と説明するのは大変です。

その前提を AGENTS.md に書いておけば、Codexを起動したときに読み込まれ、作業のズレを減らしやすくなります。

Claude CodeのCLAUDE.mdとの違い

Claude Codeでは、開発者が CLAUDE.md を置いて運用するケースがよくあります。

Codexの標準は、これに近い役割を持つ AGENTS.md です。

項目	Claude Code	Codex
よく使われる指示ファイル	`CLAUDE.md`	`AGENTS.md`
役割	Claude Code向けのプロジェクト説明	AIエージェント向けのプロジェクト説明
置き場所	プロジェクトルートなど	グローバル、プロジェクト、サブディレクトリ
考え方	Claudeに前提を渡す	Codexに前提を渡す

重要なのは、名前の違いではありません。AIに毎回同じ前提を説明しなくて済むようにすることです。

なおCodexでは、設定によって CLAUDE.md をfallbackファイルとして読ませることもできます。すでにClaude Code用のナレッジがある場合は、それを活かせます。

CodexはどのAGENTS.mdを読むのか

Codexは、起動時に指示ファイルを探して読み込みます。公式ドキュメントでは、主に次のような考え方です。

全体ルール：~/.codex/AGENTS.md
プロジェクトルール：プロジェクトルートの AGENTS.md
作業場所ルール：今いるディレクトリに近い場所の AGENTS.md
一時的な上書き：AGENTS.override.md

たとえば、次のような構成です。

~/.codex/AGENTS.md
my-project/
  AGENTS.md
  apps/
    web/
      AGENTS.md
  services/
    payments/
      AGENTS.override.md

apps/web でCodexを動かすと、全体ルール、プロジェクトルール、Web領域のルールが重なって読み込まれます。

より具体的な場所にある指示ほど、現在の作業に近いルールとして効きやすくなります。これは人間の組織でいうと、「会社全体のルール」「プロジェクトのルール」「担当チームのルール」が順番にあるイメージです。

まず作るべきは、自分用の全体ルール

最初におすすめなのは、~/.codex/AGENTS.md を作ることです。

これは、どのプロジェクトでも共通して守ってほしい自分用の基本方針です。

mkdir -p ~/.codex
nano ~/.codex/AGENTS.md

内容例です。

# ~/.codex/AGENTS.md

## Working agreements
- 日本語で説明する
- 変更前に、何を変えるかを短く説明する
- 既存の設計意図を壊さない
- 新しい依存パッケージを追加する前に確認する
- ファイル変更後は、可能な範囲でビルドやテストを実行する
- APIキー、パスワード、個人情報をチャットやコードに出さない

非エンジニアの場合、ここに難しい技術ルールを書く必要はありません。

むしろ、以下のような「仕事の進め方」を書く方が効果的です。

いきなり実装せず、まず方針を説明してほしい
変更後は、何が変わったかを日本語でまとめてほしい
本番公開に関わる操作は慎重に扱ってほしい
不明点がある場合は、勝手に決めずに確認してほしい

プロジェクトごとのAGENTS.mdに書くこと

次に、プロジェクトのルートに AGENTS.md を置きます。

これは、そのサービスやサイトに固有の説明書です。

# AGENTS.md

## Project overview
このリポジトリは、BtoB向けサービスサイトです。
Next.jsで構築し、ブログはmicroCMSで管理しています。

## Commands
- 開発: npm run dev
- ビルド: npm run build
- Lint: npm run lint

## Content rules
- 記事本文にh1は入れない。テンプレート側でタイトルをh1表示する
- 画像はCMSへアップロードしたURLを使う
- CTA文言は「無料相談」または「資料請求」を基本にする

## Safety rules
- 本番DB、決済、認証まわりは勝手に変更しない
- APIキーやトークンを表示しない
- 公開前に表示確認とリンク確認を行う

このように書いておくと、Codexに依頼するときの説明量が減ります。

たとえば、「ブログ記事を1本作って」と頼んだときに、毎回「h1は入れないで」「画像はmicroCMSにアップして」「公開URLも確認して」と言わなくても、プロジェクトのルールとして参照しやすくなります。

非エンジニアがAGENTS.mdをLP改善、CMS運用、チーム引き継ぎ、小さな自動化に使う例 — AGENTS.mdは、開発者だけでなく事業・マーケ・運用担当がAIに前提を渡すためにも使えます。

具体的なユースケース

1. LP・サービスサイト改善

LP改善では、デザインやコピーの前提がとても重要です。

たとえば、AIに「CTAを強くして」とだけ頼むと、派手すぎる表現やブランドに合わない文言になることがあります。

AGENTS.md に次のようなルールを書いておくと、ズレを減らせます。

## LP rules
- トーンは誠実で、煽りすぎない
- ファーストビューでは「誰向けか」と「何が得られるか」を明確にする
- CTAはページ上部・中部・下部に配置する
- 価格や実績の数字は、根拠があるものだけ使う
- 既存のブランドカラーを大きく変えない

非エンジニアがLP改善を依頼する場合、Codexにこう頼めます。

AGENTS.mdのLP rulesを守って、ファーストビューの訴求とCTAを改善してください。いきなり実装せず、まず変更方針を3案出してください。

2. CMS・ブログ運用

ブログやCMS運用では、記事の型、画像の扱い、公開前チェックが毎回発生します。

ここを AGENTS.md に書いておくと、記事作成やリライトの作業が安定します。

## Blog rules
- 専門用語は、最初にやさしく説明する
- 導入文では読者の悩みを明確にする
- 画像は記事内容を補足する図解にする
- 本文にh1は入れない
- 公開後はURL、タイトル、画像、CTAリンクを確認する

たとえば、今回の記事のように「非エンジニアにもわかるように」といった方針も、プロジェクトのコンテンツルールとして残しておけます。

3. チーム引き継ぎ・外部パートナー連携

新しいメンバーや外部パートナーに作業を依頼するとき、毎回口頭で背景を説明するのは大変です。

AGENTS.md は、AIだけでなく人間にとっても役立ちます。

このサービスは誰向けか
何を大事にしているか
触ってよい範囲はどこか
過去に起きた失敗や注意点は何か
公開前に誰が何を確認するか

こうした前提を1ファイルにまとめることで、「担当者しか知らない暗黙知」を減らせます。

4. 小さな自動化・社内ツールづくり

Codexは、LPやアプリ開発だけでなく、小さな業務自動化にも使えます。

CSVを整形してレポートにする
問い合わせ一覧を分類する
定例レポートのテンプレートを作る
Slack通知文を整える
Googleスプレッドシート用のデータを作る

このときも、AGENTS.md に「出力形式」「禁止事項」「確認方法」を書いておくと便利です。

## Automation rules
- 元データは上書きしない
- 変換後のファイルは output/ に保存する
- 金額や日付の形式を勝手に変えない
- 処理件数とエラー件数を最後に報告する

AGENTS.override.mdは、一時的な強い指示に使う

Codexでは AGENTS.override.md も使えます。

これは、通常の AGENTS.md より優先して読ませたい指示があるときに使います。

たとえば、決済まわりのディレクトリでは次のように書けます。

# services/payments/AGENTS.override.md

## Payments service rules
- 決済処理の仕様を勝手に変更しない
- APIキーやWebhook secretを表示しない
- テストなしで本番向け変更を完了扱いにしない
- 不明点がある場合は実装前に確認する

ただし、override は強い指示です。常用するというより、特定領域でミスを防ぐために使うのがよいです。

既存のCLAUDE.mdをCodexでも使う方法

すでにClaude Code用に CLAUDE.md を整備している場合、それをCodexでも使いたくなるはずです。

Codexでは、設定ファイルでfallback filenameを指定できます。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md", ".agents.md"]
project_doc_max_bytes = 65536

これにより、Codexは各ディレクトリで次のような順番で指示ファイルを探します。

AGENTS.override.md
AGENTS.md
CLAUDE.md
.agents.md

つまり、既存の CLAUDE.md を無駄にせず、Codexにも読ませることができます。

ただし、長期的にCodexをよく使うなら、標準名である AGENTS.md に寄せていく方がわかりやすいです。

非エンジニア向け：AGENTS.mdに書くべき項目テンプレート

最初から完璧なファイルを作る必要はありません。まずは次のテンプレートを埋めるだけで十分です。

# AGENTS.md

## このプロジェクトの目的
例：中小企業向けにAI活用支援サービスを紹介し、問い合わせにつなげるサイト。

## 主な読者・ユーザー
例：AI導入に興味はあるが、何から始めるべきかわからない経営者・事業責任者。

## 大事にするトーン
例：専門的すぎず、誠実で、現場で使える説明にする。

## 変更してよいこと
例：見出し、説明文、CTA、FAQ、ブログ本文、画像差し替え。

## 勝手に変更してはいけないこと
例：料金、契約条件、問い合わせ先、認証・決済・本番DB。

## 公開前チェック
- ビルドが通るか
- 画像が表示されるか
- リンクが切れていないか
- スマホで崩れていないか
- CTAが正しいURLになっているか

ポイントは、技術用語よりも 判断基準 を書くことです。

AIはコードを書くことはできますが、「この表現はブランドに合うか」「このCTAは営業上まずいか」「この情報はまだ公開してよいか」といった判断は、人間側の文脈がないとズレます。

読み込まれているか確認する方法

設定したら、Codexに確認させます。

codex --ask-for-approval never "Summarize the current instructions."

サブディレクトリで確認したい場合は、次のように指定します。

codex --cd apps/web --ask-for-approval never "Show which instruction files are active."

意図した指示が出てこない場合は、以下を確認します。

ファイル名が AGENTS.md になっているか
空ファイルになっていないか
Codexを起動しているディレクトリが正しいか
AGENTS.override.md が別の場所に置かれていないか
CODEX_HOME を変更していないか

運用で気をつけたいこと

AGENTS.md は便利ですが、万能ではありません。

特に非エンジニアがCodexを使う場合は、次のガードレールを持っておくと安全です。

本番DB、決済、認証、権限まわりは最初から任せない
APIキーやパスワードをチャットに貼らない
AIの変更差分を必ず確認する
大きな変更は小さく分けて依頼する
公開前に、表示・リンク・フォーム・スマホ表示を確認する
「わからないときは質問する」とAGENTS.mdに書いておく

AIに任せる範囲を広げるほど、事前のルール作りが重要になります。

逆に言えば、AGENTS.md を整えることは、AI活用以前に 自社の業務ルールや判断基準を言語化する作業 でもあります。

まとめ：AGENTS.mdは、AI時代の業務マニュアルになる

Codexにも、Claude Codeの CLAUDE.md に相当する仕組みがあります。

標準的には AGENTS.md を使います。

全体ルールは ~/.codex/AGENTS.md
プロジェクトルールは project/AGENTS.md
領域別ルールはサブディレクトリの AGENTS.md
一時的な強い指示は AGENTS.override.md
既存の CLAUDE.md はfallback設定で使い回せる

非エンジニアにとって重要なのは、コードを書けるようになることだけではありません。

むしろ、AIに対して「この事業では何を大切にするのか」「何を変えてよくて、何を変えてはいけないのか」「公開前に何を確認すべきか」を渡せることが重要です。

AGENTS.md は、そのための実務的な入口です。

AIに毎回同じ説明をするのではなく、プロジェクトの前提をファイルとして残す。これだけで、Codexを使ったLP改善、CMS運用、チーム引き継ぎ、小さな自動化はかなり進めやすくなります。

参考：OpenAI Developers - Custom instructions with AGENTS.md / AGENTS.md

サービス

メニュー