- Codex CLIでレガシーコードの問題点を自動分析・可視化できる
- 段階的リファクタリング戦略でリスクを最小化しながら改善可能
- SES現場特有の「触れないコード」問題をCodex CLIで安全に解決
「このコード、誰も触りたがらない…」——SES現場でこんな声を聞いたことはありませんか？
レガシーコードや技術的負債は、多くの開発プロジェクトが抱える深刻な課題です。特にSES現場では、前任者が退場済みでドキュメントもなく、変更の影響範囲が読めないコードに直面することが少なくありません。
OpenAI Codex CLIを活用すれば、こうしたレガシーコードの解析・理解・段階的な改善を安全に進められます。この記事では、Codex CLIを使ったリファクタリングの実践手法を、SES現場でそのまま使える形で解説します。
- Codex CLIでレガシーコードを自動解析する方法
- 技術的負債の可視化と優先順位付け
- 段階的リファクタリングの戦略と実行手順
- テスト不足のコードを安全に改善するワークフロー
- SES現場で「変更してはいけないコード」に対処する方法
レガシーコードとは？SES現場で直面するリアルな課題
よくあるレガシーコードの特徴
レガシーコードには明確な定義があるわけではありませんが、多くの場合、以下の特徴を持っています。
- テストがない（または極端に少ない）
- ドキュメントがない（コメントも不十分）
- 1つの関数が数百行ある
- グローバル変数や副作用が多い
- 依存関係が複雑に絡み合っている
- 元の開発者がいない
SES現場では、これらに加えて「前任者が退場して引き継ぎが不十分」「客先のコーディング規約と実態が乖離」といった問題も頻発します。
なぜ手作業のリファクタリングは失敗しがちか
手作業でのリファクタリングが難しい理由は主に3つです。
- 影響範囲の把握に時間がかかる：1つの変更が予期しない箇所に波及する
- テストがないと変更の正しさを検証できない：デグレの恐怖が変更を躊躇させる
- 工数の見積もりが困難：「ちょっとした改善」が数週間のプロジェクトになることも
Codex CLIは、これらの課題をAIの力で大幅に軽減します。
Codex CLIでレガシーコードを自動解析する
コードベース全体の健全性スキャン
まず、プロジェクト全体の技術的負債を可視化しましょう。
# プロジェクト全体の技術的負債を分析
codex "このプロジェクトの技術的負債を分析してください。
以下の観点でレポートを作成：
1. 複雑度が高い関数（循環的複雑度15以上）
2. 重複コードの箇所
3. 未使用のインポート・変数
4. 型安全性の問題（any型の使用など）
5. エラーハンドリングの不備
結果をmarkdownテーブルで出力してください。"Codex CLIはサンドボックス内でプロジェクトのファイル構造を読み取り、静的解析に近い分析結果を返してくれます。
特定ファイルの詳細解析
問題のありそうなファイルを絞り込んだら、詳細な解析を行います。
# 特定ファイルの問題点を詳細分析
codex "src/services/OrderService.js を分析してください。
以下を特定してください：
- 単一責任原則に違反している箇所
- テストしにくい密結合な依存関係
- リファクタリングの優先順位（高・中・低）
- 各問題の修正方針の提案"Codex CLIの基本操作がまだの方は、先にセットアップを済ませてください。
技術的負債の可視化と優先順位付け
負債マトリクスの作成
Codex CLIを使って、技術的負債を影響度×修正コストのマトリクスで整理できます。
codex "プロジェクトの技術的負債を以下のマトリクスで分類してください：
| 影響度＼修正コスト | 低コスト | 中コスト | 高コスト |
|---|---|---|---|
| 高影響 | 🔴 最優先 | 🟠 優先 | 🟡 計画的に |
| 中影響 | 🟠 優先 | 🟡 計画的に | ⚪ 様子見 |
| 低影響 | 🟡 計画的に | ⚪ 様子見 | ⚪ 保留 |
各負債項目をこのマトリクスに配置し、
具体的なファイル名と行番号を添えてください。"修正計画の自動生成
優先順位が決まったら、具体的な修正計画を生成します。
codex "最優先の技術的負債3件について、
それぞれリファクタリング計画を作成してください。
各計画には以下を含めてください：
- 現状の問題点
- 目標の状態
- 段階的な修正ステップ（1ステップ=1コミット単位）
- 各ステップでのリスクと確認事項
- 推定所要時間"段階的リファクタリングの実践手順
ステップ1：テストの追加（変更前の安全網）
レガシーコードを変更する前に、現在の動作を保証するテストを追加します。これが最も重要なステップです。
# 既存の動作を保証するテストを自動生成
codex "src/services/OrderService.js の現在の動作を保証する
テストコードを生成してください。
条件：
- 既存の動作を変更せずテストする（特性テスト）
- エッジケースも含める
- モックは最小限にする
- テストファイル名: __tests__/OrderService.test.js"テストなしのリファクタリングは「綱渡り」です。必ずテストを先に書きましょう。Codex CLIテスト自動化の記事も参考にしてください。
ステップ2：関数の抽出と責務の分離
テストが通る状態を維持しながら、巨大な関数を分割します。
# 巨大関数を小さな関数に分割
codex "src/services/OrderService.js の processOrder 関数（280行）を
リファクタリングしてください。
ルール：
- 1関数30行以内に分割
- 各関数に明確な命名をつける
- 既存のテストが全て通ることを確認
- 変更は段階的に行い、各段階でテスト実行可能にする"ステップ3：型安全性の強化
JavaScript → TypeScriptへの段階的な移行もCodex CLIで効率化できます。
# JSファイルをTSに段階的に変換
codex "src/services/OrderService.js を TypeScript に変換してください。
条件：
- any型は使わず、適切な型定義を作成
- 既存のインターフェースがあれば活用
- 型定義ファイルを別途作成（types/order.ts）
- 変換後もテストが通ることを確認"ステップ4：依存関係の整理
密結合な依存関係を、依存性注入（DI）パターンで解消します。
codex "OrderService の依存関係を整理してください。
現状：直接 new でインスタンス生成している箇所が多い
目標：コンストラクタインジェクションで依存性を注入
- PaymentGateway, EmailService, InventoryService を
インターフェース経由で注入する形に変更
- テストでモックに差し替え可能にする"SES現場での安全なリファクタリング戦略
「触ってはいけないコード」への対処法
SES現場では、「このモジュールは触るな」と暗黙的に言われることがあります。Codex CLIを使えば、コードを変更せずに周辺から改善するアプローチが取れます。
# レガシーモジュールをラップするアダプター生成
codex "src/legacy/PaymentModule.js は変更禁止です。
このモジュールをラップするアダプタークラスを作成してください。
目的：
- レガシーAPIを新しいインターフェースで隠蔽
- 新規コードからはアダプター経由でのみアクセス
- 将来的にレガシーモジュールを差し替え可能にする
- エラーハンドリングをアダプター側で統一"変更影響範囲の事前確認
リファクタリング前に、変更の影響範囲をCodex CLIで確認しましょう。
# 変更影響範囲の分析
codex "src/services/OrderService.js の processOrder 関数を
変更した場合の影響範囲を分析してください。
以下を調査：
- この関数を呼び出している全ファイル
- 依存しているグローバル状態
- 副作用（DB書き込み、API呼び出し、ファイル操作）
- テストカバレッジの状況"段階的デプロイとフィーチャーフラグ
大規模なリファクタリングでは、フィーチャーフラグを使って段階的にリリースします。
codex "リファクタリング後の新しいOrderServiceを
フィーチャーフラグで段階的にリリースする仕組みを作成してください。
- 環境変数 USE_NEW_ORDER_SERVICE で切り替え
- 旧実装と新実装を並行稼働可能に
- ログで新旧の結果を比較記録
- 問題発生時に即座にロールバック可能"Codex CLIセキュリティ管理の記事で、安全な運用のベストプラクティスも確認しておきましょう。
リファクタリングの効果を測定する
Before/Afterメトリクスの比較
リファクタリングの効果を定量的に示すことで、チームや顧客への説明がしやすくなります。
codex "リファクタリング前後のコード品質メトリクスを比較してください。
以下の指標で評価：
- 循環的複雑度（Cyclomatic Complexity）
- 関数あたりの平均行数
- テストカバレッジ率
- 重複コードの割合
- TypeScript型カバレッジ率
結果をmarkdownテーブルで出力してください。"| メトリクス | Before | After | 改善率 |
|---|---|---|---|
| 平均循環的複雑度 | 24.3 | 6.8 | -72% |
| 関数あたり平均行数 | 89行 | 22行 | -75% |
| テストカバレッジ | 12% | 78% | +550% |
| 重複コード率 | 18% | 3% | -83% |
ドキュメントの自動生成
リファクタリング後のコードに対して、ドキュメントを自動生成しておくと、次の担当者への引き継ぎがスムーズです。
codex "リファクタリング後の src/services/ 配下の全ファイルについて、
JSDocコメントとREADME.mdを生成してください。
含める内容：
- 各クラス・関数の責務
- 依存関係の図（mermaid記法）
- 使用例
- 設計判断の理由"
実際のリファクタリング事例：SES現場での成功パターン
事例：Java Spring Bootプロジェクトの改善
あるSES現場で、5年間メンテナンスされてきたJava Spring Bootプロジェクトの改善にCodex CLIを活用した事例です。
課題：
- 1つのControllerクラスが3,000行超
- サービス層がなく、ビジネスロジックがControllerに直書き
- テストカバレッジ8%
Codex CLIでの改善アプローチ：
# 1. 現状分析
codex "src/main/java/com/example/controller/OrderController.java を
分析し、責務ごとにサービスクラスに分割する計画を作成"
# 2. サービス層の生成
codex "OrderController から注文処理ロジックを抽出し、
OrderService クラスを作成。DIで注入する形に変更"
# 3. テスト生成
codex "新しい OrderService に対するユニットテストを生成。
Mockito でモック化し、全パターンをカバー"結果：
- Controller: 3,000行 → 200行（93%削減）
- サービスクラス5つに責務を分離
- テストカバレッジ: 8% → 82%
- バグ発生率が月平均12件 → 3件に減少
まとめ
Codex CLIを活用したレガシーコードのリファクタリングは、SES現場の技術的負債を効率的に解消する強力な手法です。
- 自動解析で技術的負債を可視化し、優先順位をつける
- テストを先に追加して安全網を構築してからリファクタリング
- 段階的な改善でリスクを最小化しながら進める
- アダプターパターンで変更禁止のコードにも対処
- メトリクス比較で改善効果を定量的に示す
まずは小さなファイルから始めて、チームにCodex CLIリファクタリングの文化を根付かせていきましょう。
関連記事：
SES BASEでは、AIツール活用やエンジニアのスキルアップに関する最新記事を公開中です。
