技術情報

Claude Code などのAIツールで既存システムを改修する:棚卸し・テスト・段階的な置き換え・レビュー

Claude Code のようなAIコーディングツールは既存システムの改修やリファクタリングに使えますが、順番を逆にしてはいけません。まずAIの力を借りてコードとデータの流れを棚卸しし、次にテストで現在の挙動を固定し、そのうえでモジュールを一つずつ置き換え、すべての変更は人がレビューしてからマージします。本記事では開発チームの立場から、この4つのステップの進め方、AIに任せられないこと、そして JoinX がソースコードをAIツールに入れる際の実際の運用と制約を説明します。

執筆 JoinX 創業者兼CEO公開 約12分で読めます
Claude Code などのAIツールで既存システムを改修する:棚卸し・テスト・段階的な置き換え・レビュー

この記事の要点

  • 既存システムの改修にAIコーディングツールを使うときの順番は、棚卸し、テストによる安全網、段階的な置き換え、人によるレビューです。AIにいきなり書き直させることはできません。
  • AIが最も役立つのは古いコードの読解、データの流れの整理、テストの追加ですが、どの不自然な分岐が業務ルールでどれが不具合かは、人と利用者が確認します。
  • コードを変える前にテストで現在の挙動を固定し、テストに通らない変更はマージしない。これが改修で事故を起こさない鍵です。
  • JoinX の開発プロセスは SDD + TDD です。変更する挙動をまず仕様に書き、テストで検証し、AIが生成したコードも人が書いたコードと同じレビューを通します。
  • JoinX はソースコードを法人向けのAIツールに入れており、契約上データはモデルの学習に使われません。パスワード、鍵、個人情報はAIツールに入れません。全工程でAIを使わないという要望には対応できず、協業前にその旨をお伝えします。
目次

既存システムは Claude Code のようなAIコーディングツールで改修できますが、順番があります。まず棚卸しをし、テストによる安全網を作り、段階的に置き換え、すべての変更を人がレビューしてからマージします。 最初の2ステップを飛ばしてAIに旧システムを一気に書き直させると、よくある結果は、見た目はきれいでも、旧システムが長年積み重ねてきた例外ルールが抜け落ちたコードです。以下では開発チームの立場から、各ステップでAIができること、人が責任を持つこと、そして JoinX のAIツールの実際の使い方を説明します。

AIコーディングツールは既存システムの改修に向いているのか?

向いています。ただしその価値は、改修をより網羅的にし抜け漏れを減らすことにあり、人がコードを読む量を減らすことではありません。既存システムのリスクは見えないルールにあり、AIはそれを見つけてテストにするのを助け、最終判断は人が行います。

Claude Code はターミナル上で動くAIコーディングツールで、プロジェクト全体を読み、コードを検索し、コマンドやテストを実行し、指示に従ってファイルを編集できます。エディタ内で1行を補完するだけのツールと違い、ファイルをまたいだ関係を把握できるため、改修前の棚卸しや改修中のリファクタリングに特に向いています。

ただし、既存システムは新規プロジェクトとは違います。新規プロジェクトの仕様は要件文書にありますが、既存システムの仕様の多くは、コード、データ、そしてベテラン社員の記憶の中にしかありません。Michael Feathers は『Working Effectively with Legacy Code』で、レガシーコードを「テストのないコード」と定義しています。テストがなければ、変更で何かを壊したかどうかを確かめられないからです。AIツールがコードを速く変えられるほど、このリスクは大きくなるため、ツールそのものより順番のほうが重要です。

改修の前に、AIは既存システムの棚卸しをどう手伝えるのか?

AIはコードベース全体を短時間で読み、モジュール、データの流れ、外部連携、高リスク箇所を整理できるため、チームは手を入れる前にシステムの全体像をつかめます。棚卸しの結果はエンジニアと利用者が確認するもので、そのまま仕様にはしません。

棚卸しでは、次の項目の整理をAIに手伝ってもらい、エンジニアが一つずつ確認します。

  • モジュールと依存関係: どのモジュールが互いに呼び出し、どれが同じテーブルを共有し、一か所の変更がどこに波及するか。
  • データの流れ: 1件の注文や伝票が作成から完了までにどのプログラムとテーブルを通るか。
  • 外部連携: ERP、決済、アカウントシステムなどとデータをやり取りする箇所と形式。
  • 高リスク箇所: テストがない、ロジックが極端に長い、最近不具合が多い、日付や金額のルールがハードコードされている箇所。
  • 業務ルールらしきもの: 不自然に見える条件分岐を一覧にし、ルールなのか不具合なのかを利用者に確認してもらいます。

最も重要なのは最後の項目です。AIは分岐が「不自然」だとは分かりますが、それが10年前の大口顧客との特別契約なのか、当時の不具合なのかは分かりません。この一覧は実際にシステムを使っている社員に確認し、答えを仕様に書き戻します。引き継ぎ時の棚卸し項目の全体は、既存システムの引き継ぎ・リファクタリング・再構築の完全ガイドをご覧ください。

