OpenAI Codexの使い方完全ガイド：AGENTS.md, Skills, Rules, MCPを一気に理解

AIが既存のコードベースを読み、新機能を実装し、テストまで回してくれる。OpenAIのコーディングエージェント「Codex」は、まさに革命的な開発体験を実現するツールだ。

ただ、使い始めは壁にぶつかりやすい。AGENTS.md、Skills、Rulesなど聞き慣れない用語が多く、どこから手をつければいいのか分からない。公式ドキュメントを読んでも、全体像が見えづらい。

本記事は、そんな初心者のための導入ガイドだ。

Codexを使い始めたばかりの人、あるいはClaude CodeからCodexに乗り換えようとしている人に向けて、主要機能の全体像を一気に解説する。

記事の後半では、CodexのようなAIエージェントを利用する上で注目されている「仕様駆動開発」にも触れる。
「仕様駆動開発」は、複雑・大規模なプロジェクトでも、AIエージェントを暴走させずに、最大限に能力を発揮させるためのベストプラクティスだ。

この記事を読むだけで、Codexの基本を理解し、自分のワークフローに組み込める状態になっているはずだ。

Codexの全体像

まずはCodexの主要概念と構成要素を俯瞰しておく。個別の詳細は後述するので、ここでは「どんなパーツがあるか」を掴むことが目標だ。

主要概念：早見表

概念	役割
AGENTS.md	「このプロジェクトではこう動け」という常設の指示書
Skills	再利用可能な特定タスク用の手順書
Custom Prompts	よく使うプロンプトのテンプレート
Rules	コマンド実行の許可/確認/禁止の制御
config.toml	モデル選択・承認ポリシー・サンドボックス

競合の類似ツール「Claude Code」の用語で言うと、AGENTS.mdはCLAUDE.md、Skillsは同名の概念に対応する。RulesはCodex固有の概念だ。Claude Codeユーザー向けの詳しい対応表は記事後半にまとめている。

ディレクトリ構成：どこに何を置くか

Codexの設定ファイルには「グローバル」と「プロジェクト」の2つの配置場所がある。

プロジェクト単位の設定:

プロジェクト固有の設定は、リポジトリ内に配置する。

my-project/
├── AGENTS.md              # プロジェクト指示書
├── AGENTS.override.md     # 上書き用（任意）
├── .codex/
│   └── skills/            # プロジェクト固有のSkills
│       └── deploy/
│           ├── SKILL.md
│           └── scripts/
└── src/
    └── components/
        └── AGENTS.md      # サブディレクトリ固有の指示（任意）

グローバル設定（~/.codex/）:

すべてのプロジェクトに適用されるユーザー単位の設定は、ホームディレクトリの~/.codex/配下に配置する。

~/.codex/
├── config.toml          # 基本設定（モデル、承認ポリシー等）
├── AGENTS.md            # グローバル指示書
├── prompts/             # Custom Prompts
│   └── draftpr.md
├── rules/               # Rules
│   └── default.rules    # CLIで承認したルールが自動追記される
└── skills/              # ユーザー単位のSkills
    └── pr-review/
        ├── SKILL.md
        └── scripts/

3つの利用形態

Codexには大きく3つの利用形態がある。

利用形態	特徴	典型用途
CLI	ターミナル中心。設定や自動化と相性が良い	小回りの効く修正、調査、レビュー
IDE拡張（VS Code等）	エディタで完結。変更の確認が速い	普段の開発フローに溶け込ませる
Web（Codex cloud）	環境構築なし。隔離コンテナで動く	並列タスク、手元環境が重い作業

基本機能を理解するという意味では、CLI版から試してみると良い。

ただ、コードの差分などの見やすさ、プロジェクトツリーの見やすさは、VS CodeなどのIDEの拡張機能がベストだ。筆者も、利用頻度としてはIDE内が一番多い。

この記事では、IDE版とCLI版のスクショを混ぜて解説している。

とりあえずCodexを動かしてみる

全体像を掴んだら、まずは1回動かしてみよう。細かい設定は後からでよい。

Codexは、ChatGPTの有料プランに含まれている。また、OpenAIのAPIキーで従量課金で利用することも可能だ。

インストールと起動

