← Back to Blog
Journal

レガシーシステムにClaude Codeを適用するコツ――文脈・安全網・段階的移行

· Yuki Tachi
Claude CodeレガシーシステムAIリファクタリング技術的負債開発フロー

はじめに

長年動き続けているシステムにこそ、改修のニーズは集中します。ドキュメントは古く、テストはなく、当時の判断理由は退職した誰かの頭の中にしかない――そんなコードベースにAIエージェントを持ち込むとき、何から手をつければよいのでしょうか。

本記事では、Anthropicのコーディングエージェント「Claude Code」を、レガシーシステムの保守・改修に適用するための実践的なコツを整理します。新規プロジェクトとは異なるレガシー特有の難しさを踏まえたうえで、(1) 暗黙知をCLAUDE.mdに書き出す、(2) 特性化テストで安全網を張る、(3) 探索と実装を分けて段階的に移行する、という三つの軸で解説します。本テーマは技術トピックのため、査読付き論文ではなく公式ドキュメント・一次資料・公的統計を中心に裏付けます。

背景・課題

まず、レガシー保守がいかに開発リソースを食っているかを確認します。米政府説明責任局(GAO)は2019年の報告書で、連邦政府が年間900億ドル超をITに投じ、その大半が老朽化したシステムを含む既存システムの運用・保守に使われていると指摘しました(GAO, 2019)。同報告書が「最も重要」と特定した10システムは8〜51年前のもので、サポート切れのハードウェアや既知の脆弱性を抱えたまま稼働していました(GAO, 2019)。

開発者個人の時間という観点でも傾向は同じです。Stripeが2018年に公表した調査「The Developer Coefficient」によれば、平均41.1時間の週あたり労働のうち、技術的負債への対応に13.5時間、質の低いコードの修正に3.8時間が費やされ、世界全体で年間約850億ドルの機会損失に相当するとされています(Stripe, 2018)。

レガシーシステムが難しいのは、単に古いからではありません。「変更すると何が壊れるか分からない」点にあります。Michael Feathersは著書『Working Effectively with Legacy Code』で、レガシーコードを端的に「テストのないコード」と定義しました(Feathers, 2004)。テストがなければ、変更が既存の振る舞いを壊していないかを機械的に確認できません。AIエージェントは大量のコードを高速に書き換えられますが、検証手段がなければ、その速さはそのまま「速く壊す」リスクに変わります。

本論

CLAUDE.md に「コードから読み取れない知識」を書き出す

Claude Codeは会話の冒頭でCLAUDE.mdという特別なファイルを読み込み、プロジェクト固有の文脈として扱います(Anthropic, 2026a)。レガシーシステムでは、ここに何を書くかが効きます。公式ドキュメントは、CLAUDE.mdに含めるべきものとして「コードを読んでも推測できないBashコマンド」「既定と異なるコードスタイル」「テスト手順と推奨テストランナー」「プロジェクト固有のアーキテクチャ上の決定」「開発環境の癖(必要な環境変数など)」「非自明な落とし穴」を挙げています(Anthropic, 2026a)。

レガシーコードはまさに「コードを読んでも分からない事情」の宝庫です。なぜこの順序でしか起動しないのか、どのモジュールに触れてはいけないのか、ビルドに必要な隠れた前提は何か――こうした暗黙知を明文化することは、AIのためであると同時に、人間にとっての引き継ぎ資料にもなります。ただし公式ドキュメントは「長すぎるCLAUDE.mdは肝心の指示が埋もれて無視される」とも警告しており、各行について「これを消したらClaudeが間違えるか?」を基準に削るよう勧めています(Anthropic, 2026a)。

特性化テストで「壊していない」を検証可能にする

Claude Codeのベストプラクティスの第一は「Claudeに自分の作業を検証する手段を与える」ことです。公式ドキュメントは「Claudeは作業が完了したように見えると止まる。検証手段がなければ『完了に見える』が唯一の信号になり、あなたが検証ループそのものになってしまう」と述べ、テスト・ビルド・スクリーンショット比較など、合否を返す仕組みを与えるよう求めています(Anthropic, 2026a)。

