Codex プロンプト設計：精度を上げる指示の型

TL;DR: Codexへの指示は「タスク種別・コンテキスト・受入条件・制約」の4要素を揃えると精度が大幅に上がる。本記事では即使用可能なプロンプトテンプレート3種（コードレビュー・バグ修正・新機能実装）と、精度を下げる失敗パターン3種を解説する。

はじめに

Codexを試したが「期待した出力が返ってこない」という経験は多い。原因の大半はモデル性能ではなく、プロンプトとコンテキストの設計にある。

OpenAI Codex CLIは2025年4月にリリースされたコーディングエージェントで（公式リリースノート）、o3モデルの推論能力を活用して複雑なコーディングタスクを自律実行できる。しかしその推論能力を活かすには、エージェントが正しい判断を下せるだけの情報を適切に渡す必要がある。

Codexの基本特性とClaude Codeとの違いについてはCodex vs Claude Code 使い分け2026を先に読んでほしい。本記事はその続編として、Codexに特化したプロンプト設計の実践を扱う。

確認日: 2026-06-01 / 対象バージョン: codex CLI 0.1.x系

Codexへのコンテキスト渡しの基本原則

なぜコンテキストが精度を左右するか

Codexはo3モデルを使った推論エンジンだ。推論とはつまり「与えられた情報から最も妥当な解を導く」処理であり、入力情報が不足するほど推論の幅が広がり、意図と異なる出力が返りやすくなる。

公式ドキュメント（Codex GitHub README）にも「provide as much context as you can」と明記されている。これは性能の問題ではなく設計上の前提だ。

逆に言えば、プロンプトの質を上げるだけで体感精度は大きく変わる。筆者の実務経験では、コンテキストを揃えた指示とそうでない指示で、一発で使える出力が得られる確率が2〜3倍異なる（経験則）。

渡すべき情報の4要素

Codexへの指示を構成する要素は次の4つだ。

この4要素が揃うと、Codexはタスクの範囲と完了条件を正確に把握した上で推論できる。

プロンプトテンプレート3種

以下の3テンプレートはそのままコピーして {...} の箇所を差し替えて使える。

テンプレート1：コードレビュー依頼

コードレビューは「何を見てほしいか」を絞ることが最重要だ。全部見てほしいという指示は、Codexが優先度を付けられず冗長な指摘になりやすい。

タスク: コードレビュー
対象ファイル: {ファイルパス}
確認してほしい観点:
  - セキュリティ（{具体的な懸念点、例: SQLインジェクション・XSS}）
  - {観点2}
  - {観点3、最大3点推奨}
変更禁止範囲: {変えてはいけないインターフェース・ファイル}
出力形式: 指摘事項を severity（Critical/Important/Nice）付きで箇条書き

実際の使用例:

タスク: コードレビュー
対象ファイル: src/api/auth.ts
確認してほしい観点:
  - セキュリティ（JWTトークンの検証処理・セッション管理）
  - エラーハンドリングの漏れ
  - TypeScriptの型安全性
変更禁止範囲: APIのエンドポイントパスとレスポンスの型定義
出力形式: 指摘事項を severity（Critical/Important/Nice）付きで箇条書き

コードレビューにおけるAIペアプログラミングのより広い視点はAIペアプログラミングパターンを参照してほしい。

テンプレート2：バグ修正依頼

バグ修正は再現条件と期待動作の明確化が鍵だ。「動かない」だけの指示はCodexが問題の範囲を推定しすぎて、関連する他の処理まで変更する事故が起きやすい。

タスク: バグ修正
対象ファイル: {ファイルパス}
バグの再現条件:
  - 入力: {具体的な入力値・状態}
  - 操作: {何をしたか}
  - 環境: {Node.jsバージョン・OS・ブラウザなど}
現在の動作: {実際に起きていること}
期待する動作: {本来起きるべきこと}
変更スコープ: 上記のバグ修正のみ。関連するリファクタリングは行わない

実際の使用例:

タスク: バグ修正
対象ファイル: src/utils/dateFormatter.ts
バグの再現条件:
  - 入力: タイムゾーンがUTC+9の環境でformatDate("2026-01-01")を呼ぶ
  - 操作: 関数を実行
  - 環境: Node.js 22.x, macOS
現在の動作: "2025-12-31"が返る（1日ずれる）
期待する動作: "2026-01-01"が返る
変更スコープ: 上記のバグ修正のみ。関連するリファクタリングは行わない

テンプレート3：新機能実装依頼

新機能実装は受入条件を「テストケース」の形で書くと精度が上がる。Codexはテストを書きながら実装を進める能力が高く、テストケースが明確だと完了判定も自動化しやすい。

タスク: 新機能実装
機能概要: {1〜2文で機能の目的}
受入条件（テストケースとして）:
  - {正常系ケース1}: 入力{A}のとき、出力{B}を返す
  - {正常系ケース2}: 入力{C}のとき、出力{D}を返す
  - {異常系ケース}: 入力{E}のとき、エラー{F}をスローする
使用するファイル・モジュール: {既存の関連ファイル}
使用禁止: {特定ライブラリ・グローバル変数など}
テストフレームワーク: {Jest / Vitest / Node.js test runner など}

実際の使用例:

タスク: 新機能実装
機能概要: ユーザーのメールアドレスを正規化する関数（小文字化・末尾スペース除去）
受入条件:
  - "[email protected]"を入力したとき"[email protected]"を返す
  - " [email protected] "を入力したとき"[email protected]"を返す
  - メールアドレス形式でない文字列を入力したときErrorをスローする
