Claude Codeのコード近代化を着手前に準備する6ステップ

数年がかりだったコード近代化が数か月、時には数週間で終わるようになりました。一方で組織側の作業量は、多くの場合変わりません。銀行の基幹システムへの変更は今も変更管理・レビュー・承認を通ります。人間が1件ずつ書き、人間が1件ずつ差分を見る前提で作られた仕組みだからです。エージェントが変更を書く速度を上げるほど、ボトルネックは「変更を作る」から「組織をその変更に合意させる」へ移ります。

近代化のボトルネックは書く速度から合意形成の速度に移った

この論点は、Anthropicのforward deployed engineer(顧客先の導入現場に常駐して伴走するエンジニア)であるJonah EzekielとLexie Tonelliの記事が中心に据えるものです。同記事は「Notes from the Field」シリーズの1本で、顧客導入の現場で得た実務知見を共有する枠組みです。今回は顧客の基幹システム近代化に伴走した経験がベースになっています。

エージェントが差分を書く速度は、人間のレビュー速度をとうに超えました。だとすれば律速するのは執筆側ではなく、組織側の意思決定です。何を近代化のゴールとするか、どの変更を機械的に合格とみなすか、誰がどこまで見るか。これらを近代化が始まる前に決めておくかどうかで、プロジェクトの所要時間は大きく変わります。その事前準備は、ターゲットの選定から始まる6ステップの手順に分かれます。移行そのものの技術手順(依存関係マッピング・ルールブック・移行ループ)はClaude Codeのコードモダナイゼーションに譲り、ここでは着手前に組織で決めておくことを扱います。

ステップ1: 近代化には3つの型があり、選ぶ基準は挙動を変えるかどうか

近代化のゴールは「ターゲット」(target、近代化の到達目標)と呼ばれ、3つの型に分かれます。どれを選ぶかで対象範囲と証明書の設計が丸ごと変わるため、最初に確定させる必要があります。Claude Codeでコード近代化を進める場合も、最初に決めるのはこの型です。

スタックは問題なくバージョンだけが古いならUplift、スタックそのものが問題で挙動は今のままでよいならTransform、挙動ごと作り替える必要があるならReimagineです。この選択は組織内でしばしば割れます。本番運用に近い担当者はリスクを抑えたいのでTransformを望み、技術的負債の解消や新要件の追加を狙うステークホルダーはReimagineを望みがちです。未確定のまま着手すると「この変更は正しいか」という論争が後から蒸し返されます。

ターゲットを決めたら、現行システムの挙動を棚卸しします。Claudeが得意なのは依存関係のマッピングと、文書化されていなかったワークフローの言語化です。公式のcode modernization pluginは/code-modernization:配下のmodernize-assess・modernize-map・modernize-extract-rulesの各段階でソース引用付きのビジネスルールを抽出し、エンジニアがレビューできる形で出力します。ただしClaudeの発見だけでは全挙動を捉えきれず、業務ユーザーへのインタビューや既存ドキュメントでの補完が前提です。Reimagineでは挙動仕様書そのものをユーザーグループと合意しながら書き下ろします。プラグインという仕組み自体の構造(commands・agents・skills・hooks)はClaude Codeのプラグイン移行手順で扱っています。

正当化の根拠も早めに固めます。近代化の主目的はコスト削減より「リスク低減」であることが多く、未パッチの脆弱性やサポート切れランタイム、システムを理解するエンジニアの減少が挙げられます。エージェント型ツールはタイムラインを縮めましたが予算の見積りは依然として難しく、これが着手の停滞要因になります。それでも最大の壁は、システムを所有するチームと依存するチームからの社内合意形成です。

ステップ2: 証明書(certificate)は人手を介さない合否基準の集合

証明書とは、すべての近代化変更が満たすべき条件とテストの集合です。人手を介さず機械的にチェックできる条件を選ぶことで、エージェント型ワークフローは証明書を満たすまで変更を反復するか、満たせない場合だけ人間レビューへフラグを立てられます。代表的な項目は次の通りです。

