AIに既存コードの仕様書を作らせてみた

私は普段、自分が入社する前から動いているシステムの保守を担当しています。

弊社はアジャイル的な空気が強く、対応内容の詳細は口頭での説明がメインです。

開発や改修におけるスピード感としてのメリットは大きいのですが、
整理されないまま積み重なって肥大化したことで仕様が複雑になりすぎています。

なので、いつかは仕様をちゃんと整理したい！！

・・・AIに作らせればいいのでは？

その予行演習として、ちょうどいい題材が手元にありました。

以前このブログで作った、サブスク管理ツールです。

参考：Claude Codeでサブスク管理画面を作ってみた

HTML・CSS・JavaScriptが全部入った1ファイルで、コメントもほぼ無し。

仕様書なんてもちろんありません。

実験台にうってつけでした。

環境

• OS：Windows 11
• 使用ツール：Claude（デスクトップ版）
• 入力：以前作ったサブスク管理ツールのHTMLファイル1枚

やってみた

HTMLファイルをまるごと渡して、こう頼んだだけです。

「このファイルについて、社内向けの仕様書として整理してください」

仕様がわからないシステムの仕様書を作成してもらうことを想定しているため、背景説明はゼロ。

「サブスクを管理するツールだよ」とも言っていません。

※求めている出力内容をプロンプトに書いてないのもこのため。

これでどうなるか・・・。

出てきたのは、表紙と目次つきの9ページのWord文書でした。

（最初からv3だったので、どうやらチェックと修正が回ったようです）

概要、動作環境、画面構成、機能仕様、データ仕様、主要ロジック、関数一覧。

見出しが並んでいます。

データの持ち方も、項目ごとに表で整理されていました。

月額換算のロジックや、更新日の残り日数でバッジの色を変える判定まで、ひと通り言語化されています。

シンプルに仕様を書き出しすだけだと思ってたので、
ここまで資料として完成されたものが出力されたことは嬉しい誤算です。

コードレビューがついてきた

今回「おっ」となったのはここです。

仕様書の「制限事項」の章に、潜在バグの指摘が混ざっていました。

要約すると、こういう話です。

ジャンル別一覧の開閉処理で、要素IDを生成する側はエスケープ済みの文字列、開閉する側は未エスケープの文字列を使っている。ジャンル名に空白やHTML特殊文字が入ると、開閉が動かなくなる可能性がある。

該当箇所を見に行ったら、本当にそうなっていました。

今はジャンル名が日本語だけですが、自由入力を許した瞬間に踏むかもしれない地雷です。

「制限事項」が人間より正直

人間が自分のコードの仕様書を書くと、注意書きはどうしても薄くなります。

理由は単純で、『自分は全部わかっているから、わざわざ書く気にならない』からです。

AIにはその慢心がないので淡々と、後から触る人が本当に困るポイントを並べてきました。

「まあわかるよね」がないのは、資料として助かります。

AIに書けないものがある

AIが書けるのは、「何がどう動くか」まで。

コードを正確に文書化してくれますが、イケてない実装もイケてないまま丁寧に清書されます。

だけであればいいのですが、そのイケてない実装が

「なぜそうなっているのか」

までは書けません。

「なぜ年額を単純に12で割っているのか」「なぜAdobeだけ特別扱いなのか」——その背景にある判断や過去の事情は、コードのどこにも書いていないので当然出てきません。

設計書がなく、判断の経緯が口頭でしか残っていない以上、引き継ぎたい『なぜ』が、コードにもAIにも存在しません。

ここは過去の行いを悔いるしかなく、人間側の明確な弱みになると思います。

感想

予行演習として十分な手応えでした。

AIに仕様書を書かせてみて新たに気づいたことは、

今後、

コメントやドキュメントの役割は、意思決定の記録へと変わるのではないか

ということ。

コードや仕様はAIが瞬時に理解し、分かりやすく解説までしてくれます。

そう考えると、「あとから設計や動作仕様を理解するための資料」の価値は、既になくなっているのかもしれません。

一方で、「なぜその仕様になったのか」「なぜ別案を採用しなかったのか」といった意思決定の背景は、AIだけでは復元できません。

今回得られたものは仕様書作成の効率化ではなく、

意思決定を残すことの重要性への気付き

という、思っていたのとは少し違う結末となりました。