直接回答
プロンプトの目標は長く書くことではなく、スコープ、制約、エビデンス、意思決定の境界を十分に明確にし、Codex が継続的に自己修正できるようにすることである。
このガイドで解決できること
Codex CLI プロンプトの改善と複雑なコーディングタスクの分割
5つの要素でタスク契約を定義する
安定したエンジニアリングプロンプトは、少なくとも目標動作、現在の証拠、許容範囲、遵守すべき制約、検証方法を説明する。停止条件も同じく重要で、プロトコルの曖昧さ、依存関係の変更、破壊的操作に直面した際は、Codex に先に質問させるべきである。
未検証の実装案を要件のように偽装しないこと。再現手順とユーザーが観察できる振る舞いを提供し、Codex にまず既存の設計を調査させた上で、リポジトリと整合する実装を選ばせる。
- 目標：どのユーザー動作またはエンジニアリング結果を変更する必要があるか。
- 証拠：エラー、失敗したテスト、ログまたは関連ファイル。
- 範囲：変更を許可するモジュールと明示的に変更禁止するモジュール。
- 制約：互換性、依存関係、性能、セキュリティ、コーディング規範。
- 検証：必ず実行すべきコマンドと期待される判定方法。
探索と修正を2回の承認に分ける
根本原因が不明な場合は、まず読み取り専用のサンドボックスを使う。Codex にエントリーポイントの特定、データフローの追跡、問題の再現、候補案の列挙を求め、計画を確認した後に書き込み可能なセッションを開始する。
この分割は計画が必ず正しいことを保証しないが、ファイルが変更される前に人間が範囲の誤判断、プロトコルの破壊、情報の欠落を発見できるようにする。
codex -C /path/to/repo -s read-only "Issue のタイムアウトを再現し、エントリーポイントからネットワークリクエストまでのデータフローを追跡してください。根本原因と 2 つの修正案、変更対象ファイル、検証コマンドを示し、ファイルは変更しないでください。"codex -C /path/to/repo -s workspace-write -a on-request "承認済みの最小修正を実装してください。最初に回帰テストを追加し、計画にあるファイルだけを変更してください。関連テストと静的チェックを実行し、失敗時は根本原因を修正してチェックを省略しないでください。"意思決定の境界に沿って複雑なタスクを分割する
「フロントエンド半分、バックエンド半分」と機械的に分割してはいけない。より確実な分割順序は、事実の調査、契約の確認、最小の縦断パスの実装、例外パスの補完、検証とレビューである。各ステップには独立した成果物と継続条件がある。
あるステップでユーザーによる API の選択、データベース移行、新規依存関係の追加が必要な場合は一時停止し、モデルにビジネスオーナーの代わりに不可逆な決定をさせないこと。
- 01事実の確立既存のエントリーポイント、呼び出しチェーン、テスト、制約を特定し、ファイルは変更しない。
- 02契約の確認入力、出力、エラー振る舞い、互換性の境界を定義する。
- 03最小実装エンドツーエンドのパスを1本完成させ、対応するテストを追加する。
- 04境界の補完失敗、キャンセル、タイムアウト、権限、ロールバックを処理する。
- 05独立したレビュー必要な一連のチェックを実行し、最終的な diff をレビューする。
コンテキストを一括提示するのではなく、位置特定の手がかりを提供する
ファイルパス、シンボル名、再現コマンド、既存の用例を明確に示すことで、無関係なファイルの読み取りを減らせる。ログやコードベース全体を一度に貼り付けず、まず最小の再現を残し、Codex に必要に応じて読み取らせる。
長期的なリポジトリの事実は AGENTS.md に置き、専用フローは Skill に置き、現在のタスクの受け入れ基準はプロンプトに残す。すべてを1つのプロンプトに詰め込むと、矛盾が増えコンテキストを消費する。
問題: `src/auth/session.ts` は token の期限切れ直後に 500 を返すが、API 契約では 401 が必要。
再現: `<targeted-test-command>` を実行。
参照: エラーマッピングのパターンは `src/api/errors.ts`。
範囲: auth モジュールとそのテストだけを変更し、公開レスポンス構造は維持。
検証: 対象テスト、auth テストスイート、typecheck。
判断点: 共有エラープロトコルの変更が必要なら、影響を説明して承認を待つ。検証を同じタスクに書き込む
「修正後に知らせて」では、品質判断が自然言語の要約に委ねられる。より良いプロンプトは、Codex が実行できるチェックを指定し、コマンド、終了ステータス、まだ未検証の部分を提示するよう求める。
UI タスクには比較可能なスクリーンショットを、データ変換には固定の入出力を、並行処理の問題にはストレステストやレーステストを提供する。検証シグナルが明確であるほど、エージェントは自律的に反復できる。
codex -C /path/to/repo "対象の失敗を修正してください。その後、最も限定的な関連テスト、関連モジュールのテスト、git diff --check を実行してください。チェックが通るか判断が必要になるまで続け、各コマンドと結果を報告してください。未実行のチェックを成功したと報告しないでください。"短いフィードバックで適時軌道修正する
方向の逸脱に気づいたら即座にスコープの拡大を止め、具体的な不一致を指摘して制約を再確認する。誤った案の上に新たな要件を連続で追加してはいけない。
タスク完了後、繰り返し現れるリポジトリの事実は AGENTS.md に定着させる。一時的な選択を永続化してはいけない。有効なプロンプトは、実際の失敗に対する継続的な修正から生まれる。
- どの観察または仮定が誤っていたかを指摘する。
- 直近の検証済み状態に戻るよう要求する。
- ファイルとインターフェースの境界を再定義する。
- 必要に応じて読み取り専用の調査に再入する。
公式情報と検証範囲
本ガイドは公開されている公式ドキュメントを根拠にしています。コマンドや設定はクライアントのバージョンにより変わるため、実行前に参照元も確認してください。
ドキュメントの適用範囲を見る