社内システムを何年も使っていると、コードの中に「もう使われていない処理」「同じことをしている関数が3つ」「1つのファイルに何でも詰め込まれた巨大なモジュール」がたまっていきます。どれもすぐに困るわけではありません。ただ、新しい機能を足すたびに読む量が増え、修正のたびに確かめる範囲が広がり、少しずつ開発が遅くなっていきます。

Codex はこうした片付けを手伝える道具です。ただし「このシステムをきれいにして」と一度に頼むと、差分が大きくなりすぎて誰も確かめられません。この記事では、既存コードのリファクタリングを 動きを変えずに・小さく区切って 進める手順を順番に整理します。製品の動きに関わる内容は、2026年11月19日に OpenAI の公式ドキュメント(Refactor your codebase・Best practices・Modernizing your Codebase with Codex)で確かめた範囲に絞りました。

i

本記事の結論: まず Codex に対象の範囲を洗い出させ、どれから片付けるかは人が選びます。1回の作業は「使われていないコードを消す」「巨大なファイルを分ける」など1つのテーマに絞り、編集の前に計画を出させます。1回ごとに差分を見直して検査を実行し、ライブラリの更新や設計の変更は別の作業に分けます。うまくいった進め方は AGENTS.md と Skills に書き残して、チームで繰り返せるようにします。

リファクタリングを Codex に頼むときの考え方

公式ドキュメントのリファクタリングの使い方では、Codex の役割を「使われていないコードを消し・大きなファイルを解きほぐし・重複した処理をまとめ・古い書き方を今の書き方に直す」ことと説明しています。その進め方は 小さく見直せる単位で と書かれています。目標として挙げられているのは次の4つです。(出典: Refactor your codebase)

  1. もう要らないコード・古い補助関数・使われていないフラグ・互換のための仮の処理を消す
  2. 補助関数を切り出す・部品を分ける・副作用を分かりやすい場所に移すなどして、読みにくいモジュールを小さくする
  3. 古い書き方を、そのリポジトリの今の書き方に置き換える
  4. 外から見た動きは変えず、次の変更をしやすくする

大事なのは4つ目です。このページではリファクタリングを、仕組みの総入れ替えではなく、今の仕組みのまま形を整える作業 として扱っています。新しい言語やフレームワークへの移行とは別の作業だと最初に決めておくと、頼む範囲がぶれません。

作業の種類 中身 Codex への頼み方
リファクタリング 今の仕組みのまま、使われていないコードを消す・分ける・まとめる 1つのテーマごとに小さく頼む。動きは変えない
依存の更新 ライブラリやフレームワークの版を上げる リファクタリングとは別の作業にする
移行・作り直し 別の言語や仕組みに移す 計画書と新旧を比べる検査を先に作ってから進める
機能の変更 動きそのものを変える リファクタリングと混ぜない。仕様として別に頼む

手順1: 対象の範囲を洗い出させる

最初の作業ではコードを変えさせません。対象の範囲を調べて一覧にするところまでを頼みます。公式ドキュメントでは、扱いにくいモジュール・重複した処理・使われていないコード・テスト・外から使われている部分・古い書き方を Codex に挙げさせることが、最初の手順として示されています。(出典: Refactor your codebase)

src/order/ 以下を片付けたい。まだコードは変えない。

調べて一覧にしてほしいこと:
- 使われていないと思われる関数・ファイル・設定のフラグ(根拠も書く)
- 同じことをしている処理の組み合わせ
- 大きすぎるファイルと、分けられそうな境目
- 今のリポジトリの書き方と違う古い書き方
- 外から呼ばれている関数・API(変えてはいけない部分)
- それぞれに関係するテストの有無

最後に、片付けの候補を「影響が小さい順」に並べて提案する。

ここで出てきた一覧は、そのまま信じずに担当者が確かめます。Cookbook の古いシステムを刷新する例でも、本番で実際に動いている処理を技術者が確かめ、担当者や業務上の約束など Codex には推し量れない情報を補うよう注意されています。(出典: Modernizing your Codebase with Codex)「使われていない」と判定された処理が、実は月末の締めだけで動く処理だったということは、既存システムでは珍しくありません。

手順2: 1回の作業を1つのテーマに絞る