CLI版は、ターミナルで以下のコマンドを打つだけで、インストール＆起動ができる。

# インストール
npm install -g @openai/codex
# 起動（適当なプロジェクトフォルダ内で）
codex
# 初回はChatGPTアカウントでのログインが求められる

起動したら、「このリポジトリの構成を説明して」など簡単な指示を出してみよう。Codexがファイルを読み、回答してくれれば成功だ。

超基本のスラッシュコマンド

CLI内では、平文でのプロンプトのほか、スラッシュ記号と組み合わせて特定の機能を呼び出すコマンドが使える。

例えば/modelと打ち込むことで、Codexが使用するモデルを選択することができる。

コマンド	機能
`/model`	使用中のモデルを確認・変更
`/approvals`	承認ポリシーを確認・変更
`/skills`	利用可能なSkillsを一覧表示
`/help`	ヘルプを表示

主要機能を理解する：AGENTS.md, Rules, Skills, Custom Prompts

Codexを使う上で重要・頻出な概念は、AGENTS.md・Rules・Skills・Custom Promptsの4つだ。

これらを適切に使い分けることで、エージェントの挙動を制御し、繰り返し作業を効率化できる。

AGENTS.mdで「毎回変わらない前提・背景」を固定する

AGENTS.mdは、Codexに対する常設の指示書だ。

「テストはpnpm testで実行」「コミットメッセージはConventional Commits形式」といったプロジェクトの前提を記述しておくと、毎回指示しなくてもCodexが自動的に従ってくれる。

/initコマンドを使えば、AGENTS.mdの雛形を生成することも可能だ。

グローバル → プロジェクト → 現在地で設定可能

Codexは起動時に複数の場所からAGENTS.mdを探し、それらを連結して読み込む。

グローバル: ~/.codex/AGENTS.md（すべてのプロジェクトに適用）
プロジェクトルート: リポジトリ直下のAGENTS.md
サブディレクトリ: 現在の作業ディレクトリまでの各階層

重要: 複数ファイルは「上書き」ではなく「連結」される。グローバル → プロジェクト → サブディレクトリの順に空行で結合され、1つのプロンプトとしてCodexに渡される。現在地に近いファイルほどプロンプトの後ろに配置されるため、AIは後から出てきた指示を優先的に参照する仕組みだ。

なお、各ディレクトリからは1ファイルのみ読み込まれる。同じディレクトリにAGENTS.override.mdがあればAGENTS.mdは無視される。チーム共有のAGENTS.mdを残したまま個人設定を追加したい場合に便利だ。

なお、AGENTS.mdの合計サイズは32KiBに制限されている。上限に達すると、それ以降のファイルは読み込まれない。長くなりすぎるとCodexのコンテキストを圧迫するため、簡潔さを保つことが重要だ。

AGENTS.mdには何を書くべきか

agents.md公式サイト（Linux Foundation傘下のAgentic AI Foundationが管理）では、AGENTS.mdを「エージェント向けのREADME」と位置づけている。人間向けのREADME.mdとは別に、エージェントが作業するために必要な情報を書く場所だ。

公式が推奨するセクションは以下の通り。

Project overview: プロジェクトの概要
Build and test commands: ビルド・テストコマンド
Code style guidelines: コードスタイルのガイドライン
Testing instructions: テストの実行方法
Security considerations: セキュリティ上の注意点

モノレポなど大規模なリポジトリでは、サブディレクトリごとにAGENTS.mdを配置することで、各パッケージに固有の指示を与えられる（agents.md公式によると、OpenAIのメインリポジトリには88個ものAGENTS.mdファイルがあるという）。

Skillsは「チームで共有できる手順書＋道具箱」

Skillsは、特定のタスクに必要な手順・スクリプト・参考資料をパッケージ化したものだ。

Skillsの最大の魅力は、プログラミング不要で、Markdownを書くだけでCodexの能力を拡張できる点にある。

「PRレビューの観点チェックリスト」「このサービス特有のデプロイ手順」「運用Runbook」など、手順やノウハウをSkill化しておけば、繰り返し瞬時に実行できる。

AGENTS.mdは常に読み込まれるため、こうした手順を盛り込みすぎると、AIが一度に処理できる情報量（コンテキスト）を圧迫してしまう。Skillsは必要なときだけ読み込まれる（Progressive Disclosure）設計のため、多くのSkillを登録しても無駄がない。

