原典: How to prepare for AI-driven code modernization projects
一行要約
エージェントが変更を書く速さが上がると、ボトルネックは変更を作ることから、組織をそれに合わせて動かすことへ移る。だから実行の前に 目標（何をもって完了か）・証明書（変更が持つべき証拠）・昇格の方針（証明された変更が本番に届く道）・前提 を決め、小さな区画で端から端まで通してから広げる。
要点
ボトルネックが移る
Those processes are what make critical systems trustworthy, and they were built on the assumption that a human wrote each change and a human would review each diff. Once agents accelerate writing the changes, the bottleneck shifts from producing changes to mobilizing the organization around them.
そうした手続きこそが重要なシステムを信頼できるものにしており、それは人が各変更を書き、人が各 diff をレビューするという前提で作られている。エージェントが変更を書くのを速めると、ボトルネックは変更を作ることから、組織をそれらの周りに動かすことへ移る。
6つの手順
- 目標を決める —— 移行の種類を決める。uplift（同じスタックの版上げ。C++11 → C++20）、transform（振る舞いを固定したまま別スタックへ。COBOL → Java）、reimagine（新しいアーキテクチャで振る舞いも変える。書かれた振る舞いの仕様が要る）。本番に近い人は transform を、長く付き合ってきたエンジニアや事業側は reimagine を望みがち —— 決めずにおくと、後で個々の変更が「正しいか」の議論として再燃する。現行の振る舞いを Claude に洗い出させる（依存の地図、誰も作った覚えのない手順）が、Claude の発見だけでは足りず、業務ユーザーと開発者へのインタビューで埋める。移行の一番の理由はたいていコスト削減ではなくリスク削減
- 証明書を決める —— すべての変更が満たすべき条件。各条件は人を介さずに確かめられるものにし、ワークフローが満たすまで繰り返すか、満たせなければ人のレビューに回す。候補: 元のテストが通る、Claude が書いたテストが通る、カバレッジ、性能の範囲、新しい context での Claude の独立した敵対的レビュー、UI なら computer use で回帰なし、新旧で同じ入力に同じ出力、状態とワイヤ形式の往復、staging での一定期間、静的解析とセキュリティスキャン、ビルドと型。レビューし昇格させる人と一緒に書き、「この証拠だけでマージしてよいと思えるか」で確かめる。古いシステムでテストが薄いなら、欠けた証拠（本番並行の仕組み、リプレイ、テスト）を Claude に作らせる
- 昇格の方針を決める —— エージェントは人が diff ごとにレビューできるよりずっと速く変更を出すので、変更ごとの人のレビューの深さを段階で決める（影響範囲とエージェントの確信度で分け、重要な経路は人が全部見る）。同じ種類の指摘が繰り返されたら、1件ずつレビューするのではなくワークフローか証明書の原因を直す。専門家（SME）の時間は最も希少なので、最もリスクの高い段と、その中で印の付いたエージェントの判断に直行できるようにする。レビューを最後に置く従来の形の逆で、SME の時間を前に寄せる。規制のある環境では、方針の指示を組織のトップから出し、事前に合意しておく —— 本番に漏れたバグの責任が、それを承認した個人に押し付けられないように
- 前提を整える —— 専用のリモートホスト、テストの容量、依存の地図、コードフリーズの方針、他チームとの合意、ソースコードに承認された Claude Code へのモデルアクセス、最小権限（移行ブランチにだけ書けて本番の資格情報は無い）、秘密と PII の除去、すべての変更をエージェントの transcript と証明書の証拠に結びつける
- エージェントのワークフローを作り、磨く —— Claude Code で dynamic workflow を作る（code modernization plugin から始める）。目標・証明書・昇格の方針・コードベース・ドキュメントを、ファイルシステムか MCP で Claude が届く所に置く。問題が出たら個々の変更ではなくワークフローを直す
- 実行する —— まずコードベースの小さな部分で端から端まで（昇格の方針を通して実際に取り込むまで）通し、安いうちに直し、確信が持てたら全体へ広げる。稼働中のコードで in-place の uplift をするなら、葉から内側へ区画に分け、1区画ずつ凍結して移行し、CI/CD で移行済みの区画が戻されないようにする
費用
主な要因は、読む量と変える量の比、証明書の重さ（規制のある環境では、変更を書くより検証のほうがたいてい大きい）、テストの新規作成と修正、実行中に他チームがマージしてくる分の突き合わせ。小さな区画でトークン使用量を測って外挿し、パイロットで見えなかったもの（稼働中のコードでの突き合わせなど）は未知として扱う。
- 重い検証は安い検査の後ろに置き、易しい検査が通ってから走らせる
- 証明書が完全に確かめる機械的で量の多い作業は Sonnet のような釣り合いの取れたモデルに、難しい変換と正しさを確かめる敵対的レビューは賢いモデルに
- 安いモデルが証明書を満たせないときに高いモデルへ上げてよいが、パイロットで再試行率をよく見る —— 安い試行を何回も重ねると、高い1回より高くつくことがある
成果物はコードだけではない —— それを生んだワークフロー、何を正しいとするかの書かれた証明書、変更管理の手続きが受け入れた昇格の方針、取り込まれた全変更の証拠の跡。次の更新や書き直しのために再利用できる手順として残す。
そのまま使える具体例
証明書の候補（原典の一覧から選ぶ）:
- 元のテストスイートが通る / 移行中に Claude が書いたテストが通る
- カバレッジが合意した閾値以上 / 性能ベンチマークが合意した範囲内
- 新しい context window で走る Claude の独立した敵対的レビューが、止めるべき問題を見つけない
- UI なら Claude の computer use で回帰が無い
- 新旧の版が同じ入力（本番・記録・Claude が生成）に同じ出力を返す
- 永続化された状態とワイヤ形式が新旧の間で往復する
- staging で合意した期間、エラー率・遅延・アラートに回帰が無い
- 静的解析とセキュリティスキャンに新しい指摘が無い / ビルドがきれいで型が通る
原典で言及されている関連文書
- ai-code-migration — 数週間で終わった大規模移行（原典のリンク先）