リバースエンジニアリング Claude Codeで設計書を復元する手順

Claude Codeで行うリバースエンジニアリングとは

ソフトウェアのリバースエンジニアリングは、完成したコードや動作を手がかりに、構造・処理・データの流れを理解し直す作業です。Claude Codeを使う場合は、ソースコードを読ませて「何が書かれているか」を説明させ、ファイル名や行番号などの根拠と一緒に設計情報へ変換します。

目的は、いきなり改修コードを生成することではありません。まずは次のような問いに答えられる状態を作ります。

• どの画面、API、バッチが処理の入口なのか
• 入口から認証、検証、業務ロジック、保存、通知まで何を経由するのか
• どのデータベースや外部サービスに依存しているのか
• コードから確認できない仕様や、追加調査が必要な箇所はどこか

Anthropicの公式概要でも、Claude Codeはコードベースを読み取り、複数ファイルをまたいで作業できるツールと説明されています。対象を自分が管理するリポジトリや、利用許可を得たコードに限定し、契約・ライセンス・秘密情報の扱いも先に確認してください。

出典: https://code.claude.com/docs/ja/overview

先に作るべき成果物は「説明」ではなく根拠付きの地図

「このシステムを説明して」とだけ頼むと、もっともらしい概要で終わりがちです。先に成果物の形を指定すると、調査の抜けを見つけやすくなります。

設計書には、図だけでなく「どのファイルを読んで判断したか」を残します。たとえば「ログイン処理は認証サービスが担当」と書くなら、src/auth/login.ts:42 のように入口を併記します。行番号は改修で変わるため、関数名やコミットIDも添えると後から追跡しやすくなります。

作業前に読み取り専用の境界を作る

調査段階で最も避けたいのは、理解が足りないままコードや設定を変更することです。作業用ブランチ、複製したリポジトリ、またはバックアップを用意し、秘密鍵・本番接続情報・個人情報を読み取り対象から外します。必要ならサンプル設定やマスキング済みデータに置き換えてください。

Claude Codeには変更前にファイルを読むPlan Modeがあります。公式ベストプラクティスでは、探索、計画、実装を分ける流れと、Plan Modeで変更せずにファイルを調べる方法が案内されています。調査だけなら次のように開始します。

claude --permission-mode plan

さらに、プロジェクト直下の CLAUDE.md に「調査中は編集しない」「推測には未確認と書く」「回答に根拠ファイルを付ける」「秘密情報を表示しない」といったルールを置くと、毎回の指示を短くできます。読み取り専用でも、外部サービスへ接続するMCPやシェルコマンドを追加する場合は、対象と権限を確認してください。

出典: https://code.claude.com/docs/ja/best-practices 出典: https://code.claude.com/docs/ja/security 出典: https://code.claude.com/docs/ja/memory

5段階で進める手順

1. 全体を棚卸しする。 リポジトリのディレクトリ、使用言語、フレームワーク、起動コマンド、設定ファイル、テストの場所、外部サービスを列挙させます。この段階では編集を禁止し、見つからない情報も「不明」と記録します。
2. 対象の入口を一つ選ぶ。 画面、API、バッチなどから一つに絞り、「入口から最終出力までの呼び出し順を、ファイル・関数・行番号付きで示す」と頼みます。いきなり全機能を追うより、具体的な一経路から始める方が誤読を検証しやすいです。
3. 構造とデータの地図にする。 モジュールの責務、依存方向、データの変換、外部APIとの境界を docs/reverse-engineering/ に分けて出力させます。architecture.md、modules.md、flows/<機能名>.md のように用途別にすると、後の更新箇所が明確になります。
4. 実コードと照合する。 主要な説明ごとに定義元、呼び出し元、テスト、ログ、設定の少なくとも一つを確認させます。実行できるテストやローカルのサンプル入力があるなら使い、結果と説明が一致するかを比べます。
5. 確度を付けて引き継ぐ。 「確認済み」「コードからの推定」「未確認」の3分類で設計書を見直し、未確認事項と追加で聞くべき質問を最後にまとめます。調査用の資料と改修用の指示を分けてコミットすると、後から内容が混ざりません。

