大規模コードベースの段階的リファクタリング戦略｜レイヤー別PR分割・不要コード削除・閉域環境デプロイ対応の実践ガイド【2026年版】

大規模コードベースのリファクタリングはなぜ失敗するのか

「技術的負債を返済したい」「不要コードを削除してビルドサイズを半分にしたい」「閉域環境にデプロイするため外部依存を全て除去したい」——大規模リファクタリングの動機は明確でも、実行段階で頓挫するプロジェクトは後を絶ちません。

よくある失敗パターンは「1つの巨大PRで一気にやろうとする」ことです。Files changedが100を超えるPRは、レビュアーが全体を把握できず、見落としが増え、コンフリクトが頻発し、最終的には「マージできない」「元に戻せない」状態に陥ります。

本記事では、大規模コードベースの段階的リファクタリングを成功させるためのレイヤー別PR分割戦略を、実際のプロジェクトで使われた手法に基づいて解説します。不要コードの削除、認証基盤の除去、閉域環境対応など、実務で発生する典型的なシナリオをカバーします。

「削除が先、改善が後」の原則

大規模リファクタリングで最も重要な原則は、不要コードの削除（Phase 1）を改善作業（Phase 2）より先に行うことです。

この順序を守る理由は明確です。不要コードが残ったまま改善に着手すると、改善のたびに「このコード触っていいのか？」「この依存まだ使ってるのか？」という判断コストが発生します。削除を先に終わらせることで、Phase 2以降の作業が格段にスムーズになります。

3フェーズ構成

フェーズ	目的	PR数の目安
Phase 1: 削除	不要機能・不要コードの除去	3〜5 PR
Phase 2: 改善	UX向上・機能改善	2〜4 PR
Phase 3: 新機能	新しい機能の追加	1〜2 PR

Phase 1：レイヤー別5PR分割戦略

不要コードの削除は、コードベースのレイヤー構造に沿って5つのPRに分割します。この分割は「1PRにまとめるとFiles changedが100を超える」という実務上の問題から生まれた方法です。

PR1：トップページ改修 + 認証基盤の除去

最初のPRで最もリスクの高い変更を行います。認証基盤（NextAuth, Auth0等）の除去は、全ページに影響するlayout.tsxの変更を伴うため、他の削除より先に実施します。

対象

• SessionProvider・AuthWrapperの除去
• ログインページ・認証関連APIルートの削除
• トップページの整理（不要な機能へのナビゲーションを削除）

成功条件の設計

• yarn buildがエラーなく完了すること
• 残す機能の全画面が正常に表示されること
• 削除した機能のURLにアクセスすると404になること
• Before/Afterのスクリーンショットを成果物に含めること

前提が崩れた場合の対応方針を事前に定義しておくことが重要です。「AuthWrapper除去後に残す画面の表示に影響が出た場合は、git revertで戻し、原因を調査してから再実施する。自己判断せず相談する」——このように具体的なロールバック手順を明記します。

PR2：UI層の削除（ページ・コンポーネント・store・hooks）

画面に直接関わるコードを削除します。

• ページ：不要な画面ディレクトリごと削除
• コンポーネント：不要画面専用のUI部品を削除
• 状態管理：Zustand store、React hooksなど

「要確認」フラグの活用が重要です。削除対象がグレーなファイル（例：MarkdownText.tsx — 残す機能で使われている可能性あり）は、import依存を全件調査した上で「未使用を確認済み」と明記します。

PR3：API層の削除

バックエンドのAPIルートを削除します。特に外部通信を行うAPI（GitHub連携のOctokit、Slack連携など）は、閉域環境でエラーの原因になるため優先的に除去します。

残すべきAPIの明確化が鍵です。「残す機能のAPIルート（/api/targets/, /api/conversion/, /api/files/）は全て残す」と明示的にリストアップし、削除対象との境界を可視化します。

PR4：サービス層の削除（lib/・types/・agents/・scripts/）

