AIエージェントのための効果的な仕様書の書き方 - Addy Osmani

• AIエージェントの生産性に最も大きな差を生むもの → 明確で構造化されたSPEC
• 悪いSPEC = 曖昧さ → AIのドリフト、反復的な失敗、コンテキスト超過
• 良いSPEC = 生きたドキュメント（SPEC.md）+ 継続的な更新

良いSPECの中核構成要素

• 目標 / ビジョン（なぜ作るのか、誰のためなのか）
• 機能一覧 + 優先順位
• 技術スタック（React 18 + TS、Node 20 など具体的に）
• 実行コマンド（npm test、lint、build など）
• テスト基準（どのテストを実行すれば成功なのか）
• コード構造 / スタイルガイド
• Gitワークフロー（ブランチ規則、コミットメッセージ）
• 境界設定（✅ 常に / ⚠️ 要確認 / 🚫 絶対にしない）

効果的な開始プロンプトのパターン

• “Draft a detailed specification for … covering objectives, features, constraints, step-by-step plan”
• まず Plan Mode → AIにSPECの草案を書かせる
• その後、小さな単位の作業に分割して指示する

実務のヒント（要点のみ）

• SPEC.md を別ファイルとして維持 → 作業ごとに関連セクションだけを入れる
• モジュール化 + サブタスク分離
• 各作業後に自動テスト + SPEC準拠かどうかの確認
• 境界ルールの3段階を明確に（Always / Ask / Never）