コードは残るが、仕様は誰も知らない——AIコーディング時代の構造問題
2026.05.29執筆者：DigKnow株式会社 CTO 桑原 脩
先日、ある開発マネージャーと話していて妙に印象に残った一言がありました。「うちのシステム、コードは全部GitHubにあるんですよ。でも『なぜこう作ったか』を知ってる人間は、もう社内にいないんです」——半ば笑いながら、半ば困ったように言っていたのですが、笑える話ではないと感じました。コードは残ります。でも、仕様は、意図は、判断の経緯は、どこに行ったのでしょうか。
「コードは残るが、仕様は誰も知らない」という現象
ソフトウェア開発の現場では、近年、奇妙な事態が静かに進行しています。GitHubのリポジトリにはコードが完璧に保存されている。バージョン管理も行き届いている。CI/CDも整備されている。それなのに、そのシステムが「なぜこういう設計になっているのか」「どんな経緯でこの実装に至ったのか」を答えられる人間が、組織内に一人もいない——そんな状態に陥るプロジェクトが、確実に増えています。
私はこの現象を、ひとつの言葉で表現したいと考えています。
「コードは残るが、仕様は誰も知らない」
この言葉は、Codeledgeというサービスを構想する過程で、私自身がずっと向き合ってきた問いの核心でもあります。ここで言う「仕様」とは、いわゆるSpecドキュメントだけを指しているわけではありません。もっと広く、「なぜこのシステムがこう動いているのか」を誰かが説明できる状態、くらいの意味で使っています。
コードが記述しているのは「何をするか」です。関数の振る舞い、データの流れ、条件分岐の結果——これらは構文としてコードに書き込まれます。しかしソフトウェアには、コードには書かれない情報が大量に存在します。なぜこの設計を選んだのか。どんな制約のもとでこの実装に落ち着いたのか。どのケースを意図的に対応しなかったのか。どんな議論の末にこの判断になったのか。
これらこそが「仕様」の本体とも言えるもので、コードそのものからは読み取れません。以前の開発現場では、こうした「コードに書かれない情報」の一部は、設計書やレビューコメント、チャットのログ、口頭の議論として、なんとなくチームの中に残っていました。完璧ではないにせよ、書いた人間の頭の中に、ある程度の文脈が保管されていたのです。
AIコーディングが加速した現場で起きているのは、この「保管場所」そのものの崩壊です。
なぜAIコーディング時代にこの問題が深刻化するのか
理由は三つあります。
①：書いた人間の頭の中にも、文脈がない
AIが生成したコードの場合、「なぜこの実装になったか」を書いた本人にも答えられないことがあります。Claude Codeにタスクを投げて、出力が返ってきて、動作を確認してマージする——このフローでは、実装の細部を私自身が判断していません。だから後から「なぜここはこうなっているのか」と聞かれても、「AIがそう提案したから」としか答えようがないのです。
これは、チームの「最後の記憶装置」が消えるということを意味しています。以前なら、設計書がなくても書いた本人に聞けばわかりました。今は、書いた本人に聞いてもわからないケースが静かに増えています。
②：コードの増加速度と、理解の共有速度が乖離する
チームが週に生み出すコードの量は、AIツールの導入前と後で明らかに変わりました。一方で、コードレビューにかけられる時間、設計議論に使える時間、ドキュメンテーションに割ける時間は、ほとんど変わっていません——むしろ減っていることも多いでしょう。
人間が一日に処理できる「理解」の量には限界があります。実装だけが先に進み、理解がついていけない。このギャップは、時間とともに複利で拡大していきます。
③：「動いている」ことが、問題の存在を隠す
私が一番厄介だと感じているのはこれです。仕様が失われても、システムは動き続けます。ユーザーには気づかれません。売上も立ちます。表面上は何も起きていないように見えます。
だからこの問題は、バグのようには顕在化しません。障害が起きたとき、大きな改修が必要になったとき、担当者が退職したとき——そのタイミングで初めて、「このシステム、誰も全体を理解していない」という事実が姿を現します。それまでは、静かに、確実に、進行しています。
マネージャー・CTOが見落としている「時間の軸」
エンジニア個人の視点では、書いたコードを本人が理解できていれば、当面は問題ありません。しかしマネージャーやCTOの視点に立つと、この問題は別の顔を見せます。
ソフトウェアは、3年・5年・10年のタイムスパンで運用されます。その間にチームは変わり、人は入れ替わり、技術トレンドも移ります。その変化のたびに、「このシステムを理解している人」が必要になります。問題は、書いた本人がチームを離れた後、誰がそのシステムを理解し続けるのか、ということです。
時間軸が伸びるほど、「コードは残るが、仕様は誰も知らない」状態は、三つの具体的なコストとして企業の内部にじわじわと現れてきます。
①は、変更のたびに探索コストが発生することです。新機能追加、バグ修正、性能改善——どんな変更も、まず「今どうなっているか」を解読するところから始まります。この解読の時間は、本来の開発時間とは別に発生する純粋なオーバーヘッドです。
②は、人の入れ替わりが致命傷になることです。理解している人が一人しかいないシステムは、その人が辞めた瞬間にブラックボックスになります。AIコーディングが普及した現在、この属人性はさらに奇妙な形を取ります。「○○さんが作った」のではなく、「○○さんがAIと一緒に作った、でも○○さん自身も細部は覚えていない」——という状態です。この場合、誰に聞いても答えが返ってきません。
③は、意思決定が遅くなることです。「このシステムに手を入れるべきか」「リプレイスすべきか」——経営判断を下すために必要な情報が、社内の誰にも答えられない状態になります。CTOがシステムの全体像を把握できないというのは、組織にとって相当に危険な状態だと私は考えています。
これらのコストは、財務諸表には現れません。しかし確実に存在します。「コードは残るが、仕様は誰も知らない」は、将来の話ではなく、すでに多くの現場で起きている現在の話なのです。
なぜこの問題は、これまで解決されてこなかったのか
少し構造に踏み込んでみたいと思います。
「技術ドキュメントは重要である」という議論は、ソフトウェア開発の歴史上、繰り返し言われてきました。それなのに、どの現場でも同じ問題が起き続けています。なぜでしょうか。
理由はシンプルで、「書く」コストと「得られる価値」のタイミングがずれているからだと私は捉えています。
ドキュメントを書くコストは、今、書いている人間が払います。書いている本人は、書かなくてもコードを理解しています。だから、書くことによる恩恵を最も受けるのは、書いた本人ではなく、未来の誰か——数ヶ月後の自身、新しく入ったメンバー、退職後の後任者——です。
このコストと価値の非対称性が、ドキュメント文化が定着しない根本原因だと考えています。どんなに「書きましょう」と号令をかけても、書くインセンティブが構造的に弱いままなのです。
そしてAIコーディング時代には、このインセンティブの弱さがさらに加速します。実装が速くなるほど、次のタスクに移る圧力が強くなります。「とりあえず動いた」で先に進むことが、短期的には合理的な選択肢になってしまうからです。
この構造問題は、個人の意識や、ツール導入だけでは解けません。「書く」コストを下げるか、「書かなくても残る」仕組みを作るか——どちらかが必要になってきます。AIが10倍速くコードを書く世界で、ドキュメントは一体どこへ消えていくのか。この問いについては、今後の記事で改めて掘り下げていく予定です。
それで、何を考えればいいのか
この記事を締めるにあたって、ひとつだけ提案させてください。
「ドキュメントを書く文化を作ろう」という号令は、たぶん今回も失敗します。これまでと同じ構造で解こうとしても、これまでと同じ結果にしかなりません。
問うべきは、別のことです。「書かなくても、あるいは書く負担を最小化しながら、仕様がチームに残る仕組みをどう作るか」——この問いを立てること自体が、次の時代の開発組織に求められる視点だと、私は考えています。
AIが実装を加速させている今、仕様の保存にもAIが使えるのではないか、という方向に思考が向かうのは自然な流れです。その可能性と現実的な限界、そして「技術ドキュメント問題」の全体像については、今後の記事で順を追って掘り下げていきます。
まずはこの記事で、「コードは残るが、仕様は誰も知らない」という言葉を、頭の片隅に置いていただければと思います。ご自身のチームのコードベースを眺めたときに、この言葉が少しでもザラっとひっかかるとすれば、その感覚はおそらく正しいものです。
まとめ
AIコーディングが普及した開発現場で静かに進行しているのは、「コードは残るが、仕様は誰も知らない」という構造問題です。コードの書き手にも文脈がなく、実装速度と理解速度は乖離し、「動いている」という事実が問題の存在を隠します。これは個人の怠慢でも、ツールの不在でもなく、書くコストと得られる価値のタイミングがずれているという構造そのものの問題です。この問題を解くには、「書かせる」のではなく「残る仕組みを作る」という発想の転換が必要になります。
あなたの組織で、5年前に作られたシステムの「なぜこの設計になっているか」を答えられる人は、今、何人残っているでしょうか。
次回以降、この問題の人的側面——エンジニアが退職するとき、コードは引き継げても文脈は引き継げない、その非対称性についても順を追って掘り下げていきます。