ビジネスロジック層の不要コードを削除します。ある実例では、src/lib/にワークスペース専用ファイルが約67ファイル存在することが、コードベース調査で初めて判明しました。

「叩き（初版）では未記載だった。コードベース調査で判明」——この発見は、削除対象の網羅性を確保するために事前調査が必須であることを示しています。

PR5：不要依存パッケージ・DBモデルの整理

PR1〜PR4でコードを消しても、package.jsonにライブラリが残ります。最後のPRで不要パッケージを削除し、ビルドサイズを最小化します。

ある実例では、以下の16パッケージが削除対象となりました：GitHub API SDK、認証基盤（NextAuth）、メール送信（SendGrid）、Slack連携、Git操作、ターミナルUI、WebSocket、状態管理ライブラリなど。Prismaスキーマの不要モデル（20モデル）も同時に整理します。

PR間の依存関係管理

5つのPRは順序依存があり、必ずPR1→PR2→PR3→PR4→PR5の順にマージします。

PR1でSessionProviderを除去するため、PR2以降で削除するページは一時的にビルドエラーになりますが、それらは既に「利用停止中」の機能であり実害はありません。この一時的な不整合を許容することで、PR間の循環依存を避けられます。

依存関係を図示する

Phase 1（必須順序）
PR1 → PR2 → PR3 → PR4 → PR5

Phase 2（Phase 1完了後、順不同）
PR6（ファイル操作改善）
PR7（進捗可視化）
PR8（UI/UX向上）

Phase 3（Phase 2完了後）
PR9（新機能追加）

コードベース調査：削除前の必須ステップ

大規模削除で最も怖いのは「使っていると思わなかったコードが実は使われていた」という見落としです。これを防ぐために、削除対象のimport依存を全件調査します。

調査手法

1. 残す機能のimportを全件リスト化：残す画面のファイル（例：Fortran変換ページ3ファイル）からのimport先を全て列挙
2. 依存先を分類：フレームワーク（React, Next.js）、UIライブラリ（Chakra UI）、型定義、独自モジュール
3. 独自モジュールの使用状況を確認：「残す機能で使用 → 残す」「未使用 → 削除候補」
4. 削除候補に「確認済み」フラグを付与：「全件Fortran変換で未使用を確認済み」

この調査を「叩き（初版）」の段階で実施し、フィードバックを経て精緻化するプロセスが効果的です。初版では概要レベルの分割案を作成し、レビューで「何がなぜ必要かわからない」というフィードバックを受けて、「なぜ必要か」の観点で全PR項目を再構成します。

レビュー観点の設計

大規模リファクタリングのPRレビューでは、通常のコードレビューとは異なる観点が必要です。

6つのレビュー観点

1. スコープの妥当性：合意した改善項目を漏れなくカバーしているか。スコープ外のものが混入していないか
2. 削除対象の網羅性：関連するページ・コンポーネント・API・依存パッケージが全て特定されているか
3. 技術的整合性：認証基盤除去後に残す機能が正常に動作する設計になっているか
4. 動作確認方法：各PRの成功条件が具体的に定義されているか
5. 優先順位・依存関係：PR間の依存関係が明示されているか
6. 前提が崩れた場合：ロールバック手順が用意されているか

AIエージェントを活用した大規模リファクタリング

2026年現在、AIコーディングエージェントは大規模リファクタリングの強力なツールとなっています。特に「コードベースを理解した上でのリファクタリング」が進化しており、LLMとインデックス/検索/グラフを組み合わせることで、複数ファイル・複数リポジトリにまたがる推論が可能になっています。

AIに任せるべき作業

• import依存の全件調査：残す機能のファイルからのimport先を自動で列挙
• 削除対象の特定：「どのファイルがどの機能でのみ使われているか」のマッピング
• パッケージ使用状況の調査：package.jsonの各ライブラリが実際にimportされているかの確認
• grep残存チェック：削除後に関連する参照が残っていないかの検証

人間が判断すべきポイント