洗い出しが終わったら、人がテーマを1つ選びます。公式ドキュメントでは、使われていないコードを消す・処理の流れを単純にする・書き方を今のものに直す・大きなファイルを分ける、のどれか1つずつを選んで進めることが勧められています。(出典: Refactor your codebase)

最初の1回におすすめなのは、使われていないコードを消す 作業です。理由は次の3つです。

  1. 差分を確かめやすい: 消した行が本当に使われていないかだけを見ればよい
  2. 効果が見えやすい: 行数やファイル数が減るので、チームに説明しやすい
  3. 戻しやすい: 問題があれば消した部分を戻すだけで済む

反対に、最初から「処理の流れを単純にする」や「大きなファイルを分ける」を選ぶと、1回の差分で動きが変わる可能性のある箇所が増えます。慣れてから順に進めましょう。

進める順番の例 テーマ 確かめること
1回目 使われていないコード・フラグを消す 呼び出し元が本当に無いか。テストが通るか
2回目 重複した処理を1つにまとめる まとめる前とあとで同じ入力に同じ結果を返すか
3回目 大きなファイルを分ける 外から呼ばれている関数の名前と引数が変わっていないか
4回目 古い書き方を今の書き方に直す リポジトリの今の書き方に合っているか

手順3: 編集の前に計画を出させる

テーマを決めたら、すぐに編集させずに計画を出させます。公式ドキュメントでは、1回ごとに 今の動き・改善する構造・動きが変わっていないことを示す最小の検査 の3つを Codex に書かせてから編集に入るよう案内されています。(出典: Refactor your codebase)

計画を先に出させるには Plan mode が使えます。公式ドキュメントでは、Plan mode は文脈を集め、分からない点を質問し、コードを書く前に計画を組み立てる機能と説明され、/plan か Shift+Tab で切り替えられます。(出典: Best practices)作業の途中で方向を直す方法はSteer と Queue・/plan・/goal の記事で解説しています。

頼み方の例です。公式ドキュメントで勧められている「目的・文脈・制約・完了の条件」の4つに沿って書いています。(出典: Best practices)

目的: src/order/ の使われていないコードを消す(手順1の一覧の1〜4番)。
文脈: 一覧は担当者が確かめ済み。5番は月末の締めで使うため対象外。
制約:
- 外から見た動きは変えない
- 外から呼ばれている関数の名前と引数は変えない
- ライブラリの更新や設計の変更はしない。必要そうなら別の作業として報告する
完了の条件:
- 既存のテストがすべて通る
- 実行したコマンドと結果を報告する

編集の前に、今の動き・消す範囲・確かめる検査を計画として出して、確認を待つ。

「必要そうなら別の作業として報告する」の1行が大切です。公式ドキュメントでも、仕組みの移行・依存の更新・API の変更・設計の移動は、片付けに本当に必要な場合を除いて別の作業として扱い、報告させるよう書かれています。(出典: Refactor your codebase)

範囲が広いときは計画書を作らせる

複数のモジュールにまたがる片付けでは、会話の中の計画だけでは追いきれなくなります。公式ドキュメントでは、長く複数の段階がある作業には PLANS.md のような実行計画のひな形を用意する方法が紹介されています。(出典: Best practices)リファクタリングの使い方のページでも、全体像・目指す姿・1回ごとの検査・消すもの・変えない約束・後回しにしたものを記録する計画書(ExecPlan)を使う方法が挙げられています。(出典: Refactor your codebase)

Cookbook の刷新の例では、AGENTS.md から PLANS.md を参照させ、計画書の進み具合と決めたことの記録を作業のたびに更新させる流れになっています。(出典: Modernizing your Codebase with Codex)担当者が途中で交代しても、計画書を読めば続きから進められます。

手順4: 1回ごとに見直して検査する

計画に沿って編集が終わったら、次のテーマに進む前に必ず見直します。公式ドキュメントでは、片付け全体を1つの差分にまとめず、1回ごとにレビューとテストを行うよう案内されています。(出典: Refactor your codebase)

見直しは次の順番で行います。

  1. 検査が実行されて通ったか: 実行したコマンドと結果が報告に書かれているか
  2. 差分が計画どおりか: 計画に無いファイルや関数に手が入っていないか
  3. 外から使われている部分が変わっていないか: 関数の名前・引数・戻り値の形が同じか
  4. 別の作業として報告された点: 依存の更新などの提案が出ていれば、別の課題として記録したか
  5. 普段のレビューに回す: 他の変更と同じ手順でレビューを通す