• 元のテストスイートが通る
• 近代化中にClaudeが書いたテストがすべて通る
• テストカバレッジが合意閾値を満たす
• パフォーマンスベンチマークが合意範囲内に収まる
• 毎回新しいコンテキストウィンドウで動くClaudeの独立した敵対的レビューでブロッカーが見つからない
• UIについてはClaude駆動のcomputer useでリグレッションが見つからない
• 現行システムと近代化後のシステムが同一入力から同一出力を生成する(入力はライブ・記録済み・Claude生成のいずれか)
• 永続化された状態やワイヤーフォーマットが現行システムと近代化後のシステムで相互変換できる
• ステージングで合意期間、エラー率・レイテンシ・アラートにリグレッションなく稼働する
• 静的解析・セキュリティスキャンで新規指摘が0件
• コンパイル型のターゲットでは、ビルドがクリーンで型チェックが通る

証明書は、レビューして本番へ昇格させる人たちと一緒に書きます。開発者・ユーザーグループ・事業責任者を設計段階から巻き込むと、レビュー時の納得感が生まれます。「証明書の根拠だけでマージして納得できるか」が、証明書の完成度を測る実用的な問いです。検証手段を先に用意する考え方は個人開発のリファクタリングでも同じで、Claude Codeのリファクタリング手順やClaude CodeでのTDDの回し方で扱っている「検証を先に固定する」順番と地続きです。

証明書が照合する対象は近代化タイプごとに変わります。

Reimagineでは、仕様から書いたテスト、各変更を仕様と照合するClaudeの独立敵対的レビュー、新システムが旧システムの挙動を保っているかの差分チェックに頼ることになります。仕様が明確になるにつれて証明書も改定が必要になり、仕様の穴はこの過程で最初に露呈します。

旧システムはテストカバレッジが薄く、テストがフレーキーで、テレメトリも乏しいことが珍しくありません。証明書の設計は、こうした穴を特定する作業でもあります。強い証明書を支えるのが難しいと分かったら、この段階でClaudeに不足するテストや検証基盤を作らせます。代表はprod-parallel環境と、リプレイハーネスです。prod-parallelは新旧システムを本番と並行稼働させ、出力を突き合わせる構成を指します。リプレイハーネスは本番トラフィックを複製して新旧システムに流し込み、差分を検証する仕組みです。

プラグインのmodernize-verifyは、この証明書の判定をモジュールごとに出します。判定はPROVEN・PARTLY PROVEN・NOT PROVENの3段階です。旧システムが手元で動かない場合(メインフレームのプログラムや本番でしか動かないシステム)は、記録済みの出力との照合しかできないため、最良でもPARTLY PROVENに留まります。

ステップ3: 昇格ポリシーは変更の影響範囲でレビューの深さを階層化する

エージェントは、人間チームが1件ずつレビューできる速度をはるかに超える量の変更を生成します。昇格ポリシーは、変更ごとの人間レビューの深さを定める階層型のレビュー経路で、事前に文書化し合意しておくものです。近代化を許容できるタイムラインで終えるための仕組みで、証明書と同様にレビュー担当者と一緒に設計し、既存の変更管理プロセスへ組み込みます。共通するルールは4つです。

1. 影響範囲(blast radius)とエージェントの確信度で変更を階層化する。組織に既存のリスク分類があればそれを流用し、クリティカルパスは完全な人間レビューを維持する
2. 繰り返し出るフラグは個別対応せず根本で直す。同種のフラグが続くならエージェント型ワークフローか証明書側の原因を疑う
3. レビュー担当者と一緒に出力フォーマットを設計する。レビューを速くする情報や、確信度の高いシグナルを事前に合意する
4. SME(領域専門家、subject matter expert)の時間配分を最適化する。SMEは全ての差分を読むわけではないので、大量の差分に埋もれず最もリスクの高い階層の変更、その中でフラグが立ったエージェントの判断へ直行できるようにする

これらのルールの多くは、SMEの稼働時間をプロジェクトの早い段階に前倒しする効果を持ちます。早期フィードバックがあれば、本格近代化の前に証明書とワークフローを調整できます。サンプル変更へのSME承認は、軽いレビュー経路を採る根拠にもなります。レビューを最後に置く従来の非エージェント型パターンとは順序が逆です。