• PR分割の粒度：レビュー負荷とマージリスクのバランス
• グレーゾーンの判断：使われているかどうか微妙なコードの削除/残存判断
• ロールバック戦略：どの段階でgit revertするか
• ステークホルダーとの合意：何を残して何を消すかの意思決定

効果的なAI活用パターン

小さなパッケージ単位でバッチ処理し、テストとCIを頻繁に実行し、プロンプトを洗練してからスケールするアプローチが推奨されています。AIにコードベース全体の調査を任せつつ、分割戦略と判断は人間が行うハイブリッドアプローチが最も効果的です。

閉域環境デプロイのためのコード整理

閉域ネットワーク内のVMへのデプロイを前提としたリファクタリングでは、通常の技術的負債解消とは異なる観点が必要です。

閉域環境特有の問題

• 外部通信コードの残存：GitHub連携、Slack連携、外部API呼び出しのコードが残っていると、閉域環境でエラーが頻発する
• 認証サーバーへの依存：Auth0やNextAuthが全ページで認証チェックを行う設計の場合、認証サーバーのない閉域VMで起動遅延やエラーの原因になる
• 不要パッケージのダウンロード：yarn install時に不要パッケージのダウンロードが発生し、オフライン環境ではインストール自体が失敗する

対応の優先順位

1. 外部通信の除去（最優先）：エラーの直接原因となるため
2. 認証基盤の除去：全ページに影響するため早期に対処
3. 不要UIの除去：顧客に説明コストが発生するため
4. 不要パッケージの除去：ビルドサイズ削減のため

コミット方針とロールバック戦略

コミット粒度

各PRはさらに機能単位でコミットを細かく分割します。

• refactor: トップページを1カラム化し不要カードを削除
• refactor: layout.tsxからSessionProvider・AuthWrapperを除去
• chore: 認証関連ページ・APIルートを削除

この粒度にすることで、問題発生時にgit revertで特定の変更だけを巻き戻すことが可能になります。

ロールバック判断基準

状況	対応
yarn buildエラー	git revertで直前のコミットに戻し、importの依存関係を調査
残す画面の表示崩れ	UIテーマとの整合性を調査して報告。自己判断せず相談
削除対象が実は使われていた	削除せず相談。大きな構造変更が必要なら計画を再策定

まとめ：段階的リファクタリングのチェックリスト

フェーズ	チェック項目	完了基準
事前調査	残す機能のimport全件調査	全ファイルの依存先を分類済み
事前調査	削除対象リストの作成	全件「確認済み」フラグ付き
事前調査	PR分割案のレビュー	依存関係・成功条件・ロールバック手順が明記
Phase 1	PR1: 認証基盤除去	yarn build成功、残す画面全て正常表示
Phase 1	PR2: UI層削除	yarn build成功、404確認
Phase 1	PR3: API層削除	yarn build成功、残すAPI正常動作
Phase 1	PR4: サービス層削除	yarn build成功
Phase 1	PR5: パッケージ整理	yarn install → yarn build成功
Phase 2	UX改善PRs	各PRの成功条件を満たす
Phase 3	新機能PRs	各PRの成功条件を満たす

大規模リファクタリングは「一気にやる」のではなく「構造化して段階的に進める」ことが成功の鍵です。レイヤー別PR分割、事前のimport全件調査、明確な成功条件とロールバック手順の定義——この3つを実践することで、100ファイル超の変更でも安全にマージできます。

あわせて読みたい

• 5Sとは｜整理・整頓・清掃・清潔・しつけの意味・目的・進め方を解説
• AIリードスコアリング実装ガイド【2026年版】— 4要素スコアリング×テリトリー管理×ステータス倍率の本番アーキテクチャ
• AIカスタマーサポート完全ガイド【2026年版】— RAG・チャットボット・有人連携の実装パターンとツール比較

関連記事

• デプロイ障害の6ステージ切り分け
• 作業方針書テンプレート
• ポストモーテム設計
• 納品前セキュリティ検品

開発プロセスの改善はrenueにご相談ください。