Codex にリファクタリングを任せるときの依頼手順と失敗回避策

Codex が得意なリファクタリングと苦手なリファクタリング

リファクタリングとは、外部から見た振る舞いを変えずにコードの内部構造を改善することだ。Codex（OpenAI）はこの定義の「内部構造の改善」部分において高い能力を持つが、「外部から見た振る舞いを変えない」という約束の検証は人間側の確認作業に依存する。Codex 公式ドキュメント（https://platform.openai.com/docs/codex）では、エージェントが変更を加えた後に検証ステップを挟むことが推奨されており、その理由がここにある。

Codex が得意な作業

Codex が安定して高品質な成果を出しやすいリファクタリング作業は以下のカテゴリに分類できる。

1. 命名規則の統一 — 変数名・関数名を camelCase や snake_case など一定の規則に揃える。スコープが明確で完了条件が客観的に判定できるため、Codex は正確に実行しやすい。言語ごとの標準（Python なら snake_case、TypeScript なら camelCase）を前提として書いておくと迷いが減る。
2. 重複コードの排除（DRY 化） — 同一ロジックが複数箇所に散在する場合、共通関数やユーティリティクラスとして抽出する。ただし抽出先のファイルを明示しないと、意図しない新ファイルが生成されることがある。事前に「共通関数は src/utils/ に置く」と指定しておくのが安全だ。
3. 型注釈の追加 — TypeScript や Python の型ヒントが未記載のコードに型情報を付与する。静的解析ツール（tsc --noEmit や mypy）の出力を参照させると精度が向上し、Codex が生成した型が実際に正しいかを自ら確認できる状態にする。
4. マジックナンバー・文字列リテラルの定数化 — コード中に直接書かれた数値や文字列を定数に置き換える。定数ファイルの場所と命名規則を事前に指定すると統一感が生まれ、後の検索コストも下がる。
5. コメントや JSDoc の補完 — ドキュメントコメントが不足しているファイルに説明を追記する。既存コメントのサンプルを 1〜2 個提示すると出力スタイルが揃いやすく、後から整形し直す手間が省ける。

Codex が苦手な作業（人間の判断が必要）

一方、以下の作業は Codex 単独では完結しにくい。

ビジネスロジックを変えるリファクタリングは最も注意が必要だ。「この条件分岐を別のアルゴリズムに置き換えて」という依頼は、振る舞いが変わるリスクが高い。Codex は指示通りに実装するが、エッジケースの変化を自覚していない場合がある。ビジネスルールが埋め込まれたコードへの変更は、Codex に実装させた後で必ず人間がロジックを読み直す必要がある。

アーキテクチャレベルの再設計も同様だ。レイヤー分割の変更やデータフローの整理など、複数ファイルにまたがる構造変更は、依頼の粒度が細かくても副作用の予測が難しい。このような変更は Codex を補助ツールとして使い、設計の意図は人間が明示的に指示し続ける必要がある。

依頼の基本パターン

Step 1: スコープを一つのファイルか一つの関心事に絞る

最もよくある失敗は、スコープが広すぎる依頼だ。「src/ ディレクトリ全体のリファクタリング」という指示を出すと、Codex は広範な変更を試みるが、レビューしなければならない差分が数百行を超えることになり、意図しないバグが入り込む温床になる。

依頼の単位は「1 ファイル × 1 種類の変更」を基本とする。複数ファイルに同じ変更を加えたいときは、同じプロンプトを複数の並列タスクに振り分ける方が管理しやすい。

良い依頼の例:

src/utils/dateFormatter.ts の関数名を全て camelCase に統一してください。
変数名は変更しないでください。
変更後に TypeScript の型エラーが出ないことを確認してください。

避けるべき依頼の例:

src/ フォルダのコードをきれいにしてください。

前者は完了条件が明確で差分が予測可能だが、後者は「きれい」の定義が曖昧で Codex の解釈次第で大きく変わる。

Step 2: 完了条件を観察可能な形で指定する

「きれいにして」「最適化して」という指示は Codex の判断に委ねる余地が広すぎる。完了条件はツールや CI で検証できる形で書く。

観察可能な完了条件の例:

• tsc --noEmit がエラーを出さない
• eslint --max-warnings 0 がパスする
• テストスイート npm test が全件グリーンを維持する
• 変更前後で関数のシグネチャ（引数の型と戻り値の型）が変わっていない
• git diff --stat の変更行数が指定した範囲内に収まる

完了条件を Codex に示すことで、Codex は自己レビュー時にそのチェックリストを参照し、余計な変更を加えにくくなる。逆に完了条件を省略すると、Codex が「ついでにこちらも直しておこう」という判断で想定外の変更を加えることがある。

Step 3: AGENTS.md に設計方針を蓄積する

Codex はプロジェクトルートや src/ に配置された AGENTS.md を参照して作業の方針を把握する（GitHub リポジトリ: https://github.com/openai/codex）。リファクタリングに関するルールを AGENTS.md に記載しておくと、毎回プロンプトに書かなくて済む。

AGENTS.md に書いておくと便利な内容の例:

• 命名規則（camelCase, snake_case, PascalCase の使い分け）
• import の順序ルール（外部ライブラリ → 内部モジュールの順など）
• コメントスタイルの方針（JSDoc を必須とするか、関数の先頭のみか）
• 変更してはいけないファイルや関数（API の公開インターフェース、プロトコル定義など）
• リファクタリング後に実行すべき検証コマンド