昇格ポリシーは、近代化が「速度」と「レビューの深さ」のどちらに寄るかも反映します。固いデッドラインがある近代化では、軽いレビューで速く進めるポリシーと、そのリスクを受け入れるという明示の合意が要ります。期限に余裕があれば、深いレビューで緩やかに移行できます。規制環境では軽いレビュー経路への心理的抵抗が強くなります。承認者は個別の悪い変更のリスクを負う一方、経営層はシステム老朽化というより大きなリスクを負っているためです。

ステップ4: 前提条件は4つの領域にまたがり、3つの外部チームが関わる

ステップ1〜3(ターゲット・証明書・昇格ポリシーの設計)と並行して早めに着手すべき前提条件は、4つの領域にまたがります。その多くは近代化チームの外にある3つのチーム — 基盤/インフラ、QA/リリースエンジニアリング、セキュリティ/コンプライアンス — が関わる領域で、それぞれ独自のバックログと承認プロセスを持つため、要件が判明した時点で会話を始めます。

セキュリティ領域が求める最小権限は、近代化ブランチへの書き込みのみで本番クレデンシャルを持たせないという線引きです。MCP経由で本番系に接続するワークフロー全般に共通する設計原則は、MCPで本番環境に接続する権限設計で扱っている読み取り専用ロールと承認フローの考え方とほぼ同じです。近代化ブランチだけに書き込みを絞り、本番への昇格は昇格ポリシーという別の層に委ねる構造になっています。code modernization plugin自体もレガシーのソースは編集せず、書き込み先はanalysis/とmodernized/に限られます。

ステップ5・6: コード近代化のワークフローは小さな範囲で磨いてから広げる

ステップ5: code modernization pluginで専用ワークフローを作る

前提条件が整ったら、Claude Codeでコードベース近代化専用のカスタムワークフローを作ります。出発点はcode modernization pluginです。

claude

/plugin install code-modernization@claude-plugins-official

公式マーケットプレイス(claude-plugins-official)はターミナルでの初回の対話セッションで自動登録されるため、/plugin marketplace addは通常不要です。ただし/plugin installはその場ではインストールされません。実行すると/pluginパネルが開き、プラグインの内容を確認したうえで、ユーザー単位・プロジェクト単位・このリポジトリのみのいずれかのインストールスコープを選んでから確定します。未追加のマーケットプレイスのプラグインは、/plugin install <name> --marketplace <source>で追加と導入をまとめて行えます(Claude Code v2.1.275以降)。導入後の入口コマンドは/code-modernization:modernizeで、実行すると近代化で何をしたいかを聞かれます。

ターゲット・証明書・昇格ポリシー・コードベース・ドキュメント・証明書が要求するデータソースは、ファイルシステムかMCP経由でClaudeが参照できる場所にまとめて置きます。これがプロジェクトの中核知識ベースになり、このプレイブック(Anthropicのブログ記事)自体をコンテキストとして渡すことも想定されています。土台さえ整えば、ワークフローの構築自体は難しい部分ではありません。

構築したワークフローをスケールさせる前に、SMEにClaudeの作業(コードベース固有のskillsや抽出されたルールを含む)をレビューしてもらいます。コードベースの小さな部分に適用して洗練し、生成された変更・エージェントのプロセス・証明書が満たされた証拠をSMEが確認します。問題が出たら個々の変更を直すのではなく、ワークフロー側を修正します。目標は、スケール後もほぼ全ての変更が証明書を満たし、レビュー担当者が昇格ポリシーの下で安心してマージできる状態です。

準備の決定事項は、プラグインのどの工程の前提になるか

Upliftはextract-rulesとreviewを飛ばせて、preflight→assess→uplift→verifyで完結する経路があります。人が決めるのはpreflightの回答、要確認ルール、ブリーフ承認、証明が見つけた差分の受容、証明への署名、セキュリティパッチの適用の6点です。

技術手順の側はClaude Codeのコードモダナイゼーションが扱います。上の表は、そこで動く各工程が準備段階の合意に依存することを示す対応です。

ステップ6: 小さな範囲で仕上げてからフルコードベースへ広げる

