10分で読める · AIシステムアーキテクトが執筆
注力分野: AGENTS.md · Skills · Automations · コスト最適化
ほとんどの人がCodexを間違った使い方をしています。
悪意があるわけではありません。Codexの動作方法が直感に反しているからです。あなたはCodexを「もっと賢いChatGPT」だと思っていますか？実際は違います。
Codexは、毎回記憶喪失の状態でプロジェクトディレクトリに入ってくる新しい同僚のようなものです。プログラミングの知識はあるけれど、あなたのプロジェクト構造も、使っているテストフレームワークも、触ってはいけないディレクトリも、何も知りません。
Codexの真価を引き出す鍵は、より良いプロンプトを書くことではありません。プロジェクトに関する永続的な記憶を与えることです。
OpenAIの公式Codexドキュメントは、これを6つの柱と8つのよくあるミスにまとめています。本記事では、3ヶ月間Codexを毎日使ってきた経験から、各項目を実例とともに詳しく解説します。
まず前提：Codexの正しいメンタルモデル
Codexに必要なのは「もっと指示」ではなく「もっと安定したコンテキスト」です。
Codexを起動するたびに、あなたのプロジェクトを読んで構造を理解します。しかし、設定が永続化されていないと、セッションのたびにすべてを忘れてしまいます。6つの柱は、この問題を段階的に解決するためのシステムです：
AGENTS.md → 設定 → MCP → Skills → Automations
それぞれが前の柱の上に構築されます。初日から全部を実装する必要はありません。
柱1：毎回のタスクに十分な文脈を
Codexにタスクを依頼する前に、以下の情報を確保してください：
- プロジェクト構造：ソースコード、テスト、設定ファイルの場所
- 技術スタック：言語、フレームワーク、ビルドツール
- 規約：コードスタイル、命名ルール、過去の教訓
- 現在の状態：変更内容、発生したエラー
毎回プロンプトに書き込んでも構いません。しかし、もっとスマートな方法があります——柱2で説明します。
柱2：AGENTS.md — AIのためのプロジェクトマニュアル（最重要）
AGENTS.mdはAIエージェント向けに書かれたREADMEです。 Codexはセッション開始時に自動的にこのファイルを読み込みます。これはCodexの出力品質を上げるためにできる、最も効果的な施策です。
何を書くべきか
| カテゴリ | 例 |
|---|---|
| ディレクトリ構造 |
src/ がソース、db/schema/ は絶対に触らない |
| 起動コマンド |
pnpm dev、docker compose up
|
| テスト/ビルド/lint |
pnpm test、pnpm build、pnpm lint
|
| コーディング規約 | TypeScriptで any を使わない |
| 制約事項 |
db/schema/ は変更禁止、実験的依存関係は追加しない |
| 完了条件 | 「pnpm test がすべてパスしたら完了」 |
3つの優先レベル
~/.codex/AGENTS.md → 個人のグローバルデフォルト
リポジトリルート/AGENTS.md → チーム共有の標準
サブディレクトリ/AGENTS.md → ローカルルール（最優先）
作業ディレクトリに近いファイルほど優先度が高くなります。フロントエンドとバックエンドで異なるルールを書くこともできます。
最初の一歩
Codex CLIで /init を実行すれば、初期バージョンが自動生成されます。その後、プロジェクトの実情に合わせて編集してください。
AGENTS.mdを進化させる方法
短く正確なAGENTS.mdは、長く曖昧なものよりはるかに役立ちます。
基本項目だけを書き、Codexが同じミスを繰り返したときにだけルールを追加していきます。
実例： TypeScriptプロジェクトで、Codexが2回 any 型を使ったとします。あなたは手動で修正しました。このときAGENTS.mdに以下を追加します：
修正：any型は使わない。unknown + 型ガードで代替する。
以後、この問題は発生しなくなります。
判断基準：Codexに同じことを2回注意したら、AGENTS.mdに書き込むべきです。
柱3：設定ファイルで挙動を統一
AGENTS.mdはCodexに「プロジェクトのルール」を教えます。設定ファイルはCodexに「自分の振る舞い方」を教えます。
3層構造：
~/.codex/config.toml → 個人のデフォルト
.codex/config.toml → リポジトリ固有
CLIフラグ → 一時的な上書き
設定できる項目：デフォルトモデル、推論レベル、サンドボックスモード、承認戦略、MCPサーバー。
編集方法は2つ： config.toml を手動で編集するか、Codexに直接「configを更新して」と頼むか。どちらでも構いません。
柱4：MCPで外部システムと接続
MCP（Model Context Protocol）を使うと、Codexをデータベース、API、Jira、Notionなどの外部ツールに接続できます。
コードを書く前にデータベーススキーマを確認したり、GitHub Issueを自動取得したり——これらの操作をCodexが直接実行できるようになります。
黄金ルール： 最初は1〜2個の高価値なMCPサーバーだけを接続します。一度に十数個も設定すると、Codexが混乱します。
柱5：Skills — 繰り返し作業をパッケージ化
あるワークフローが繰り返し登場するようになったら、長いプロンプトに頼るのをやめましょう。Skillとしてカプセル化します。
Skillの本体は SKILL.md ファイルです。CLI、IDE、Codex Appのすべてで動作します。
Skill化に適したシナリオ
| シナリオ | Skill名 |
|---|---|
| 標準デバッグフロー | debug-standard |
| PRレビューチェックリスト | pr-review |
| リリースノート自動生成 | generate-release-notes |
| ログ分析 | analyze-logs |
| マイグレーション計画 | migration-plan |
判断基準：同じプロンプトを3回書いたら、それはSkillにすべきです。
保存場所
-
個人用：
$HOME/.agents/skills— 自分だけのスキルライブラリ -
チーム用：リポジトリ内の
.agents/skills— gitコミット可能、新メンバーもcloneするだけで使える
柱6：Automations — 安定したフローを自動実行
ワークフローが安定したら、Codexに自動実行させましょう。
Codex App → Automationsタブ で設定：対象プロジェクト、プロンプト（Skills呼び出し可）、実行頻度、作業環境（worktreeかローカルか）。
自動化に適したタスク
| タスク | 頻度 |
|---|---|
| 直近コミットの要約 | 毎日 |
| 潜在バグのスキャン | 毎週 |
| リリースノートの下書き | リリースごと |
| CIエラーの原因調査 | CI実行ごと |
| デイリースタンドアップ要約 | 毎日 |
Skillsが方法を定義し、Automationsがリズムを定義します。
人の介入が必要なフローは、まず安定したSkillにしてから自動化を検討しましょう。
8つのよくあるミス（公式ドキュメントが明示）
以下はOpenAI公式ドキュメントで明示されている8つのミスです。ほとんどの人が少なくとも4〜5個は経験しています。
ミス1：毎回プロンプトに永続ルールを書く
コーディング規約、コードスタイル、制約条件を毎回手書きする。一度忘れたらそれで終わり。
✅ 解決策：ルールはAGENTS.mdに。一度書けば永続的に有効。
ミス2：Codexにビルド・テスト方法を教えない
「このコードを修正して」という指示だけ。Codexは修正後に検証できないので、感覚で「たぶん大丈夫」と判断するしかありません。
✅ 解決策：AGENTS.mdに検証コマンドを明記。各タスクの「完了条件」にも具体的な確認ステップを入れる。
ミス3：複雑なタスクで計画をスキップ
いきなり実装を始め、システムを理解する時間を与えない。結果、一見合理的だけどプロジェクト構造にまったく合わないソリューションが生成される。
✅ 解決策：複雑なタスクでは必ずPlanモード（
/plan）を使う。または「まず説明して、それから実装して」と指示する。
ミス4：初日から完全アクセス権限を付与
「権限が大きいほど便利だろう」と考えて、いきなり完全アクセスに設定する。その結果、予期せぬグローバルな変更が発生する。
✅ 解決策：まずChat/読み取り専用モードから始める。ワークフローを理解してから、必要な範囲だけ徐々に権限を広げる。
ミス5：Worktreeを使わない
複数のCodexセッションが同じファイル群で同時に作業する。変更が競合し、どのバージョンが正しいのかわからなくなる。
✅ 解決策：並列作業は必ず独立したgit worktreeで行う。
ミス6：検証前に自動化
「このフロー良さそう」と思ったら即座にAutomationを設定してしまう。不安定な挙動がスケールされてしまう。
✅ 解決策：まずSkill化。手動で数回検証して安定を確認してからAutomationを設定する。
ミス7：Codexの全ステップを監視する
ジュニアエンジニアを見張るように、Codexの全作業を横で見ている。非同期・並列のメリットがまったく活かせない。
✅ 解決策：タスクを起動したら別の仕事をする。後で結果をレビューすれば十分。Codexはバックグラウンドタスクであり、リアルタイム会話ではない。
ミス8：プロジェクトに1スレッド
1つのスレッドにプロジェクトの全作業履歴を蓄積する。コンテキストが膨張し、Codexがノイズの中から関連情報を見つけられなくなる。
✅ 解決策：タスクまたは独立した作業単位ごとに新スレッドを作成。
/forkを使えばコンテキストを保持したまま分岐できる。
コスト最適化：Plus契約を6倍活用する方法
ChatGPT Plus/Proユーザーの場合：重要なのはクレジット消費
多くの人はAPI費用を直接払っているわけではなく、ChatGPT Plus（月額$20）またはPro（月額$200）のサブスクリプションでCodexを使っています。この場合、気にすべきはドル価格ではなく、クレジットの消費速度です。
各モデルはトークンあたりのクレジット消費量が異なります：
| モデル | 入力クレジット（1Kトークン） | 出力クレジット | 相対コスト |
|---|---|---|---|
| GPT-5.5 🏆 | 125 | 750 | 基準（100%） |
| GPT-5.4 ⭐ | 62.5 | 375 | 5.5の半分 |
| GPT-5.4 Mini 🏃 | 18.75 | 113 | 5.4の1/3、5.5の約1/6 |
この数字が意味すること：GPT-5.4 MiniをGPT-5.5の代わりに使えば、同じ月額契約で6倍の作業量が可能です。
賢い使い分け戦略：
- 日常の単純タスク → GPT-5.4 Mini（コード読み、小さいバグ修正、テスト作成、質問）
- 中程度の複雑さ → GPT-5.4（リファクタリング、デバッグ、機能追加）
- 高難度タスクのみ → GPT-5.5（アーキテクチャレビュー、セキュリティ監査、複雑なクロスモジュール変更）
APIユーザーの場合：ドル価格
| モデル | 入力（100万トークンあたり） | 出力 | 最適な用途 |
|---|---|---|---|
| GPT-5.5 | $5.00 | $30.00 | アーキテクチャレビュー、セキュリティ |
| GPT-5.4 | $2.50 | $15.00 | 複雑なリファクタリング、デバッグ |
| GPT-5.4 Mini | $0.75 | $4.50 | コード読み、単純バグ、テスト作成 |
比率は同じ：5.4は5.5の半分、5.4 Miniは5.4の1/3。
推論レベルの選び方
| レベル | 使用タイミング |
|---|---|
| Low 🏃 | 素早く、範囲の明確なタスク |
| Medium ⭐ | 日常のデフォルト、コスパ最高 |
| High 🧠 | 複雑な変更、デバッグ |
| Extra High 🚀 | 長時間の自律エージェントタスク |
推論レベルが高いほどクレジット消費も増えます。日常はMedium、単純タスクはLow、複雑タスクだけHighに。
キャッシュを活用する
同じシステムプロンプトとプロジェクトコンテキストを繰り返し使う → キャッシュが有効化 → 消費量が大幅削減。
実測データ（1000万トークン処理時）：
- GPT-5.5 キャッシュなし：約$22.00
- GPT-5.5 高キャッシュヒット：約$1.25
- GPT-5.4 Mini 高キャッシュ：約$0.24
同じスレッドで会話を継続し、不必要に新規セッションを作らないことがキャッシュヒット率を最大化するコツです。
セッション管理：1タスク1スレッド
基本原則
プロジェクトに1スレッドではなく、タスクに1スレッドです。
コンテキストの膨張は出力品質を静かに蝕む最大の要因です。1つのスレッドに蓄積される情報が増えるほど、Codexはノイズから関連情報を見つけ出せなくなります。
主要コマンド
| コマンド | 使い道 |
|---|---|
/fork |
作業が分岐したとき、現在のスレッドから分岐 |
/compact |
コンテキストが長くなりすぎたとき圧縮 |
/plan |
計画モードに移行 |
/status |
セッション状態の確認 |
並列作業の正しい分割方法
Codexはマルチエージェント並列作業に対応しています。ただし条件は書き込み範囲が競合しないことです。
✅ 良い分割：
- バックエンド変更 + ドキュメント更新
- 1人がテスト作成、もう1人が根本原因調査
- 1人が実装、もう1人はレビューのみ
- 複数人がそれぞれ代替案を提案
❌ 悪い分割：
- 複数人が同じファイル群を同時に編集
- 要件未確定のまま複数実装を並行実行
- スキーマとその呼び出し側が調整なしで同時変更
完全な成熟ワークフロー
初期設定（一度だけ）
① /init → AGENTS.mdの初期バージョン自動生成
② AGENTS.mdを編集 → ビルドコマンド、制約、パターンを追加
③ ~/.codex/config.toml を設定 → モデル、推論レベル、承認戦略
④ 高価値なMCPサーバーを1〜2個追加
日常タスク
① タスクごとに新スレッド作成
② 4要素プロンプト（目標 → 文脈 → 制約 → 完了条件）
③ 複雑なタスクはPlanモード
④ 起動したら別の仕事に移る
⑤ 戻ってdiffを確認
⑥ 安定したパターンを見つけたらSkill化
継続的改善
① 同じミスが2回 → AGENTS.mdを更新
② Skillが安定 → Automationを設定
③ 定期的にセッションを振り返り → 設定とAGENTS.mdを更新
完全な開発ループを回す
OpenAI公式ドキュメントの言葉を借りれば：
「Codex shouldn't just generate code. With the right instructions, it can also help test it, check it, and review it.」
Codexにコードを書かせるだけでは不十分です。完全なループを回しましょう：
コード変更 → テスト作成/更新 → テスト実行 → lint/型チェック
→ 動作確認 → diffレビュー → リグレッション発見
まとめ：3つだけ覚えてください
この記事が長かったので、最も重要な3点に絞ります：
第一に：AGENTS.mdを書くこと。 10分の初期設定で、毎日30分を節約できます。Codexを記憶喪失のツールから、あなたのプロジェクトを理解しているチームメイトに変える最重要ファイルです。
第二に：タスクに応じてモデルを選ぶこと。 日常の単純作業はGPT-5.4 Mini + Low推論で十分。クレジット消費を60〜80%削減できます。
第三に：1タスク1スレッド、分岐には/forkを使うこと。 コンテキスト膨張はCodexの出力品質を静かに殺す最大の要因です。
進化のパス：AGENTS.md → Config → Skills → Automations。一歩ずつで構いません。
Skillsが方法を定義し、Automationsがリズムを定義します。
📖 初心者ガイドをまだ読んでいませんか？ まずはこちら：初めてCodexを使うとき、私は3つのことだけを頼んだ — ダウンロードから最初のコード変更まで。
本ガイドはOpenAI公式Codexドキュメントとコミュニティの実践に基づいています。価格情報は2026年6月時点のものです。最新情報は openai.com でご確認ください。