🧭 本記事は Claude Code実務運用シリーズ の STEP 3「ガードレールを作る」です。
Codexユーザー向けの回です。STEP 1〜3の内容をAGENTS.mdに翻訳します。
シリーズ全体の地図と読む順は親記事にまとめています。

はじめに

AIコーディングエージェントを使っていると、便利な一方で次のような挙動に困ることがあります。

頼んでいない機能まで追加する
必要以上に大きなリファクタリングをする
既存コードのスタイルを勝手に変える
不明点を確認せず、推測で実装を進める
実装後の検証が弱い

これらは、AIの能力不足というよりも、事前に行動ルールを与えていないことが原因で起きやすい問題です。

そこで参考になるのが、GitHubで18万スターを超えている andrej-karpathy-skills の CLAUDE.md です。Andrej Karpathy 氏が指摘したLLMコーディングの失敗パターンを、Forrest Chang 氏が1枚の CLAUDE.md に落とし込んだもので、2026年に入って一気に広まりました。

この CLAUDE.md には、LLM Coding Assistant がよく起こす失敗を減らすための行動指針が整理されています。

本記事では、その考え方を OpenAI Codex の AGENTS.md に応用する方法を紹介します。

この記事でやること

この記事では、Claude Code向けの CLAUDE.md の思想を参考にしながら、Codex向けに次のようなグローバル指示を作ります。

~/.codex/AGENTS.md

目的は、Codexに対して全プロジェクト共通で以下の行動を促すことです。

不明点を推測で進めない
必要最小限の実装にする
余計なリファクタリングをしない
変更範囲を小さく保つ
実装後に検証する

Claude CodeのCLAUDE.mdとCodexのAGENTS.mdの対応関係

Claude Codeでは、グローバルな指示ファイルとして次のようなファイルを使います。

~/.claude/CLAUDE.md

一方、Codexでは通常、次のファイルを使います。

~/.codex/AGENTS.md

対応関係を整理すると、次のようになります。

観点	Claude Code	Codex
グローバル指示	`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`
プロジェクト固有指示	各リポジトリの `CLAUDE.md`	各リポジトリの `AGENTS.md`
目的	Claude Codeの行動制御	Codexの行動制御
内容	開発時の行動原則・制約	開発時の行動原則・制約

つまり、今回やることはシンプルです。

Claude Code向けのCLAUDE.md運用を、
Codex向けのAGENTS.md運用に移植する

ということです。

参考にした4つの考え方

andrej-karpathy-skills の CLAUDE.md では、LLM Coding Assistantのよくある失敗を減らすために、主に次の4つの観点が整理されています。

1. Think Before Coding
2. Simplicity First
3. Surgical Changes
4. Goal-Driven Execution

それぞれを、Codex向けに解釈すると次のようになります。

1. Think Before Coding

これは、実装前に前提を確認するという考え方です。

AIコーディングエージェントは、仕様が曖昧でもそれらしく補完して実装してしまうことがあります。

しかし、実務ではこの「それらしい補完」が危険です。

たとえば、次のようなケースです。

「バリデーションを追加して」

この指示だけでは、どの入力に対するバリデーションなのか、エラー表示はどうするのか、既存仕様との整合性はどうするのかが不明です。

そのため、Codexには次のような行動を求めます。

実装判断に影響する不明点がある場合は質問する。
軽微な不明点であれば、前提を明記して最小実装で進める。

ここで重要なのは、毎回止まることではありません。

目的は、作業を遅くすることではなく、危険な推測を減らすことです。

2. Simplicity First

これは、必要最小限の実装にするという考え方です。

AIは、頼んでいないのに次のようなことをしがちです。

汎用化する
設定項目を増やす
抽象クラスを作る
将来使うかもしれない拡張ポイントを作る
過剰なエラーハンドリングを追加する

しかし、多くの場合、これは不要です。

たとえば、1箇所でしか使わない処理に対して、いきなり汎用的なヘルパーやプロトコルを作る必要はありません。

Codexには、次のような方針を与えると安定します。

依頼された問題を解決するための最小コードを書く。
求められていない機能、抽象化、設定項目は追加しない。

これは、コード品質を下げるという意味ではありません。

むしろ、レビューしやすく、壊れにくく、保守しやすいコードにするための方針です。

3. Surgical Changes

これは、変更範囲を必要最小限にするという考え方です。

AIコーディングで特に困るのが、次のような変更です。

依頼した修正とは関係ないファイルまで変更される

または、

ついでにフォーマットや命名まで変えられる

これをされると、レビューが難しくなります。

本来確認したい修正内容よりも、「なぜここまで変わったのか」を追う時間が増えてしまいます。

そのため、Codexには次のように指示します。

依頼に直接関係するファイルと行だけを変更する。
隣接コードの改善、整形、リファクタリングは勝手に行わない。
既存のスタイルに合わせる。

この方針はかなり重要です。

AIにコードを書かせる場合、賢く動かすことよりも、勝手に動きすぎないようにすることが重要になる場面が多いです。

