仕様は残すな、接続しろ¶

対象 / ポイント

対象: Claude Code や Codex のような AI エージェントを日常的に使い始めた開発者、あるいは導入を検討しているテックリード・開発プロセス設計者。仕様をどこまで書くか、どう効かせるかの判断軸を探している人。

ポイント:

AI 時代の仕様化で問うべきは「書くか書かないか」ではない。使い捨てるのか、永続資産にするのか。永続化するなら検証や制約にどこまで接続されているのかである
ここでいう「薄い仕様駆動」とは、軽量であることではない。仕様を残しているのに、テスト・制約・証跡へ十分つながっていない状態を指す
接続にも段階がある。agent に参照される → 更新が強制される → 実装を生成する → 検証系で正しさが確認される、と保証の強度は上がっていく
コンテキストウィンドウ経由で効く知識と、実行結果経由で効く知識は構造が違う。後者はコンテキスト消費を必要な時点まで遅延させ、スケールしやすい

仕様書不要論の核心は「中間コスト論」である¶

いまの AI コーディングでは、Claude Code も Codex も、コードを読み、編集し、コマンドを実行しながら作業を進める前提を公式に置いている¹²。

この前提に立つと、仕様書不要論が支持される理由はかなり明快だ。AI が直接読めるのはコード、テスト、設定、差分、実行結果である。ならば人間が自然言語で一度「翻訳」した仕様書は、書くコストと更新コストがかかり、コードとズレやすく、しかも AI は元のコードを直接読める——という具合に、中間コストに見えやすい。

つまり仕様書不要論の核心は「ドキュメント嫌い」ではない。AI が一次情報を直接読めるなら、人間が作る中間翻訳物は構造的に非効率ではないか、という問いである。この問題提起自体はかなり当たっている。

「仕様書あり vs なし」の二択は、切る軸が間違っている¶

ここで最もやってはいけないのが、議論を「仕様書あり vs なし」の二択にすることだ。この二択は、議論をほぼ確実に噛み合わなくする。

なぜなら、「仕様書あり」の中身が人によってまったく違うからだ。社内 Wiki に置いたきりの設計書を指す人もいれば、スキーマ定義からのコード生成を指す人もいる。agent の設定ファイルに参照先を書いて hooks で更新を強制する運用を指す人もいれば、テスト契約とポリシー検査のセットを指す人もいる。これらを「仕様書あり」で束ねた瞬間、議論は空転する。

本当に切るべき軸はそこではない。AI 時代の仕様化は、次の2軸で見た方がよい。

軸1：仕様化を使い捨てるのか、永続化するのか。

軸2：永続化するなら、検証や制約に接続されているのか。

この2軸で整理すると、少なくとも3つの型が見える。

型	何をしているか	特徴
使い捨て仕様型	その場で要件整理・計画をするが、永続資産としては残さない	速い。探索・試作向き
未接続の永続仕様型	spec は書いて残すが、テスト・制約・証跡に十分つながっていない	コストだけ増えやすい
接続された永続仕様型	spec を残し、テスト・契約・ポリシー・証跡に接続する	厳格運用向き

この記事で批判したいのは、真ん中の「未接続の永続仕様型」である。仕様を書いているのに、後段の検証に効いていない状態だ。

なお、この記事が扱っているのは AI agent に実装を統治させたい仕様の話である。人間同士の合意形成・オンボーディング・監査証跡が主目的の仕様は、agent 接続がなくても十分機能する場面がある。以下の議論は、agent に仕様を守らせたいのに守らせる仕組みがない、という状況に焦点を当てている。

plan-only は「仕様の不在」ではなく「仕様の使い捨て」である¶

plan-only と言うと仕様が存在しないように聞こえるが、実際には Claude Code でも Codex でも、作業の中で要件整理や手順分解のような構造化は行われている¹²。plan-only を正確に言い直すなら、仕様がないのではなく、仕様化を永続資産として扱わないということだ。

その場で整理する。必要なら AI にタスク分解もさせる。しかし、それを後からトレーサビリティや監査や回帰管理の中心にはしない。

この型は、個人開発・試作・小規模な内部ツールではかなり合理的である。目的が「長期統治」ではなく「早く作って確かめること」だからだ。spec なしで小さく作り、小さく壊し、小さく直す。探索目的なら整合的だ。

ここでいう「薄い仕様駆動」は、軽量な仕様のことではない¶

ここが最も誤解されやすい。「薄い仕様駆動」と言うと「軽量な spec は全部ダメ」に見えやすい。だがそうではない。

ここでいう「薄い」とは、密度が低いことではなく、接続が弱いことを指す。

薄い仕様——spec は書く、保存もする、だがテストや制約に十分つながらない。変更影響も追えない。結果として「読むための文書」以上にならない。

軽い仕様——スコープを限定している、仕様の量は少ない。しかしその範囲では受け入れ条件やテストに接続している。だから中規模のアプリ開発では普通に機能する。

