レガシーコードにAIを放っても何も壊さない方法

典型的なシナリオを想像してみてください。5年分の歴史を持つプロジェクトを継承し、ドキュメントは存在せず、元のコード著者は3年前に去り、ビジネスロジックは数百のファイルに散らばっています。Claude CodeやCursorのようなAIエージェントをこのようなコードベースに接続するのは恐ろしいことです。1つの関数を修正するよう依頼すると、隣接するモジュールを書き換えて、誰も知らなかった暗黙の依存関係を破壊してしまいます。

最近、GitHubにsandecoという開発者が作成したReversaという興味深いツールが登場しました。このフレームワークは独自の方法でこの問題を解決します：レガシープロジェクトに深く潜り、リバースエンジニアリングを実行し、ソースコードを実行可能な仕様に変換します。

なぜコードを仕様書に置き換えるのか

ほとんどのコーディングエージェントは、ゼロからプロジェクトを作成することに優れています。プロンプトを書くと、クリーンな構造と動作するコードを生成します。この手はレガシーコードでは通用しません。エージェントがアーキテクチャの制約とコンテキストを理解していなければ、盲目的に動作します。

Reversaは古いコードと最新のAIアシスタントの間の架け橋として機能します。このツールは традиционном意义上 の人間のためのドキュメントを書くのではありません。代わりに、実行可能なコントラクトを生成します。これらに基づいて、任意のコーディングエージェントは、ゲームのルール、データベーステーブル、権限マトリックス、および違反してはならないアルゴリズムを即座に確認できます。

リサーチプロセスの仕組み

インストールはプロジェクトルートで単一のコマンドを実行します：

npx reversa install

インストーラーはシステム内のインストール済みエンジンを自動的に検出します — Cursor、Claude Code、Codex、Windsurf、またはCopilot。その後、スキルセットを .agents/skills/ ディレクトリにコピーし、構成ファイルを作成します。

AIクライアント内で /reversa コマンドを実行すると、複数の specialized agents のパイプラインが起動します。各エージェントは分析プロセスで各自の役割を実行します：

• Scout は表面構造をスキャンし、言語、フレームワーク、エントリーポイントを特定します。
• Archaeologist はモジュールに深く潜り、データ構造と複雑なアルゴリズムを解析します。
• Detective は暗黙的なビジネスルール、状態図、アクセスルールを抽出します。
• Architect は収集したデータをC4ダイアグラム、ERDスキーマ、統合マップにコンパイルします。
• Writer は最終仕様をコードの特定の行へのバインディングを持つコントラクトとしてフォーマットします。

興味深い詳細：Reversaは最終ドキュメントの各ステートメントに特別な精度バッジを付与します。🟢アイコンは、ファイルと行の参照を持つコードで直接裏付けされたルールを意味します。🟡アイコンは、AIが論理的推論を行った場所に配置されます。赤いマーカー🔴は、コードが何かを説明できなかった「空白部分」を示し、人間の介入が必要です。

デフォルトで安全

複雑なリポジトリの上で自動化されたユーティリティを起動する際の主な恐怖は、データの損失または偶発的な編集です。Reversaの作成者は完全な分離を強調しました。

このフレームワークは厳格なルールに従います：分析中にプロジェクトのソースコードが変更または削除されることは決してありません。すべての結果はエージェントによって2つのサービスフォルダにのみ書き込まれます：分析状態用の .reversa/ と、完成した仕様用の _reversa_sdd/ です。

さらに、このツールはAPIキーを要求または送信することはしません。すべての分析作業はあなたがローカルで既に実行しているAIツールにオフロードされます。

データ抽出後に何が起こるか

仕様の作成は最初のステップに過ぎません。生成された _reversa_sdd/ フォルダに基づいて、追加のコマンドで他のワークフローを起動できます。

• /reversa-forward はシステムを段階的に進化させ、回帰制御を伴う新しい要件を作業コードに変換します。
• /reversa-migrate はレガシースタックを最新アーキテクチャに移行する計画を準備します。
• /reversa-docs は収集したデータをインタラクティブなD3グラフと3Dアーキテクチャマップを持つ静的HTMLサイトにコンパイルします。
• /reversa-debugger はバグを登録し、仕様に対して因果的にリンクします。

定常的な停止や確認なしでフルサイクルを実行する必要がある場合は、自律モード /reversa-autonomous があります。このモードでは、ユーティリティは起動時のインタビュー中にすべての明確化質問を行い、その後独立して動作します。

結果はどこに保存されるか

_reversa_sdd/ フォルダ内では、Markdownファイルの明確な構造が現れます。そこにはデータ辞書、ドメインの説明、ロールマトリックス、OpenAPI仕様、Mermaid形式のシーケンスダイアグラムが見つかります。

_reversa_sdd/
├── inventory.md              # Инвентаризация файлов
├── dependencies.md           # Зависимости и версии
├── code-analysis.md          # Помодульный технический анализ
├── data-dictionary.md        # Словарь данных
├── domain.md                 # Бизнес-правила и глоссарий
├── state-machines.md         # Конечные автоматы в формате Mermaid
├── architecture.md           # Обзор архитектуры
├── confidence-report.md      # Отчет о точности анализа 
└── sdd/                      # Спецификации отдельных компонентов

システム改良中に /reversa-forward を使用してコードを変更すると、特別なSyncエージェントが変更履歴を保持しながら新しい機能に関する情報を _reversa_sdd/addenda/ フォルダに慎重に追加します。

採用する価値はあるか

Reversaは、AIにレガシープロジェクトの混沌をもたらす前に整理を試みる成熟したアプローチのように見えます。このプロジェクトは積極的に開発されており、2026年5月のarXivでの最近のプレプリントは、フレームワークのアーキテクチャを学術的なアプローチで裏付けています。

このツールは、ドキュメントなしで放置されたサービスを継承したチームや、古いスタックからの段階的な移行を計画しているチームに役立ちます。既存のファイルを変更しないため、任意のテストリポジトリでユーティリティを試すことができます。

クイックスタートとして、ターミナルで npx reversa install を実行し、通常のAIエディタでプロジェクトを開くだけです。