【2026年版】レガシーシステムを刷新する仕様駆動開発｜導入ステップ5選

AIコーディングエージェントの登場によって、開発のスピードは劇的に上がった。ただ闇雲にAIへ指示を出すだけでは、いずれコードベースは崩壊する。特に仕様書が存在しないレガシーシステムを刷新する場合、AIが生成する情報の洪水に人間が飲み込まれてしまうリスクがある。

これからの開発には仕様駆動開発（SDD: Spec-Driven Development）が不可欠だ。これはコードを書く前に、人間が「何を」「なぜ」作るのかという仕様を定義し、AIには「どのように」実装するかを任せる手法だ。

この記事では、1人SaaS開発者として毎日Claude Codeを使い倒している筆者が、レガシーシステムを安全かつ効率的に刷新するための導入ステップを解説する。これを読めば、AIを単なる代筆屋ではなく、最強の参謀として使いこなす方法がわかる。

導入の前提知識

仕様駆動開発を始める前に、準備しておくべきものがある。まずはClaude CodeなどのAIコーディングCLIツールが動く環境だ。そして、対象となるレガシーシステムのソースコードが手元にあることも前提となる。

もっとも重要なのは、AIに丸投げするというマインドセットを捨てることだ。AIは仕様の推測は得意だが、ビジネス上の正解を決めることはできない。主導権は常に人間が握る。この役割分担を理解することが、SDD成功の第一歩になる。

ステップ1：既存コードから仕様を逆生成する

レガシーシステムの刷新において最大の障壁は、仕様書がどこにもないことだ。担当者はすでに退職し、コードだけが動いているという状況は珍しくない。ここで役立つのが、cc-rsg（Reverse Spec Generator）というツールだ。

これは既存のコードベースを解析し、仕様書を自動で逆生成するためのスキルだ。まずは小規模なモジュールから解析を始める。cc-rsgを実行すると、コード内の関数やクラスをすべて洗い出し、それらが何をしているのかをドキュメント化する。

このプロセスの優れた点は、生成された仕様書に信頼度マーカーが付与されることだ。AIがコードから確実に読み取った内容は「HIGH」、推測が含まれる場合は「MED」といった印がつく。人間はこのマーカーを確認し、推測部分が正しいかどうかを判断する。ゼロから仕様書を書く手間に比べれば、圧倒的な時短になる。

ステップ2：ドキュメントの肥大化を堰き止める

AIにドキュメント作成を任せると、放っておけば情報の量は指数関数的に増えていく。AIは丁寧に説明しようという善意から、不要な付録や冗長な解説を勝手に追加する傾向があるからだ。これが続くと、ADR（アーキテクチャ決定記録）が100件を超え、仕様書が数万行に膨れ上がる情報洪水が発生する。

これを防ぐための強力な枠組みがdoc-frameだ。AIが文章を書き始める前に、必ず「誰が読むか」「どのカテゴリの文書か」「字数上限はいくらか」といった5項目を宣言させるルールを運用する。

このルールをCLAUDE.mdなどの設定ファイルに記述しておけば、AIは自ら設定した枠組みの中でしか出力をしない。たとえば「字数上限：既存ファイルにプラス30行以内」と宣言させれば、AIが勝手に100行の解説を付け加えることはなくなる。枠を与えることで、ドキュメントの品質と密度をコントロールできる。

しんたろー：
実際に筆者が開発しているThreadPostでも、このdoc-frameの考え方は重宝している。AIは放っておくと将来の拡張性について語り始める癖があるが、枠をはめることで、今必要な実装だけに集中させることができる。

ステップ3：EARS構文で要件を構造化する

仕様書を作成する際は、曖昧な自然言語ではなく、構造化された構文を使うのが賢いやり方だ。特におすすめなのがEARS（Easy Approach to Requirements Specification）構文だ。

これは「いつ、どのような条件下で、システムは何をするか」というパターンに当てはめて要件を記述する手法だ。AIはこの構造化されたテキストを理解するのが非常に得意だ。箇条書きで要件を並べるよりも、EARS構文で書かれた仕様書のほうが、AIは矛盾のない正確なコードを生成できる。

この段階では、人間が「何を」実現したいのかを明確に言語化することに集中する。エッジケースや例外処理の条件をこの時点で定義しておけば、実装段階でAIが迷うことはなくなる。

ステップ4：ADRとSpecを明確に分離する

プロジェクトが進むにつれて、ドキュメントの置き場所が混乱しがちだ。なぜその設計にしたのかという決定事項と、現在システムはどう動くべきかという仕様が混ざると、AIも人間も混乱する。

解決策は、ADR（決定記録）とSpec（仕様書）の役割を完全に分けることだ。ADRには決定に至った背景や経緯だけを残し、具体的な挙動や構造は常にSpec側に反映させる。Specを「真実の単一ソース（SSOT）」として維持し続けることが重要だ。

AIに指示を出す際は、常に最新のSpecを参照させる。過去の経緯が書かれた古いADRをAIが読み込んでしまうと、現在の仕様と矛盾したコードを出力する原因になる。情報の鮮度と役割を整理しておくことが、長期的な保守性を担保する鍵だ。

ステップ5：AIを参謀として対話しながら設計を磨く