使用するファイル: src/utils/emailValidator.ts（既存バリデーション処理を参照）
使用禁止: 外部ライブラリ（標準APIのみ使用）
テストフレームワーク: Node.js built-in test runner

精度を下げる典型的な失敗パターン

失敗1：コンテキスト不足

「src/api.tsを修正して」という指示はCodexに何も伝えていない。Codexはファイルを読んで推測を試みるが、推測の精度は入力情報に依存する。

修正方針: タスク種別・受入条件・変更スコープを必ず付け加える。テンプレート1〜3を雛形として使えば自然と揃う。

失敗2：曖昧な受入条件

「使いやすく改善して」「パフォーマンスを上げて」という指示は受入条件が存在しない。Codexが「改善した」と判断した時点で処理を終えるため、意図しない方向に最適化される。

修正方針: 「何が起きたら完了か」を具体的に書く。「ページロードを2秒以内にする」「APIレスポンスを200ms以内にする」という数値目標か、「以下のテストが全て通ること」というテストケースで代替する。

失敗3：スコープ肥大化

「このモジュール全体をリファクタしながらバグも直して型定義も改善して」という複合指示は失敗しやすい。Codexは指示を全て満たそうとするが、複数の変更が絡み合うと競合や意図しない副作用が起きる。

修正方針: 1指示1タスクを徹底する。バグ修正とリファクタリングは必ず別のプロンプトに分ける。マルチステップな作業を分割して実行するパターンについてはマルチエージェント開発パターンが参考になる。

実践：approval-modeと組み合わせた安全運用

Codexには --approval-mode オプションがあり、エージェントが行おうとしている操作を事前確認できる（公式ドキュメント：approval-mode）。

プロンプトの精度が上がっても、最初のうちは必ず suggest モードで動作を確認してから運用を判断することを推奨する。

# suggest: 提案のみ、実行は手動確認（推奨：初期運用）
codex --approval-mode suggest "タスク内容"

# auto-edit: ファイル変更は自動、シェルコマンドは確認
codex --approval-mode auto-edit "タスク内容"

# full-auto: 全て自動（CI環境での利用を想定）
codex --approval-mode full-auto "タスク内容"

AI駆動の開発計画全体におけるエージェントの位置づけについてはAI駆動の開発計画設計も参照してほしい。

FAQ

Q1. プロンプトが長くなりすぎて逆に精度が下がる気がするが？

A. Codexのコンテキスト長は200,000トークン（公式値）あるため、通常の業務プロンプトで長さが問題になることはほぼない。精度低下の原因は長さではなく、関係ない情報の混入や矛盾した指示の共存が多い。4要素に絞って構造化すれば冗長にならない。

Q2. AGENTS.mdやCLAUDE.mdのようなプロジェクト設定ファイルはCodexでも有効か？

A. Codexは実行時にカレントディレクトリのファイルを読み込む。AGENTS.md というファイル名はCodexエージェント向けの設定として公式ドキュメントで言及されている。プロジェクト固有のルール（使用禁止パターン・コーディング規約）を書いておくと毎回プロンプトに書く必要がなくなる。

Q3. 日本語でプロンプトを書いても精度は変わらないか？

A. o3モデルは日本語を十分に処理できる。コード内のコメントや変数名が英語でも日本語のプロンプトで問題なく指示できる（経験則）。ただし技術的な固有名詞（ライブラリ名・関数名など）は英語のまま記述する方が誤認識が少ない。

Q4. Codexにテスト自動生成をさせるときのベストプラクティスは？

A. テンプレート3（新機能実装依頼）の受入条件のフォーマットをそのまま使える。加えて「既存のテストファイルのスタイルに合わせること」という制約を付けると、プロジェクトの命名規則・構造に揃ったテストが生成される。

Q5. 失敗したプロンプトを改善する手順は？

A. まず4要素（タスク種別・コンテキスト・受入条件・制約）のどれが欠けているかを確認する。次に「期待した出力」と「実際の出力」の差分を言語化し、その差分を補う情報を追加する。3回試しても改善しない場合はスコープを分割するサインと見なし、タスクを小さく切り直す。

👉 シリーズ全体像: Codex vs Claude Code 使い分け2026

まとめ

Codexのプロンプト設計は4要素（タスク種別・コンテキスト・受入条件・制約）を揃えることが基本だ。今日から取れる具体的なアクションは次の3つだ。

1. テンプレートを手元に置く: 本記事の3テンプレートをコピーして ~/.codex-templates/ に保存し、毎回の指示の雛形として使う
2. 1指示1タスクを守る: バグ修正とリファクタリングを同時に指示しない。複合タスクは分割してから各ステップをテンプレートに当てはめる
3. approval-mode suggest で出力を確認する: 新しいタスクパターンに初めて取り組む際は必ず suggest モードで動作確認を先に行う

プロンプト設計の習熟は積み上げ型のスキルだ。テンプレートを使いながら自分のプロジェクトに合った型を少しずつ育てていくことで、CodexのLLMが持つ推論能力を最大限に引き出せるようになる。

References

• OpenAI Codex 公式リポジトリ — ソースコード・CLI仕様・設定オプション
• Introducing Codex – OpenAI — 2025年4月リリース公式発表
• Codex system card – OpenAI — 安全設計・能力の公式評価
• o3 技術レポート – OpenAI — o3モデルの推論特性
• Codex approval-mode ドキュメント — 実行モードの公式仕様