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

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

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

よくある失敗パターンは「1つの巨大PRで一気にやろうとする」ことです。Files changedが100を超えるような大きなPRでは、変更の広がりや複雑さによってレビュー負荷、見落とし、コンフリクト、マージやロールバックの難しさが増す可能性があります。100ファイルは一律の失敗閾値ではありません。Googleのコードレビュー資料も固定的な上限を置かず、自己完結した小さな変更と、各変更後にシステムが動作することを重視しています。

本記事では、大規模コードベースの段階的リファクタリングを成功させるためのレイヤー別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へ分ける例を示します。変更が大きい場合にレビューや切り戻しをしやすくするための分割案であり、特定案件の経緯や一律のファイル数を基準とする方法ではありません。

PR1：トップページ改修 + 旧認証基盤の置換

この構成では、最初のPRで共通レイアウトと認証の影響範囲を確認します。旧認証基盤（NextAuth, Auth0等）の除去は、代替の認証・認可を実装し、残すページとAPIで動作を検証した上で行います。閉域ネットワークへの配置だけを認証不要の根拠にはしません（NIST SP 800-207のネットワーク位置と認証に関する原則）。代替方式の準備や依存関係によっては、認証の移行を先行PRに分けてから進めます。

対象

• 代替認証に切り替えた旧認証プロバイダ類の除去
• 置換後に不要となった旧ログインページ・旧認証関連APIルートの削除
• トップページの整理（不要な機能へのナビゲーションを削除）

成功条件の設計

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

前提が崩れた場合の対応方針を事前に定義しておくことが重要です。共通レイアウトの変更で残す画面に影響が出た場合は元の状態へ戻し、原因調査後に再実施する、といったロールバック手順を事前に定義します——このように具体的なロールバック手順を明記します。

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

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

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

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

PR3：API層の削除

バックエンドのAPIルートを削除します。特に外部通信を行うAPI（GitHub連携のOctokit、Slack連携など）は接続先と利用箇所を調べ、不要と確認できたものを優先して除去します。残す機能で必要なAPIは、閉域内の代替や許可された接続方式を設計します。

残すべきAPIの明確化が鍵です。「残す機能のAPIルート（残す画面が利用するもの）は全て残す」と明示的にリストアップし、削除対象との境界を可視化します。

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

ビジネスロジック層では、特定機能にだけ使うファイルが残っている場合を想定し、参照元・呼び出し経路・テストを調べて削除対象を判断します。これは点検方法を説明する例で、実際のコードベースで発見された出来事の報告ではありません。

初版の分割案に含まれていない削除候補がないか、事前調査で確認します。参照元や呼び出し経路を調べ、削除対象の網羅性を確かめる工程を設計します。

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

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

外部連携SDK・旧認証基盤・メール送信・状態管理などのうち、残す機能で使われていないと確認できた依存だけを削除対象にします。ORMスキーマの不要モデルも同時に整理します。

PR間の依存関係管理

本記事の5つのPRには順序依存を設け、PR1→PR2→PR3→PR4→PR5を基本のマージ順とします。実際の依存調査で各段階のビルド・動作が保てない場合は、変更のまとめ方や先行PRを調整します。

PR1で旧認証プロバイダを除去すると、PR2以降で削除予定のページに参照が残り、ビルドエラーになる場合があります。利用停止中のページでもビルド対象なら影響があるため、その状態ではマージしません。参照元の削除を同じPRに含めるか、互換性を保つ移行を先行させ、各PRでビルド成功と残す機能の認証・動作を確認します。依存する変更のまとめ方や順序を見直し、移行途中も整合性を保ってPR間の依存を解消します（Google資料「Don’t Break the Build」）。

依存関係を図示する

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

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

調査手法

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

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

レビュー観点の設計

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

6つのレビュー観点

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

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

2026年現在、AIコーディングエージェントは大規模リファクタリングの強力なツールとなっています。特に「コードベースを理解した上でのリファクタリング」が進化しており、LLMとインデックス/検索/グラフを組み合わせ、複数ファイル・複数リポジトリの情報を回答に利用する仕組みがあります。たとえばSourcegraphのCody Context公式説明は、検索・コードグラフと複数リポジトリのコンテキストを扱っています。参照できる範囲は製品・権限・設定によるため、網羅的な依存把握は別途検証します。

AIに任せるべき作業

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

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

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

効果的なAI活用パターン

本記事では、小さなパッケージ単位でバッチ処理し、テストとCIを頻繁に実行し、プロンプトを洗練してから対象を広げる進め方を提案します。AIにコードベース全体の調査を任せつつ、分割戦略と判断は人間が行うハイブリッドアプローチを選択肢とし、調査の漏れ・レビュー負荷・テスト結果で効果を確かめます。

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

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

閉域環境特有の問題

• 外部通信コードの残存：GitHub連携、Slack連携、外部API呼び出しが実行され、必要な接続先へ到達できない場合にエラーや遅延が生じる
• 認証サーバーへの依存：Auth0やNextAuth等を用いた認証処理で、外部の認証先への接続が必要なのに到達できない場合は、認証失敗や遅延の原因になる。製品名だけで外部通信の有無は決まらず、Auth.jsのJWT・DBセッション方式やプロバイダ構成に応じて必要な通信を確認する
• 不要パッケージのダウンロード：yarn install時に必要なパッケージがキャッシュや閉域内レジストリに揃っていないと、オフライン環境ではインストールが失敗する。不要依存の削除に加え、必要依存の配布方法も用意する

対応の優先順位

1. 不要な外部通信の除去（優先）：到達不能な接続のエラーを解消し、必要な通信は代替・許可経路を確保するため
2. 旧認証基盤の置換：全ページ・APIの認証と認可を維持できる代替方式を先に確認し、早期に移行を設計
3. 不要UIの除去：顧客に説明コストが発生するため
4. 不要パッケージの除去：ビルドサイズ削減のため

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

コミット粒度

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

• refactor: 不要なUI要素を削除しレイアウトを整理
• refactor: 代替認証への移行後に共通レイアウトの旧認証プロバイダを除去
• chore: 不要ページ・APIルートを削除

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

ロールバック判断基準

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

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

フェーズ	チェック項目	完了基準
事前調査	残す機能のimport全件調査	全ファイルの依存先を分類済み
事前調査	削除対象リストの作成	全件「確認済み」フラグ付き
事前調査	PR分割案のレビュー	依存関係・成功条件・ロールバック手順が明記
Phase 1	PR1: 旧認証基盤の置換	yarn build成功、残す画面・APIの認証と認可を維持し正常動作
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にご相談ください。