概要
https://addyosmani.com/blog/good-spec/
詳細内容
## AIエージェントのための優れた仕様書（Spec）作成ガイド
https://addyosmani.com/blog/good-spec/
**Original Title**: How to write a good spec for AI agents
AIエージェントのコンテキスト限界と「注意力の予算」を考慮し、構造化された仕様書とモジュール化されたプロンプトを用いて開発を導くための実践的フレームワークを提示する。
**Content Type**: 📖 Tutorial & Guide
**Language**: en
**Scores**: Signal:5/5 | Depth:4/5 | Unique:4/5 | Practical:5/5 | Anti-Hype:4/5
**Main Journal**: 91/100 | **Annex Potential**: 88/100 | **Overall**: 88/100
**Topics**: [[AIエージェント, 仕様書駆動開発, プロンプトエンジニアリング, Claude Code, 開発ワークフロー]]
GoogleのAddy Osmani氏は、AIコーディングエージェント（Claude CodeやGemini CLIなど）を最大限に活用するには、従来のドキュメント作成能力をAI向けに最適化した「スマートな仕様書（Spec）」が必要であると説いている。多くの開発者が膨大な指示を一つのプロンプトに詰め込んで失敗する原因は、モデルのコンテキストウィンドウの制限と「アテンション・バジェット（注意力の予算）」の浪費にある。著者は、エージェントの集中力を維持し、生産性を高めるための5つの原則を提示している。
第一の原則は、ハイレベルなビジョンから開始し、詳細な設計はAIにドラフトさせることだ。開発者は「プロダクトの概要」を提示し、エージェントに詳細な`SPEC.md`を生成させる。この際、Claude Codeの「Plan Mode」のような読み取り専用モードを活用し、コードを書く前に計画を反復・洗練させることが重要である。
第二に、仕様書をプロフェッショナルなPRD（製品要求仕様書）として構造化することを推奨している。GitHubの2,500以上のエージェント設定ファイルの分析に基づき、以下の6つのコア領域を網羅すべきだとしている。(1)実行コマンド、(2)テストフレームワーク、(3)プロジェクト構造、(4)コードスタイル（コードスニペットを含む）、(5)Gitワークフロー、(6)境界条件（触れてはいけないディレクトリや秘匿情報など）。特に、一つのコード例は数段落の説明に勝る。
第三に、タスクをモジュール化し、一度に一つのサブタスクに集中させることだ。巨大な仕様書は要約された目次（TOC）で管理するか、役割に応じたサブエージェント（スキル）に分割して、特定のコンテキストのみを供給する手法が有効である。
第四の原則は、境界条件と自己チェック機能の組み込みである。エージェントの行動を「✅常に実行（テストの実施など）」「⚠️まず確認（スキーマ変更など）」「🚫決して行わない（秘匿情報のコミットなど）」の3段階で定義する。また、実装後に仕様書と照らし合わせて自己監査させるステップを組み込むことで、精度の向上が期待できる。
最後に、仕様書を「生きたドキュメント」として反復・進化させる重要性を強調している。テストに失敗した場合は仕様書を修正し、常に「唯一の真実（Source of Truth）」として維持する。著者は、これらの一連のプロセスを「AIアシスト・エンジニアリング」と呼び、単なる「Vibe Coding（ノリでのコーディング）」とは一線を画すべきだと主張している。エージェントは「非常に有能だがズルをすることもあるデジタル・インターン」であり、明確な仕様書による管理こそが、持続可能な開発の鍵となる。