codex

Codex

Codex は PATH 上で利用できる独立したエージェントです（codex — シェルのエイリアスに隠されている場合は command codex として実行します）。この作業ツリーを共有し、すでに認証済みです。Codex はセカンドオピニオンであり、絶対的な正解ではありません。報告内容を検証し、変更には責任を持ってください。Codex はリポジトリに含まれる同じスキルを読み込みます。

ユーザーから特定のモデルを指定されない限り、Codex のモデルは CLI のデフォルトのままにしてください。デフォルトは現在の Codex リリースに従います。このスキルで日付付きのモデル ID を固定しないでください。明示的な上書きが必要な場合は、現行のモデルであることを確認し、-m <model> で指定されたモデルを渡してください。

codex がインストールされていない場合

codex が PATH に見つからない場合は、インストールを提案してください。必ず事前にユーザーの承認を求め、独断でインストールしてはいけません。 承認されたら、https://developers.openai.com/codex/cli の最新の手順に従ってください。初回の認証は対話形式で行われるため、その手順はユーザーに委ねてください。続行する前に codex --version で確認してください。

Codex へのプロンプト

Codex には共同作業者ではなく、オペレーターとして指示してください。XML タグを使い、簡潔でブロック構造のプロンプトにします。タスク、完了の定義、重要な制約を少数だけ明記してください。大規模な実行に移る前に、指示の契約を改善してください。曖昧さを残したまま --effort を上げるより効果的です。

• 1 回の実行につき 1 つのタスクにします。 無関係な依頼（レビュー、修正、ドキュメント作成など）は別々の実行に分けてください。複数の依頼を混ぜたプロンプトでは、結果も混在します。
• スキルを言い換えず、スキル名を指定します。 Codex はリポジトリに含まれる同じスキルを読みます。「ドキュメントには write-docs に従ってください」「refactor-clean に従い、互換性ラッパーを追加しないでください」のように指示します。スキルの内容を重ねて説明する必要はありません。
• タスクに必要なブロックだけを追加します。
  • <task> — 具体的な作業、リポジトリや失敗の状況、期待する最終状態を記述します。ほぼ必ず含めます。
  • <output_contract> — 出力の厳密な形式を、重要度の高い順に簡潔に記述します。
  • <default_follow_through> — リスクの低い解釈を採用して作業を進めます。情報不足によって正確性、安全性、または取り消し不能な操作に影響する場合に限り、作業を止めます。
  • <verification_loop> — 最終化する前に、要件と変更したファイルに照らして結果を確認します。初稿をそのまま提出せず、必要に応じて修正します。リスクのある修正では必ず行います。
  • <grounding> — 主張はすべてコードまたはツールの出力を根拠とし、推論は推論であると明記します。レビューや調査に使います。
  • <action_safety> — 差分を必要な範囲に厳密に絞り、依頼と無関係なリファクタリングは行いません。書き込みタスクに使います。
• アンチパターン： 曖昧な依頼（「見てみて」）、出力の契約がない指示（「報告してください」）、契約の代わりに「もっと深く考えて」と求めること、1 回の実行で複数の作業を混ぜること、証拠から判断できない確実性を要求すること。

レビュー — 積極的に実施

リファクタリング、複雑なアルゴリズム、レンダラーの作業、セキュリティ上重要な変更など、別の視点から確認してほしい実質的な差分がある場合は、完了を宣言したりコミットしたりする前に、必ず Codex のレビューを実行します。些細な編集（誤字、コメント、ドキュメントのみの変更）は対象外です。