Skillの作り方

チームでリポジトリにコミットして共有することも、個人用に~/.codex/skills/に置くこともできる。

.codex/skills/（リポジトリ用）または~/.codex/skills/（個人用）にフォルダを作成し、SKILL.mdを配置するだけでよい。

~/.codex/skills/
└── pr-review/
    ├── SKILL.md        # Skill本体（必須）
    ├── scripts/        # 補助スクリプト（任意）
    └── references/     # 参考資料（任意）

SKILL.mdの中身も非常にシンプルに書くことができる。

---
name: PR Review
description: Assists with pull request code reviews
---

## 手順
1. `gh pr diff --name-only` で変更ファイル一覧を取得
2. セキュリティ・パフォーマンス・規約準拠の観点でレビュー
3. Good / Concern / Suggestion の形式で結果をまとめる

nameとdescriptionだけが必須項目だ。Codexはこのdescriptionを見て、ユーザーのタスクに関連するSkillを自動選択する。

なお、Claude Codeにも全く同じSkills機能がある。CodexとClaude Codeでスキルを使い回すことも可能だ。

Claude Codeではdescriptionを英語で書くことが推奨されているため、両方で使い回したい場合は英語にしておくと無難だ。

Skillの呼び出し方

明示的: /skillsコマンドで一覧を表示し、$skill-nameで指定
暗黙的: 普通に「このPRをレビューして」と依頼すると、descriptionに基づいてCodexが適切なSkillを自動選択

なお、Codexには$skill-creator（新しいSkillを作成）などのビルトインSkillが同梱されており、GitHubで公開されているSkillをインストールすることもできる。

Custom Promptsは「自分専用のショートカット」

Custom Promptsは、繰り返し使う指示をテンプレート化する機能だ。Skillsが「チームで共有可能な複雑なタスク定義」であるのに対し、Custom Promptsは「個人用の簡単なショートカット」という位置づけである。

基本的な作り方

~/.codex/prompts/ディレクトリにMarkdownファイルを作成する。

ファイル名（拡張子を除いた部分）がコマンド名になり、/prompts:<name>として呼び出せる。

Custom PromptsのMarkdownファイルも、非常にシンプルな構造で、簡単に作れる。

---
description: PRをレビューしてフィードバックを提供
---

このPRの変更内容をレビューしてください。
コードの品質、潜在的なバグ、改善点を指摘してください。

YAMLフロントマターのdescriptionは、/promptsと入力したときのポップアップに表示される説明文だ。省略可能だが、設定しておくとどのプロンプトか一目で分かる。

引数を受け取る

Custom Promptsは引数を受け取ることができ、これにより汎用性が大幅に高まる。$FILEや$TICKET_IDのように大文字の名前でプレースホルダーを定義し、呼び出し時にKEY=value形式で指定する。

---
description: ブランチ作成、コミット、ドラフトPR作成を一括実行
argument-hint: [FILES=<paths>] [PR_TITLE="<title>"]
---

`dev/<feature_name>` ブランチを作成する。
$FILES が指定されていればステージングする。
明確なメッセージでコミットし、ドラフトPRを開く。
$PR_TITLE が指定されていればそれを使用する。

argument-hintは、ユーザーがどのような引数を渡せばよいかを示すヒントで、ポップアップに表示される。

よりシンプルなケースでは、$1〜$9の位置引数も使える（$ARGUMENTSで全引数を取得可能）。

なお、プロンプトファイルを編集した後はCodexの再起動が必要だ。

Rulesで「承認の手間」を減らしつつ事故を防ぐ

Rulesは、サンドボックス外で実行されるコマンドに対して「許可」「確認」「禁止」を細かく制御する機能だ（記事執筆時点ではプレビュー段階）。

AGENTS.mdの指示には強制力がないため、「rm -rfを使うな」と書いてもエージェントがうっかり実行する可能性はゼロではない。Rulesは「強制的に禁止」できるため、AGENTS.mdと組み合わせることでより安全に運用できる。

Rulesの書き方

~/.codex/rules/ディレクトリに.rulesファイルを作成する。構文はStarlark（Pythonに似た言語）で、prefix_rule()を使ってコマンドの先頭パターンを指定する。

