AIエージェント向けの仕様の書き方
Addy Osmaniが2026年2月に公開した記事 How to Write a Good Spec for AI Agents は、AIコーディングエージェントに対する仕様書（spec）の設計方法を整理したものである。
彼の主張は一貫している。巨大な仕様を一度に渡すのではなく、構造化し、分割し、検証可能な形に設計することが重要である。
背景
AIに長大な仕様をそのまま与えると、次の問題が生じやすい。
- コンテキストウィンドウの制約
- 注意配分の分散
- 指示が多すぎることによるミスの増加（指示の呪い（curse of instructions）と呼ばれる）
したがって、必要なのは「網羅的な文書」ではなく、「実行可能な設計図としての仕様」である。
原則1：高レベル仕様から始める
最初は目的と成功条件を簡潔に記述し、詳細な技術仕様はAIに任せる。
手順は次の通りである。
- 目的・ユーザー体験・成功条件を記述する
- AIに詳細仕様を生成させる
- 実装前に計画をレビューする
重要なのは、実装より先に設計を固めることである。仕様は保存し、後続の作業で参照する。
原則2：構造化する
仕様は散文的なメモではなく、明確な章立てを持つ文書とする。
特に重要とされるのは次の6領域である。
- Commands（build / test / lint など実行可能なコマンド）
- Testing（テスト方法と基準）
- Project structure（ディレクトリ構成）
- Code style（サンプルコードを含む）
- Git workflow（ブランチやコミットの規則）
- Boundaries（操作制限）：「Always / Ask first / Never」の三層で定義する
仕様は固定文書ではなく、更新され続ける「生きた文書」として扱う。
原則3：タスクを分割する
すべてを一度に処理させるのではなく、作業を小さく分割する。
- 一度に一つの課題に集中させる
- 必要な文脈のみを与える
- 完了後に検証し、次へ進む
仕様が長い場合は、目次を作り、必要な箇所だけ参照させる方法が推奨されている。これにより、コンテキスト消費を抑えつつ全体像を保持できる。
原則4：自己検証と制約を組み込む
仕様は実装指示だけでなく、品質管理の仕組みでもある。
有効な手法として次が挙げられる。
- 実装後に仕様項目との照合を行う
- テストやlintを必須化する
- 別プロンプトでレビューを行う（LLM-as-a-Judge）
- 仕様由来の適合テストを用意する
また、ドメイン特有の知識や既知の落とし穴を仕様に明示することで、出力の精度が向上する。
原則5：反復と更新を前提とする
仕様は一度書いて終わるものではない。
- 実装で誤解が生じた場合は仕様を更新する
- 仕様をバージョン管理する
- 「Spec → 実装 → テスト → 修正」の循環を維持する
AIの速度や非決定性を前提に、検証工程を組み込むことが必要である。