4. Goal-Driven Execution

これは、成功条件を明確にしてから実装するという考え方です。

たとえば、次のような依頼があったとします。

このバグを直して

この場合、良い進め方は次のようになります。

1. バグの再現条件を確認する
2. 修正する
3. 再現しなくなったことを確認する

テストがあるなら、対象のテストを実行します。

テストがない場合でも、最低限、何を確認したのかを明記します。

Codexには次のように指示します。

作業を検証可能なゴールに変換する。
テストがある場合は、関連する最小範囲のテストを実行する。
テストできない場合は、何を確認し、何が未確認かを明記する。

AIに「実装して」とだけ伝えると、実装した時点で完了したように見えることがあります。

しかし実務では、実装よりも検証が重要です。

グローバルAGENTS.mdに追記する内容

以下を、Codexのグローバル AGENTS.md に追記します。

## Coding Behavior Guidelines

Prefer correctness, clarity, and minimal diffs over speed.

### 1. Clarify Before Risky Implementation

Before coding, identify assumptions that affect the implementation.
If ambiguity changes the design, API, data model, test strategy, or user-visible behavior, ask a clarifying question.
If the ambiguity is minor, state the assumption and proceed with the smallest reasonable implementation.

Do not silently choose between materially different interpretations.

### 2. Keep the Solution Simple

Implement the minimum code needed to satisfy the request.
Do not add speculative features, abstractions, configuration options, or flexibility that was not requested.
Avoid over-engineering single-use logic.

Prefer straightforward code that a senior engineer would consider easy to review.

### 3. Make Surgical Changes

Touch only the files and lines required by the task.
Do not refactor, reformat, rename, or clean up adjacent code unless it is directly necessary.
Match the existing style, even if a different style would be preferable.

If your change makes imports, variables, functions, or comments obsolete, remove only the dead code introduced by your own change.
If you notice unrelated issues, mention them separately instead of changing them.

### 4. Verify Against a Concrete Goal

Turn the task into verifiable success criteria before or while implementing.

Examples:
- Bug fix: reproduce the bug or identify the failing path, then verify the fix.
- Validation change: cover valid and invalid inputs where practical.
- Refactor: preserve existing behavior and run relevant tests or checks.

When tests are available and relevant, run the narrowest useful test command first.
If tests cannot be run, state what was verified and what remains unverified.

Every changed line should trace back to the user request.

追記手順

まず、Codexのグローバル設定ディレクトリを作成します。

mkdir -p ~/.codex

次に、AGENTS.md を開きます。

code ~/.codex/AGENTS.md

VS Codeを使っていない場合は、次のように nano でも問題ありません。

nano ~/.codex/AGENTS.md

開いたファイルに、先ほどの Coding Behavior Guidelines を追記します。

コマンドで一括追記する場合

手動でエディタを開かず、コマンドで追記する場合は次のようにします。

cat >> ~/.codex/AGENTS.md <<'EOF'

## Coding Behavior Guidelines

Prefer correctness, clarity, and minimal diffs over speed.

### 1. Clarify Before Risky Implementation

Before coding, identify assumptions that affect the implementation.
If ambiguity changes the design, API, data model, test strategy, or user-visible behavior, ask a clarifying question.
If the ambiguity is minor, state the assumption and proceed with the smallest reasonable implementation.

Do not silently choose between materially different interpretations.

### 2. Keep the Solution Simple

Implement the minimum code needed to satisfy the request.
Do not add speculative features, abstractions, configuration options, or flexibility that was not requested.
Avoid over-engineering single-use logic.

Prefer straightforward code that a senior engineer would consider easy to review.

### 3. Make Surgical Changes

Touch only the files and lines required by the task.
Do not refactor, reformat, rename, or clean up adjacent code unless it is directly necessary.
Match the existing style, even if a different style would be preferable.

If your change makes imports, variables, functions, or comments obsolete, remove only the dead code introduced by your own change.
If you notice unrelated issues, mention them separately instead of changing them.

### 4. Verify Against a Concrete Goal

Turn the task into verifiable success criteria before or while implementing.

Examples:
- Bug fix: reproduce the bug or identify the failing path, then verify the fix.
- Validation change: cover valid and invalid inputs where practical.
- Refactor: preserve existing behavior and run relevant tests or checks.

When tests are available and relevant, run the narrowest useful test command first.
If tests cannot be run, state what was verified and what remains unverified.

Every changed line should trace back to the user request.
EOF

追記されたか確認する

追記できたかどうかは、次のコマンドで確認できます。

tail -n 80 ~/.codex/AGENTS.md

見出しだけ確認する場合は、次のコマンドで十分です。

grep -n "Coding Behavior Guidelines" ~/.codex/AGENTS.md

次のように表示されれば、追記されています。

12:## Coding Behavior Guidelines

AGENTS.override.mdがある場合の注意

Codexでは、グローバル設定として通常は次のファイルが使われます。

~/.codex/AGENTS.md

ただし、次のファイルが存在する場合は注意が必要です。

