3行まとめ
最初は現状理解だけを任せます。
速度、保守性、拡張性を分けます。
採用案だけを小さく実装します。
本気で直す前に、壊さない条件を決めます。
- Codexにリファクタリングを頼むなら、最初から「本気で直して」と変更させるより、read-onlyで現状理解、リスク、変えてはいけない挙動を整理させるほうが安全です。
- 速度重視、保守性重視、拡張性重視の3案を出させると、選択肢は増えます。ただし、採用する案は1つに絞り、採用しない理由まで残す必要があります。
- 合格ラインは「コードがきれいに見える」ではなく、差分が小さく、テストが通り、未検証項目が明記され、人間がレビューできることです。
本文の事実確認には、OpenAIのCodex関連公式資料、Codex permissions、Running Codex safely、公開済みのベンチマーク/導入記事を使っています。Xで伸びていた「Codexに強く改善を頼む」系の投稿は需要シグナルとして扱い、本文の根拠にはしていません。
この記事でわかること
変更前に現状理解を出せます。
3案のメリットとリスクを並べられます。
1案に絞る理由を残せます。
テストと未検証を確認できます。
改善案より、選ぶ理由を残すことが大事です。
- Codexへリファクタリングを頼む前に固定する前提
- read-only調査で出させるべき現状理解とリスク
- 速度、保守性、拡張性の3案比較表の作り方
- 採用案を1つに絞る判断基準
- 大差分を小さなPRへ分ける手順
- テスト、レビュー、停止条件の置き方
前提知識
- 1固定
変えてはいけない挙動を決めます。
- 2調査
呼び出し元とテストを確認します。
- 3比較
3案を分けて評価します。
- 4実装
小さな差分で進めます。
機能追加が混ざるなら別タスクにします。
リファクタリングは、動くコードを壊さずに構造を改善する作業です。AIコーディングエージェントにとって魅力的な作業に見えますが、実務では危険な作業でもあります。見た目が整理されても、公開API、エラー処理、非同期処理、境界値、パフォーマンス、アクセシビリティ、ログ、監視、テストfixtureが壊れることがあります。
Codexはコード理解、差分作成、テスト補助、レビュー指摘の整理に使えます。ただし、Codexが出した改善案をそのまま採用するのではなく、現状維持ライン、比較軸、採用基準、テスト、レビューを人間側で固定する必要があります。
リファクタリングと機能追加を分ける
リファクタリングでは、基本的に外部挙動を変えません。機能追加、仕様変更、依存関係追加、DB変更、UI文言変更が混ざるなら、それは別タスクとして分けます。
確認項目
公開API、入力/出力、エラー時の挙動、ログ、既存テスト、手動確認項目、パフォーマンス上の制約を最初に固定します。これがないと、Codexの改善案が本当に改善なのか判断できません。
注意点
「読みやすくして」は便利な依頼ですが、広すぎます。対象範囲、変えてよいもの、変えてはいけないもの、完了条件を一緒に渡します。
まずread-onlyで現状理解をさせる
| 項目 | 内容 | 見方 |
|---|---|---|
| 役割 | 対象コードが何をしているか整理します。 | |
| 呼び出し元 | 影響範囲を確認します。 | |
| 既存テスト | 変わらないことを確認する材料です。 | |
| リスク | 壊れやすい挙動を先に出します。 |
根拠ファイルがない改善案は採用しません。
最初に任せるべきなのは、変更ではなく調査です。Codexに対象ファイル、呼び出し元、テスト、リスク、改善候補を整理させます。この段階ではファイル編集をさせません。
調査依頼の型
まだファイルは変更しないでください。
対象コードの役割、呼び出し元、公開API、既存テスト、壊しやすい挙動、
リファクタリング候補を整理してください。
速度、保守性、拡張性の観点でリスクも分けてください。根拠
Codexのようなエージェントは、コードベースを読み、変更案を出す前の調査にも使えます。read-onlyで始めると、実行権限を広げる前にレビュー材料を作れます。
評価基準
調査結果に、対象ファイル、呼び出し元、既存テスト、未確認の点が含まれているかを見ます。根拠ファイルがない改善案は、採用候補にしません。
変えてはいけない挙動を先に書く
Codexは改善案を出す時、内部構造を変えるだけでなく、境界挙動まで変えてしまうことがあります。先に「変えてはいけない挙動」を列挙します。
確認項目
空文字、null、undefined、0件、重複、タイムアウト、権限エラー、リトライ、ログ出力、既存CSS class、公開イベント名、URL、API responseを確認します。
注意点
既存挙動がきれいでない場合でも、勝手に直さないほうがよいことがあります。仕様として残っている挙動なのか、バグなのかを分けます。
3案比較を作らせる
| 項目 | 内容 | 見方 |
|---|---|---|
| 速度重視 | 実測がある時だけ候補にします。 | |
| 保守性重視 | 読みやすさと責務分離を見ます。 | |
| 拡張性重視 | 確定した仕様追加がある時に見ます。 | |
| 不採用条件 | 各案を捨てる理由も書きます。 |
メリットだけでは比較になりません。
現状理解ができたら、Codexに3案を出させます。ここで大事なのは、3案全部を混ぜないことです。速度重視、保守性重視、拡張性重視は、それぞれ別の判断軸です。
3案比較表を作る
| 案 | 目的 | 変更量 | 向いている場面 | 注意点 |
|---|---|---|---|---|
| 速度重視 | hot pathを軽くする | 中 | 計測で遅い箇所が分かっている | 実測なしに採用しない |
| 保守性重視 | 読みやすさと責務分離 | 小〜中 | 変更頻度が高い箇所 | 抽象化しすぎない |
| 拡張性重視 | 将来の分岐を受ける | 中〜大 | 仕様追加が見えている | 今ない要求を作り込まない |
依頼例
このコードを改善する案を3つ出してください。
1. 速度重視
2. 保守性重視
3. 拡張性重視
各案について、変更範囲、メリット、リスク、必要なテスト、
採用しないほうがよい条件を書いてください。
まだ実装しないでください。評価基準
各案に、変更範囲、リスク、テスト、採用しない条件があるかを見ます。メリットだけの案は比較になりません。
速度案は実測なしに採用しない
速度重視案は魅力的ですが、実測がない最適化は危険です。コードが複雑になり、体感では速くなった気がしても、実際には差がないことがあります。
確認項目
対象処理が本当に遅いのか、どの入力で遅いのか、計測方法は何か、改善後に同じ条件で測れるかを確認します。
停止条件
計測できない、hot pathではない、可読性が大きく落ちる、キャッシュで整合性リスクが出る。この場合は速度案を採用しません。
採用案は1つに絞り、残りは捨てる
変更量の小ささを優先します。
実測がある速度案だけ採用します。
確定範囲だけ拡張性を見ます。
最小差分を選びます。
不採用理由を残すと、同じ議論を減らせます。
3案を出す目的は、全部を混ぜることではありません。比較したうえで1つを選び、残りは捨てます。混ぜると、目的が曖昧な大差分になります。
採用基準を先に置く
採用基準は、プロジェクトの状況で変わります。障害対応中なら変更量の小ささ、長期保守なら読みやすさ、今後の仕様追加が確定しているなら拡張性を重視します。
判断表
| 状況 | 優先する案 |
|---|---|
| 本番障害後の修正 | 保守性重視の小差分 |
| 明確な性能問題 | 速度重視。ただし実測必須 |
| 仕様追加が確定 | 拡張性重視。ただし範囲限定 |
| レビュー担当が少ない | 変更量が最小の案 |
注意点
「良さそうだから全部入れる」は避けます。採用案が1つに絞れない時は、タスクを分けます。
採用しない理由も残す
採用しなかった案の理由を残すと、後で同じ議論を繰り返さずに済みます。これはスレッド管理や永続メモリとも相性が良い情報です。
例
速度案は、実測でボトルネックではないため不採用。拡張性案は、今期中に仕様追加が確定していないため不採用。今回は保守性重視で、関数分割とテスト追加だけを行う。
評価基準
採用理由と不採用理由が、PR descriptionや作業ログに残っているかを見ます。理由が残っていない改善は、次のレビューで蒸し返されます。
差分は小さなPRへ分ける
- PR1
テスト追加で現状挙動を固定します。
- PR2
関数分割など構造変更だけを行います。
- PR3
命名整理など低リスク変更を分けます。
- PR4
性能改善は計測つきで行います。
小さな差分ほどレビューとロールバックが楽です。
Codexは一度に多くの変更を提案できますが、レビューできる差分に分ける必要があります。リファクタリングは、差分が大きくなるほど不具合を見つけにくくなります。
PR分割の基本
1つのPRに、命名変更、関数分割、テスト追加、性能改善、仕様変更を混ぜないようにします。
| PR | 内容 | レビュー観点 |
|---|---|---|
| PR1 | テスト追加だけ | 現状挙動を固定できているか |
| PR2 | 関数分割だけ | 外部挙動が変わっていないか |
| PR3 | 命名整理だけ | 参照漏れがないか |
| PR4 | 性能改善 | 計測結果があるか |
根拠
小さな差分ほど、レビューとロールバックがしやすくなります。Codexに複数案を出させても、実装は小さく分けます。
注意点
テスト追加と実装変更を同じPRに入れる場合もありますが、既存挙動を固定するテストは先に出すほうが安全です。
スレッドとworktreeも分ける
並行して複数のリファクタリング案を試すなら、スレッドとworktreeを分けます。同じworktreeで速度案と保守性案を混ぜると、どの差分がどの案なのか分からなくなります。
関連
スレッドやworktreeの分け方は、Codexのスレッド管理記事で詳しく整理しています。
停止条件
差分が複数目的に広がった、テストが追いつかない、レビュー担当が追えない、同じファイルに複数案が衝突している。この場合は作業を止め、分割し直します。
テストとレビューゲートを固定する
| 項目 | 内容 | 見方 |
|---|---|---|
| lint/typecheck | 静的な崩れを確認します。 | |
| unit/e2e | 既存挙動を確認します。 | |
| 未検証 | 実行できなかった確認を残します。 | |
| 人間レビュー | 過剰抽象化やログを見ます。 |
外部挙動が変わらない根拠を報告に入れます。
リファクタリングのレビューでは、テスト通過だけでなく、変わっていないことを確認します。Codexに差分を作らせる前に、テストとレビューゲートを固定します。
最低限のゲート
npm run lint
npm run typecheck
npm test
npm run test:e2eプロジェクトによってコマンドは違います。大事なのは、Codexに任せる前に、どのコマンドを合格条件にするかを決めておくことです。
確認項目
unit test、integration test、E2E、型チェック、lint、snapshot、手動確認、パフォーマンス計測を確認します。全部を毎回走らせる必要はありませんが、必要なものを選ぶ理由を残します。
注意点
テストが通っても、レビュー不要にはなりません。命名、責務分離、過剰抽象化、エラー処理、ログ、可観測性、ロールバックしやすさは人間が見ます。
レビュー依頼の型
Codexに最終報告を作らせる時は、次の型にします。
採用した案:
採用しなかった案:
変更したファイル:
外部挙動が変わらない根拠:
実行したテスト:
未検証:
レビューで見てほしい点:評価基準
レビュー担当が、この報告だけで差分を見る順番を決められるかを見ます。未検証が空欄の場合は、本当に未検証がないのか確認します。
関連
評価タスクや比較条件の作り方は、AI Coding Benchmark Kitの記事も参考になります。
セキュリティ・コスト注意
envやcredentialsを読ませません。
本番ログは対象から外します。
大差分は人間の時間を増やします。
戻しやすい単位に分けます。
AIが速く作っても、人間が読めなければ遅いです。
リファクタリングはセキュリティとコストにも影響します。認証、権限、ログ、外部通信、依存関係、データ変換を触る場合は、通常の整理作業より慎重に扱います。
権限とsecretを分ける
Codexにリファクタリングを頼む時も、secret、.env、credentials、顧客データ、本番ログは読ませません。read-only調査でも、対象ファイルに機密が含まれる場合は除外します。
確認項目
対象ファイル、参照してよいログ、外部通信の有無、MCP toolの権限、書き込み可能範囲を確認します。
注意点
「改善のために全体を見せる」は危険です。必要な範囲だけを読ませ、権限は段階的に広げます。
コストはレビュー時間にも出る
AIの利用量だけでなく、レビュー時間もコストです。大きなリファクタリングは、生成が速くてもレビューが遅くなります。
評価基準
レビュー担当が30分以内に差分意図を説明できない場合、そのPRは大きすぎる可能性があります。Codexが速く作った差分でも、人間が読めなければ実務では遅いです。
改善方法
PRを小さく分け、先にテスト追加、次に構造変更、最後に性能改善へ進めます。スレッドとPRを対応させると、レビュー時に追いやすくなります。
失敗点とハマりどころ
速度、保守性、拡張性を混ぜます。
まだない要求を作り込みます。
期待値を書き換えて仕様変更になります。
レビュー不能なPRになります。
リファクタリングと仕様変更を分けます。
Codexリファクタリングの失敗は、AIがコードを書けないことより、目的が広すぎることから起きます。
変更目的が混ざる
読みやすくする、速くする、将来に備える、テストを増やすを同時にやると、差分が大きくなります。目的が複数あるなら、PRも複数に分けます。
抽象化しすぎる
保守性を上げるつもりで、まだ必要ない抽象化を増やすことがあります。将来の仕様が確定していないなら、拡張性案を採用しない判断も必要です。
テストを書き換えてしまう
リファクタリングでテストが落ちた時、期待値を変えると仕様変更になります。既存挙動を変えるなら、リファクタリングではなく仕様変更タスクとして扱います。
実務で使うなら
- 1日目
対象と変えない挙動を決めます。
- 2日目
read-only調査を行います。
- 3日目
3案比較を作ります。
- 4-5日目
採用案を小さなPRへ分けます。
最初の目的は、大改修ではなくレビュー可能な型作りです。
実務では、Codexに「全部きれいにして」と頼むより、1週間の小さなパイロットで型を作ります。
1週間の進め方
1日目に対象コードと変えてはいけない挙動を整理します。2日目にread-only調査をさせます。3日目に3案比較を作ります。4日目に採用案を1つ選び、小さなPRを作ります。5日目にテスト、レビュー、未検証、次のPR候補を整理します。
スコアカード
| 評価軸 | 合格ライン |
|---|---|
| 現状理解 | 対象ファイル、呼び出し元、既存テストが整理されている |
| 比較 | 3案のメリット、リスク、採用しない条件がある |
| 差分 | 1目的で小さい |
| テスト | 実行結果または未実行理由がある |
| レビュー | 採用/不採用理由が残っている |
| 安全性 | secretや本番ログに触れていない |
関連導線
Codexをチーム導入へ広げる前提は、Codex 101をチーム導入へ落とす記事で確認できます。リファクタリングの評価タスクを作るなら、AI Coding Benchmark Kitの記事も合わせて使えます。
FAQ
まず調査と案出しに使います。
実測なしには採用しません。
保守性重視でも必要です。
1案に絞って実装します。
迷ったら、小さく戻せる差分を選びます。
Codexに「本気でリファクタリングして」と頼んでもよいですか？
調査や案出しには使えますが、そのまま大差分を作らせるのは危険です。まずread-onlyで現状理解と3案比較を出させます。
速度重視案はいつ採用しますか？
実測で遅い箇所が分かっていて、同じ条件で改善後を測れる時です。実測がない場合は、速度案を採用しないほうが安全です。
保守性重視ならテストは不要ですか？
不要ではありません。外部挙動を変えないことを確認するために、既存テストや追加テストが必要です。
3案を全部混ぜてもよいですか？
混ぜないほうがよいです。採用案を1つに絞り、残りは別タスクにします。混ぜると目的が曖昧な大差分になります。
更新履歴
- 2026年5月31日
Codex関連公式資料、permissions、安全運用記事を確認して初版を作成しました。
導入時には最新の公式情報を確認してください。
2026年5月31日 JSTに、OpenAIのCodex関連公式資料、Codex permissions、Running Codex safely、公開済みの導入/ベンチマーク記事を確認して初版を作成しました。Codex関連機能は更新されやすいため、導入時には最新の公式情報を確認してください。