prefix_rule(
  pattern = ["gh", "pr", "view"],
  decision = "prompt",
  justification = "PR閲覧は都度確認する",
)

フィールド	説明
`pattern`	マッチさせるコマンドの先頭部分（必須）
`decision`	`"allow"`（許可）/ `"prompt"`（確認）/ `"forbidden"`（禁止）
`justification`	ルールの理由（任意）。forbiddenの場合は代替コマンドを書くと親切

また、CLIで承認を求められた際に「Always allow」を選択すると、そのコマンドが~/.codex/rules/default.rulesに追記される。ただし、手動で設定したforbiddenルールがあればそちらが優先されるため、意図せず危険なコマンドが許可されることはない。

典型的な使い分け

git status、git diff → allow（作業のたびに止まらない）
gh pr view → prompt（外部アクセスが絡むため都度確認）
rm -rf → forbidden（justificationに「git cleanを使う」など代替案を記載）

応用設定：config.tomlとMCP

ここからは、基本的な使い方に慣れてから設定すれば十分な項目を紹介する。

config.toml：デフォルト設定・外部連携がまとまったファイル

~/.codex/config.tomlはCodexの基本動作を制御する設定ファイルだ。CLIとIDE拡張で共通の設定となる。

Codexを使っていると、ファイル編集やコマンド実行のたびに「これを実行してよいか？」と確認を求められることがある。これはCodexのセキュリティ機構が働いているからだ。config.tomlでは、この挙動を自分好みに調整できる。

Codexの2つのセキュリティ層

Codexはサンドボックスと承認ポリシーの2層で安全性を確保している。

サンドボックス（sandbox_mode）は「Codexが技術的に何をできるか」を制限する。OSレベルで強制されるため、設定を超えた操作は物理的に不可能だ。

値	挙動
`"read-only"`	ファイルの読み取りのみ。編集やコマンド実行は不可
`"workspace-write"`	ワークスペース内の読み書きとコマンド実行が可能（推奨）
`"danger-full-access"`	制限なし（推奨しない）

承認ポリシー（approval_policy）は「Codexがいつ確認を求めるか」を制御する。サンドボックスの範囲内で許可された操作でも、承認を求めるかどうかを決められる。

値	挙動
`"on-request"`	すべてのアクションで承認を求める（最も安全）
`"untrusted"`	信頼されていないコマンドのみ承認を求める
`"never"`	承認なしで実行（上級者向け）

デフォルトでは、Gitリポジトリ内で起動するとworkspace-write + on-requestが適用され、バージョン管理されていないフォルダではread-onlyが推奨される。

初心者はon-requestから始めて、どのような操作で承認が求められるかを把握してからuntrustedに移行するのがよい。

config.tomlの設定例

# 使用するモデル
model = "gpt-5.2"

# 承認ポリシー
approval_policy = "on-request"

# サンドボックスモード
sandbox_mode = "workspace-write"

プロファイルで設定を切り替える

状況に応じて設定を切り替えたい場合は、プロファイル機能が便利だ。

model = "gpt-5.2"
approval_policy = "on-request"

[profiles.readonly]
sandbox_mode = "read-only"

CLIでcodex --profile readonlyのように指定すると、該当プロファイルの設定が適用される。

MCP：外部サービスとつながり、Codexの能力を広げる

MCP（Model Context Protocol）は、AIが外部ツールやデータソースを扱うための標準規格だ。

MCPを設定すると、CodexがWeb検索したり、GitHubのPRを操作したり、ブラウザを自動制御したり、Figmaのデザインを参照したりできるようになる。素のCodexではできないことが、MCPを足すだけでできるようになるのだ。

AGENTS.mdやSkillsが「Codexにどう振る舞ってほしいか」を定義するのに対し、MCPは「Codexに何ができるか」を拡張する。使いこなすと作業効率が大きく変わるので、慣れてきたらぜひ試してほしい。

config.tomlでのMCP設定

MCPサーバーは~/.codex/config.tomlに記述する。リモートサーバー（URL指定）とローカルサーバー（コマンド実行）の2パターンがある。