そのまま使えるプロンプト例

最初の指示は、目的、調査範囲、禁止事項、出力形式を一つにまとめます。

このリポジトリをリバースエンジニアリングしてください。
まだファイルを編集せず、読み取りと検索だけを行ってください。
1. 使用言語・フレームワーク・起動方法
2. ディレクトリごとの責務と主要な入口
3. 主要機能「ユーザー登録」の入力から保存までの処理フロー
4. 関係するファイル、関数名、行番号
5. コードだけでは判断できない点
を、確認済み・推定・未確認に分けて Markdown で出力してください。

特定の処理を深掘りするときは、対象を狭くします。

src/orders/checkout.ts の checkout 関数について調査してください。
呼び出し元、入力の検証、在庫確認、決済、DB保存、通知の順番を追跡し、
各説明にファイルパスと関数名を付けてください。存在しない処理は補わず、
分からない箇所は「未確認」と書いてください。コードは変更しないでください。

最後に、第三者の目で誤りを探させます。「この設計書の各主張を実装上の根拠へ対応付け、根拠が不足する説明、循環依存、実行経路の飛躍を一覧にしてください」と依頼すると、説明の体裁だけでは見えない穴を拾えます。

失敗しやすい進め方と改善策

よくある失敗は、リポジトリ全体を一度に説明させて終わることです。コンテキストが埋まると重要な前提が薄れ、一般的な構成を実際のコードに当てはめた説明が混ざります。公式のベストプラクティスも、調査範囲を分け、具体的なファイルや制約をプロンプトで示す方法を勧めています。

もう一つは、出力された行番号や仕様を検証しないことです。Qiitaの実践記事でも、コードベースの構造把握や処理フロー整理は速い一方、行番号や業務ロジックの解釈は実コードとの照合が必要だと報告されています。

インフラの復元では、一般的な設定を優先してしまう問題もあります。AWS環境をCDKへ変換した事例では、特殊なCIDR配置が一般的な順序に置き換わり、通信できない状態になったと説明されています。珍しい設定、手動運用、例外的な命名は「特殊だから無視」せず、実際の設定値と一緒に明示しましょう。

出典: https://qiita.com/ryo_cresc/items/8d03bf0d9b4ee0a3c10b 出典: https://note.com/nyle_engineer/n/n3e024ba94225

設計書化した後にできることと限界

根拠付きの資料ができると、引き継ぎ、影響範囲の初期調査、テスト項目の洗い出し、改修前のレビューに再利用できます。Qiitaの別の実践例では、ソースコードからシステム概要、アーキテクチャ、API仕様、データ構造、セキュリティ、デプロイ手順を含む設計書を作る流れが紹介されています。

ただし、コードから業務上の意図まで完全に復元できるわけではありません。仕様書にない判断基準、運用担当者だけが知る例外、外部サービスの契約条件は、担当者への確認や実データを使わない検証で補います。設計書は完成品ではなく、根拠と未確認事項を持つ調査記録として更新するのが安全です。

調査後に改修へ進む場合も、いきなり大規模変更を依頼せず、対象範囲、変更しない範囲、テスト方法、ロールバック方法を別に合意します。読み解く作業と書き換える作業を分離することで、誤った理解をそのまま本番変更へ持ち込むリスクを抑えられます。

出典: https://qiita.com/yamaguchi37/items/7e3903dd18a0ecfe016c

まとめ

Claude Codeでのリバースエンジニアリングは、既存コードを丸ごと要約させる作業ではありません。読み取り専用で全体を棚卸しし、入口ごとの処理を根拠付きで追跡し、推測と確認済みの事実を分けて設計書へ残す流れが基本です。最後は人がコード、テスト、運用知識を照合し、保守に使える資料へ更新してください。