つまり軽量であることと薄いことは同じではない。この区別を入れると、「中規模なら軽い仕様で十分機能する場面はある」という話と「薄い仕様駆動が弱い」という話は矛盾なく両立する。

接続にも段階がある¶

ここまで「接続あり / なし」の二値で話を進めてきたが、実務では接続にグラデーションがある。大きく4段階に分けられる。

段階	何を保証するか	具体例
visibility（参照される）	agent が仕様の存在を知っている	CLAUDE.md に仕様の参照先を記載する
sync（更新される）	仕様の鮮度が保たれる	hooks や CI で commit 前に仕様更新を強制する
generation（生成に使われる）	仕様と実装の構造的一致	OpenAPI / JSON Schema / IDL からコードを生成する
verification（ガードレールになる）	仕様の正しさが機械的に確認される	spec → test case、contract test、policy as code

これらは組み合わせで効く。visibility → sync → verification は保証の強度がこの順に上がっていく主系列であり、generation は形式的なスキーマ定義がある領域で機能する補強手段で、省略しても verification 接続は成立する。

注意すべきは2点ある。visibility だけでも、何もないよりはるかにマシだ。agent の設定ファイルに「このドキュメントを読め」と書くだけで、仕様を無視する確率は下がる。コストはほぼゼロで、多くのチームにとって最初の一歩はここになる。

一方で sync は「更新されている」ことを保証するが、「正しい」ことは保証しない。更新が回っていても中身が間違っている可能性は残る。

この記事で「未接続」として批判しているのは、visibility すらない、あるいは visibility はあるが sync にも verification にも至っていない状態だ。visibility + sync の段階にいるチームを一括で「薄い」と切り捨てる意図はない。

なぜ verification 接続が構造的に強いのか——コンテキストエンジニアリングの観点¶

段階の違いを理解するには、知識が agent に「効く」経路に注目するとわかりやすい。

経路1：コンテキストウィンドウ経由で効く。

agent が仕様ドキュメントを読み、理解し、従う。visibility や sync はこの経路で機能している。

この経路の特性は明確で、コンテキストを消費する。仕様ドキュメントが増えるほど agent が読むべきテキストが増え、コード本体や差分に使えるコンテキストが圧迫される。しかも agent が「読んだ」ことと「従った」ことは別であり、遵守は確率的で決定論的ではない。

実務的な手触りとしては、モジュールが数十に及び、それぞれに設計仕様・制約・変更履歴がある規模になると、「全部読ませる」のは現実的でなくなってくる。agent の検索・要約で部分的に絞ることはできるが、関連仕様の取捨選択自体が確率的になるという問題は残る。

経路2：実行結果経由で効く——ガードレールとして機能する。

テストが落ちる、schema validation が reject する、hooks が commit を止める。agent は仕様を事前に「読んで理解する」必要がない。実行して、止められて、失敗メッセージを見て直す。

この経路が「ガードレール」と呼ばれるのは、agent の振る舞いを事前に読ませた知識で律するのではなく、逸脱した時点で自動的に止める構造だからだ。人間のコードレビューに頼らずとも、仕様から外れた実装は通過できない。

仕様ドキュメントを毎回前提知識として読ませる方式に比べて、この経路はコンテキスト消費を必要な時点まで遅延させられる。agent は仕様全文を常時保持する必要がなく、テストが落ちた時点ではじめて関連する仕様や設計意図を読みに行けばいい。コンテキスト消費がゼロになるわけではないが、「常時全文を持つ」から「失敗時に必要な分だけ参照する」に変わることで、スケーラビリティは大きく改善する。

つまり verification 接続が構造的に強い理由は3つある。

ひとつは、ガードレールとして正しさが機械的に確認できること。ふたつめは、コンテキスト消費を必要最小限に遅延させながらスケールできること。ここまではテストや schema validation という実行系の仕組み自体が持つ性質であり、仕様接続がなくても TDD 的に書いたテストで同じ効果が得られる。

3つめが仕様接続に固有の価値で、トレーサビリティだ。「なぜそのテストが存在するのか」「仕様変更時にどのテストを見直すべきか」——仕様と検証系が紐付いていることで、変更影響の追跡が可能になる。テストだけが存在して仕様との対応関係がなければ、テストの追加・削除・修正の判断は人間の記憶に依存する。仕様接続はその依存を構造で置き換える。

なぜ未接続の永続仕様が最も費用対効果が悪いのか¶

ここまでの議論を踏まえると、理由は2つに整理できる。

理由1：書くコストは残るのに、仕様が仕事をしない。

使い捨て仕様型は速さに振っている。後から残る資産は薄いが、それを前提にしているので整合的だ。接続された永続仕様型は重いが、その重さはテスト・契約・ポリシー・証跡・変更影響分析に変換される。厳格性が必要な領域では重さに見合うリターンがある。