# リモートサーバー（クラウド上のMCPに接続）
[mcp_servers.jina]
url = "https://mcp.jina.ai/v1"
bearer_token_env_var = "JINA_API_KEY"

# ローカルサーバー（自分のマシンでプロセスを起動）
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

追加方法や認証方法はMCPサーバーによって異なるため、詳細は公式MCPドキュメントや、各外部サービスのDocを参照してほしい。

Claude Codeユーザー向け：乗り換え・併用ガイド

Claude Codeを使っているユーザー向けに、主要概念の対応関係と移行のポイントをまとめた。

用語の対応表

Claude Code	Codex	備考
CLAUDE.md	AGENTS.md	役割は同じ
Skills	Skills	相互に使い回し可能
スラッシュコマンド	スラッシュコマンド + Custom Prompts	ビルトインコマンドは両者にある Codexではユーザー定義テンプレートを`/prompts:<name>`で呼び出せる
`--dangerously-skip-permissions`	`--yolo`	全権限付与のオプション
Hooks	（対応なし）	イベント駆動でシェルコマンドを実行（自動フォーマット、通知、ログ等）
（対応なし）	Rules	コマンドの許可/確認/禁止を制御

移行・併用のポイント

移行時は、既存のCLAUDE.mdの内容をAGENTS.mdにコピーするだけで基本的に動作する。両者の設定ファイルは独立しているため、同じマシンで併用しても干渉しない。

Skillsは両ツールで共通のフォーマットを採用しているため、同じSKILL.mdファイルを使い回すことも可能だ。ただし、Claude Codeではdescriptionを英語で書くことが推奨されているため、両方で使う場合は英語で統一しておくと無難だ。

発展：仕様駆動開発への入門（Spec-Driven Development）

GitHubやAIコーディングエージェントのコミュニティで、「仕様駆動開発（Spec-Driven Development）」と呼ばれるワークフローが注目されている。

なぜ仕様駆動開発が必要なのか

コーディングエージェントは強力だが、曖昧な指示を与えると「推測」で補完してしまう。結果として、コンパイルは通るが意図と違うコード、使いたくないライブラリの採用、想定外のアーキテクチャといった問題が起きやすい。

仕様駆動開発は「コードを書く前に、仕様と計画を固める」アプローチだ。エージェントにいきなりコードを書かせるのではなく、まず実装計画を提示させ、人間が確認・承認してから実装に移る。これにより、エージェントの暴走を防ぎ、レビュー可能な単位で開発を進められる。

仕様駆動開発をCodexで実践する

仕様駆動開発を実践するうえで便利なのが「Plan Mode（計画モード）」だ。Claude Codeには公式のPlan Modeが実装されており、読み取り専用の計画フェーズを強制できる。

Codexには公式のPlan Modeはまだ実装されていないが、AGENTS.mdに以下のような指示を書くことで疑似的に実現できる。OpenAI Codexチームのメンテナーも同様の手法を紹介している。

## 計画モード
「計画を作成して」と依頼された場合、計画の概要を提示し、
ユーザーの確認を待ってからコードを変更する。
不明点があれば質問し、選択肢はA/B/C形式で提示する。

小規模なタスクでは不要だが、複雑な機能や新規プロジェクトでは、計画を先に固めることでエージェントの出力品質が大きく向上する。

仕様と計画をファイルで管理する

仕様駆動開発をさらに本格的に取り入れる場合、計画をその場限りの会話で終わらせず、Markdownファイルとしてリポジトリに残しておくと良い（次回以降も繰り返し参照できる）。

公開リポジトリでspec.mdやplan.mdといったファイルを見かけたことがあるかもしれない（SPEC.mdのように大文字で書く流派もある）。

ファイル	役割	内容
spec.md	「何を作るか」の契約書	要件、ユーザー体験、成功基準
plan.md	「どう作るか」の設計図	技術スタック、タスク分解、実装順序

specは比較的安定した「契約」であり、planはspecを実現するための「設計図」という位置づけだ。チームで開発する場合や長期にわたるプロジェクトでは、これらをファイルで残しておくと「なぜこの設計にしたのか」を後から振り返れる。

ファイルを残す場合は、プロジェクトルートに/specsディレクトリを作成するか、個人用なら~/.codex/plans/に保存する方法がある。