Codex プロンプト設計レポート（2025-09-09）

このレポートは、OpenAI のオープンソース開発者エージェント「Codex CLI」を対象に、効果的なプロンプト設計の原則・実践パターン・テンプレート・チェックリストを体系化したものです。公式ドキュメントと公開情報を一次情報として参照しています（参考資料を末尾に記載）。

1. 要約（TL;DR）

成功の鍵は「明確な目的、具体的な変更範囲、十分なコンテキスト、検証手順、自律性の度合いの指定」。
コンテキストは層で与える（グローバル: ~/.codex/instructions.md、プロジェクト: CODEX.md、タスク: その都度の指示ファイル）。
タスク規模に応じてプロンプト構造を変える（Small / Medium / Large）。Small は一文で「どのファイル/関数をどう変えるか」を明示、Medium は指示ファイルに詳細、Large は計画・状態共有（.codex/や計画ファイル）を組み込む。
検証方法（テストやコマンド、成果物、レビュー観点）を明記し、Codex に「自分で動作確認→結果を残す」まで求める。
承認モード（Suggest / Auto Edit / Full Auto）に合わせて、どこまで自動化して良いかを先に宣言する。

2. 用語と前提

Codex CLI: 端末で動くエージェント。ローカルのコードを「読み・編集・実行」できる。インタラクティブ UI と承認ワークフローを持つ。
承認モード（代表的な3種）
- Suggest: 読み取りのみ自動。編集・コマンドは提案にとどまり要承認。
- Auto Edit: 読み取りと編集を自動。コマンド実行は要承認。
- Full Auto: 読み・書き・コマンド実行を自動（通常はネットワーク無効のサンドボックス下）。
プロジェクト指示ファイル
- ~/.codex/instructions.md: ユーザー全体の既定方針。
- CODEX.md: リポジトリ固有の合意事項（構成、ルール、テスト方法など）。
- AGENTS.md: 製品版 Codex（クラウド側）の案内では、リポジトリに置くガイドとして触れられており、CLIでも実質的に CODEX.md が同等の役割を担う。

3. プロンプト設計の原則

目的を短く一文で定義する

例: 「utils/priceUtils.js の discount 関数に10%割引を適用する。」

変更範囲と期待される振る舞いを具体化する

ファイル名・関数名・入出力・境界条件・受け入れ基準（Acceptance Criteria）を明記。

コンテキストを層で与える

グローバル既定は ~/.codex/instructions.md、リポジトリ固有の規約や手順は CODEX.md に整理。タスク特有の補助情報（対象ファイル一覧、依存、背景）はその場の指示に含める。

検証と成果物を「最初に」指定する

実行コマンド（例: npm test -w pkg-a）、確認観点、生成/更新すべきファイル（例: final_output.md への変更点サマリ）を列挙。

自律性の度合いを宣言する

現在の承認モードに応じて、どこまで自動で進めてよいか（編集/コマンド/計画更新など）を明記。

フィードバック・ループを前提にする

うまくいかなければインタラクティブに修正指示。Large タスクでは中間成果物（計画、設計、PRドラフト）を要求。

4. タスク規模別パターン

4.1 Small（局所変更・1ファイル/1関数中心）

狙い: 高速反復。具体性が命。

必須要素
- 変更対象の明確化（ファイル/関数）
- 期待する新しい挙動（入力→出力、境界ケース）
- 受け入れ基準（テスト観点/実行例）
例（1行プロンプト）
- 「utils/priceUtils.js の discount に税込合計への10%割引を実装。価格が負にならないよう下限0を保証。npm test -w pricing が通ること。」

テンプレートは §5 を参照。

4.2 Medium（複数ファイル・非自明なリファクタ）

狙い: 指示ファイルに詳細を書く。Codex に「読むべきファイル」「アウトプット」を列挙。

推奨: 指示内容をローカルファイル（例: task_description.md）に記述し、Codex に渡す。
含めるべき内容
- 背景とゴール（短く）
- 関連ファイルのリスト
- 命名規約/設計方針（必要なら CODEX.md へ誘導）
- 実行/検証コマンド、生成物（変更記録の出力先など）

4.3 Large（長時間・段階計画・自己管理）

狙い: 計画→実装→検証→ふりかえりを自己管理させる。

推奨パターン
- 共有用ディレクトリ .codex/ を作り、計画・メモ・出力を集約
- 高レベル要件を最初に渡す（範囲・優先度・制約）
- 計画ファイルの継続更新（例: .codex/plan_2025-09-09.md）
- 重要な完了時には README.md に変更履歴を追記

5. すぐ使えるテンプレート

5.1 Small: 単一関数の挙動変更

目的: `utils/priceUtils.js` の `discount(amount, taxIncluded)` に 10% 割引を実装し、最小値 0 を保証する。

変更範囲:
- ファイル: utils/priceUtils.js
- 関数: discount

