📌 完全版（インタラクティブな SVG 図解 5 枚付き）はこちら
👉 https://okikusan-public.pages.dev/context-is-the-gap
本記事は Qiita 向けの要点版です。可視化込みの本文は上記の本家サイトでご覧ください。
はじめに
AI エージェントの精度は、プロンプト技巧よりもコンテキストで決まる場面が増えている。
ここでいうコンテキストは、整えられた仕様書のことではない。本当に効くのは、仕様書と Source of Truth のギャップそのものと、「なぜズレたか」の理由を蓄えることだ。
仕様書だけ読ませた AI は「過去の正しさ」を再現する。差分理由まで読ませると「今の正しさ」に近づける。Spec-Driven Development の流行の盲点と、Harness Engineering の本当の核を整理する。
TL;DR
- AI エージェントの精度は、モデル単体 → プロンプト → コンテキストと頭打ちの先が移ってきた
- 「コンテキスト」を整った仕様書だと誤解すると、AI は 「過去の正しさ」を再現 する
- 本当に効くのは「なぜズレたか」の差分理由。仕様変更 / 例外許容 / 実装妥協 / issue 議論 / レビュー判断、5 つの "なぜ" を蓄えるかどうかで AI の出力品質が変わる
- 資料は整えるもの、コンテキストは蓄えるもの。仕様書は Harness の核に置きつつ、差分理由を外側に重ねる
仕様書 vs Source of Truth ── ギャップは必然
仕様書は "こうあるべき" を書く。ある時点での合意で、整合性が取れている。
でも実装や運用が進むと、実際の "正" は別の場所に寄っていく：
- 動いているコード ── ハードコード・例外ハンドリング・コメントアウトされた古い分岐
- DB のスキーマと実データ ── マイグレーション履歴 / 想定外のレコード
- API の実挙動 ── ドキュメントに書かれていないレスポンス / 非公式エンドポイント
- 顧客運用の判断 ── 仕様書に書いていない承認ルート / 暗黙の例外
- 現場判断 ── オペレータがその場で下した判断
これらが Source of Truth (SoT)。仕様書は時間が経つにつれて SoT から乖離する。これは怠慢ではなく、必然的に起こる。
問題はギャップが「ある」ことではない。そのギャップが説明されていない ことだ。
仕様書だけ読ませた AI は "過去の正しさ" を再現する
典型的な失敗：
- 「仕様書では X が正と書かれていますが、コードでは Y です」→ 仕様書を信じて X を答え、現実とズレる
- 「仕様書には例外処理が書かれていないので、エッジケースは無視できます」→ 運用上ありえない誤判断
- 「最新の API ドキュメントに従って実装しました」→ 非公式の運用ルールを見落とす
これは AI が悪いのではない。食わせたコンテキストが古い時点で固まっている から、その時点に対して忠実に動いただけ。整った仕様書ほど、AI は安心して「過去の正しさ」を引用してしまう。
リバースエンジニアリングだけでも足りない。コードから読み取れるのは「何が・どう実装されているか」だけで、「なぜそうなったか」はどこにも書かれていない。
5 つの「なぜ」を蓄えれば、強いコンテキストになる
| # | 何を残すか | どこに残せるか |
|---|---|---|
| 01 | なぜ仕様を変えたか | 変更履歴 / 議事録 / Slack ログ |
| 02 | なぜ例外を許したか | 運用判断ログ / 個別対応メモ |
| 03 | なぜこの実装で妥協したか | コードコメント / PR コメント |
| 04 | なぜ issue でこう議論されたか | issue / discussion |
| 05 | なぜレビューでこの判断になったか | PR レビューコメント |
これらは Nonaka の SECI モデルでいう 表出化（Externalization） そのもの。違いは 結論ではなくプロセスを表出化する こと。プロセスが残るからこそ、別の文脈でも判断パターンが再現できる。
資料は整えるもの、コンテキストは蓄えるもの
| 資料（DOCUMENT） | コンテキスト（CONTEXT） | |
|---|---|---|
| 対象 | 人間 / クライアント | AI エージェント |
| 性質 | 整合性・一貫性・完成度 | 判断材料・矛盾・揺れ・迷い |
| 例 | 提案書 / 仕様書（最終版） / 記事 / マニュアル | issue / PR レビュー / 運用メモ / 失敗ログ / ラフメモ |
| 動作 | 整える | 蓄える |
矛盾を許容するのが核。「コンテキスト = 思考プロセス」と捉えると、矛盾を含むのは当然になる。人間の判断は常に揺れているし、組織の決定は時間とともに上書きされる。これを除去せず残せるか が、AI エージェントが「あなたらしい判断」を再現できるかの分かれ目になる。
Harness の核は仕様書、外側は差分理由のレイヤー
Agent = Model + Harness（Karpathy 由来）。SDD だけでは不十分で、SDD の "外側" を設計する 必要がある。
SDD と並んで「Issue Driven Development（IDD）」を提唱する声もあるが、本記事の論と相性が良い ── SDD = 仕様の正、IDD = 差分理由の正、と分担すれば両立する。
良い AI = 確認負荷を下げる量
2026 年 5 月、Linux カーネル 7.1 RC4 公開時、リーナス・トーバルズが AI による脆弱性報告の急増 でセキュリティメーリングリストが「almost entirely unmanageable（ほぼ管理不能）」になったと表明した1。2 年前は週 2-3 件だった報告が、AI ツール経由で 1 日 5-10 件 に。
Linus 自身は「AI 活用そのものを否定しない。ただしコードを理解し、修正パッチまで用意する形で貢献せよ」と求めている。
これは AI エージェント運用一般の縮図だ。AI の価値はアウトプット量ではなく、人間の確認・修正・検証負荷をどれだけ下げるかで決まる。
仕様書だけ食わせた AI は、それっぽい回答を量産する。一見正しいが、SoT と乖離していて、人間が一つひとつ確認しないと使えない ── これが "Slop"（AI 生成の低品質・凡庸・テンプレ的な出力）の典型例。差分理由まで食わせた AI こそが、人間の確認負荷を下げる本物の AI になる。
まとめ — 整えるのではなく、蓄える
AI エージェントの精度を上げる方法は、もはやモデルでもプロンプトでもない。仕様書と Source of Truth のギャップ、そして「なぜズレたか」の理由を蓄えられているかどうか に移った。
- 資料は整える（対象は人間 / クライアント）
- コンテキストは蓄える（対象は AI / 矛盾も揺れも残す）
- 仕様書は Harness の核、その外側に "なぜズレたか" を重ねる
SDD の流行で「仕様書を磨く」方向に注力する組織は多い。だが本当の差別化は、仕様書を整えることではなく、SoT との差分を蓄えること にある。「過去の正しさ」を再現する AI を作らないために、いま整えることをやめて、蓄えることを始める。
📌 完全版（SVG 図解 5 枚込み）はこちら
👉 https://okikusan-public.pages.dev/context-is-the-gap
- FIG.0 — THE GAP（仕様書 vs SoT 乖離曲線）
- FIG.1 — SPEC-ONLY VS SPEC + GAP（2 つの AI 比較）
- FIG.2 — FIVE WHYS（5 つの "なぜ" 構造）
- FIG.3 — DOCUMENTS VS CONTEXT（資料 vs コンテキスト二軸）
- FIG.4 — HARNESS LAYERS（仕様書を核とした同心円）
参考になったら LGTM・コメントいただけると励みになります 🙏
関連記事
- コードでは書けない領域に降りる AI エージェント — ロングテール × 暗黙知 × 暗黙考 — 本記事の哲学的前提
- Hermes Agent — 第二の脳の実行エンジン — Harness 実行基盤の具体例
- 「AI で消える職種」より「職種の中の業務」を見ろ — Applied Engineer / FDE 論
-
The Register (2026-05-18): Linus Torvalds says AI-powered bug hunters have made Linux security mailing list 'almost entirely unmanageable' / Tom's Hardware (2026-05-18): Linus Torvalds says flood of duplicate AI-generated vulnerability reports... ↩