なぜコードを変える前にテストの安全網を作るのか?

テストは「変更後も挙動が変わっていない」ことを証明できる唯一の方法だからです。テストで現在の挙動を固定しておけば、人でもAIでも、テストに通らない変更はマージしないというルールで改修のリスクを抑えられます。

古いシステムにはテストがまったくないことがよくあります。このとき最初に書くのは理想的な単体テストではなく、「特性テスト」(characterization test)です。システムが今実際に出力している結果を記録し、基準とします。今の挙動が間違っていても、まずはそのまま記録し、不具合と確認できてから別途修正します。リファクタリングと不具合修正を同じ変更に混ぜないためです。

AIはこうしたテストの作成に向いています。計算ロジックを読み解いたうえで境界条件を挙げ、テストデータとテストケースを生成できます。ただし何をテストするかは、業務上のリスクに基づいてエンジニアが決めます。会計、権限、在庫のように誤りの代償が大きい処理を優先し、画面レイアウトのように問題が目に見えやすい部分は後回しにできます。テストデータは必ず架空のデータか匿名化したデータを使い、実際の顧客の個人情報は使いません。

SDD + TDD で旧モジュールを段階的に置き換えるには?

モジュールを一つずつ置き換え、それぞれ仕様、テスト、コードの順に進め、新旧を並行稼働させて一致を確認してから切り替えます。段階的に置き換えることで改修中もシステムは使い続けられ、問題が起きても影響は一部にとどまります。

JoinX の開発プロセスは SDD + TDD です。SDD(仕様駆動開発)で変更する挙動をまず仕様に書き、TDD(テスト駆動開発)でコードが仕様を満たしているかをテストで検証します。既存システムの改修では、各モジュールを次の手順で進めます。

  1. 最初のモジュールを選ぶ。 境界が明確で、テストが書けて、誤りの影響範囲を抑えられるモジュールを選びます。最初から中核の会計には手を付けません。
  2. 仕様を書く。 棚卸しの結果と利用者が確認したルールを仕様にまとめ、例外と残すべき旧挙動も含めます。
  3. テストを追加する。 仕様に沿ってテストを書き、旧コードですべて通ることを確認して、テストが現在の挙動を表していることを証明します。
  4. 実装を置き換える。 エンジニアがタスクを分解し、AIが新しいコードの生成を手伝い、同じテストがすべて通るまで繰り返します。
  5. 新旧を並行稼働させる。 必要に応じて新旧のモジュールに同じデータを処理させ、結果が一致してからトラフィックを切り替えます。
  6. 人のレビューを経てマージする。 レビューが通り、テストがすべて通り、デプロイに切り戻し手順があって初めてマージしてリリースします。

Martin Fowler は『Refactoring』で、リファクタリングとは「外部の振る舞いを変えない小さな変更」の積み重ねであり、各ステップがテストで守られていなければならないと強調しています。AIで一歩一歩は速くなりますが、そのせいで一歩を大きくしてはいけません。一度の変更が小さいほど、レビューで見通せます。

AIが生成したコードはどうレビューするのか?

人が書いたコードと同じレビューを通し、AIが書いたからといって基準を下げません。レビューの重点は、ルールが残っているか、権限やデータアクセスが変わっていないか、依存パッケージが信頼できるかで、いずれも担当エンジニアが承認します。

レビュー項目AIが手伝えること人が判断すること
ルールが残っているか新旧コードの分岐の差分を比較し、抜けている可能性のある条件を挙げる各差分が意図した変更か抜け漏れかを確認する
テストは十分かテストで網羅されていないコードパスを指摘し、境界ケースを追加する必ずテストすべきリスクと許容できるリスクを決める
権限とデータアクセス新規・変更されたクエリ、項目、権限チェックを洗い出す権限外のアクセスがなく、個人情報へのアクセスが規定に沿っていることを確認する
依存パッケージ新しく追加されたパッケージとバージョン、既知の脆弱性を挙げる採用するかを決め、ライセンス条件を確認する
性能と互換性大量のクエリやループになりそうな箇所を見つける実際のデータ量で検証し、既存データとの互換性を確認する
デプロイと切り戻し変更一覧と設定の差分をまとめるリリースの時間帯と切り戻し手順を承認する

米国 NIST のセキュアソフトウェア開発フレームワーク(SP 800-218)は、コードを誰が書いたかにかかわらず、コードレビュー、脆弱性チェック、サードパーティ製コンポーネントの管理を基本要件としています。JoinX は納品前にソースコードスキャンと脆弱性スキャンを自社で実施し、ブラックボックステストが必要な場合は第三者に委託します。JoinX は委託先との連絡や業者の推薦をお手伝いし、見つかった脆弱性を修正してから納品します。

ソースコードをAIツールに入れるとき、データの安全はどう守るのか?

