このガイドは、AI コーディングエージェントのための仕様を書く際の 5 つの原則を示すものである。対象は、曖昧さを避けられるほど詳細な仕様を書くと、今度はモデルが確実に扱えないほど大きくなってしまうと感じている開発者である。著者自身のコーディングエージェントの利用経験と、2,500 を超えるエージェント設定ファイルを対象とした GitHub の分析に基づき、エージェントを集中させ続けるのは仕様の長さではなく仕様の質だと論じる。
5 つの原則とは次のとおりである。高レベルのビジョンから始め、詳細は AI に起草させること。仕様をプロフェッショナルな PRD のように 6 つの中核領域を網羅する形で構成すること。1 つの大きなプロンプトではなく、モジュール化されたプロンプトにタスクを分割すること。セルフチェック、3 層の境界、そして人間の専門知識を組み込むこと。そして仕様を、テストし、反復し、進化させていく生きたドキュメントとして扱うことである。
要点
- 2,500 を超えるエージェント設定ファイルを対象とした GitHub の分析によれば、最も効果的な仕様は 6 つの領域を網羅している。コマンド、テスト、プロジェクト構成、コードスタイル、git ワークフロー、そして境界である。見つかった有用な制約の中で最も多かったのは「シークレットを決してコミットしない」であった。
- フラットなルールの羅列よりも、3 層の境界システムを推奨している。「常に行う」（確認せずに実行する）、「まず確認する」（人間の承認が必要）、「決して行わない」（絶対的な禁止）の 3 つであり、GitHub の調査では、区別のない禁止事項のリストよりも効果的だと報告されている。
- 1 つのプロンプトに指示を積み重ねるほど個々の指示へのモデルの遵守度が下がるという「指示の呪い」の知見を引用し、代わりに要件を逐次的で焦点の絞られた指示に分解することを推奨している。
- GitHub の Spec Kit を、Specify、Plan、Tasks、Implement の 4 フェーズからなるゲート付きワークフローとして紹介している。そこでは仕様は一度書いて放置されるものではなく、タスクの分解と実装を駆動する実行可能な成果物となる。
- 「拡張目次」の利用を推奨している。これは大きな仕様の各セクションをエージェントが階層的に要約したものであり、エージェントはコンパクトな索引をコンテキストに保持し、必要なときに関連するセクションだけを取り込める。
- 自動テストが難しい主観的な品質基準（スタイル、可読性、アーキテクチャへの準拠）には LLM-as-a-Judge を推奨している。2 つ目のエージェントまたはプロンプトを使い、最初のエージェントの出力を仕様のガイドラインに照らしてレビューさせるというものである。
- Simon Willison を引用し、AI エージェントを危険にする性質の「致命的な三要素」として、速度、非決定性、コストを挙げる。そして仕様とレビューのプロセスは、速度が検証を追い越すに任せるのではなく、この 3 つすべてを考慮しなければならないと論じる。
- 「バイブコーディング」と「AI 支援エンジニアリング」を区別している。前者は探索や使い捨てのプロジェクトに適したものとされ、後者はこの記事が説明する規律（仕様、テスト、レビュー）を必要とするものとされる。そして本番環境に出荷する際に両者を混同しないよう警告している。
背景
この記事は、仕様の構成に関する主な根拠として、GitHub 自身が公開したエージェント設定ファイルの分析と GitHub の Spec Kit のドキュメントを引用している。また、人間によるレビューとリスクに関する注意点については、Simon Willison が別途公開している文章（バイブエンジニアリング、致命的な三要素、AI 生成コードのレビューについて）を繰り返し参照している。記事は自らを独自の研究ではなく、これらの情報源の実践的な統合として位置づけている。