spec-interview

# Spec Interview — 訪談式 Spec 建立 > 來源：Thariq Shihipar (@trq212, Anthropic Claude Code 核心團隊) > 「my favorite way to use Claude Code to build large features is spec based」 > 原始 gist：[claude-code-interview-command](https://gist.github.com/robzolkos/40b70ed2dd045603149c6b3eed4649ad)（71 ★） ## 核心理念 大多數人開發大型功能的問題不是技術能力不足，而是**需求不夠清楚就開始實作**。 Spec Interview 強迫你在動手前先被訪問一遍，把模糊的需求變成 Claude 可以 1-shot 執行的精確 spec。 ``` 模糊 prompt → 直接實作 ❌ Claude 邊猜邊做，來回修改多次 模糊 prompt → 訪談 → spec → 新 session 執行 ✅ Claude 1-shot 完成 ``` ### Unhobbling the Model（Thariq 核心工程哲學） > "The goal is to constantly remove constraints to give Claude more agency." 模型本身已有很強的能力，但環境中充滿**不必要的限制**（hobbles）： - 過度細碎的步驟指令（讓 Claude 無法自主判斷） - 僵化的工具 schema（限制 Claude 組合工具的方式） - 過多的 safety guardrails（在不必要的地方阻斷代理行為） **Spec Interview 是 Unhobbling 的體現**：把模糊需求轉成清晰 spec，讓 Claude 在執行 session 中擁有充足資訊，不需要不斷回頭確認 → 更多自主性、更少中斷。 **Delete-and-Rebuild Cycle（隨模型能力升級主動刪除）**： - 模型能力每隔幾個月大幅提升 - 過去需要 10 行 spec 才能描述清楚的需求，現在 3 行就夠 - **積極刪除舊的 scaffolding**（詳細步驟、重複限制、過度 handholding） - 衡量標準：「移除這段說明後，Claude 還能做對嗎？」→ 能就刪 --- ## 執行流程（3 步驟） ### Step 1：寫最小 Spec（或直接描述目標） 不需要完整，1-2 句話描述你想做什麼： ``` 我想在 dashboard 加一個 real-time 通知系統 ``` 或先建立 plan 檔案： ```bash echo "實作 real-time 通知系統，支援 WebSocket，UI 右上角 bell icon" > plan.md ``` ### Step 2：啟動 Spec Interview ``` 請用 AskUserQuestionTool 深度訪問我關於這個功能的所有細節： 技術實作、UI/UX、邊界案例、風險、取捨。 不要問顯而易見的問題。訪談完成後，產出完整的 spec 文件。 功能：[你的功能描述] ``` 或用 `/spec-interview` 搭配 plan 檔案： ``` /spec-interview plan.md ``` Claude 會用 AskUserQuestionTool 逐一訪問（modal UI 阻塞 agent loop，確保你充分回答）： - 技術實作細節與限制 - UI/UX 期望行為 - 邊界案例與例外處理 - 與現有系統的相容性 - 接受標準（何謂「完成」） ### Step 3：開新 Session 執行 Spec 訪談完成後，Claude 產出 spec 文件。**開新 session**，把 spec 貼進去： ``` 請依照以下 spec 實作，不要問問題，直接執行： [貼上 spec 內容] ``` 新 session 有乾淨的 context，Claude 專注在執行而非釐清需求。 --- ## 為什麼要開新 Session 執行？ 訪談 session 的 context 已經充滿探索性的對話和中間產物。 執行 session 需要的是乾淨的 context — 只有 spec 和程式碼。 ``` 訪談 session：問題、反問、釐清、模糊探索 ← 留在 child context 執行 session：精確 spec → 直接執行 ← 乾淨開始 ``` --- ## Interview Command（Thariq 原版） 可以把以下內容存成 `.claude/skills/spec-interview/scripts/interview.sh` 供 Claude 呼叫： ```bash #!/usr/bin/env bash # 讀取 plan 檔案，啟動訪談模式 # 用法：claude --model claude-opus-4-8 "$(cat interview-prompt.txt)" < "$1" PLAN_FILE="${1:-plan.md}" cat <<EOF Read this plan file and interview me in detail using the AskUserQuestionTool about literally anything: technical implementation, UI & UX, concerns, tradeoffs, etc. Ask non-obvious questions that I might not have thought of. Continue interviewing until you have enough information, then generate a specification document. Plan file content: $(cat "$PLAN_FILE" 2>/dev/null || echo "No plan file found at: $PLAN_FILE") EOF ``` --- ## 架構哲學（Thariq — Seeing like an Agent） 設計功能時，採用「從模型視角出發」的方法： ### 工具設計原則（Claude Code 內部採用） | 原則 | 說明 | |------|------| | **Progressive Disclosure 優於加工具** | 不要把所有資訊塞進 system prompt；讓 Claude 在需要時透過子 agent 探索 | | **~20 個工具上限** | 每個工具都增加模型認知負荷；加新工具需高門檻 | | **工具需讓模型理解如何呼叫** | AskUserQuestion 成功關鍵：不是格式指令，而是獨立工具 + modal UI | | **Tasks > Todos** | 隨模型能力提升，舊工具可能變成限制；Tasks 支援跨 session 協作 | ### 3 次失敗 → 1 次成功：AskUserQuestion 的設計過程 1. **第 1 次（失敗）**：把問題加為 ExitPlanTool 的參數 → 模型被衝突資訊搞混 2. **第 2 次（失敗）**：用 markdown 格式指令 → 模型不穩定遵守 3. **第 3 次（成功）**：獨立工具 + modal UI → 阻塞 agent loop 直到使用者回應 ✅ **洞察**：工具設計失敗通常不是因為模型能力不足，而是**工具設計沒讓模型清楚理解呼叫時機**。 --- ## Gotcha - **不要跳過訪談直接執行**：模糊 spec 讓 Claude 邊猜邊做，最終需要多次來回修改。 - **訪談結束後一定開新 session**：帶著訪談對話執行 = context rot 從一開始就發生。 - **spec 要包含接受標準**：「功能完成」的定義必須可驗證（測試、截圖、端到端流程）。 - **不要問顯而易見的問題**：Claude 已經知道很多，訪談要專注在你的特定限制和邊界。 - **Spec 完成後搭配 `/go` 驗證模式**：讓 Claude 端到端測試 → `/simplify` → 開 PR（Boris Cherny 建議）。