Zenn Agent Flow Spec Writing
AIエージェントに渡す仕様書の書き方──巨大な依頼を壊さず小さく渡す
- URL: https://zenn.dev/aiwatch_jp/articles/agent-flow-spec-writing
- 日付: 2026-06-12
- Tier: Tier 3
- 要旨: Claude CodeやCodexへの依頼では「何をプロンプトに書くか」よりも「仕様の渡し方」が重要。作業境界を明確にする8項目フレームワーク（目的・非目的・背景・変更範囲・入力文脈・受け入れ条件・テスト条件・停止条件）を提案。
詳細
核心の考え方: 仕様書は「命令文」ではなく「作業境界を作る文章」
8項目フレームワーク:
- 目的: 誰のどの場面を良くするのか
- 非目的: 今回やらないことを明示（エージェントが推測で勝手に実装することを防ぐ）
- 背景: コードベース・設計の文脈
- 変更範囲: どのファイル・モジュールに触ってよいか
- 入力文脈: エージェントが見てよい情報
- 受け入れ条件: 完了の定義
- テスト条件: 何でどう確認するか
- 停止条件: 不明点が出たらどこで止まるか
悪い依頼の例:
商品一覧に検索機能を追加してください。→ 検索対象・実装場所・URL反映・テスト方針・触ってよいファイルが全部曖昧
良い依頼の例（一部）:
商品一覧で、商品名の部分一致検索を追加する。
今回はやらない：SKU検索・検索履歴・サジェスト
維持する挙動：categoryフィルタ・statusフィルタ・pagination「非目的」の重要性: 境界を明示しないと、エージェントは「それっぽい答え」を作りに行き、速く間違える。非目的を書くことで推測による範囲外実装を防ぐ。
実装前の思考順序: 誰のどの場面→入力→出力→正常系→失敗系→今回やらないこと→テスト確認方法の順で固めてからプロンプトを書く