差分の見直しには Codex のレビュー機能も使えます。公式ドキュメントでは、/review で基準のブランチとの比較・コミットしていない変更・特定のコミット・独自の指示のどれかを選んでレビューさせられると説明されています。デスクトップアプリでは差分の画面で変更を確かめ、行ごとに付けた指摘を次の依頼に渡せます。(出典: Best practices)チームでのレビューの分担はコードレビューをチームで使う記事にまとめています。

なお、認証・依存関係・外部に公開している部分に触れる片付けは、取り込む前にセキュリティの観点でも見直します。リファクタリングの使い方のページでは、そうした変更を見直すための Security Best Practices という Skill が紹介されています。(出典: Refactor your codebase)

検査が足りないと分かったら先にテストを足す

手順3の計画で「動きが変わっていないことを示す検査」が書けない場合は、そこで片付けを止めます。確かめる手段が無いまま進めると、動きが変わっても誰も気づけません。先に今の動きを記録するテストを足し、それから片付けに戻ります。テストの足し方は既存システムにテストを足す記事で手順を解説しています。

手順5: 進め方をチームの決まりにする

1つ目のテーマがうまくいったら、その進め方を書き残して、次からは毎回説明しなくても済むようにします。公式ドキュメントでは、長く使う決まりを毎回の指示に書くことがよくある失敗の1つとして挙げられ、AGENTS.md か Skills に移すよう勧められています。(出典: Best practices)

書き残す場所 書く内容の例
AGENTS.md テストと lint の実行方法。外から呼ばれている関数は変えないこと。依存の更新は別の作業にすること
Skills 「使われていないコードを消す」など、うまくいった片付けの手順と確かめ方
計画書(PLANS.md など) 片付けの全体像・進み具合・決めたこと・後回しにしたこと

公式ドキュメントでは、AGENTS.md にはリポジトリの構成・動かし方・ビルドやテストのコマンド・決まりごと・してはいけないこと・何をもって完了とするかを書き、短く正確に保つよう勧められています。(出典: Best practices)書き方はAGENTS.md の書き方の記事を参考にしてください。

何度も繰り返す片付けの手順は Skills にまとめます。リファクタリングの使い方のページでは、うまくいった書き方の直し方を Skill Creator で再利用できる Skill にする方法が紹介されています。(出典: Refactor your codebase)Skills を部門で作って共有する方法はSkills の作り方の記事で解説しています。

チームで進めるときに決めておくこと

リファクタリングは「時間があるときにやる作業」になりがちで、後回しにされやすい作業です。試験導入の段階で次の4つを決めておくと続けやすくなります。

  • 候補の一覧を1か所に置く: 手順1の洗い出しの結果を課題管理に登録し、上から1つずつ進める
  • 1回の作業の大きさを決める: 「1回の Pull Request で扱うテーマは1つ」をチームの約束にする
  • 同じファイルを同時に触らない: 公式ドキュメントでは、同じファイルに対して作業を同時に走らせるときに Git の worktree を使わないことが、よくある失敗の1つとして挙げられています。(出典: Best practices)作業場所の分け方はLocal・Worktree・Cloud の使い分けの記事をご覧ください
  • 効果を記録する: 消した行数やファイル数に加えて、その後の修正にかかった時間が変わったかを記録しておくと、続ける理由を説明しやすくなります

まとめ

既存コードのリファクタリングを Codex に頼むときは、まず対象の範囲を洗い出させ、どれから片付けるかは人が選びます。1回の作業は1つのテーマに絞り、編集の前に「今の動き・改善する構造・確かめる検査」を計画として出させます。1回ごとに差分を見直して検査を実行し、ライブラリの更新や設計の変更は別の作業に分けます。確かめる検査が無いと分かったら、先にテストを足します。うまくいった進め方は AGENTS.md と Skills に書き残して、チームの決まりにします。

この記事の内容は、2026年11月19日時点の OpenAI 公式ドキュメントの記載に基づいています。機能の名前や画面の操作は変わることがあるため、使う前に最新の記載をご確認ください。デジライズでは、既存の社内システムに Codex を組み込む手順づくりから、AGENTS.md・Skills の整え方、現場向けの研修までを含めた Codex の法人導入支援のご相談を承っています。「まず1つのシステムで使われていないコードを消すところから試したい」という段階からでもお問い合わせください。