AI 主導のコード モダナイゼーションプロジェクトの準備方法
重要システムや規制対象の企業向けの AI 主導のモダナイゼーションプロジェクトを組織する方法。
フィールドからのメモシリーズでは、Anthropic の前向きな導入を行ったエンジニアが、実際のお客様の導入からインスピレーションを得たベストプラクティスを共有します。 この記事では、大規模なコードの最新化プロジェクトを管理した経験を共有します。
かつては複数年にわたる範囲に及んでいたコードの最新化は、今では数か月（または数週間）で完了できますが、組織的な作業は多くの場合で同じままです。
たとえば重要な銀行システムに対するすべての変更は、変更管理、レビュー、承認を経る必要があります。 規制当局、監査人、そしてビジネスが要求しているため、堅牢なプロセスです。
これらのプロセスこそが重要なシステムを信頼できるものにしており、各変更は人間が作成し、各差分を人間がレビューするという前提に基づいて構築されています。 エージェントが変更内容の作成を加速すれば、ボトルネックは変更内容の作成から組織の動員へと移行します。
この記事では、モダナイゼーションを実施する前に企業が行うべき作業について説明します。完了したことの意味、変更に伴うべきエビデンス、認証済みの変更が本番環境にどのように到達するか、運用を開始するために必要な内容を定義します。
このプロセスは以下の 6 つのステップに分かれています。
- ターゲットを定義します。つまり、モダナイゼーションされたコードに必要な技術スタックと動作です。
- 証明書を作成します。変更内容が目標の状態で正しいと判断されるために満たす必要のある条件です。
- プロモーションポリシーを設定します。これは、認定された変更が実装されるペースで本番環境に反映されるパスです。
- 環境、CI/CD、レビュー能力、承認といった前提条件を整えます。
- エージェントワークフローを構築し、改善します。カスタムの Claude Code 動的ワークフローでは変更を生み出す、多数の小規模な並行サブエージェントワークストリームに最新化を分散します。 これは目標、認定、プロモーションポリシーを中心に構築されています。
- 最新化の実行：コードベースの小さいパーティションでワークフローをエンドツーエンドで実証したうえで、拡張します。
ステップ 1：ターゲットを定義
目標は、近代化の最終状態です。 希望する最終状態によって、以下の表に詳述されている 3 つのモダナイゼーションのいずれを実行しているかが決まります。
モダナイゼーションのタイプを決定
どのタイプのモダナイゼーションを行うかを決定する問題は、組織内でしばしば議論されています。 私たちの経験から、本番環境に最も近い人たちは、リスクを抑制するために動作を一定に保つスタックを入れ替えたいと考えています（トランスフォーメーションの最新化）。 反対側にはコードベースをこれまで使用してきたエンジニアがおり、最新化によって技術的な負債を返済したいと考えています。また、新しい要件を定義する機会を得たい（最新化の再構築）他のビジネス関係者もいます。
どちらの立場も妥当ですが、この疑問が解決されないまま放置されると、与えられた変更が「正しい」かどうかを巡る議論として後で再び浮上します。 どの道を進むべきかについてコンセンサスを構築することは初期の摩擦を増やす一方で、プロジェクト全体を合理化します。
コードベースをマッピングし、動作仕様を作成
現在のシステムを理解することが、ターゲットを定義するうえで有効な第一歩であることが多いです。 古いコードが実際に何をしているのかを抽出し現在の動作を把握することで、パーツを変更または廃止すべきかどうかを簡単に判断でき、近代化が変革なのか、再構築なのかを簡単に判断できます。 また、未知のビジネスロジックやエッジケースを明らかにすることもよくあります。
Claude は、依存関係をマッピングしたり、誰も構築したことを覚えていないワークフローを文書化したりすることで、その発見の多くを行います。 コードモダナイゼーションプラグインの assess、map、extract-rules コマンドは、ソースの引用からビジネスルールを抽出し、エンジニアがレビューできるようにします。
ただし Claude の発見だけでは、レガシーシステムの動作を完全に把握できない場合があります。 ビジネスユーザーや開発者とのインタビューや内部文書化によって、これらのギャップを埋めることができます。 コンテキストの収集には事前に時間がかかる場合がありますが、そのコンテキストの質が、ワークフローがその後行うすべての決定を左右します。
再構築のためにターゲットを定義するには、追加の作業が必要です。詳細な動作仕様を書き留め、ユーザーグループと合意する必要があります。
プロジェクトの正当性と目標を確立
目標を定義するだけでなく、組織はモダナイゼーションに着手する価値がある理由を検討する必要があります。 レガシーシステムの近代化は、継続的なメンテナンスと運用コストを削減できます。しかし私たちの経験から言えば、ほとんどの近代化プロジェクトではコスト削減が目標ではありません。
“リスクの低減は多くの場合、モダナイゼーションにおける最も重要なメリットです。 プロジェクトを継続するかどうかを検討する際には、モダナイゼーションを行わないリスクを考慮してください。”
たとえばパッチが適用されていない脆弱性を抱えるシステムは、サイバー侵害やビジネス自体をリスクにさらすほど深刻なシステム停止を意味する可能性があります。 サポートされていないランタイムや、システムを理解するエンジニアの減少がリスクを悪化させます。
Claude Code などのエージェントコーディングツールは、モダナイゼーションのスケジュールを短縮しましたが、予算を見積もるのが依然として困難であり、慣性につながっています。 大規模なモダナイゼーションの一部のコストを、他のものと同様に公表しました。 これらは大まかな基準として使用でき、このガイドの下部に予算見通しに関する追加のガイダンスがあります。
これらのプロジェクトを開始するにあたっての主な課題は、通常、システムを所有するチームやそれに依存するチームから内部の合意とコミットメントを構築することです。 ビジネスケースを構築し、プロジェクトの目標を設定することが多く、リーダーシップレベルで行うことで、プロセスのこの部分が容易になります。 これは、認定証とそれに伴うプロモーションポリシーにおいて、トレードオフを確実にするための手段でもあります。 変更がどれくらいのリスクを抱えるかについて利害関係者の間で意見が一致しない場合、最新化されないリスクがその相対効果となります。
ステップ 2：証明書を定義
証明書とは、すべてのモダナイゼーションの変更が満たす必要がある一連の条件やテストです。 目標に対して変更が正しいものであることを示す、最も強力な累積的証拠を提供する条件を選択します。
各条件は人間が介在しなくても確認できる必要があります。そのためエージェントのワークフローは、証明書を満たすまで変更を繰り返し実行したり、満たない場合は人による確認のためにフラグを立てることができます。
証明書に記載される内容はターゲットによって異なりますが、通常はこのリストから抽出されます。
- 元のテストスイートが合格
- モダナイゼーション期間中に作成された Claude のテストはすべて合格
- テストカバレッジが合意された閾値を満たす
- パフォーマンスベンチマークは、合意された範囲内で維持
- Claude による独立した敵対的レビューはそれぞれが新しいコンテキストウィンドウで行われ、ブロックする問題は一切ありません。
- ユーザーインターフェースでは、Claude 主導のコンピューターの使用において後退はありません。
- 現行バージョンとターゲットバージョンは同じ入力から同じ出力を生成し、ライブ、記録、Claude 生成のいずれかで、
- 持続的な状態とワイヤーフォーマットを現行バージョンとターゲットバージョン間で往復する
- 変更は合意された期間にわたってステージングされ、エラー率、レイテンシー、アラートが低下することはありません。
- 静的な分析とセキュリティスキャンでは、新しい発見は見つかりません。
- コンパイルされたターゲットでは、ビルドがクリーンでチェックパスと入力
“変更をレビューし、本番環境に反映する人たちと認定書を作成します。 証明書とエージェントのワークフローをまだ設計中である間に、現在コードベースに依存する開発者、ユーザーグループ、ビジネスリードを呼び込みましょう。”
彼らの専門知識が認定の測定基準を左右し、変更がレビューに至ったときに彼らの早期の関与が支持を得る要因となります。 完成した証明書を確認する上で、証明書の証拠だけをマージすることに慣れているかどうかを確認します。 自社のバーが記載されている場合、ステップ 3 のプロモーションポリシーを緩和できる可能性があります。
証明書が何を基準にどのように基準を満たすかは、最新化のタイプによって異なります。
- アップグレードの最新化では、パリティが元のコードベースと比較し、元のテストスイートを証明書の中核にすることができます。
- トランスフォーメーションの最新化では、パリティが元のコードベースにも対応しますが、元のテストスイートが新しいスタックで実行されることはめったにありません。 本番環境のトラフィックのリプレイ、旧旧と新との差分テスト、実運用並行の導入が、代わりに作業の大部分を処理します。
- 最新化の再構築に向けて、この認定書は動作仕様に反映されています。 これは最も難しいケースです。 仕様は既存のシステムと比べて客観性が低いため、より幅広いモデル判断が必要となり、結果が変動する可能性があります。 ここでは、証明書は仕様書から書かれたテスト、各変更を sec と照合して確認する Claude による独立した対抗的レビュー、新しいシステムが旧システムの動作を維持する差分チェックに依存しています。 仕様が明確になったときに証明書の改訂を期待します。仕様のギャップが最初にここに表示されます。
古いシステムではテストカバレッジが薄く、テストが不規則で、テレメトリがほとんど行われていないことがよくあります。 証明書の定義の一部は、これらの問題点を特定することです。 強力な証明書のサポートが難しい場合、このステップで最も有用なことの 1 つは、Claude を使用して、不足している証拠を構築することです。つまり、実稼働を並行するセットアップ、リプレイハーネスの構築、テストをさらに作成することです。
ステップ 3：プロモーションポリシーを設定
エージェントは人間のチームが相違点ごとにレビューできるよりも、はるかに迅速に変更を作成します。 プロモーションポリシーは、事前に文書化され合意された段階的なレビューパスであり、変更に対する人的レビューの深さを定めることで、許容可能なスケジュールで最新化を完了できるようにします。
認定書と同様に、このステップもレビュー担当者と連携し、組織の既存の変更管理プロセスに可能な限り適合させてください。 詳細は組織や直面するリスクのトレードオフによって異なりますが、いくつかのルールがあらゆる場所で当てはまります。
- 影響範囲とエージェントの信頼性による階層の変化。 組織独自の変更やリスク分類がある場合は、その使用をお試しください。 重要なパスについては、人的による全面的なレビューを継続すること。
- ソースで繰り返し発生するフラグを修正します。 時間の経過に伴うフラグを付け、変更をグループ化して分析します。 同じ種類のフラグが繰り返し発生する場合は、個々をレビューするのではなく、エージェントのワークフローや証明書で原因を修正してください。
- レビューアと出力形式を設計します。 どの情報とフォーマットが最も迅速にレビューを行うか、そしてどのシグナルが他のシグナルよりも信頼性があるかについて合意します。 ステップ 5 で初期のサンプル出力をレビューしてもらいます。
- SME の時間を効果的に配分します。 中小企業は最終的な diff をすべて読むわけではありませんが、彼らの判断は依然として不足している情報です。 大規模な差分を踏むことなく、リスクの最も高いティアでの変更や、各ティア内でフラグを付けられたエージェントの意思決定にすぐに移行できるようにします。 その後、専門家が少数の時間を使って、最もリスクの高い変更に対応します。
これらのルールの多くは、プロジェクトの初期段階で SME を巻き込むことで、前倒しの時間を要しています。 完全な近代化が始まる前に、彼らのフィードバックによって証明書とエージェントのワークフローが調整されます。
サンプルに対する彼らの承認は、高い信頼度を持つ、より簡易なレビューパスを採用する正当性にもなります。 これは、レビューが最後に行われる従来の非エージェント型のパターンとは逆です。
プロモーションポリシーには、最新化がスピードとレビューの深さの間でどの程度位置にあるかを反映することも必要です。 実行時のサポートが失われるなど、厳しい期限に迫るモダナイゼーションではより簡易な人によるレビューを備えた迅速なポリシーと、変更ごとにより多くのリスクを受け入れる明確な合意が必要です。
より長いタイムラインで最新化を行うことで、より詳細な人的レビューとより迅速なカットオフが可能になります。 利害関係者はリスク選好度や制約に応じて、このスペクトルの異なるポイントに着目する可能性があるため、作業を始める前に確かめる価値があります。
規制された環境では、変更について人によるレビューがより軽いとされる場合、非常に不便な思いを招く可能性があります。 個々の承認者は悪い変更を招くリスクを抱えるため、承認を躊躇します。一方、経営陣はシステムの老朽化というリスクをより大きな負担をかけます。
私たちの経験からすると、プロモーションポリシーの指示は組織のトップから来るのが最善です。 また、事前に合意があると良いでしょう。そうすることで本番環境に到達したバグの責任を共有し、変更を承認した人たちに任せるのではありません。
“これらはいずれも実際の証拠として十分に詳細な証明書と、Claude がどのように変更に至ったかを信頼できるほど十分に理解しているレビューアに依存しています。”
ステップ 4：前提条件を整える
このステップの多くはホストを担当するプラットフォームやインフラストラクチャ、テスト容量を担当する QA やリリースエンジニアリング、セキュリティ、コンプライアンスを担当するなど、最新化の外部のチームを通じて行われます。 これらのチームにはそれぞれ独自のバックログや承認プロセスがあることが多いため、要件を特定したらすぐに、ステップ 1 から 3 がまだ進行中の場合が多いです。
環境
- Claude がアクセス可能なコードベースやその他の関連ソースで、ワークフローを実行する専用のリモートホスト
- 認定書に必要なテスト能力
- 認定を強化するあらゆるもの：本番環境のテレメトリ、本番環境での並行処理、再現用の本番環境データ
コードベースと CI/CD
- ビルドログとコンパイルログ、インポート分析、ランタイムトレースに基づいた、コードベースの依存関係マップ。 注：プラグインの map コマンドは良い出発点ですが、コードベースのサイズや経過時間によっては、より広範な事前作業が必要な場合があります。
- ターゲット定義の一部として、依存関係やパッケージを計画的に処理
- 必要に応じて CI/CD に追加できる互換性チェック
- 合意されたコードフリーズポリシー（モダナイゼーションを導入している場合）
- コードの凍結や新しい互換性要件を網羅したアクティブな開発者向けのコミュニケーションプラン
チームとレビュー
- コードベースに依存する他のチームと、認定証の承認やプロモーションポリシーに基づくレビューなど、参加方法について合意を得、レビュー担当者の時間を確保
セキュリティとコンプライアンス
- ソースコードが承認された Claude Code のモデルアクセスパス
- エージェントワークフロー向けの最小特権アクセス：最新化ブランチへの書き込みのみで、本番環境の認証情報は不要
- シークレットと PII を削除、またはマスクする、最新化ブランチ
- すべての変更を追跡可能で、PR はエージェントのトランスクリプトと証明書の証拠にリンク
- 新しい依存関係のライセンスと脆弱性のチェック
ステップ 5：エージェントワークフローを構築し、改善
Claude Code を使用して、コードベースを最新化するためのカスタマイズされた動的なワークフローを開発します。
コードの最新化プラグインから始め、ワークフローに必要なすべてのものをファイルシステムまたは Claude がアクセスできる MCP 上で配置することをお勧めします。 これにはターゲット、証明書、プロモーションポリシー、コードベース、ドキュメント、および証明書に必要なあらゆるデータソースやツールが含まれます。 この記事をコンテキストとして Claude に提供することもできます。 これがプロジェクトの中核的なナレッジベースを形成します。
これらが整えば、モダナイゼーションのワークフローを構築するのは簡単です。 必要に応じて、コードベース固有のスキルや抽出したルールなど、下流で利用する前に Claude の作業をレビューしてもらいます。
コードベースの小さな部分に適用して、構築したものを改良しましょう。中小企業は、それが生じる変更点、エージェントのプロセス、認定資格を満たした証拠をレビューします。
“問題が表面化した際は個々の変更ではなく、ワークフローを修正する必要があります。 目標は、スケールアップすれば変更内容がほぼすべての場所で認定書に適合し、レビュー担当者がプロモーションポリシーに沿って統合することに自信を持つことです。”
ステップ 6：モダナイゼーションを実行
まず、コードベースのごく一部でモダナイゼーションを完了します。これには、プロモーションポリシーを通じて変更内容をレビューして公開することも含まれます。 まだ安価なうちに動作しないものを修正し、自信があるまでこのプロセスを繰り返し、完全なコードベースにスケールします。
変革や再構築のモダナイゼーションには、既存のシステムと並行してターゲットを構築し、完了したら切り替えることが必要ですが、アップグレードには 2 番目のオプションがあります。開発を継続しながら、ライブのコードベースでモダナイズを進めることです。
システムがダウンできない場合や、コードベースが急速に変化し、最新のコピーを個別に保つことが困難な場合に、通常の選択肢です。 コードベースを論理的なパーティションに分割し、一度に 1 つのパーティションを固定して最新化し、新しいコミットが一度はパーティションが元に戻らないように CI/CD を適用しました。
コストに関するメモ
このようなモダナイゼーションのコストをトークン単位で把握できると、よく質問されます。 最新化の取り組みはそれぞれ異なりますが、主なコスト要因は次のとおりです。
- コードベースの読み取りと変更をどの程度行う必要があるか。
- 証明書の関与度（通常、変更内容を記述しない検証が、規制された環境では大きなシェアを占める）
- 新しいテストの作成とテストの修復に必要な額、および
- 実行中に、周囲のチームが統合することで、調整作業がどの程度行われているかを示します。
“コードベースのごく一部でモダナイゼーションを完了したら、トークンの使用状況を測定し、それを使用して残りの実行期間を推定します。 ライブコードベースでの調整など、パイロットが確認できなかったものは、未知のものとして扱います。 この方法で、完全な近代化の最低コストを見積もることができます。”
パイロット試験の測定結果からは、エージェントのワークフローをコスト面で最適化する箇所も示されます。 最もトークンを消費するワークフローの部分を見つけ、より効率的な方法を検討します。 計算負荷の高い検証シグナルを、より安価なゲートに移行し、より簡単なチェックに合格したときにのみ実行できるようにします。
認定書が完全に検証する、機械的で大量の作業において、コストと能力のバランスを保った Sonnet のようなモデルの使用を検討してください。 ハードトランスフォーメーションや、正確性を検証する敵対的レビュー向けに、よりインテリジェントなモデルを維持します。
安価なモデルが証明書を満たしていない場合には、より高価なモデルにエスカレーションすることもできます。ただし高価なモデルを複数回使用する可能性があるため、パイロット運用の際には再試行率を慎重に分析します。 ワークフローとパイロットデータの両方にアクセスできる Claude が、この分析の多くをお客様と協力して行えるようになります。
モダナイゼーションを超えて
最新化されたコードベースは 1 つの出力です。 その他には、それを実現したワークフロー、正しい内容を証明する書面による証明書、変更管理プロセスがすでに受け入れているプロモーションポリシー、実施されたすべての変更の証拠証跡があります。 再利用可能な資産としてプレイブックを整理することで、次のアップグレードや書き直しに向けてパターンをすでに整理できます。
フロントに配備されたエンジニアは、お客様に最も重要なシステムとともにこれらのステップをお客様と連携します。 モダナイゼーションを準備している場合は、当社のチームにお問い合わせください。