AI-DLC Workflow V2のReverse Engineering: 既存コードの「理解」を自動化する
「既存コードが数十万行あるんだけど、AI-DLC Workflow V2は本当にそこから始められるの？」。始められます。Reverse EngineeringステージがコードベースをCodeKB（コードナレッジベース）に変換し、後続のすべてのステージがその知識を前提に動きます。シリーズ第15回。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 15AI-DLC Workflow V2のReverse Engineering: 既存コードの「理解」を自動化する This article
1. はじめに
この記事はAI-DLC Workflow V2（以降V2）シリーズの第15回です。第10回 ではInception phase全体を概観し、Reverse Engineeringステージの位置づけと概要を紹介しました。今回はそのReverse Engineeringステージ（2.1）を深堀りし、生成されるCodeKBの構造と活用を詳しく見ていきます。
ここで重要なのは、V2がBrownfield（既存コードベースがある状態）に対して専用のステージと仕組みを持っている点です。起動時にBrownfieldかGreenfield（新規）かを自動判定し、Brownfieldであれば既存コード解析用のステージが走り、スペースレベルのCodeKBが構築され、後続ステージがその知識を前提に動作する。この一連の流れが組み込まれています。
2. なぜReverse Engineeringが必要か
Brownfieldプロジェクトでは、AIが既存コードの構造を理解していなければ、的外れな設計や既存パターンと矛盾するコードを生成するリスクがあります。
では、具体的にどのような課題があるか振り返りましょう。
- コンテキストの断片化: AIはプロンプトに含まれたコードしか見えない。プロジェクト全体のアーキテクチャ、依存関係、命名規則をプロンプトに詰め込むことは現実的ではない
- 暗黙知の喪失: ビルド設定、テスト戦略、デプロイ手順といった「コードに書かれていないが開発者が知っている情報」がAIに伝わらない
- 再利用のコスト: 毎回コードを読み直すのは、セッションが長くなりコストが増える。一度構造化すれば、後続の作業で再利用できる
V2のReverse Engineeringは、これらの課題に対して「コードベースを一度構造化して、永続的なCodeKBとして保持する」というアプローチを取ります。
3. パイプラインモードの動作
Reverse Engineeringは「パイプラインモード」で動作します。V2の4つのマルチエージェント構成（inline、subagent、pipeline、mob）のひとつで、2つのエージェントが順番に作業する直列構成です。
リンク1: Developer Agent（コードスキャン）
Developer Agentがコードベース全体をスキャンし、以下の観点で構造化された結果を返します。
- パッケージ構成とモジュールの役割
- ビルドシステム、設定ファイル、依存関係
- 外部・内部API（エンドポイント、契約、メソッド）
- フレームワーク、ライブラリとそのバージョン
- テストディレクトリ、テストフレームワーク、カバレッジ設定
- コード品質指標（linting、CI/CD、ドキュメント）
- 技術負債のシグナル
スキャンの範囲は「フルスキャン」と「フォーカススキャン」の2種類から選べます。フルスキャンはリポジトリ全体を対象とし、フォーカススキャンはそのインテントが対象とする領域のみをスキャンします。
リンク2: Architect Agent（統合とCodeKB化）
Architect Agentは、Developer Agentのスキャン結果を受け取り、9つの構造化されたアーティファクトとして整理します。パイプラインモードの設計上、最終リンク（Architect Agent）が
produces[]に宣言されたアーティファクトを完成させる責任を持ちます。このパイプライン構成により、スキャンの粒度（Developer Agentの仕事）とアーキテクチャ的な判断（Architect Agentの仕事）が分離されます。Developer Agentが「何があるか」を洗い出し、Architect Agentが「それはどういう構造か」を解釈します。
4. CodeKBの構造
Reverse Engineeringの成果物がCodeKBです。
aidlc/spaces/<スペース名>/codekb/<リポジトリ名>/ ディレクトリに格納され、9つのmarkdownファイルで構成されます。9つのアーティファクト
| ファイル名 | 内容 |
|---|---|
| business-overview.md | ビジネスドメイン、システムの目的、主要機能 |
| architecture.md | システムアーキテクチャ、設計パターン、コンポーネント関係（Mermaid図を含む） |
| code-structure.md | パッケージ/モジュール構成、ファイル分類、コードパターン |
| api-documentation.md | 外部・内部APIサーフェス、エンドポイント、契約 |
| component-inventory.md | コンポーネント一覧と責務・依存関係 |
| technology-stack.md | 言語、フレームワーク、ライブラリとバージョン |
| dependencies.md | 外部依存、内部クロスパッケージ依存 |
| code-quality-assessment.md | テストカバレッジ、lint設定、CI/CD、技術負債の評価 |
| reverse-engineering-timestamp.md | 実施日時、分析スコープ、フィンガープリント |
ディレクトリ構造
CodeKBはリポジトリ単位で格納されます。ディレクトリ名にはリポジトリ名が入ります（マルチリポジトリの場合、リポジトリごとに独立したCodeKBが作られます。詳細は§7で扱います）。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
aidlc/
└── spaces/
└── default/
└── codekb/
└── my-project/ # リポジトリ名
├── business-overview.md
├── architecture.md
├── code-structure.md
├── api-documentation.md
├── component-inventory.md
├── technology-stack.md
├── dependencies.md
├── code-quality-assessment.md
└── reverse-engineering-timestamp.mdここで重要なのは、CodeKBがスペースレベルの共有ストアである点です。特定のインテント（作業単位）に紐づくのではなく、同じスペース内の全インテントから参照できます。あるインテントでReverse Engineeringを実行すれば、次のインテントではそのCodeKBを再利用できるということです。
5. 鮮度チェックと再利用
CodeKBはスペースレベルのストアなので、同じリポジトリに対してReverse Engineeringが複数回実行される可能性があります。V2はこの状況に対して「鮮度チェック」の仕組みを持っています。
再実行時の判定フロー
新しいインテントでReverse Engineeringが実行されると、まず既存のCodeKBの状態を確認します。判定は
codekb-scope-diffユーティリティが行います。判定結果は以下の4種類です。
| 判定 | 意味 | 選択肢 |
|---|---|---|
| NO_STORE | このリポジトリのCodeKBが存在しない | スキャンを実行（選択不要） |
| CURRENT | 分析済みパスに変更がない。最新の状態 | 再利用 / フルスキャン / フォーカススキャン |
| STALE | 分析済みパスが前回のスキャン以降に変更されている | フルスキャン / フォーカススキャン |
| UNVERIFIED | 鮮度を検証できない（スコープ追跡以前に作成されたストア） | フルスキャン / フォーカススキャン |
再利用の判断
CURRENTと判定された場合、ユーザーに3つの選択肢が提示されます。
- 再利用: スキャンをスキップし、既存のCodeKBをそのまま使う。後続ステージは既存ストアを読む
- フルスキャン: リポジトリ全体を再スキャンし、CodeKBを完全に置き換える
- フォーカススキャン: 今回のインテントが対象とする領域のみスキャンする。対象外の領域の知識は破棄される
この設計により、コードに変更がなければスキャンコストをゼロにできます。大規模リポジトリでのスキャンは時間とトークンを消費するため、この再利用メカニズムは実用上重要です。
フィンガープリントによる変更検出
reverse-engineering-timestamp.mdの末尾に記録される「Scope of Analysis」ブロックが、鮮度チェックの基盤です。分析対象パスとそのフィンガープリント（ファイルハッシュ）が記録され、次回のチェック時にファイルシステムの現状と比較されます。6. 後続ステージでの活用
CodeKBは生成して終わりではありません。V2の後続ステージがCodeKBを参照し、既存コードの知識を前提に動作します。参照の仕方には2種類あります。
正式な入力として宣言されるステージ
以下のステージは、Brownfieldプロジェクトの場合にCodeKBのアーティファクトを正式な入力（
consumes）として宣言しています。ステージ開始時に自動的に読み込まれます。| ステージ | 読み込むアーティファクト | 利用方法 |
|---|---|---|
| 2.3 Requirements Analysis（要件分析） | business-overview, architecture, code-structure | 既存機能との整合性確認、重複要件の検出 |
| 2.4 User Stories（ユーザーストーリー） | business-overview, component-inventory | 既存コンポーネントとの接続点の把握 |
フォールバックとして参照するステージ
以下のステージは、上流のデザインステージがスキップされた場合に、CodeKBを代替の構造情報として参照します。
bugfixやrefactorといったincremental scopeでは、Units GenerationやDomain Designがスキップされるため、CodeKBが「既存コードの構造がどうなっているか」を伝える唯一の情報源になります。| ステージ | 参照条件 |
|---|---|
| 3.1 Functional Design（機能設計） | Units Generation / Domain Designがスキップされた場合 |
| 3.2 NFR Requirements（非機能要件） | Functional Designの成果物が存在しない場合 |
| 3.4 Infrastructure Design（インフラ設計） | Domain Design / Functional Designがスキップされた場合 |
| 3.5 Code Generation（コード生成） | Units Generation / Domain Designがスキップされた場合 |
では、なぜこの区別が重要でしょうか。
enterpriseやfeatureスコープのように全ステージが実行される場合、Constructionの各ステージは上流の設計成果物（Functional Design、Domain Design等）を入力として受け取ります。CodeKBは補助的な参照に留まります。一方、bugfixスコープのようにInceptionの設計ステージが大幅にスキップされる場合、CodeKBが既存コードの構造を伝える主要な手段になります。
7. マルチリポジトリ対応
V2はマルチリポジトリのインテントにも対応しています。インテント作成時に複数リポジトリが登録されている場合、Reverse Engineeringは各リポジトリごとに独立してスキャンと鮮度チェックを実行します。
各リポジトリのCodeKBは
aidlc/spaces/<スペース名>/codekb/<リポジトリ名>/に個別に格納されます。リポジトリAは再利用、リポジトリBはフルスキャンという混合判定も可能です。8. まとめ
Reverse Engineeringステージは、V2がBrownfieldプロジェクトに対応するための基盤です。
- パイプラインモード（Developer Agent → Architect Agent）により、スキャンとアーキテクチャ解釈が分離される
- 9つの構造化アーティファクトがスペースレベルのCodeKBとして永続化される
- 鮮度チェックにより、変更がなければスキャンコストをゼロにできる
- 6つの後続ステージとAdaptive Composerが、CodeKBの知識を前提に動作する
大規模な既存コードベースがあっても、V2は「まず理解し、その理解を共有し、理解に基づいて設計・実装する」というフローを自動化します。コードベースの規模が大きいほど、このステージの価値は高まります。
Series: AI-DLC Workflow V2の解説 (31 articles)
- …
- 15AI-DLC Workflow V2のReverse Engineering: 既存コードの「理解」を自動化する This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article