AGENTS.md の内容は Codex が全タスクで参照するため、一度書いてしまえばプロジェクト全体で一貫したリファクタリングスタイルが維持できる。

失敗しやすいパターンと回避策

パターン 1: 曖昧な指示で巨大な差分が生成される

症状は、1 回の依頼で数十ファイルにまたがる変更が入り、コードレビューに依頼前より長い時間がかかるというものだ。Codex は「指示が許す範囲で最大限の改善」を行おうとするため、指示が抽象的だと想定より広い変更を加えることがある。

回避策: 依頼の末尾に「変更するファイル数は最大 3 ファイルに制限してください」「この依頼で変更するのは dateFormatter.ts 一つだけです」という制約を加える。あるいはサンドボックスモード（--sandbox フラグ）で実行して差分が想定内かを確認してから本番環境のリポジトリに適用する方法も有効だ。

パターン 2: テストが存在しないファイルを変更させる

Codex はコードを変更できるが、変更が正しいかどうかを自律的に検証するには実行可能なテストが必要だ。テストが存在しないファイルへの変更は正しく動いているかを確認する手段が無く、問題が後から発覚することが多い。リファクタリングの安全性はテストカバレッジに大きく依存している。

回避策: テストが無い場合は、リファクタリング依頼の前にテストを追加するタスクを別に依頼する。「src/utils/parser.ts の主要な関数に対するユニットテストを作成してください」という依頼をリファクタリング依頼の前に出すことで、変更の安全網ができる。テスト作成もリファクタリングも Codex に任せられるが、順序を守ることが重要だ。

パターン 3: 命名変更が他ファイルに波及する

関数名や変数名を変えると、その関数を呼び出している他ファイルにも変更が波及する。Codex はスコープを広げて対処しようとするが、結果として意図しないファイルまで変更されることがある。特にエクスポートされた関数の名前を変えると、依存するファイルが多い場合に大規模な変更が生じる。

回避策: 命名変更の依頼には「インポート側のファイルは変更しないでください。変更が必要な箇所の一覧だけを教えてください」という制約を加え、まず影響範囲を把握してから実行する。影響範囲が把握できたら、改めてその一覧を使って変更を依頼する 2 ステップのアプローチが安全だ。

パターン 4: エラーが出るまで変更を繰り返させてしまう

Codex は指示が抽象的だと「完了」の判定が曖昧になり、追加の変更を繰り返すことがある。「ESLint のエラーをゼロにして」という依頼に対して、コードを修正するのではなくルール自体を緩和する設定変更を提案することもある。これは Codex が「目的を達成するもっとも手っ取り早い方法」を選ぼうとした結果だ。

回避策: 「ESLint のルールは変更しないでください。ルールに従うようにコードを変更してください」という制約を明示する。また、依頼の前に npm run lint 2>&1 | head -50 の出力を貼り付けて、修正すべきエラーの一覧を Codex に提示する。Codex はエラーリストが具体的に示されているほど、的確な変更に絞り込みやすくなる。

大規模リファクタリングへの応用：並列タスク活用

Codex v0.142 以降では、複数の並列タスクを安定して動かせるようになった。ワークツリーを分けてタスクを並走させるため、タスク間の競合が発生しにくい構造になっている。大規模なリファクタリングには、以下のアプローチが有効だ。

1. ファイルを分割して並列依頼 — リファクタリング対象ファイルを 3〜5 ファイルのグループに分け、それぞれを別タスクとして同時依頼する。各タスクに同一の変更ルール（AGENTS.md またはプロンプト）を渡すことで統一感を保てる。タスクの命名を「refactor-utils-group-1」「refactor-utils-group-2」のように整理すると進捗の追跡がしやすい。
2. 変更内容のレビューを並列に進める — タスク A の差分を確認しながらタスク B の処理を待つことができるため、待機時間を有効に使える。各差分が小さく独立しているため、レビューの負荷も分散できる。
3. 段階的な適用で安全性を確保する — まず影響が小さい（テストが存在する、ロジック変更なし）ファイルから変更を適用し、動作確認後に次のグループへ進む。問題が起きたときに切り戻す範囲が限定されるため、リスクを最小化できる。

並列タスクを使う場合でも、互いに依存し合うファイルを別タスクに分けることは避ける。たとえば、インターフェースを定義するファイルとそれを実装するファイルを別タスクに割り当てると、マージ時にコンフリクトが生じる可能性がある。依存関係の有無を確認してからタスクを分割することが、並列処理を安全に使う上での前提条件だ。

まとめ

Codex はリファクタリング作業の多くを自動化できるが、その効果を最大化するには依頼の粒度と完了条件の設計が鍵になる。「1 ファイル × 1 種類の変更」を単位にし、観察可能な完了条件（CI コマンドの出力、型エラーの有無など）を指定することで、Codex が生成する差分はレビューしやすいサイズに収まる。AGENTS.md に設計方針を蓄積することで、繰り返しの依頼でも一貫したコーディングスタイルが維持される。サンドボックスモードと並列タスクを組み合わせれば、大規模なコードベースのリファクタリングも安全かつ効率的に進められる。Codex を正しく使えば、リファクタリングにかかる時間を大幅に短縮しつつ、人間がチェックに集中できる環境が整う。