Codexを実運用して分かった注意点と対策まとめ
- 1. 「止まり方」を前提に監視・制御を組む
- 2. やり過ぎ（過剰な挙動）を「数」で制約する
- 3. 解釈の「保守化・極端化」を防ぐ
- 4. 周辺環境・インフラの堅牢化
- 5. うまくいった指示の出し方（ベストプラクティス）
Codexを本格的に自動運用・並列実行させる中で見えてきた「つまずきポイント」と「効果的だった指示出し（プロンプト）のコツ」をまとめました。
1. 「止まり方」を前提に監視・制御を組む
Codexは正常動作していても「沈黙」したり、プロセスの重複や指示反映のタイムラグが発生します。あらかじめこれらを想定した運用システム（ループ処理）が必要です。
- 30分以上の沈黙（無応答）対策
- codex exec はモデルの応答待ちで30分以上ログが出力されなくなることがあります（子プロセスも生成されません）。
- 対策: 「turn.completed の後 20 分経過」および「30分間出力がなく配下にコマンドもない」の双方を検知して自動停止し、次のループを回す仕組みを構築します。
- 二重起動の防止
- 1回のタスクが終わっても codex-code-mode-host などのプロセスが残り、次の回と二重に実行されるケースがあります。
- 対策: 終了判定はプロセス状態だけでなく、jsonl ログの最終行を確認して正確に行います。
- 設定変更の反映タイミング
- scope.md などの指示ファイルは、タスク開始時に一度しか読み込まれません。指示を変更しても次の回（1〜2時間後）まで有効にならない点に注意が必要です。
- 対策: 急ぎの指示変更がある場合は、実行中のタスクを強制停止して再起動させます。
2. やり過ぎ（過剰な挙動）を「数」で制約する
放置すると、徹底的にテストや報告を繰り返してリソースを食いつぶします。明確な上限ルールを明記しておくことが重要です。
- テスト実行回数の制約
- 放っておくと、1回のタスク内で全テスト（約10分）を何度も実行してしまいます（一晩で141回実行された例も）。
- 対策: 「変更したファイルの関連テストのみ実行し、最終 push 前に 1 回だけ全体テストを行うこと」と明記します。
- 報告ログの爆発防止
- 1回の投稿ごとに400字オーバーの文面＋詳細な添付＋「変更していないこと」の列挙を毎回出力し、Gitサーバーをダウンさせる原因になりました。
- 対策: 「1回の報告につき1コメント・3行以内・長いログはファイル添付」とルール化します。
- 「待ち」動作の禁止
- 「3回確認して待つ」「Start-Sleep でジョブ待機」など、待機状態に時間を使ってしまう傾向があります。
- 対策: 「待たずにタスクを終了する」「止まって人に聞く指示は禁止し、既定の行動をとる」よう指示します。
3. 解釈の「保守化・極端化」を防ぐ
Codexは安全側に倒した解釈（守りのルール）を厳密に適用しすぎるきらいがあります。
- 禁止事項だけでなく「許可事項」も書く
- ガードレールを広く解釈しすぎる傾向があります（例：「門は道具で判定すること」と指示しなかったため、latest.json を直読みして「門が閉じている」と誤判定し8時間停止。「退役させない」を「新バージョンをメインに昇格させない」と解釈など）。
- 対策: ルールを提示する際は「禁止事項」だけでなく「何をしてよいか（許可される操作）」もセットで記述します。
- ボトルネックファイルの担当見直し
- 「担当外のファイルは絶対に触らずIssueで依頼を出す」という規律自体は優秀ですが、受け渡しごとに30〜60分のタイムロスが発生します。
- 対策: 依頼が集中するファイルがあれば、リポジトリの構造や担当の割り振りを変更します（例: relocate.py を data 側へ移動）。
- 設計判断のフィードバック高速化
- Codexは自ら設計の判断をしません（この挙動自体は正常です）。
- 対策: 人間側（または上位システム側）が判断を素早く返せるレビュー・フィードバックの仕組みを整えます。
4. 周辺環境・インフラの堅牢化
Codex自体の問題ではなく、連携するコマンドや環境の不備でタスク全体がストップすることがあります。
- Git / API 通信のタイムアウト設定
- git fetch や git push にタイムアウトが設定されていないと、サーバーがダウンした際にプロセスごと永久に固まります。
- 対策: SSH接続に ConnectTimeout を設定し、API呼出には -m 20（タイムアウト20秒）オプション等を付与します。
- ステータスファイルの書き込み競合（排他制御）
- 自作の status ファイルを出力する際、書き込み途中の不完全なJSONを別プロセスが読み込み、JSONDecodeError が発生することがあります。
- 対策: 一時ファイル（.tmp等）に書き出してから rename（アトミック操作）で置き換える処理を徹底します。
- 実行環境の依存パッケージチェック
- pyproject.toml には記述されているものの、本番環境のPythonに pip install されずに実行エラーとなるケースがあります。
- 対策: デプロイ側のスクリプトで、実行前に依存関係がインストールされているか自動検知する仕組みを入れます。
5. うまくいった指示の出し方（ベストプラクティス）
- 最初の1文で「役割 ＋ 目的 ＋ 終わりの定義」を伝える
- プロンプトの冒頭にこれらを1文で簡潔に書くのが最も効果的でした。詳細すぎる手順書やチェックリストを渡すと、かえって混乱して逆効果になります（モデルは既に手順の基礎を記憶しています）。
- 実装仕様をガチガチに固定して渡す
- 仕様を固めて渡すと驚異的なスピードと正確さで実装します（例：engine2のタスクを20分で1件処理、門の撤去作業を50分で完了など）。逆に設計から任せようとすると迷走します。
- 1ファイル1担当・1役割1プロセス
- 役割やファイルの競合を避け、並列度を上げたい場合は「プロセスごとに明確に役割を分割して増やす」構成が一番安定します。
Write a comment