~/.codex/AGENTS.override.md

Codexはグローバルスコープで、AGENTS.override.md が存在すればそれを読み込み、なければ AGENTS.md を読み込みます。同じ階層では AGENTS.override.md が優先され、そのスコープでは最初に見つかった非空ファイル1つだけが使われます。

AGENTS.override.md は、リリースフリーズやインシデント対応など、一時的・期間限定のルールを入れる用途に向いています。恒久的なルールをここに入れると「もう1つのルートファイル」と化し、削除を忘れて混乱の元になります。今回の行動原則は基本的に AGENTS.md 側に書くのがおすすめです。

設定が反映されない場合は、次のコマンドで確認します。

ls -la ~/.codex/AGENTS*.md

もし AGENTS.override.md があり、そちらが優先されてしまっている場合は、今回の内容を AGENTS.override.md に入れるか、不要であればリネームします。

mv ~/.codex/AGENTS.override.md ~/.codex/AGENTS.override.md.bak

Codexに読み込まれているか確認する

ファイルに追記しただけではなく、Codexが読み込んでいるかも確認したい場合は、次のようにCodexに聞きます。

codex --ask-for-approval never "Summarize the current instructions related to coding behavior."

期待する返答は、次のような内容です。

- Prefer correctness, clarity, and minimal diffs.
- Clarify assumptions before risky implementation.
- Keep solutions simple.
- Make surgical changes.
- Verify changes against concrete success criteria.

このような要約が出れば、Codexが今回の方針を読み込めている可能性が高いです。

既存セッションは再起動する

Codexは、起動時（TUIではセッション起動ごとに1回）に指示チェーンを組み立て、AGENTS.md の指示を読み込みます。

そのため、すでに開いているCodexセッションには、変更内容が反映されていない可能性があります。

AGENTS.md を更新した後は、新しいCodexセッションを起動して確認するのがおすすめです。

グローバルに入れるべき内容と、プロジェクト固有に入れるべき内容

今回のような行動原則は、グローバル AGENTS.md に向いています。

~/.codex/AGENTS.md

理由は、どのプロジェクトでも共通して効いてほしい内容だからです。

一方で、以下のような内容はプロジェクト固有の AGENTS.md に書く方が適しています。

- このリポジトリのビルドコマンド
- テストコマンド
- 使用しているフレームワーク
- 命名規則
- ディレクトリ構成
- レビュー時の注意点
- 特定機能の仕様

たとえば、iOSアプリのプロジェクトなら次のような内容です。

## Project Rules

- Minimum supported iOS version is iOS 15.
- Match the existing Swift style.
- Do not change Firebase, DRM, or LINE login behavior unless explicitly requested.
- Run the relevant unit tests before reporting completion when practical.

このように分けると、運用しやすくなります。

グローバルAGENTS.md
→ AIコーディング全般の行動原則

プロジェクトのAGENTS.md
→ そのリポジトリ固有のルール

なお、プロジェクトスコープでは、現在の作業ディレクトリに近い階層の AGENTS.md が後ろに連結され、競合するルールについては手前（近い側）が優先されます。サブディレクトリ単位で細かくルールを足したいときに使えます。

なぜこの運用が有効なのか

AIコーディングエージェントは、何も指示しないと「良かれと思って」広く変更することがあります。

しかし、実務でありがたいのは、派手な実装ではなく、次のような動きです。

- 依頼された範囲だけ変更する
- 既存コードに合わせる
- 不明点を勝手に決めない
- 検証結果を明記する
- 余計な機能を追加しない

この行動を毎回プロンプトで指示するのは面倒です。

だからこそ、AGENTS.md に共通ルールとして書いておく価値があります。

まとめ

18万スター超の CLAUDE.md から学べる重要なポイントは、AIに「もっと賢く動いてもらう」ことではありません。

むしろ重要なのは、次のことです。

AIに勝手なことをさせない

Codexでも同じです。

~/.codex/AGENTS.md に行動原則を書いておくことで、次のような効果が期待できます。

推測による実装を減らせる
不要な差分を減らせる
レビューしやすい変更にできる
過剰設計を抑えられる
検証意識を持たせられる

AIコーディングエージェントは、性能だけでなく、運用ルールで使いやすさが大きく変わります。

Codexを使うなら、まずはグローバルの AGENTS.md に、自分の開発方針を書いておくのがおすすめです。

参考

このシリーズの歩き方

Claude Code実務運用シリーズ ― 暴走させない、から仕組みにするまで。

◀ 前の記事: 18万スター超のCLAUDE.mdに学ぶ、Claude Codeを暴走させない運用術
▶ 次の記事: Redmineチケット確認からSlack通知まで行うiOSコードレビュー用Codex Skillを作成する
🔍 あわせて読む: AGENTS.md / CLAUDE.md が100行を大幅に超えたら危険。チームに無視されないAI指示ファイルの分け方 ― AGENTS.mdの分割基準は共通
🗺 シリーズ全記事の地図(親記事)