JoinX はソースコードをAIツールに入れています。法人向けプランを使い、契約上お客様のデータはモデルの学習に使われません。パスワード、鍵、個人情報などの機密情報は入れません。これらは協業前にご説明します。

具体的には次の4点です。

  • ソースコードはAIツールに入れます。 棚卸し、テストの追加、リファクタリングにはAIがコードを読む必要があり、これが私たちの実際のやり方で、隠すことはしません。
  • 法人向けプランを使い、モデルの学習には使わせません。 法人向けまたは商用プランのAIツールを使っており、契約や利用規約上、お客様のデータがモデルの学習に使われることはありません。
  • 機密データはAIツールに入れません。 パスワード、APIキー、証明書、本番環境の接続設定、個人情報はAIツールに入れず、テストには架空のデータか匿名化したデータを使います。個人情報は台湾の「個人資料保護法」に沿って取り扱います。
  • 全工程でAIを使わない対応はできません。 私たちの開発プロセスはAIとの協働を前提にしているため、プロジェクト全体でAIを一切使わないという要望には対応できません。見積もりと契約の前にその旨をお伝えし、先に引き受けてから対応を考えることはしません。

お客様に独自のAI利用ポリシーがある場合、たとえば特定のディレクトリを外部ツールに入れない、指定のサービスを使うといった条件は、協業前に範囲を一緒に確認できます。

この記事は、AI協働開発や既存システム引き継ぎの記事とどう違うのか?

この記事が扱うのは一つだけです。既存システムを改修するときに、AIコーディングツールを安全に使う方法です。AI協働開発の全体の流れやコスト構造、既存システムを引き継ぐかどうかの判断は、それぞれ別の記事で説明しています。

知りたいことおすすめの記事
AI協働開発の全体の流れと人とAIの分担AI協働開発で30%コストを削減できる理由:JoinX の実際のプロセス
AI協働開発でコストと品質を両立する方法AI協働開発とは?コストを抑えながら品質を高める方法
保守されていないシステムを引き継ぐか、リファクタリングか、再構築か既存システムの引き継ぎ・リファクタリング・再構築の完全ガイド
既存システムの改修でAIツールを安全に使う方法本記事

よくある質問

自社のシステムは古く、技術も時代遅れです。AIツールで理解できますか?

ほとんどの場合、理解できます。主要なAIコーディングツールは ASP.NET、PHP、Java などのよく使われてきた技術を読め、文書のないコードの整理も手伝えます。ただしコードが読めることとルールの由来が分かることは別なので、棚卸しで出た疑問点は利用者に確認する必要があります。

プロジェクト全体でAIを一切使わないよう求めることはできますか?

JoinX では対応できません。私たちの開発プロセスはAIとの協働を前提にしており、AIを外して別のプロセスで納品することはできません。御社のポリシーで全工程でのAI不使用が求められる場合は、協業前にその旨をお伝えし、先に引き受けることはしません。

ソースコードをAIツールに入れると、モデルの学習に使われますか?

JoinX は法人向けまたは商用プランのAIツールを使っており、契約や利用規約上、お客様のデータがモデルの学習に使われることはありません。パスワード、鍵、個人情報などの機密情報は、一切AIツールに入れません。

テストがまったくないシステムは、どこから改修を始めればよいですか?

特性テストの追加から始めます。会計計算や権限判定など、最も重要な処理の現在の挙動をまずテストとして記録し、それからコードを変更します。テストの追加自体が改修の一部であり、AIはこのステップを速めるのに役立ちます。

AIツールを使った改修の費用と期間はどう見積もりますか?

まず棚卸しを行い、モジュールごとに見積もります。JoinX が手がけてきた案件では、初期のコードとシステムの診断は約5万〜20万台湾ドル、単一モジュールのリファクタリングは約50万〜200万台湾ドルです。AIツールで棚卸しとテストはより網羅的になりますが、これらのステップを省くことはできません。

参考資料

  • Working Effectively with Legacy Code(邦題:レガシーコード改善ガイド)Michael Feathers、Prentice Hall
  • Refactoring: Improving the Design of Existing Code(邦題:リファクタリング)Martin Fowler、Addison-Wesley
  • NIST SP 800-218 Secure Software Development Framework (SSDF)米国国立標準技術研究所(NIST)
  • 個人資料保護法台湾 法務部
  • Claude Code 公式ドキュメントAnthropic

上記は執筆時点で引用した法令・資料です。改正される場合がありますので、実際の適用は所管官庁の最新の公告をご確認ください。

シェアLINEFacebookXLinkedIn
ブログ一覧へ

著者について

李秉哲(Jack Lee)

JoinX 創業者兼CEO

2016年にJoinXを創業。台湾と日本にまたがる80名以上のチームを率い、220社以上のお客様に520件以上のプロジェクト(うち中・大規模システム56件)を提供してきました。

関連記事