小さな部分でエンドツーエンドの近代化(昇格ポリシーを通したレビューと着地を含む)を1回完遂してから、フルコードベースへスケールします。TransformとReimagineは既存システムと並行してターゲットを構築しカットオーバーする形になりますが、Upliftにはもう一つの選択肢があります。開発を止めずに稼働中のコードベース上でそのまま近代化する方法で、システムを止められない場合や変更が速すぎて別コピーを維持しづらい場合に選ばれます。有効な手法の一つは、コードベースを葉から内側へ向けて論理パーティションに分割することです。パーティションを1つずつフリーズして近代化し、済んだパーティションを新規コミットが覆せないようCI/CDでゲートします。

着手前に潰しておきたい4つの落とし穴

• スキップされたテストを網羅の根拠に数えない: プラグインの試用例では、実行されなかったテストでしか言及されないルールまで、証明が「カバー済み」と数えていた事例があります。現在は、この状態に警告が出ます。証明書に書く合格条件は、実行されたテストを前提にします。
• 成果物のコミットは人が行う: プラグインのコマンドはリポジトリにコミットしません。analysis/とmodernized/は自分でコミットします。Upliftの作業コピーは、差分をレビューできるよう専用のローカル履歴を持ちます。
• 大規模実行の権限設定に気をつける: extract-rulesは試行で50〜200のエージェントを起動し、大きな実行の前には確認が入ります。多数の書き込みエージェントを同時に走らせる工程(upliftの手順5bとreimagineのフェーズE)では、Bashを確認付きの権限モードに保ちます。
• 安価なモデルでリトライを重ねるとコストが逆転する: 複数回の安価な試行が1回の高価な試行のコストを上回ることがあります。試行(パイロット)中にリトライ率を分析します。

トークンコストを左右する4つの要因

トークンコストの主な要因は4つあります。コードベースのうち読む部分と変更する部分の比率。証明書がどれだけ厳格か(規制環境では検証のコスト比率が書く作業より大きくなるのが通常)。証明書が要求する新規テスト作成・テスト修復の量。実行中に他チームがマージしてくる調整作業の量です。

見積りの実務は、コードベースの小さな部分で近代化を終えた時点のトークン使用量を計測し、残りの実行を外挿する方法です。試行(パイロット)では見えない要素(稼働中のコードベース上での調整作業など)は未知数として扱い、これでフル近代化のコストの下限を見積もります。

同じ計測は、どこを最適化すべきかも示します。最もトークンを消費した部分を効率化し、計算コストの高い検証シグナルは安価なチェックが通った後段に回します。証明書が機械的に全チェックする高ボリュームな作業にはコストと能力のバランスが良いSonnetのようなモデルを使い、難しい変換や敵対的レビューにはより知的なモデルを取っておきます。安価なモデルが証明書を満たせないときは、より高価なモデルへエスカレーションできます。

Claude Codeの安全網づくりと同じ発想がエンタープライズ規模でも効く

証明書と昇格ポリシーは、個人開発でのリファクタリングと同じ論理を組織スケールに引き延ばしたものです。検証手段を先に用意してからClaudeに任せるという原則は規模が変わっても崩れません。変わるのは、証明書を誰が設計し、誰がその根拠でマージを承認するかという合意形成の重さだけです。

近代化が終わった後に残る成果物は、近代化されたコードベースだけではありません。ワークフロー・証明書・昇格ポリシー・証拠トレイルは、いずれも次のアップグレードや書き換えに転用できる資産になります。Anthropicのforward deployed engineersは顧客の重要システムでこれらのステップを一緒に進めており、このプレイブックは、顧客の導入現場での経験をもとにまとめられた手順です。COBOLのような長期稼働システムを抱える日本企業の基幹システムでも、ターゲット・証明書・昇格ポリシーを先に文書化する順番は同じ形で当てはまります。

まとめ

AI駆動のコード近代化を検討する組織が最初に決めるべきは、コードそのものではありません。ターゲットの種類、証明書の合否基準、昇格ポリシーの階層、そして4つの領域にまたがる前提条件です。これらを近代化チーム・SME・セキュリティ担当が着手前に合意しておくほど、エージェント型ワークフローをスケールさせた後のレビューは軽くなります。小さな部分での試行でトークンコストとワークフローの穴を洗い出してからフルコードベースへ進む、という順序も共通しています。Claude Codeでの個別リファクタリングと同じ「検証を先に固定する」発想を、組織的な合意形成のレイヤーまで含めて設計する点が、この準備手順の本質です。