8月17日、O'Reillyのエンジニアリングブログ「Radar」にMarkus Eiseleが「When AI Writes the Code, Specifications Need an Exit Strategy」と題した記事を公開した。AIエージェントがコードを生成する時代において、仕様書（Markdownスペック）が果たすべき正しい役割と、その管理・削除戦略について論じたものだ。
AIエージェントがコードを量産できるようになった今、多くのチームが別の問題に直面している。リポジトリを開くと、コードの隣に「第二のシステム」が出現しているのだ。要件定義、調査メモ、高レベル設計・低レベル設計、実装計画、タスクリスト、レビューレポート……増殖し続けるMarkdownファイルの山。そしてコードは先週火曜日に大きく変わったのに、最後にドキュメントが更新されたのは数週間前、という状況。
Eiseleは長年にわたり企業システムの開発に携わってきたエンジニアであり、Javaチャンピオンでもある。
仕様書は「永続する真実」ではなく「変更のための道具」
Eiseleの主張の核心はシンプルだ。仕様書は変更が完了した時点で、大部分を削除すべきである。
「仕様書をソフトウェアの恒久的な自然言語コピーとして扱うのが間違いだ。有用な仕様書は次の変更を記述し、その変更を駆動する意思決定を文書化し、境界を設定し、検証の足場を提供する。変更がリリースされたら、その大部分は削除されるべきだ。」
これは「一切の仕様書が不要」という主張ではない。Eiseleが問題視しているのは、変更が完了した後も生き続ける「死んだ仕様書」の蓄積だ。変更を駆動するために必要だった文書が、役目を終えた後も削除されず残り続けることが問題の本質である。
現在のエージェント駆動開発では、コード生成を制御しようとして、実装前に大量の思考をMarkdownに落とし込む。要件、設計アプローチ、受け入れ基準——これらがワークフローの中心になる。しかし皮肉なことに、このMarkdown群は現代のエージェントのコンテキストウィンドウの大部分を埋め尽くす。エージェントはやがてコードベースという「より強いシグナル」に注意を移し、仕様書の更新を忘れていく。
かつてのウォーターフォール開発で経験したこととまったく同じ失敗を、AIの時代に再演しているわけだ。
何を残し、何を捨てるか
Eiseleが提唱するのは「change brief（変更ブリーフ）」という概念だ。「仕様書（specification）」という言葉は重厚で完全性を装うが、実際には変更に必要な最小限の情報しか要らない：
- 意図する成果と非目標（必要な場合のみ）
- 既知の未知事項と人間の判断が必要な意思決定
- 影響を受けるシステム境界と権威あるインターフェイス成果物
- 現状と異なる機能・非機能制約
- リスクのあるパスをカバーする受け入れ基準・テストシナリオ
変更がリリースされたら、耐久性のある情報はソフトウェアチームがすでに管理方法を知っている成果物に移行する：
- コード（実行可能な唯一の真実）
- スキーマ（OpenAPI、AsyncAPI、型定義、DBの制約）
- ポリシー（アクセス制御、静的解析ルール）
- テスト（安定した検証レイヤー）
- ランタイムのテレメトリー（本番の振る舞いを観測するシグナル）
例えば、APIの形状と互換性はOpenAPIやプロトコルスキーマに、データの不変条件は型やDBの制約に、セキュリティルールはアクセスポリシーやランタイム強制に落とし込む。これらの成果物はデリバリーの一部であり、スキーマチェックが失敗すれば対処が必要になる。一方、古い設計フォルダの対応する段落は誰も読まない。
コードが「事実」であり、文書はデルタのためにある
Eiseleの論点で特に鋭いのが「Code is the fact（コードが事実だ）」という考え方だ。
本番にデプロイされたコードは、ユーザーや接続システムが依存している。バグでさえ、3年間同じ挙動をしていれば「観測されたコントラクト」になる。仕様書が異なる振る舞いを定義していても、誰も仕様書を確認しない。自然言語のサマリーを読んでも、ランタイムの振る舞いを正確に反映できない。
一方でコードが対応できないのは「次のバージョン」だ。エージェントはコードから技術的なパターンを推測できるが、ポリシー変更や将来の機能要求を予測する手段はない。特定顧客向けに毎晩だけ動くエクスポートがなぜ存在するか、という文脈はどこかから供給しなければならない。ただしそれは「システム全体の恒久的な散文的記述」を要求しない——変更の差分（デルタ）を決定するために必要な最小限のコンテキストがあれば十分だ。
コンテキストはエンジニアリングの予算である
大規模な仕様書の本当のコストは、執筆・維持にかかる時間だけではない。エージェントが現在の意思決定に必要なコードや証拠と競合する。すべての要件定義、設計メモ、リポジトリへの指示、ツール定義が限られたワーキングコンテキストを消費する。古くなった・重複した資料に重要なルールが埋もれると、エージェントはそれを見落とす。
Eiseleが推奨するのは「プログレッシブ・ディスクロージャー（段階的な情報開示）」だ。エージェントには小さなマップ、広く適用できる安定したルール数個、そして深い資料へのポインタを渡す。AGENTS.mdにはビルドコマンド、リポジトリのレイアウト、アーキテクチャの境界を記録する。すべてのクラスを解説したり、APIドキュメントを繰り返したりしてはならない。
また、エージェントに仕様書の初期バージョンを生成させるリスクにも言及している。長いワークフロー実行が調査だけでなく要件・設計・計画・レビューの成果物を直接導出する場合、完全性ゆえにすべてが制御されているように見えるが、人間のレビュアーへの負担は指数関数的に増える。モデルが特定の繰り返し表現に誤った注意を向ける確率も高く、複数のドキュメントを整合させ続けることが困難になる。
判断はワークフローに属する
Simon Willisonはコーディングエージェントに「成果を与えてタスクが必要とするプロセスの量を自ら判断させる」というアプローチを提唱している。「自動テストが必要か」「ルーティンな実装は安価なモデルに委譲できるか」——これをあらかじめ定めたプロセスの分岐リストで制御しようとするのではなく、「作業に合った戦術を選択せよ」という単一の期待値に置き換えるという考え方だ。Eiseleはこの考えを援用しつつ、変更のリスク水準に応じてプロセスを選択すべきと論じている。
その具体的な指針は以下のとおりだ：
- 小さく馴染みのある変更：短いブリーフから実装・レビューへ。ほぼワンショットのプロンプトで完結
- 馴染みのないコード：設計前に事実調査。コードベースの探索と実装詳細の特定が先決
- 不明確なUX：プロトタイプと比較。場合によってはユーザー調査を挟む
- アーキテクチャの変更：人間による明示的な合意が必要
- 高影響の振る舞い：独立した強力なエビデンスと承認を要する
重要なのは、これらを固定されたゲートとして運用するのではなく、変更の性質に応じて判断を変える姿勢そのものだ。すべての変更を同じ儀式から始めることは、時間とコンテキストを無駄に消費するだけである。
AIが高速にコードを書く時代だからこそ、仕様書の「出口戦略」——いつ、何を、どこに移行して削除するか——を設計することがチームの生産性を左右する。詳細はWhen AI Writes the Code, Specifications Need an Exit Strategyを参照していただきたい。
