AIエージェントに「文脈」を渡す技術 — 仕様書の構造がすべてを決める
AIエージェントに渡すドキュメント、本当に「読まれて」いますか
「仕様書を渡したのに、AIが意図通りに動かない」
そういう話を、AIを使ったシステム開発に取り組む現場からよく聞く。ツールの使い方が悪いのか、プロンプトが不十分なのか。あれこれ試してみても、根本的な問題が解決しないことがある。
実は、問題の多くはドキュメントの構造にある。
AIエージェントに渡す情報を、どういう形で、 どういう構造で用意しているか。これがAI活用の精度を大きく左右する。
「文脈」がないと、AIはただ読み上げるだけになる
Andrej Karpathy（Tesla元AI責任者、OpenAI共同創業者）が最近、LLMを使った知識ベース構築について興味深い考え方を発表した。
彼のアプローチはシンプルだ。生のドキュメントをLLMに渡すだけでなく、LLMに情報を構造化させてwikiとして蓄積し、以後のクエリはそのwikiに対して実行するという設計だ。
具体的には三層構造になっている。
- 第一層（Raw）: 生のソース情報（議事録、設計書、仕様書など）
- 第二層（Schema）: 情報の整理ルールと構造定義
- 第三層（Wiki）: LLMが生成・維持するMarkdown形式のエンティティページ群
重要なのは、人間がwikiを書くのではなく、LLMが継続的に整理・更新するという点だ。単なるRAG（検索拡張生成）との違いはここにある。RAGは毎回ドキュメントから断片を拾い集めるが、Karpathyのアプローチでは事前にLLMが「意味のある構造」に変換しておく。
これは、AIエージェントに渡す仕様書を考える上で、本質的なヒントを与えてくれる。
仕様書の「構造問題」——なぜAIは読めないのか
私たちが現場で仕様書を扱う中で気づいたことがある。
同じ内容を書いても、AIが正確に解釈できる仕様書と、そうでない仕様書がある。その差はどこにあるのか。
問題①：「暗黙知」が多い
「この機能は前回の打ち合わせで決まったアレ」という文脈は、会議に参加した人間なら分かる。だがAIには分からない。
日本の開発現場では、意外なほど多くの重要な情報が「言葉にされていない」。画面遷移の理由、仕様を変更した経緯、ステークホルダーの優先順位感覚。これらが文書化されていないと、AIは表面的な記述しか理解できない。
問題②：「構造」ではなく「物語」で書かれている
多くの仕様書は、人間が読むことを前提に書かれている。論理的な構造よりも、読みやすさや説得力が優先される。
ところがAIにとっては逆だ。エンティティ（ユーザー、機能、状態、条件）が明確に定義されて相互に参照されている構造の方が、長い説明文より遥かに理解しやすい。
問題③：「更新が止まった」ドキュメント
開発が進むにつれて、仕様書と実装が乖離していく。これは人間の開発者にとっても問題だが、AIにとってはさらに致命的だ。AIは文書の記述を信頼する。古い仕様書を渡せば、古い仕様に従って動く。
コンテキストエンジニアリングという考え方
最近、「プロンプトエンジニアリング」の次のステップとして「コンテキストエンジニアリング」という概念が注目されている。
プロンプトは「AIに何を聞くか」の設計だ。コンテキストは「AIに何を見せるか」の設計だ。
後者の方が、実は遥かに影響が大きい。
優れたコンテキストエンジニアリングの原則をまとめると、以下のようになる。
| 原則 | 意味 |
|---|---|
| 構造化 | 箇条書き・表・定義の明確化で情報をエンティティ単位で整理 |
| 参照可能性 | 「前述の〜」ではなく固有名詞・IDで一意に参照 |
| 最新性 | ドキュメントが現在の状態を反映しているか継続的に確認 |
| 境界の明示 | 何がスコープ内で、何がスコープ外かを明示 |
| 意図の記録 | なぜその仕様になったかの背景を残す |
これは、人間のチームにとっても良い仕様書の条件と重なる。AIを意識して仕様書を改善すると、人間のコミュニケーションも自然に改善される。
実際にやってみると——仕様書を「AIが読める形」に変えた現場
ある開発チームで、既存の仕様書をAI向けに再構造化した事例がある（企業名は伏せる）。
彼らがやったのはシンプルな変換だ。
変更前: 「ユーザーがログインした後、権限レベルに応じて表示されるメニューが変化する。管理 者の場合は...」（長文説明）
変更後:
## ユーザー認証後の画面制御
### 定義
- ユーザー種別: {一般, 管理者, 閲覧専用}
- 権限レベル: {読取のみ, 読取+書込, フルアクセス}
### ルール
| ユーザー種別 | 権限レベル | 表示メニュー |
|---|---|---|
| 一般 | 読取+書込 | A, B, C |
| 管理者 | フルアクセス | A, B, C, D, E |
| 閲覧専用 | 読取のみ | A のみ |変換後は、AIエージェントが仕様の矛盾を自動検出できるようになった。「このユーザー種別の権限定義が他の箇所と矛盾している」という指摘が来るようになったからだ。
つまり、仕様書を構造化することで、AIが品質チェックのパートナーになる。
AIエージェント時代に「要件定義」が変わる理由
AIエージェントを開発フローに組み込む動きが加速している。コードを書くエージェント、テストするエージェント、レビューするエージェント。
これらが効果的に機能するためには、共通の「文脈」が必要だ。
Karpathyの知識ベース設計が示唆するのは、AIエージェントが使いこなせる形で情報を事前に整備しておくという考え方だ。仕様 書もその例外ではない。
「AIに渡すだけで勝手にやってくれる」という段階には、まだない。だが「AIが活用できる構造で情報を整備する」ことで、エージェントの精度は劇的に上がる。
これが、私たちが開発中のKakusillで解決しようとしている課題でもある。仕様書をAIネイティブな構造で管理し、矛盾検知・要件抽出・依存関係の可視化を実現する。要件定義という上流工程を、AIとチームが協働できる場所にする。
まとめ——「仕様書の質」がAI活用の天井を決める
AIツールを使いこなしても、インプット（仕様書・要件書）の質が低ければ、アウトプットの質は上がらない。これはAIに限らない話だが、AIが介在することで問題がより表面化しやすくなった。
構造化された仕様書は、AIのためだけでなく、チーム全体の認識を揃える道具でもある。コンテキストエンジニアリングは、AI活用の技術的な話であると同時に、チームのコミュニケーション設計の話でもある。
「AIが読める仕様書」を作ることで、チームも読みやすい仕様書になる。その往復が、AI時代の上流工程の本質だと思っている。
*AIネイティブな仕様書管理に関心がある方は、Kakusillのデモをご覧ください。要件定義〜設計フェーズでのAI活用について、具体的にご相談できます。*
*参考：Andrej Karpathy「LLMを使った知識ベース構築」(classmethod解説記事)*