1. 起動する前に差分の範囲を正しく指定します。作業ツリーの変更には --uncommitted、ブランチの差分には --base <branch>、取り込まれたコミットには --commit <sha> を使用します。取り込まれたコミットは完全な SHA に解決してください。非対話型のレビューエントリポイントを使用し、明示的な読み取り専用サンドボックスを指定して、新しい一時ディレクトリに進捗ファイルと判定ファイルを個別に用意します。

   review_dir=$(mktemp -d "${TMPDIR:-/tmp}/codex-review.XXXXXX")
   codex exec --sandbox read-only -C "$(git rev-parse --show-toplevel)" review \
     --commit "$(git rev-parse HEAD)" --json -o "$review_dir/verdict.md" \
     < /dev/null > "$review_dir/events.jsonl" 2> "$review_dir/stderr.log"
   

   長時間実行する処理はバックグラウンドで実行し、プロセス／セッションのハンドルを保持します。範囲指定フラグとカスタム指示は併用できません。範囲指定フラグにはプロンプトを指定しません。カスタムの枠組みを指定する場合は、確認する差分をプロンプトで明示してください。デフォルトの範囲や、すべての参照／チェックポイント履歴の走査に頼らないでください。期待する回答を決して伝えないでください（screenshot-critique と同様、先入観を与えないこと）。

2. events.jsonl で進捗を、stderr.log で失敗を監視します。関連するコードを確認しているレビュアーは、5 分が経過しただけでハングしたとは限りません。処理が停滞したり、差分とその依存関係の範囲外に逸れたりした場合は、中断する前に直近のコマンド／エラーを確認し、原因を修正するか、タスクの範囲を狭めてから再試行します。完了とみなすには、終了ステータスが 0 であること、turn.completed があること、最終判定が空でないことが必要です。タイムアウト、turn.failed、または判定の欠落は未完了であり、レビューに問題がなかったことを意味しません。

3. 指摘事項はすべてトリアージし、対応する前にコードと照合して確認します。Codex が示した証拠の範囲を守ってください。推論として示された内容は事実ではありません。自分自身の懸念と重なる指摘は優先度の高い証拠です。却下する指摘には、黙って済ませず、理由を明記してください。

4. Codex が指摘したこと、修正したこと、却下したこととその理由をユーザーに報告します。すべての指摘を修正するか、明示的に却下したら完了です。

実装 — 明示的な依頼がある場合のみ

ユーザーがタスクで Codex を指定した場合に限り、実装を Codex に委任してください。 自分の判断で作業を任せてはいけません。また、新たな依頼がない限り、追加作業を再委任してはいけません。

1. 委任する前に、上記のプロンプト作成の原則に従って、目標、制約、検証方法を明確にし、タスクを具体化してください。内容が曖昧なタスクは、新たなエージェントが誤解する余地がなくなるまで、自分で担当してください。
2. クリーンなツリーから開始するか、ベースラインのコミットを記録して、Codex の差分を自分の変更と切り分けられるようにしてください。
3. タスクで実行する必要がある内容に応じて、サンドボックスを選択してください。
   • 純粋なコード変更と型チェック／単体テストの場合：codex exec --sandbox workspace-write "<task>"。ネットワークは無効です。新しい依存関係の取得など、タスクの実行にフェッチが必要な場合に限り、-c sandbox_workspace_write.network_access=true を追加してください。
   • ブラウザーでの検証、開発サーバー、またはテストスイート全体の実行には、codex exec --dangerously-bypass-approvals-and-sandbox "<task>" を使用してください。 サンドボックスでは localhost のバインドがブロックされるため（vite／playwright で listen EPERM が発生します）、サンドボックス内の Codex は実行を確認していないコードを提出することになります。このバイパスはその見落としと引き換えに、OS の制御を一切行いません。専用の git worktree 内でのみ使用し、プロンプトは最初から最後まで自分で作成してください（第三者のテキストをそのまま渡してはいけません）。その後に必ず行う差分レビューが、残された制御手段です。 -o <file> で最終メッセージを保存し、時間のかかる呼び出しをバックグラウンドで実行してください。コンテキストが膨らまないよう、Codex の stderr に出力される思考ノイズは 2>/dev/null で抑制してください（失敗した実行をデバッグする場合は抑制を解除してください）。git リポジトリ外で実行する場合は、--skip-git-repo-check を追加してください。非対話型の実行では、どちらの場合も承認を求められることはありません。