最後のステップは、AIを単なるツールではなく、対等な設計パートナーとして扱うことだ。仕様書がある程度固まったら、AIに対して「この設計に矛盾はないか」や「よりシンプルな代替案はないか」と問いかける。

AIは膨大な知識ベースを持っているため、人間が気づかなかったセキュリティ上の懸念や、パフォーマンス上のボトルネックを指摘してくれることがある。特にレガシーシステムの刷新では、古い設計思想をそのまま引き継いでしまいがちだ。AIの客観的な視点を取り入れることで、よりモダンで洗練されたアーキテクチャへと進化させることができる。

しんたろー：
Claude Codeを使っていると、CLI上でリアルタイムに設計の議論ができるのが便利だ。1人開発だと視点が偏りがちだが、AIに「この仕様だと拡張性が低いぞ」と突っ込まれることで、結果的に質の高いコードを書くことができている。

従来手法と仕様駆動開発（SDD）の比較

ここで、従来の開発手法と仕様駆動開発の違いを表にまとめる。

| 比較項目 | 従来の手法（AI丸投げ型） | 仕様駆動開発（SDD） |

| :--- | :--- | :--- |

| 主導権 | AIが生成したコードに人間が合わせる | 人間が定義した仕様にAIが合わせる |

| ドキュメント | 後回しになりがちで実態と乖離する | 実装前に作成され常に最新に保たれる |

| 品質管理 | テストを回すまで不具合に気づきにくい | 仕様段階で論理的な矛盾を排除できる |

| 保守性 | なぜこうなったかが不明になりやすい | ADRとSpecにより意図が明確に残る |

| 得意な場面 | 小規模なプロトタイプ作成 | 大規模開発やレガシー刷新 |

初心者がハマりやすい3つの罠

仕様駆動開発を始めるにあたって、初心者が陥りやすい失敗が3つある。

1. AIの出力をノーチェックで受け入れる

AIが生成した仕様書には、もっともらしい嘘が含まれている。特にコードから仕様を逆生成した際は、ビジネスロジックの解釈が間違っている可能性がある。必ず人間が目を通し、承認するプロセスを挟む。

1. ドキュメントを細かく書きすぎる

AIに枠を与えるのは重要だが、人間がすべての細部を手書きしていては本末転倒だ。重要なロジックや境界条件は人間が書き、自明な部分はAIに下書きさせるというバランスを意識する。

1. ツールの選定に時間をかけすぎる

世の中には多くのAIツールがあるが、まずはClaude Codeのような実績のあるツールで、シンプルなSDDのサイクルを回す。ツールを増やすことよりも、開発プロセスを定着させることのほうが価値がある。

よくある質問（FAQ）

Q1：仕様書を書くのが面倒だ。AIに自動で書かせるコツは？

cc-rsgのようなリバースエンジニアリングツールを活用し、既存コードから叩き台を生成させるのが近道だ。ただし、AIの出力には推測が含まれるため、必ず人間が信頼度マーカーを確認し、業務文脈を補完するプロセスを組み込む。丸投げするのではなく、AIが書いたものを人間が編集するスタイルが最も効率的だ。

Q2：AIがドキュメントを書きすぎて管理不能になる。どうすればいい？

doc-frameの導入を推奨する。AIに文章を書かせる前に、読み手や字数上限などの枠組みを宣言させるルールをCLAUDE.mdに記述する。これにより、AIが勝手に不要な付録を生成するのを防ぎ、必要な情報だけを抽出できる。枠をはめることで、AIの出力は劇的に洗練される。

Q3：仕様駆動開発（SDD）は小規模な開発にも必要か？

必要だ。小規模であっても、AIとの対話セッションをまたぐと文脈が失われ、一貫性のないコードが生成されがちだ。SDDの考え方を取り入れ、要件や設計をドキュメント化しておくことで、将来的な拡張やメンテナンスのコストを大幅に削減できる。未来の自分への投資だ。

Q4：レガシーシステムの刷新で一番失敗しやすいポイントは？

現行仕様の過剰な再現だ。AIに任せると、古いシステムの無駄な挙動まで丁寧に拾い上げ、情報が肥大化する。まずは何のために刷新するのかという目的を明確にし、不要な機能や古い設計を切り捨てる判断を人間が主導することが重要だ。捨てる勇気を持つことが、刷新を成功させる秘訣だ。

Q5：Claude Codeなどのエージェントツールを使いこなすには？

ツールを単なるコード生成機としてではなく、設計のパートナーとして扱う意識が重要だ。EARS構文などで要件を構造化し、人間の承認ゲートを設けることで、AIのスピードと人間の判断力を組み合わせた効率的な開発サイクルが実現する。常にAIに何を考えさせるかという視点を持つ。

まとめ

レガシーシステムの刷新は、エンジニアにとって最も困難なタスクの一つだ。しかし、AIと仕様駆動開発を組み合わせることで、その難易度は劇的に下がる。

まずはcc-rsgで現状を可視化し、doc-frameで情報の氾濫を抑え、EARS構文で意図を伝える。このステップを踏むだけで、AIはあなたの意図を完璧に理解する強力なパートナーへと変わる。

AIの進化は止まらないが、それを使う側のプロセスも進化させる必要がある。今日から仕様駆動開発をプロジェクトに取り入れ、AIネイティブな開発スタイルへとシフトする。