機械のための操作マニュアル：機械可読な仕様の姿
従来の要件ドキュメントはコミュニケーションツールである。その読者は人間であり、目的はプロダクトマネージャーとプログラマーの間で合意を形成することにある。そのため自然言語の叙述を使い、「自明な」ディテールを省略し、「既存の実装を参照」のような参照を用いることができる。人間の読者は自分の知識と経験でこれらの省略と参照を補完する。
Agentのために書かれた仕様は操作マニュアルである。その読者は事前知識ゼロの実践者である。自己完結的でなければならない。関連するすべての制約条件、境界条件、完了の定義が明示的に記述されていなければならない。検証可能でなければならない。すべての受入基準がテストケースに変換できなければならない。受入基準に対するテストが書けないなら、その基準自体が曖昧すぎるため、要件段階に差し戻して明確化する必要がある。
最小限の機械可読な仕様は、以下の構造を含むべきである。
task_id: FEAT-123
context: ["/docs/arch.md#payments", "/tickets/9876"]
inputs:
- name: amount
type: decimal
invariants:
- amount > 0
acceptance_criteria:
- "決済成功後、amount=amountかつstatus=successのレコードが請求ページに表示される"
- "失敗時、ローカライズ可能なエラーコードを返却し、請求レコードは書き込まない"
non_goals:
- "分割払いや返金は扱わない"
各フィールドには明確なエンジニアリング上の目的がある。
task_idは仕様をプロジェクト管理システムにリンクし、変更をトレース可能にする。contextはAgentが読むべき関連ドキュメントとコードを指し示し、情報スコープを限定する。inputsとinvariantsは入力空間と制約条件を定義し、どの入力が有効でどの境界を守る必要があるかをAgentに伝える。acceptance_criteriaは最も重要な部分であり、「完了」の意味を定義する。各基準はテストアサーションを直接生成できるほど具体的であるべきだ。non_goalsはスコープの境界を明示的に画定し、Agentが範囲を超えることを防ぐ。
この構造はプロジェクトのニーズに応じて拡張できる。dependencies（依存する他のモジュール）、risk_level（リスクレベル、後続のレビュープロセスに影響）、examples（具体的な入出力例）などのフィールドを追加するチームもある。しかし、中核原則は一貫している。自己完結的で、検証可能で、明確にスコープが限定されていること。
受入基準の書き方は特に強調に値する。2つのバージョンを比較してみよう。
曖昧なバージョン：「システムは決済失敗を正しく処理すべきである。」
明確なバージョン：「決済ゲートウェイが4xxエラーコードを返した場合、システムは対応するローカライズされたエラーメッセージを返却し、請求レコードを作成せず、ユーザーの残高を差し引かない。決済ゲートウェイがタイムアウトした場合（30秒超）、システムはトランザクションをpendingとマークし、非同期クエリを開始する。5分以内に確認が取れない場合、自動的にキャンセルしユーザーに通知する。」
曖昧なバージョンはAgentに膨大な判断空間を与える。何が「決済失敗」なのか？何が「正しく処理する」ことなのか？Agentは何らかの選択をするが、その選択が意図に合致するかは運次第である。明確なバージョンは判断空間をほぼゼロに圧縮する。すべてのケースに対する期待される振る舞いが明示的に定義されており、直接テストケースに変換できる。
受入基準は評価関数のつもりで書くべきである。基準を読んだ後、自分と別のエンジニアがその基準を満たしているかどうかについて異なる回答をしうるなら、その基準はさらなる分解と明確化が必要である。