4. 続きは codex exec resume <session-id> "<follow-up>" で実行してください。セッション ID は実行ヘッダーから取得します。resume --last は全体で直近のセッションを意味します。その間にレビューやその他の Codex 実行があると、対象がそちらに切り替わってしまいます。2 回再開しても収束しない場合は、委任を中止して自分で仕上げてください。混乱したエージェントに繰り返し対応するより、自分で引き取るほうが効率的です。
5. 結果に対する責任は自分にあります。差分全体を読み、テストを実行してから報告してください。「Codex が完了したと言っている」だけでは完了ではありません。

Exec の稼働状況 — ハングは作業ではありません

バックグラウンドで起動した codex exec は、起動時に停止することがあります。プロセスは生存していて CPU 使用率が約 0％でも、~/.codex/sessions/<Y/M/D>/ にセッションファイルがなく、ネットワークソケットもなく、ツリーにも変更がない状態です。「プロセスが実行中」は「作業中」を意味しません。

• 標準入力には、継承した端末ではなく、必ずファイルまたは /dev/null を指定してください。 対話用またはパイプの標準入力をプロンプトの入力元がない状態で残しておくと、exec は Reading additional input from stdin... を表示して永久にブロックします。これが最もよくあるハングです。プロンプトを位置引数として渡して < /dev/null を指定するか、codex exec [flags] - < prompt.txt でプロンプトファイルを入力してください（- によって Codex は標準入力からタスクを読み取ります。ファイルがない場合はリダイレクトで明示的に失敗するため、"$(cat prompt.txt)" のようにフォールバック文字列をタスクとして黙って送信することがありません）。必要に応じて nohup／& を追加してください。
• ウォッチドッグ： プロンプトに一意のマーカーを入れ、約 3 分以内に grep -rl "<marker>" ~/.codex/sessions/<Y/M/D>/ でセッションが見つからなければ、exec を終了してください。終了後に再起動すれば、安定して動作します。
• worktree を信頼できる状態にしてください。 Codex が信頼していないディレクトリでのヘッドレス exec は、見えないプロンプトで永久にブロックされることがあります。Git worktree は信頼済みリポジトリのルートとは別のパスになるため、worktree 内で exec する前に、~/.codex/config.toml に [projects."<worktree-path>"]\ntrust_level = "trusted" を追加してください。これが安全な解決策です。ここではバイパスフラグの使用は禁止されています。
• 同じタイミングで 2 つの exec を起動しないでください。 新しい exec を開始する前に、古くなってハングしている exec を終了してください。
• リポジトリ／worktree のルートから起動してください。 書き込み可能なサンドボックスのルートは起動時の CWD です。サブディレクトリ（例：web/）から exec すると、その外部への編集はすべて「writing outside of the project」として拒否され、never の承認ポリシーでは対処できません。その実行ではファイルが 1 つも変更されないまま時間を消費します。cd で移動する代わりに、-C <root> を渡して作業ルートを明示してください。

ルール

• Codex exec の実行中は、作業ツリーに手を加えないでください。
• レビュー、相談、質問には --sandbox read-only を明示してください。workspace-write は実装を委任する場合にのみ使用してください。
• --dangerously-bypass-approvals-and-sandbox は、ブラウザー／サーバー／全スイートを実行する必要があるタスク（上記）に限り、専用の worktree で使用してください。プロンプトは自分で作成し、実行後に必ず差分をレビューしてください。--full-auto は削除されています（workspace-write の別名でした）。安易に使用しないでください。
• 推論の労力とモデルは設定／フラグで上書きできます（-c model_reasoning_effort=high、-m <model>。以前の --effort フラグは現在の Codex では廃止されています）。ユーザーから指定がない限り、どちらもデフォルトのままにしてください。まずプロンプトを明確にし、モデル ID はバージョンなしのものを使用してください。バージョン指定が必要な場合は、使用前に最新であることを確認してください。