AI開発フロー / 記事解説
AIでコードを近代化する前に、組織で決めておく6つのこと
AIエージェントを使えば、何年もかかると見積もられていたレガシーコードの近代化が数か月で終わることもあります。ただし、変更管理・レビュー・承認といった組織側の手続きは速くなりません。コードを書く速さが上がるほど、全体の速さは組織の準備で決まるようになります。Anthropicの実践記事をもとに、着手前に決めておくことを6つのステップに整理しました。
ボトルネックは「書くこと」から「組織を動かすこと」へ移る
銀行の勘定系のような重要システムでは、どんな小さな変更も変更管理のプロセスを通り、レビューと承認を経て本番に入ります。この仕組みは規制当局・監査・事業部門が求めるもので、システムが信頼される理由そのものです。
ところが、この仕組みは「人が1件ずつ変更を書き、人が1件ずつ差分を読む」ことを前提に作られています。エージェントが大量の変更を短時間で作るようになると、詰まるのはコードを書く工程ではなく、その変更を受け入れる組織の側です。
元記事は、この詰まりを解消するために近代化の作業を始める前に決めておくべきことを整理しています。完了の定義、変更が示すべき証拠、合格した変更を本番へ届ける経路、そして作業開始に必要な準備です。
6ステップの全体像
元記事は準備を6つのステップに分けています。前半の3つで「何を作り、何をもって正しいとし、どう本番に入れるか」を決め、4つ目で環境と承認をそろえ、後半の2つで実際にエージェントを動かします。
図は左から右への順番を示していますが、実際には完全な直列ではありません。④の前提づくりは他チームへの依頼が多く時間がかかるため、①〜③を進めながら必要なものが見えた時点で依頼を始めます。また、⑥の試行で問題が見つかったら、変更を1件ずつ手で直すのではなく、合格基準やワークフローの側を直します。この「仕組みの側を直す」という考え方は、記事全体を通して繰り返し出てきます。
このページでは用語を次のように訳しています。
| 訳語 | 原語 | 意味 |
|---|---|---|
| 到達点 | target | 近代化後のコードが採用する技術スタックと、持つべき振る舞い |
| 合格基準 | certificate | すべての変更が満たすべき条件の集まり。人が介在せずに判定できるもの |
| 本番反映ルール | promotion policy | 合格した変更が、どの深さのレビューを経て本番に入るかを定めた取り決め |
| 専門家 | SME(subject matter expert) | 業務やシステムを深く理解している人。時間が最も限られた資源になる |
| 影響範囲 | blast radius | その変更が壊れたときに被害が及ぶ範囲 |
① 到達点を決める Define the target
到達点とは、近代化が終わったときの姿です。どんな姿を目指すかによって、近代化は次の3種類に分かれます。後ろの種類ほど、決めておくことが増えます。
| 類型 | 中身 | 選ぶ場面 | 到達点として決めるもの |
|---|---|---|---|
| 引き上げ Uplift | 同じ技術スタックのままバージョンを上げる(例:C++11 → C++20) | スタック自体に不満はないが、サポート切れのランタイム、未修正の脆弱性、上げられない依存関係などでバージョンが取り残されている | ランタイムのバージョンと、使うパッケージの組み合わせ |
| 載せ替え Transform | 振る舞いは変えずに別のスタックへ書き直す(例:COBOL → Java) | スタックそのものが問題で、今の振る舞いは信頼できる | 引き上げの内容に加えて、言語・フレームワーク・新しいコードが従う設計規約 |
| 作り直し Reimagine | 新しいアーキテクチャでゼロから作り、振る舞いも変える | コードと一緒に振る舞いも変える必要がある | 載せ替えの内容に加えて、新システムの振る舞いを文章にした仕様書 |
類型は早めに合意しておく
どの類型にするかは、社内で意見が割れやすいところです。本番運用に近い人ほど、リスクを抑えるために「振る舞いはそのまま、スタックだけ替える」載せ替えを望みます。一方、長年そのコードと付き合ってきた開発者は技術的負債も一緒に返したいと考え、事業部門はこの機会に新しい要件を入れたいと考えます。こちらは作り直しに近い立場です。
どちらにも理があります。ただし、ここを曖昧にしたまま進めると、あとで個々の変更について「これは正しいのか」という議論として何度も蒸し返されます。最初に合意を取る手間はかかりますが、プロジェクト全体はそのほうが速く進みます。
現行システムを棚卸しする
到達点を決める最初の一歩は、今のシステムが実際に何をしているかを把握することです。振る舞いを一覧にすると、どこを残し、どこを変え、どこを捨てるかを判断しやすくなり、載せ替えと作り直しのどちらになるかも見えてきます。誰も覚えていない業務ロジックや例外処理が見つかることもよくあります。
この調査の多くはClaudeに任せられます。公式のcode-modernizationプラグインには、現状を評価する assess、依存関係を地図にする map、業務ルールを抽出する extract-rules といったコマンドがあり、抽出したルールには根拠となるソースの場所が付くので、エンジニアが確認できます。
レガシーシステムの振る舞いは、コードを読むだけでは把握しきれないことがあります。業務ユーザーや開発者へのヒアリング、社内文書で穴を埋めます。最初に時間はかかりますが、ここで集めた文脈の質が、後でワークフローが下すすべての判断の質を決めます。作り直しの場合は、さらに詳しい振る舞いの仕様書を書き、利用者のグループと合意しておきます。
「なぜやるのか」を言葉にする
到達点と並んで、そもそもなぜ近代化するのかも整理しておきます。保守や運用のコストが下がる効果はありますが、元記事の経験では、コスト削減が主な動機になった案件は多くありません。
やるかどうかを議論するときは、やらなかった場合のリスクを天秤に載せます。未修正の脆弱性を抱えたシステムは、事業そのものを揺るがす侵害や障害につながり得ます。サポートが切れたランタイムや、そのシステムを理解している技術者の減少は、このリスクをさらに大きくします。
② 合格基準を決める Create the certificate
合格基準とは、近代化で生まれるすべての変更が満たすべき条件やテストの集まりです。「この変更は到達点に照らして正しい」と言える証拠が、全体として最も強くなるように条件を選びます。
大事なのは、どの条件も人が介在せずに判定できることです。そうすれば、エージェントのワークフローは基準を満たすまで自分で変更を作り直し、どうしても満たせないものだけを人に回せます。
条件の候補
何を入れるかは到達点によって変わりますが、たいていは次の中から選ぶことになります。
テスト
- 既存のテストスイートが通る
- 近代化の途中でClaudeが書いたテストがすべて通る
- カバレッジが合意した水準を満たす
- 性能ベンチマークが合意した範囲に収まる
新旧の一致
- 同じ入力に対して新旧が同じ出力を返す(入力は本番のもの、記録したもの、Claudeが生成したもののいずれか)
- 保存データや通信フォーマットを新旧で読み書きしても崩れない
レビューと解析
- 毎回新しい文脈で起動したClaudeによる独立した批判的レビューで、ブロッカーが見つからない
- 画面がある場合、Claudeが実際に操作して退行が見つからない
- 静的解析とセキュリティスキャンで新しい指摘が出ない
- コンパイル言語ならビルドと型チェックがクリーン
運用での確認
- 合意した期間ステージングで動かし、エラー率・レイテンシ・アラートに悪化がない
今そのコードに依存している開発者、利用者のグループ、事業責任者を、合格基準とワークフローを設計している段階から巻き込みます。彼らの知見が「何を測るべきか」を形づくり、早く関わってもらうことが、後で変更をレビューするときの納得につながります。出来上がった基準は「この証拠だけでマージしてよいと思えるか」を彼らに問うことで確かめます。自分たちの基準がそこに反映されていると感じてもらえれば、次の本番反映ルールを軽くできます。
類型ごとに「何と比べるか」が変わる
| 類型 | 比べる相手 | 中心になる証拠 | 難しさ |
|---|---|---|---|
| 引き上げ | 元のコード | 既存のテストスイートをそのまま基準の核にできる | 比較的やりやすい |
| 載せ替え | 元のコード | 既存テストは新しいスタックでは動かないことが多い。本番トラフィックの再生、新旧の差分テスト、本番と並行稼働させた比較が主役になる | 比較の仕組みを作る手間がかかる |
| 作り直し | 振る舞いの仕様書 | 仕様書から書いたテスト、仕様に照らしたClaudeの独立レビュー、振る舞いを引き継ぐ部分での新旧差分チェック | 最も難しい。既存システムと違って仕様書は解釈の余地があり、モデルの判断に頼る部分が増えて結果がぶれやすい。仕様の穴はまずここで見つかるので、基準も仕様と一緒に改訂していく前提で進める |
証拠が足りなければ、先に証拠を作る
古いシステムは、テストが少ない、不安定なテストが多い、テレメトリがほとんどない、ということがよくあります。合格基準を考える過程で、こうした穴を洗い出すこと自体がこのステップの仕事です。強い基準を支えられそうにないなら、Claudeを使って足りない証拠を作るのが一番効果的です。本番並行環境を立てる、リプレイの仕組みを作る、テストを書き足す、といった作業です。
合格基準についての会話
③ 本番反映ルールを決める Set the promotion policy
エージェントは、人のチームが1件ずつ差分を読める速さをはるかに超えて変更を作ります。本番反映ルールは、変更ごとに人のレビューをどこまで深くするかを階層で決め、事前に文書化して合意しておく取り決めです。これがあることで、近代化を現実的な期間で終わらせられます。
合格基準と同じく、このステップもレビューする人たちと一緒に進め、できるだけ既存の変更管理プロセスに組み込みます。細部は組織やリスクの事情で変わりますが、次の4つはどこでも通用します。
影響範囲とエージェントの確信度で階層を分ける
組織に独自の変更区分やリスク区分があれば、それを使います。重要な経路は、必ず人がしっかりレビューする階層に残します。
繰り返し出るフラグは発生源で直す
人に回された変更を集めて傾向を分析します。同じ種類のフラグが何度も出るなら、1件ずつレビューするのではなく、ワークフローか合格基準の側で原因を直します。
レビューしやすい出力形式をレビュー担当と決める
どの情報をどんな形で見せればレビューが最も速いか、どんな証拠なら安心できるかを担当者と決めます。⑤の段階で、実際の出力サンプルを早めに見てもらいます。
専門家の時間を一番リスクの高いところに使う
専門家がすべての差分を読むことはできませんが、その判断は最も貴重な資源です。高リスク階層の変更と、各階層でエージェントが判断に迷った箇所へ、大きな差分をかき分けずに直接たどり着けるようにします。そうすれば、少ない時間で最もリスクの高い変更をカバーできます。
これらのルールの多くは、専門家の時間をプロジェクトの前半に使うものです。彼らのフィードバックで、本番の近代化を始める前に合格基準とワークフローを調整します。サンプルへの承認は、確信度が高い変更のレビューを軽くしてよい根拠にもなります。レビューを最後にまとめて行う従来のやり方とは、ちょうど逆の順番です。
図の読み方は左から右です。人が関わるのは、右側の3階層のレビューと、下段の「人へフラグ」の2か所だけです。下段の点線が示すように、フラグで見つかった問題は、同じ種類が繰り返し出るなら個別に直さず、合格基準やワークフローへ戻して発生源をつぶします。図は流れの骨組みだけを表しており、ステージングでの並行稼働期間や承認者の割り当てといった各社の手続きは含めていません。
速さとレビューの深さ、どちらに寄せるか
本番反映ルールには、そのプロジェクトが「速さ」と「レビューの深さ」のどこに位置するかも反映させます。関係者のリスク許容度や制約によって落としどころは変わるので、作業開始前に確定させておきます。
速さ寄り
ランタイムのサポート終了など動かせない期限がある場合。人のレビューを軽くし、1件あたりのリスクが大きくなることを明示的に受け入れる。
深さ寄り
期間に余裕がある場合。人のレビューを深くし、切り替えもゆっくり進められる。
方針はトップから示し、責任は共有する
規制の厳しい環境では、レビューを軽くすることへの抵抗が強く出ます。承認者個人は悪い変更を通すリスクを背負い、経営層は古いシステムを抱え続けるリスクを背負っていて、両者の見ているリスクがずれているからです。元記事は、この方針を組織のトップから出し、事前に合意しておくことを勧めています。そうすれば、不具合が出ても責任は組織全体で持つことになり、承認した個人のせいにはなりません。
ここまでの仕組みはすべて、本当の証拠として通用するほど詳しい合格基準と、Claudeがどうやってその変更にたどり着いたかを理解して信頼できるレビュー担当がいることを前提にしています。
本番反映ルールについての会話
④ 前提をそろえる Put the prerequisites in place
このステップの多くは、近代化チームの外を通ります。実行ホストはプラットフォームやインフラのチーム、テスト環境はQAやリリースエンジニアリング、承認はセキュリティやコンプライアンスのチームです。それぞれに自分たちのバックログや承認手続きがあるので、必要なものがわかった時点で、①〜③の途中でも早めに相談を始めます。
環境
- ワークフロー専用のリモートホスト。コードベースや関連する情報源にClaudeが届く
- 合格基準が求めるだけのテスト実行能力
- 基準を強くするもの:本番テレメトリ、本番並行環境、リプレイ用の本番データ
コードベースとCI/CD
- 依存関係の地図。ビルドやコンパイルのログ、import解析、実行時トレースに基づくもの。プラグインの
mapは出発点で、古く大きなコードベースでは追加の作業が要る - 依存パッケージの扱い方(到達点の一部として決める)
- 必要なら、CI/CDに入れる互換性チェック
- その場で近代化するならコード凍結の方針
- 凍結や新しい互換性要件を、開発中のメンバーへ伝える計画
チームとレビュー
- コードベースに依存する他チームが、どう関わるかの合意(合格基準の承認、本番反映ルールに沿ったレビューなど)
- レビュー担当の時間の確保
セキュリティとコンプライアンス
- ソースコードを扱うことが承認された、Claude Codeからのモデル利用経路
- 最小権限:書き込みは近代化用ブランチのみ、本番の認証情報は持たせない
- 近代化用ブランチから秘密情報や個人情報を除去またはマスク
- すべての変更とPRを、エージェントの作業記録と合格基準の証拠にひも付けて追跡できる
- 新しく入る依存関係のライセンスと脆弱性のチェック
⑤ エージェントのワークフローを作り、調整する Build and refine the agentic workflow
Claude Codeで、そのコードベース専用のdynamic workflowを作ります。近代化の作業を小さな単位に分け、多数のサブエージェントに並列で処理させる仕組みです。
進め方の要点は3つです。
- 知識ベースを置く:code-modernizationプラグインを出発点に、①〜③で決めたこと、コード、ドキュメント、判定用のデータやツールを、ファイルシステムかMCP経由でClaudeが読める場所にまとめる
- 土台を専門家が確認する:抽出した業務ルールやコードベース固有のスキルは、それを使う処理を動かす前に確認してもらう
- 小さな範囲で調整する:変更そのものに加えて、エージェントの作業過程と合格基準の証拠まで専門家に見てもらう
問題が見つかったら、その変更を手で直すのではなくワークフローを修正します。目指すのは、規模を広げたときに、ほぼすべての変更が合格基準を満たし、レビュー担当が本番反映ルールに沿って安心してマージできる、という確信を得ることです。
⑥ 小さく回してから広げる Run the modernization
まずコードベースの一部分で、近代化を最初から最後まで通します。本番反映ルールに沿ったレビューと本番への反映まで含めて、です。うまくいかないところは、直すコストが小さいうちに直します。確信が持てるまでこれを繰り返してから、コードベース全体へ広げます。
進め方は2通り
| 進め方 | 使える類型 | 中身 | 向いている場面 |
|---|---|---|---|
| 並行して作り、切り替える | 載せ替え・作り直し(引き上げも可) | 既存システムの横で新しいものを作り、完成したら切り替える | 別のコピーを作って保てる場合 |
| その場で近代化する | 引き上げのみ | 開発が続いている本番のコードベースを、そのまま近代化していく | システムを止められない場合や、変更が速すぎて別コピーを追従させられない場合 |
その場で近代化する場合、元記事でうまくいったのは次のやり方です。
- コードベースを論理的な区画に分け、依存される側の末端(葉)から内側へ向かって順番を決める
- 区画を1つずつ凍結して近代化する
- CI/CDにゲートを設け、近代化が終わった区画を新しいコミットが元に戻せないようにする
コストの見積もり方
トークン代がどのくらいかかるかは案件ごとに違いますが、主に次の4つで決まります。
| 要因 | 内容 |
|---|---|
| 読む量と変える量 | コードベースのうち、読む必要がある部分と、実際に書き換える部分の割合 |
| 合格基準の重さ | 規制の厳しい環境では、変更を書くことより検証のほうがコストの大半を占めることが多い |
| テストの追加と修復 | 合格基準が求める新しいテストの作成と、壊れたテストの修復の量 |
| 並行開発との調整 | 作業中に他チームがマージしてくる変更との突き合わせ |
⑥の最初の小さな範囲でトークン使用量を測り、それを全体に外挿します。本番コードベースでの調整作業のように、パイロットでは見えなかったものは「未知」として扱います。こうして得られるのは、全体コストの下限の見積もりです。
パイロットの計測からコストを下げる
重い検証は、安いゲートの後ろに置く
トークンを最も使っている工程を見つけて効率化します。計算の重い検証は、安いチェックを通った変更にだけ実行されるよう、順番を後ろにします。
作業の性質でモデルを使い分ける
合格基準で完全に検証できる機械的で大量の作業には、Sonnetのようにコストと能力のバランスがよいモデルを使います。難しい変換や、正しさを確かめる批判的レビューには、より賢いモデルを残しておきます。
エスカレーションはリトライ率を見て決める
安いモデルが基準を満たせなかったときだけ高いモデルに上げる方法もあります。ただし、安いモデルで何度もやり直すと、高いモデル1回より高くつくことがあるので、パイロット中にリトライ率を注意深く分析します。ワークフローとパイロットのデータをClaudeに渡せば、この分析も一緒に進められます。
終わったあとに残るもの
近代化されたコードは、成果物の1つにすぎません。ほかにも次のものが残ります。
- そのコードを生み出したワークフロー
- 「何をもって正しいとするか」を文章にした合格基準
- 自社の変更管理プロセスがすでに受け入れた本番反映ルール
- 本番に入ったすべての変更についての証拠の記録
これらを再利用できる手順書としてまとめておけば、次のバージョンアップや書き直しのときには、同じ型がすでに手元にある状態から始められます。
まとめの会話
出典
このページは次の記事の内容を、日本語で読みやすいように再構成した解説です。逐語訳ではありません。正確な記述は原文を確認してください。
- 元記事:Jonah Ezekiel, Lexie Tonelli「How to prepare for AI-driven code modernization projects」Claude Blog, 2026-09-23
- code-modernization プラグイン(anthropics/claude-plugins-official)
- Introducing dynamic workflows in Claude Code
- AI code migration(大規模移行の事例とコスト)
- COBOL Modernization with AI: Breaking the Cost Barrier
- The AI-Native SDLC playbook
- Code modernization playbook