2025年の「仕様書」はコードから読み取るべきか——AI時代の前提崩壊
2026.06.10執筆者：DigKnow株式会社 CTO 桑原 脩
「ドキュメントは嘘をつくが、コードは嘘をつかない」——シニアエンジニアなら、一度は口にしたか、聞いたことがある言葉ではないでしょうか。仕様書なんてどうせ古い、最新の真実はコードにしかない、だから困ったらコードを読め。長らくこの考え方は、技術的に誠実な姿勢として通用してきました。ただ、この前提が静かに崩れているのではないか、と私は最近思っています。
「コードを読め」が正しかった時代の暗黙の前提
「仕様はコードから読み取れ」という考え方には、それなりの根拠がありました。
ドキュメントは更新されません。書かれた瞬間から古くなります。一方、コードは動いている以上、いまそこにある現実を正確に表現しています。仕様書が間違っていてもシステムは動きますが、コードが間違っていればシステムは動かない——だからコードのほうが信頼できます。論理として、ある程度筋は通っています。
ただ、この論理には暗黙の前提があります。コードを書いた人間の意図が、コードという形でそこに「書き残されている」という前提です。
変数名の付け方、関数の分割の仕方、エラーハンドリングの選び方、抽象化のレイヤーの切り方——こうした一つひとつの判断には、書き手の意図が反映されています。優れたエンジニアが書いたコードは、それ自体が一種のドキュメントになります。「コードを読めばわかる」という助言は、書き手の判断の総体を読み取れる、という前提のもとで成立していました。
「コードを読め」という思想は、職人がいた時代の思想だった、ということです。
AI生成コードに宿る「人間の判断の濃度」
ここで一度、立ち止まって考えてみたいのです。AIコーディングツールが生成したコードの一行一行に、人間の判断はどれだけ宿っているでしょうか。
私自身、Claude Codeで生成されたコードを読み返していて、ふと困惑することがあります。「この変数名、なぜこの名前にしたんだっけ」「このエラーハンドリング、なぜこのパターンを選んだんだっけ」——指示を出して、出力を確認して、テストを通して、マージしました。それぞれの判断はAIがしたのか、私がしたのか、もう正確には思い出せません。
これは責任放棄の話ではありません。レビューもテストもしましたし、責任はもちろん私にあります。ただ、コードに刻まれている判断のうち、どこからどこまでが私の意図で、どこからがAIのデフォルト挙動なのかが、書いた直後ですら曖昧になっているのです。
「コードを読めば仕様がわかる」という思想が書き手の判断の総体を読み取れる前提に立っていたとするなら、その前提はAIコーディングの普及とともに静かに崩れ始めています。コードという成果物の量は増えていますが、そこに刻まれている人間の判断の濃度は薄まっている。これは品質の問題ではなく、再構成可能性の問題です。
「読み取れるコード」と「読み取れる読み手」の非対称
仮にAIが書いたコードにも何らかの判断が反映されていると考えても、もうひとつ別の問題があります。コードから仕様を読み取るという行為そのものが、誰にでもできる作業ではない、ということです。
シニアエンジニアがコードを読めば、関数の意図、設計の制約、トレードオフの判断を、ある程度は再構成できます。「ああ、これはこの制約を回避するためにこう書いたんだな」と、書かれていない経緯までかなり読める。ただ、それは長年の経験と読解力があるからできることです。新人エンジニアが同じコードを開いても、目に入るのは構文と処理の流れだけで、その背後にある「なぜ」は見えません。
つまり「コードから仕様を読み取れ」という助言は、暗黙のうちに「読み取れる読み手」の存在を仮定しています。組織にシニアが厚く存在し、コードベースに詳しい人がいて、必要なときに相談できる——そういう環境があってはじめて、この助言は機能するのです。
ここで効いてくるのが、AIコーディングが進むほど、皮肉にも「読める人」が育ちにくくなる構造です。書く行為そのものが理解の機会だった時代が終わると、コードと深く向き合った経験を積む機会が、若手から減っていきます。読み取れる人を育てる仕組みのほうが、先に細っていく。「コードを読め」という助言が十年前と二〇二五年で同じ重さで使えるかというと、たぶん使えません。
仕様の二層性——コードから読めるもの、読めないもの
ここで「やっぱりドキュメントを書こう」という結論に飛びつくのは早計です。書かれないドキュメントの問題は別にあって、書くと決めただけでは解決しません。考えるべきはもう一段手前の問いです。「仕様」と呼ばれているものは、本当はどこに住んでいるべきものなのか。私が最近、現場で頭の整理に使っているのは、「仕様」を二つの層に分けて見る考え方です。
①静的な記述：このシステムは何をするか
入出力、画面遷移、データ構造、API仕様。これはコードからかなりの精度で再構成できますし、AIがそれを補助することも現実的になってきました。
②意思決定の記述：なぜこの設計を選んだか
なぜこの抽象化なのか、なぜこのライブラリなのか、なぜこの場合はあえて重複を許容したのか——これはコードを読んでも復元できません。書き手の頭の中、あるいはSlackの過去ログ、もしくはどこにも残っていないのです。
「仕様書はコードから読み取るべきか」という問いに正直に答えるなら、①についてはYes、②についてはNoです。そして、システムを長く維持するうえで本当に重要なのは、たいてい②のほう。動いている処理を再現するだけならコードを読めば足りますが、「なぜそうしたのか」がわからないと、変更も廃止も合理的にはできません。
つまり仕様の置き場所は、コードと並列に「もうひとつ必要」だ、というのが私の現時点の結論です。問題は、それを誰がいつ書くのかという運用の話に戻ってきます。これは技術ではなく、開発フローの設計の問題です。
「読み取れる」前提を疑うところから始める
整理すると、「コードを読め」という助言が成立するには、三つの前提が必要でした。①書き手の判断がコードに濃く宿っている、②読み取れる読み手がいる、③意思決定の経緯までコードに含まれている。AIコーディングが普及した現場では、この三つがどれも揺らいでいます。
「コードを読め」という助言は、過去のある時期には正しい姿勢でした。いまも一部は正しさを保っています。ただ、それを開発現場の標準的な姿勢として全面的に採用するには、根拠が薄くなりすぎている、というのが私の見立てです。
何かを書き残す。コードとは別の場所に。それを書くタイミングと動機を、開発フローのなかに設計する——たぶん、向き合うべきはこのレベルの話です。AIがこの問題を解決できるのかという論点については、今後の記事で改めて掘り下げていきます。ただその前に、「コードから読み取ればいい」という長年の前提を一度疑うところから始めないと、議論の出発点がずれたままになってしまいます。
まとめ
「仕様書はコードから読み取れ」という思想は、書き手の判断がコードに宿り、読み取れる読み手がいて、意思決定の経緯までコードに含まれる——という三つの前提のうえで成立していました。AIコーディングが普及した現場では、この前提のどれもが弱くなっています。コードから再構成できる仕様と、できない仕様を切り分け、後者をどこに置くかを設計し直すこと。これがいま向き合うべき問いだと、私は思っています。