期待挙動:
- 入力 110（taxIncluded=true）→ 出力 99
- 入力 5 → 出力 4.5（小数は小数第2位まで）
- 負値は 0 に丸める

検証:
- `npm test -w pricing`
- 変更点サマリを `final_output.md` に追記

承認モード: Auto Edit（編集は自動、コマンド実行は要承認）

5.2 Medium: リファクタ + 命名統一

ゴール: docs_site 全体のモデル名表記を簡潔化。

参照ファイル:
- docs_site/content/models.md
- docs_site/components/ModelCard.tsx
- docs_site/utils/modelList.ts
- docs_site/config/sidebar.ts

要件:
- ユーザー向けの表示名称を統一（簡潔な命名）
- 破壊的変更は避ける（公開 API 名は維持）

検証:
- `pnpm -w docs_site build`
- 変更点サマリを `final_output.md` に箇条書き

承認モード: Suggest（編集・コマンドは提案まで。内容確認後に承認する）

5.3 Large: 設計→実装→検証を自己管理

ゴール: CI の失敗を解消し、型・lint・テストを安定化。

手順:
1) `.codex/` を作成し、計画を `.codex/plan_2025-09-09.md` に書く。
2) 計画を進めながら、主要マイルストーンで更新。
3) コマンド `pnpm -w lint && pnpm -w typecheck && pnpm -w test` を通す。
4) 完了時に `README.md` の「変更履歴」に日付付きで追加。

承認モード: Full Auto（サンドボックス内で自動実行。危険操作は提案時に説明）

6. 実践チェックリスト

目的が一文で明確か
変更範囲（ファイル/関数/モジュール）を列挙したか
入出力やエッジケース、受け入れ基準を書いたか
検証コマンド・観点・成果物（サマリやログ）を指定したか
自律性（承認モード）を宣言したか
コンテキスト（CODEX.md、関連ファイル）への導線があるか
中間生成物（設計/計画/PRドラフト）を要求したか（Large）
ロールバック/安全策（ブランチ、差分表示、Dry-Run）を明記したか

7. アンチパターン（避けるべき書き方）

「○○をいい感じに」など目的が曖昧
ファイル・関数が特定されていないまま大域的変更を要求
検証基準がない（何をもって完了か不明）
互換性/制約条件（パフォーマンス・セキュリティ・コーディング規約）を後出し
承認モード不一致（Suggest なのにコマンド自動実行を暗黙期待）

8. `CODEX.md`/`AGENTS.md` の活用ポイント

リポジトリに以下の章立てで置くと、プロンプトが短くてもブレにくくなります：

プロジェクト概要 / 依存関係 / 実行方法
ディレクトリ構成と命名規約
テスト・型・Lint のコマンドと合格基準
安全に触れてよい領域／避ける領域（生成ファイル、外部API）
コミット/PR のスタイル（ Conventional Commits 等）
代表的なタスクのプロンプト例（Small/Medium/Large）

製品版 Codex のガイドでは AGENTS.md が紹介されていますが、CLI では CODEX.md に同等の運用知を集約するのが実用的です。

9. 承認モード別の書き方のコツ

Suggest
- 書き方: 「提案パッチと実行予定のコマンドを提示してから待機」
- 目的: 安全・レビュー重視。学習フェーズや初期探索。
Auto Edit
- 書き方: 「編集は自動で進め、コマンドは提案に留める」
- 目的: 機械的置換や広範囲のリファクタで手戻りを抑制。
Full Auto
- 書き方: 「指定の検証コマンドを自動実行。結果をログ/サマリに残す」
- 目的: CI 修復や原型実装など、時間のかかる反復を任せる。

10. 参考資料（一次情報）

OpenAI GitHub: Codex CLI Prompting Guide（指示ファイルと Small/Medium/Large の典型パターン）
- https://github.com/openai/codex/blob/main/codex-cli/examples/prompting_guide.md
OpenAI Developers: Codex CLI（概要、承認モード、実行形態）
- https://developers.openai.com/codex/cli
OpenAI Help Center: OpenAI Codex CLI – Getting Started（承認モードの表、利用上の注意）
- https://help.openai.com/en/articles/11096431
OpenAI Blog: Introducing Codex（AGENTS.md の活用、タスク処理と検証の考え方）
- https://openai.com/index/introducing-codex/

（注）上記は 2025-09-09 時点での公開情報を参照。

付録A: 受け入れ基準（例）

既存テストはすべて合格。新規テストは網羅条件を満たす。
生成物（API、CLI、ドキュメント）は変更方針に沿って一貫。
型・Lint・フォーマットはプロジェクト既定に準拠。
パフォーマンス劣化やセキュリティリスクを導入しない。
変更点サマリ/ログが final_output.md に残っている。

付録B: 依頼テンプレ（ショート版）

<目的: 一文>
<変更範囲: ファイル/関数>
<期待挙動と受け入れ基準>
<検証手順: コマンド/結果の出力先>
<承認モードと自律度>

kuuote/codex_guide.md