しかしレガシーコードにはテストがありません。ここで有効なのが特性化テスト(characterization test)です。これはFeathersが示した手法で、「コードが何をすべきか」ではなく「現に何をしているか」を記録するテストを指します(Feathers, 2004)。たとえ現在の出力が直感に反していても、それを正解として固定し、変更後も同じ振る舞いが保たれることを確認します。まず現状の振る舞いを安全網として固定し、その網の内側で改修を進める――この順序が、AIによる大胆な書き換えを安全に行うための前提になります。実際、Claudeに「失敗するテストでバグを再現してから直す」よう指示する手法も、公式ドキュメントが推奨する型の一つです(Anthropic, 2026a)。

探索→計画→実装を分け、段階的に移行する

Claude Codeの推奨ワークフローは「探索→計画→実装→コミット」の四段階です(Anthropic, 2026a)。まずプランモードでコードを読ませて理解させ、次に変更計画を立てさせ、それからコードを書かせる、という分離です。公式ドキュメントは「いきなりコーディングさせると、間違った問題を解くコードが生まれうる」とし、複数ファイルにまたがる変更や、自分が不慣れなコードを触るときほど計画フェーズが有効だとしています(Anthropic, 2026a)。レガシー改修はまさにこの条件に当てはまります。

探索フェーズでは、サブエージェントの活用が効きます。Claudeがコードベースを調査すると大量のファイルを読み、その内容が文脈(コンテキストウィンドウ)を圧迫します。サブエージェントは別の文脈で調査を行い要約だけを返すため、主たる会話を汚さずに「認証はどう実装されているか」「再利用できるユーティリティはあるか」を調べさせられます(Anthropic, 2026a)。大規模な移行では、対象ファイルを一覧化し、非対話モード(claude -p)でファイルごとにループ処理する「ファンアウト」も示されています(Anthropic, 2026a)。いずれも、巨大なレガシーを一度に飲み込ませず、小さく分割して進めるという原則の現れです。

実践への応用・考察

ここまでを実務の手順に落とすと、次のようになります。第一に、最初の数日はコードを書かせず、Claudeに「このシステムはどう動いているか」を質問して回るオンボーディングに充てる。公式ドキュメントも、新しいコードベースでは同僚のエンジニアに尋ねるような質問(ログはどう動くか、なぜこの関数を呼ぶのか)をそのままClaudeに投げる使い方を勧めています(Anthropic, 2026a)。第二に、理解した内容をCLAUDE.mdに蓄積する。第三に、改修したい箇所に特性化テストを張り、その安全網の中で段階的に変更する。

筆者の経験では、レガシー改修におけるAIの価値は「速くコードを書くこと」よりも「読むコストを下げること」にあります。数万行の中から関連箇所を探し、git履歴から「なぜこうなっているか」を要約させる作業は、人間が手で追うより圧倒的に速いと感じます。一方で、検証手段のないままAIに大規模な書き換えを任せるのは危険です。公式ドキュメントが挙げる失敗パターンの一つ「信頼するが検証しない(trust-then-verify gap)」――もっともらしい実装がエッジケースを取りこぼす――は、テストの薄いレガシーでこそ顕在化しやすいと考えられます(Anthropic, 2026a)。便利さと検証コストはトレードオフであり、安全網を先に張るという順序を省かないことが、レガシーにAIを入れる際の肝になります。

まとめ

  • レガシー保守は開発リソースを大きく消費する(GAO: 連邦IT予算の大半が運用・保守、Stripe: 開発者の週の約4割が技術的負債と低品質コードへの対応)。
  • レガシーの本質的な難しさは「テストがなく、変更の影響が読めない」ことにある(Feathers, 2004)。
  • CLAUDE.mdにコードから読み取れない暗黙知を書き出すと、AIと人間双方の引き継ぎ資料になる。ただし長くしすぎない。
  • 特性化テストで現状の振る舞いを安全網として固定し、その内側で改修する。
  • 探索→計画→実装を分け、サブエージェントやファンアウトで巨大なコードを小さく分割して進める。

まずは一つのモジュールを選び、「Claudeに動作を質問する→特性化テストを書かせる→小さく改修させる」という最小ループを回してみてください。AIの速さを安全に活かす鍵は、書く前に「検証できる状態」を作っておくことにあります。

参考文献

公式ドキュメント

政府・公的資料

  • U.S. Government Accountability Office. (2019). Information Technology: Agencies Need to Develop Modernization Plans for Critical Legacy Systems (GAO-19-471). 2026年6月閲覧. https://www.gao.gov/products/gao-19-471

調査レポート・Web記事

書籍

  • Feathers, M. C. (2004). Working Effectively with Legacy Code. Prentice Hall.
← Back to Blog