Amazon Web Services ブログ
[AI-Driven Modernization] 既存コードからAIエージェント向けの仕様書を起こす「Reverse Spec Flow」を公開しました
みなさんこんにちは。ソリューションアーキテクトの湖山です。
2026年10月6日に公開した記事「[AI-Driven Modernization] AIエージェントに規律ある移行作業をさせる「AI Modernization Flow」を公開しました」では、AWS Japanが進めるAI-Driven Modernizationの考え方と、技術スタックを更新するRefactorを担うツール「AI Modernization Flow(AIMF)」を紹介しました。今回は、もう一つのアプローチであるReimagine(再構築)の入口を担うツールとして、AWS Samplesに公開した「Reverse Spec Flow(RSF)」を紹介します。
RSFは、仕様書がない、古くなっている、あるいは中身がブラックボックスになっているアプリケーションのソースコードから、AIエージェントが読んで使うための仕様書を作るワークフローです。GitHubで公開しており(https://github.com/aws-samples/sample-reverse-spec-flow)、どなたでも手元のコードで試せます。
Reimagineの入口は「仕様書」
AI-Driven Modernizationでは、移行のゴールに応じて2つのアプローチを提供しています。
- Refactor(技術スタックの最新化):ビジネスロジックは変えずに、言語ランタイムやフレームワーク、ライブラリを新しくします。AIMFが担当します。
- Reimagine(再構築):既存コードから仕様書を起こし、その仕様をもとに新しいアーキテクチャで作り直します。

図1:AI-Driven Modernizationのアプローチ
Reimagineでは、再構築を仕様駆動開発で進めます。そのため、AIエージェントに渡す仕様書の質が、そのまま再構築の質を決めます。仕様書に書かれていない業務ルールは新しいシステムから消え、仕様書の誤りは新しいシステムにそのまま作り込まれます。
AIに「仕様書を書いて」と頼むだけでは何が足りないのか
コーディングエージェントに「このコードの仕様書を書いて」と頼めば、それらしい文書は返ってきます。しかし、私たちが試す中で、次のような問題を繰り返し見てきました。
- コードに根拠のない記述(ハルシネーション)が混ざり、それが下流の実装に伝わる。
- 主要な部分だけを書いて「完成」と報告し、どこが抜けているのか誰にも分からない。
- 現行のフレームワークやクラス構造、ORM(Object-Relational Mapping)といった特定の技術の都合が「仕様」として書かれ、新しい技術スタックで作り直す入力にならない。
- 画面、帳票、バッチの実行順序のように、コードから読み取りにくい部分が抜け落ちる。
さらに、AIが書いた仕様書では、確かめた記述と確かめていない記述が同じ見た目で並びます。受け取ったAIはそれを区別できず、どちらも同じ確度と判断してしまいます。
RSFは、AIの賢さに頼るのではなく、誤りが混入しにくく、混入しても見つけやすい手続きにAIを従わせることで、この問題に対処します。
Reverse Spec Flow(RSF)の特徴
5つの段階で進める
ソース全体を一度にAIに読ませると、網羅の抜けと根拠のない要約が混ざります。RSFは作業を5つの段階(Phase)に分け、各段階の出力を次の段階で検証できる入力にします。
| Phase | 内容 |
|---|---|
| Phase 0 取り込み | 解析対象のコミットを固定し、範囲を決める |
| Phase 1 コードグラフ | モジュール、入口、外部接続とそのつながりを一覧にする(網羅の分母) |
| Phase 2 分析 | アーキテクチャ、要件、API、データ、振る舞い、非機能の観点で、根拠付きで分析する |
| Phase 3 仕様化 | ISO/IEC/IEEE 29148に沿った章立てで仕様書を書く |
| Phase 4 監査 | 網羅、引用、事実と推測の区別を、書いた段階とは独立して点検する |
Phaseの境界や数え方を決める場面では、AIが作業を止めて人に確認を求めます。

図2:Reverse Spec Flowの5つのPhaseと、人が確認するゲート(HITL Gate)
すべての記述に根拠を付け、書いたAIとは別のAIが確かめる
仕様書の各記述には、それを裏付けるコードの位置(path:line)を付けます。根拠のない断定は残しません。
書いたAIが自分の記述を見直しても、同じ思い込みで誤りを見落とします。そこでRSFは、書き手から切り離した検証役のAIに、各記述を解析対象のソースコードと突き合わせさせます。根拠の位置があるかだけでなく、引用した行が記述を本当に裏付けているかまで確かめます。
コードから確かめられないことは推測で埋めず、UNKNOWNとして残します。既存の設計書がある場合は「出所の分かる、まだ確かめていない主張」として扱います。コードで裏が取れたものだけを事実にし、コードと矛盾した記述は「ずれ」として記録します。
網羅したかどうかを数えて判定する
RSFは、Phase 1で作るコードグラフを網羅の分母にします。コードグラフのすべての要素が仕様化されるまで、作業は完了しません。「主要な部分は見た」で止めないための仕組みです。
完了したかどうかは、AIの「終わりました」という報告ではなく、点検スクリプトgates.shが合格(exit 0)を返すかどうかで決めます。守らせたい規律をできるだけスクリプトに置き換えるという考え方は、AIMFと同じです。
現行技術に依存する仕様と、作り直しに必要な本質を分ける
Reimagineでは、現行の技術スタックに引きずられない仕様が必要です。RSFは仕様書を2つの層に分けて書きます。
- 実装事実の層:現行コードの実際の姿。技術に依存する内容も含み、本質を抜き出す根拠として残します。
- 技術に依存しない本質の層:業務ルール、状態遷移、論理データモデル、ユースケース、入力チェック、外部との約束事、画面の構成と遷移、帳票、バッチなど。作り直しの入力になります。
どちらに書くかの判断基準は「作り直し先がどの技術スタックでも、この情報は必要か」です。
AIエージェントが必要な部分だけを引ける
仕様書のファイルと要件には、REQ-F-01のような一意のIDを付けます。IDからファイルを引く索引と、ソースファイルから仕様書を引く逆引き索引も作ります。仕様書を使うAIエージェントは、全体を読まずに必要な部分だけを参照できます。逆引き索引は、現行システムを保守するときの影響調査にも使えます。仕様書を使う側のAIが守るルール(specs/AGENTS.md)も同梱しています。
実際の仕様化記録から:Apache Roller
AIMFの記事でも移行の例として紹介した、Javaで書かれたオープンソースのブログ用CMS、Apache Roller 6.1.5を仕様化した例を紹介します。Webアプリケーションだけでなく定期処理や外部連携のバッチ処理も対象に、Reimagineを想定した最も詳細な設定(rebuild)で仕様化しました。
| 項目 | 結果 |
|---|---|
| 対象の規模 | 約15万ステップ(うちJava約9.8万ステップ)。構成要素は約280、業務機能は17 |
| 完了の判定 | gates.shによる完了の点検をすべて通過 |
| 所要時間 | 約38時間(人の確認待ちを含む今回の実績) |
| 人の判断が要った場面 | Phaseの境界、対象の数え方、既存データとの互換方針、追加検証の要否の4種類 |

図3:Apache Rollerの成果物の例
完了の点検を通した後に、記述を無作為に200件抜き出して原典と照合しました。約5%に一部の誤り(一覧の不足、条件の欠落、言い過ぎ、引用位置のずれ)が見つかりましたが、完全に誤った記述は0件でした。誤りがゼロになるわけではないことも、数字として示しておきます。
仕様書をもとにした再構築の実績
作った仕様書を入力に、AI-DLC(AI-Driven Development Life Cycle)のワークフローでフォワードエンジニアリングを行い、Apache RollerをTypeScriptとNext.jsでゼロから作り直しました。仕様書に画面の構成や入力チェック、権限のルールまで書かれているため、AIが推測で補う必要がほとんどなく、中核となる機能の実装とテストを短期間で終えられました。移行先の技術スタックは仕様書に縛られないため、お客様の要件に合わせて選べます。
RSFでできること・できないこと
RSFは、コードを静的に読んで仕様化します。アプリケーションを起動したり、画面を操作したり、データベースに問い合わせたりする動的な確認は行いません。設定や実行時に決まる振る舞いのうちコードから断定できないものは、UNKNOWNとして残ります。
仕様書の誤りは点検によって減りますが、なくなりはしません。仕様書をもとに作り直したアプリケーションは、受け入れテストやリグレッションテストで、現行システムと同じように動くことを確かめてください。
AIツールは解析対象のソースコードを読みます。機密性の高いコードを扱う場合は、利用するAIツールの規約と組織のルールに従ってください。生成した仕様書のリポジトリにはコードの抜粋が含まれるため、ソースコードと同じように扱い、公開リポジトリには置かないでください。
AIエージェントは利用者の権限でコマンドを実行します。信頼できないコードを解析する場合は、本番の認証情報がない隔離した環境で実行し、操作の自動承認は使わないでください。
よくいただく質問
Q. AIがハルシネーションを書かないことは保証されますか。
A. 保証はしません。すべての記述に根拠を求め、別のAIに確かめさせ、確かめられないことをUNKNOWNとして残すことで、誤りを混入しにくく、見つけやすくしています。
Q. どのような環境で動作しますか。
A. 開発者のローカル端末での動作を想定しており、必要なのはbash、git、AIツールだけです。Windowsでは、WSLか、Git for Windowsに含まれるGit Bashを使えます。基本的には成果物はMarkdownで、グラフデータベースやベクターデータベースなどのツールは必要ありません。
Q. 解析対象のコードは変更されますか。
A. 変更されません。AIへのルールで変更を禁じたうえで、gates.shがソースの変更を検出します。
Q. どのくらいの規模まで対応できますか。
A. 業務機能ごとに分けて読むため、一度に読み込む量はコード全体の大きさに左右されません。オープンソースの金融システム基盤であるApache Fineract(約84万ステップ)で使った実績があります。規模に応じて増えるのは所要時間で、サブエージェントによる並列実行で短縮できます。
Q. 費用はどのくらいかかりますか。
A. 費用は、AIツールが使うモデルの利用料で決まり、コードの規模や使うモデル、設定によって大きく変わります。Reimagineを想定した設定(rebuild)は、すべての記述を別のAIで検証するため、保守目的の設定(maintenance)よりも多くかかります(5〜7倍程度)。参考としてApache Rollerを記録密度の最も高いrebuildでリバースした例では、ソースコード約15万ステップで、出力約1,500万・キャッシュ読み込み約35億トークンとなりました。費用はモデルの単価で数倍変わるため、まずは1万ステップ未満の小規模なコードを仕様化して消費量を確かめてから、範囲を広げることをお勧めします。
Q. 作り直しの予定はありませんが、使い道はありますか。
A. あります。ブラックボックスになった現行システムの保守にも使えます。AIエージェントが仕様書を参照して、現在の振る舞いや変更の影響範囲を説明します。
利用方法
WindowsやMac/Linuxでbashとgitが使える環境を用意していただき、コーディングエージェントを準備してください。現時点で動作を確かめているAIツールは、Claude CodeとKiro IDEです。ワークスペースに解析したいコードをcloneし、init.shで仕様書用のリポジトリを作ります。
cd /path/to/workspace
git clone https://github.com/aws-samples/sample-reverse-spec-flow.git
./sample-reverse-spec-flow/init.sh ./legacy-order-system order-system rebuild --playbook java-jaxrs-jpa
3番目の引数で仕様書の目的を選びます。maintenanceは保守のための理解、evaluationは作り直しの評価や見積もり、rebuildは作り直しをAIエージェントが実装できる深さまで、です。Playbookは対象技術ごとの構成要素の数え方をまとめたもので、Java、.NET、VB6、PHP、COBOL、PL/SQLなど10種類を用意しています。指定しなくても動きます。
あとは作成されたlegacy-order-system-spec/をAIツールで開き、spec-extraction/AGENTS.mdを読んでPhase 0から始めるよう指示します。
AWSと一緒にAI-Driven Modernizationを始めましょう
このブログでは、Reimagine型のモダナイゼーションの入口として、既存コードからAIエージェント向けの仕様書を起こすReverse Spec Flowを紹介しました。実際にリバースした仕様書からJavaで書かれたApache RollerをTypeScriptとNext.jsで再構築することができています。
まずは手元の小さなアプリケーションを保守目的で仕様化し、仕様書をAIエージェントに渡して、現行システムについて質問してみてください。仕様書の記述からコードの根拠までたどれることを確かめたうえで、作り直しの評価や本格的なPoCに進むのがお勧めです。
AWS Japanでは、AI-Driven Modernizationのご相談を受け付けています。Refactor型ではAIMFを使ったアセスメントとPoCを、Reimagine型ではRSFを使った仕様化と、仕様駆動開発による再構築、受け入れテストの自動化についてご相談いただけます。AWSの担当営業またはソリューションアーキテクトにお声がけください。SIパートナーの皆様からのご相談も歓迎します。
What’s next
RSFは、プロジェクトで得た知見をフレームワークに取り込みながら改善を続けていきます。利用する際はGitHubで最新版をご確認ください。GitHubのIssue、またはAWSの担当者までフィードバックをお寄せください。