一方で未接続の永続仕様型は、spec を書き、保存し、更新も気にするが、テストや制約には十分つながらない。変更時にも影響範囲が追えない。仕様を書いて維持するコストだけが残り続ける。

前述のとおり、この記事が扱っているのは agent に仕様を守らせたい文脈だ。未接続の永続仕様にも、レビュー時の設計意図確認やオンボーディングといった人間向けのリターンはある。だがそれを差し引いても、agent に仕様を守らせたいのに守らせる仕組みがガードレールとして機能していないなら、書いて維持するコストに見合う成果が返ってこない。

ここで「ならテストとスキーマだけ書けばよく、自然言語の仕様は結局要らないのでは？」と思うかもしれない。だが接続された仕様の世界でも、自然言語ドキュメントには固有の役割が残る。テストコードは「何を満たすべきか」を記述するが、「なぜその判断をしたか」は記述しない。設計意図・業務背景・変更時の影響起点——これらは自然言語でしか表現できず、agent がテスト失敗から修正に向かう際にも、この情報を参照する場面は出てくる。

つまりこの記事の主張は「自然言語仕様を廃止せよ」ではなく、「自然言語仕様を検証系に接続せよ——接続されていない自然言語仕様なら、書かない方がまだマシだ」ということだ。

逆方向の疑問もあるだろう。冒頭で仕様書不要論の核心を「中間翻訳コスト」だと整理した。ならば、自然言語仕様をテストや contract やスキーマ定義に変換する作業も、結局は中間翻訳コストの別形態ではないか——と。

だがこの2つには構造的な違いがある。読まれるだけの自然言語仕様は、書いた瞬間からコードとの乖離が始まり、更新されなければ静かに腐る。一方、テスト・スキーマ・contract は実行される。実行されるから、仕様とコードの乖離が起きた瞬間に失敗として検知される。つまり、実行可能な形式への変換は「中間翻訳」ではなく「最終形態への変換」であり、変換先が自律的に鮮度を維持する点で、読まれるだけの文書とは性質が違う。

理由2：コンテキストウィンドウを食い続けるが、スケールしない。

仕様を永続化して agent に読ませるアプローチは、コンテキストウィンドウ経由で効く知識に依存している。仕様が増えるほどコンテキストが圧迫され、agent の作業品質が下がるリスクがある。それでいて遵守は確率的だから、仕様を増やしても保証は比例して強くならない。

速さを取りたいなら使い捨てにした方がまだ正直だ。厳格性を取りたいなら verification 接続——つまりガードレール化——までやらないと、コストに見合わない。だから永続化しているのに効かない仕様が、最も費用対効果が悪く見える。

使い分けは「思想」ではなく「レイヤー」の問題である¶

ここまで来ると、議論はかなりシンプルになる。

個人開発・試作 → 使い捨て仕様型でよい。速さが正義である。

中規模アプリ開発 → visibility + sync の段階で十分機能する場面は多い。agent の設定ファイルに仕様の参照先を書き、hooks で更新を促す。generation が使える部分（API 定義、Schema 等）は積極的に使う。ここでは「軽いが接続されている」仕様が有効であり、「薄いが未接続」とは異なる。

基幹システム・規制業務 → sync だけでは足りない。仕様をガードレールとして機能させる——verification 接続まで行かないと、仕様が正しいことの保証も、コンテキストのスケーラビリティも確保できない。ただし verification の構築には初期コストがかかる。spec と test case の紐付け、contract test の設計、policy as code の整備——これらは一朝一夕には揃わない。だからこそ、必要な領域を見極めて段階的に接続を強化する判断が要る。

したがって論点は「仕様駆動か否か」ではない。仕様化を永続資産として扱うなら、どの段階の接続まで持つか——これが本当の問いである。

おわりに¶

AI がコードを直接読めるなら仕様書は中間コストに見える。この感覚は間違っていない。

ただし、そのことは「仕様を書くな」を意味しない。本当に分けるべきなのは、使い捨てる仕様なのか、永続化する仕様なのか、永続化するなら検証や制約にどの段階まで接続されているのか——である。

接続には段階がある。agent に参照されるだけでも効果はある。更新が強制されれば鮮度は保たれる。しかし、ガードレールとして正しさを機械的に確認し、コンテキストのスケーラビリティを確保するには、verification 接続まで必要になる。

そして最も費用対効果が悪いのは、仕様を書いて残しているのに、どの段階の接続にも至っていない状態だ。仕様は、残すだけでは資産にならない。少なくとも AI agent に効かせたい仕様なら、接続してはじめて仕事をする。

この「接続」の論理は、仕様書に限った話ではない。アーキテクチャ決定、コーディング規約、レビュー基準——agent に一貫して守らせたいあらゆる知識に同じ構造が適用される。ドキュメントを書くことと、それを機械的に効かせることは別の営みだ。後者のデザインこそが、agent 時代の開発プロセス設計の中心になっていく。