仕様書がないレガシーコードをAIで読み解く3ステップ

設計者が去った後のコードと、向き合ったことはあるだろうか。

ファイルは残っている。テストも、それなりに動いている。でも、なぜそうなっているのかを知っている人間が、もうどこにもいない。コメントはほぼなく、変数名は誰かのローカルルールで短縮されていて、業務フローとコードの対応は時間とともに崩れている。「とりあえず動いている」という理由だけで10年走り続けてきたシステム——そのリプレースや機能追加を任されたとき、まず何から手をつけるべきか。

多くの現場で、この「仕様書のないコードの解読」が開発最初のボトルネックになる。そして今、AIがここを変えようとしている。

なぜレガシーコードの仕様書化は難しいのか

理由はシンプルだ。コードは「何をするか」は教えてくれるが、「なぜそうするのか」は教えてくれない。

ある条件分岐が存在する。でも、その条件が生まれた背景——特定の取引先との特殊な契約ルール、規制対応で入れた例外処理、10年前の不具合への応急措置——そういった「意図」はコードの外にある。それがドキュメントに記録されていれば良いが、現実にはこうした業務的な背景こそが最も失われやすい情報だ。

従来の対処法は二通りだった。ひとつは、コードを読める人間を長期投入して読み解く（コストが高い）。もうひとつは、動作をブラックボックステストで観察して逆算する（時間がかかる）。どちらも非効率で、往々にして「だいたい合っている気がする」というレベルの成果にとどまる。

その結果、次の開発でまた同じ問いが繰り返される。「この処理って、何のためにあったんでしたっけ？」

AIがここを変える理由

AIの得意なことのひとつに、「大量のコードを短時間で読んで、構造を言語化する」ことがある。これは今まで人間が何週間もかけてやっていた作業だ。

ただし、AIに「このコードを仕様書にして」と丸投げしても機能しない。コードが教えてくれる「何をするか」と、人間だけが知っている「なぜそうするのか」——この二層を組み合わせる設計が必要だ。以下の3ステップは、その組み合わせ方の実践的な枠組みだ。

ステップ1：コード構造の自動解析と図式化

最初にやるべきことは、全体像の把握だ。大規模なレガシーコードは、一本一本読み始めると迷子になる。

コード解析ツールと生成AIを組み合わせることで、依存関係・呼び出し関係・データフローを視覚化しながら、「このモジュールが何をしているか」を自然言語で説明させることができる。実際には次のような問いかけが機能する。

> 「このファイル群を読んで、主要なデータフロー（入力→処理→出力）を箇条書きにしてください」

> 「このクラスの責務を一言で表すとしたら何ですか？」

> 「この関数が呼び出されるシナリオを3つ挙げてください」

完璧な答えは返ってこない。でも、「このあたりに注意して読めばいい」という方向感は得られる。人間が2週間かかる初期スキャンが、数時間の対話に変わる。

特に有効なのは、コードが特定の業界ドメインに特化している場合だ。たとえば独自プロトコルやカスタムフォーマットで書かれた業務システムでも、AIは「このコードは○○という処理をするパターンに似ている」という類推ができる。それがなければ読み解きに数週間かかるところを、AIが文脈の糸口を引っ張り出してくれる。

ステップ2：業務ロジックのヒアリング補完

コードが教えてくれない「なぜ」を補うのは、人間のヒアリングだ。ただし、AIを挟むことで質が大きく変わる。

ポイントは、ヒアリングを「ゼロから聞く」から「仮説の確認」に変えることだ。

AIにコードを解析させて「この条件分岐はどんな業務ルールを想定しているか、候補を3つ挙げてください」と問いかける。その候補リストをベースに、業務担当者への質問を組み立てる。「このうちどれが近いですか？」という問いは、「何か特別なルールはありますか？」より圧倒的に答えやすい。

「ゼロから話を引き出す」のではなく「仮説を検証させる」構造にすることで、ヒアリングの時間は短くなり、引き出せる情報の精度は上がる。この原理はAIエージェントによる要件ヒアリング設計と同じだ——AIが先に仮説を持ち、人間がそれを修正する形にすると、対話のスループットが上がる。

正直なところ、この段階が最も人間の関与が必要なフェーズでもある。コードには読めるが、業務背景は読めない——そこをAIが補完しようとしても限界がある。業務担当者との対話を省略すると、後でかならずつまずく。

ステップ3：仕様書ドラフトの自動生成と検証ループ

前の2ステップで得た情報——コード構造の解析結果と、ヒアリングで補完した業務ロジック——をAIに渡して、仕様書の初稿を生成する。

ここで重要なのは、生成物を「成果物」ではなく「叩き台」として扱うことだ。AIが出したドラフトには間違いが含まれる。でも、それ自体が価値を持つ。

間違いを指摘し合うプロセスで、チームの中に「この処理の認識が合っていなかった」という発見が生まれる。ゼロから仕様書を書こうとすると「何を書けばいいか」で止まりがちだが、ドラフトに赤を入れる形にすると、認識の齟齬が可視化される。「仕様書を作る」から「仕様書をレビューする」への転換——これが生成AIがもたらす最大の変化かもしれない。

このステップを繰り返すことで、仕様書の精度が上がっていく。一発で完成させようとしないことが重要だ。3〜4回のイテレーションを前提にスケジュールを組むと、現実的な品質に達する。

なぜ「上流工程」の話になるのか

「コードから仕様書を作る」ことは、一見すると下流の整理作業に見える。だが実際には、次の開発サイクルの上流工程の準備そのものだ。

リプレース・機能追加・AI化——どの文脈でも、「現状システムが何をしているか」を正確に把握していなければ要件定義はできない。現行仕様を再現しないまま新システムの要件定義を始めると、必ず途中で「あの処理って何のためにあったんでしたっけ？」と戻ることになる。

AI導入を上流工程から始めるべき理由として語られることが多いが、その前提には「現在地を把握する」というステップがある。逆引き仕様書化は、その「現在地の把握」を体系化したものだ。

Kakusillが目指していること

アツメルが開発しているKakusill（カクシル）は、こうした「仕様書がないところから始まる」現場にも対応できるAI仕様書エディタだ。

既存ドキュメントの構造化から、AIヒアリングによる暗黙知の抽出まで、「仕様書をAIが読める形に整える」というコンセプトを体現している。コードから仕様書を再現する段階で生成されたドラフトをKakusillの構造に落とし込むことで、そのまま次のAI開発サイクルに接続できる。

「仕様書がない」から始まるプロジェクトは珍しくない。そこをどう乗り越えるかが、AI時代の開発現場における新しい問いになっている。

仕様書化を後回しにしたまま「とりあえず動いている」ことを理由に先送りされているシステムが、あなたの組織にもあるかもしれない。Atsumellでは、既存システムの仕様可視化から次世代への移行設計まで、AI活用支援を行っている。まずは気軽にご相談いただきたい。