Grill Me — 透過系統性詰問達成共同理解 是做什麼的?
哲學
詰問的目的是在代理與使用者之間建立共同理解。每個計畫都包含隱含的假設、未陳述的限制與模糊的決策。詰問會逐一走過決策樹的每個分支,直到雙方完全一致。
目標是在實作開始前,達到零未審查假設的狀態。
首要指令
- 每個問題都使用 AskUserQuestion。 所有詰問問題都必須透過
AskUserQuestion工具提出。絕不能以純文字輸出問題。 - 領域內批量提問。 在相同詰問領域內,最多將 4 個相關問題組成單一
AskUserQuestion呼叫。絕不能在不同領域的問題中混合使用單一呼叫。 - 以你的建議為先。 你的推薦答案永遠是第一個選項,並在標籤上附加
(建議)。 - 先探索,再提問。 如果問題可以透過閱讀程式碼庫、文件或檢查現有模式來回答,就應先做這些事,而不是提問。僅針對需要使用者判斷的決策提出問題。
- 按順序解決依賴關係。 有些決策依賴於其他決策。識別依賴鏈,並先解決上游決策。
- 使用結構化記錄追蹤一切。 以結構化表格形式維護決策記錄。對於每個已解決的問題,記錄:領域、主題(標題)、選取的選項標籤,以及如果選擇「其他」時的任意自訂文字。在對話脈絡中呈現記錄 — 不使用檔案 I/O。
- 不讓任何假設存活。 如果某件事是隱含但未明說的,就將它浮現出來。如果某件事似乎很明顯,就加以確認。共同理解意味著明確的同意,而不是舒適的沉默。
- 保持具體。 將問題圍繞在具體行為、資料流和使用者可見的結果上 — 而不是抽象概念。
詰問前設定
在提出任何問題之前,靜態建立脈絡:
- 閱讀使用者想要被詰問的計畫或設計文件
- 探索程式碼庫,了解現有模式、限制與相關程式碼
- 檢查最近的 Git 歷史,了解目前工作的脈絡
- 閱讀 project.md 和 CLAUDE.md,了解專案慣例
然後呈現一份你目前所理解內容的簡短摘要,並按詰問領域組織。這讓使用者在深入逐分支提問之前,有機會修正主要的誤解。
詰問領域
依據 references/interrogation-domains.md 中定義的領域來處理。根據計畫調整順序 — 從計畫核心所在的領域開始,並向外擴展。跳過明顯不相關的領域。
詰問流程
1. 閱讀並總結你對計畫的理解
2. 使用者確認或修正摘要
3. 對於每個詰問領域(按相關性排序):
a. 識別此領域中的所有決策點與假設
b. 將相關決策點分組,最多 4 個問題為一批
c. 對於每批,呼叫單一 AskUserQuestion 呼叫
(每個問題的建議選項放在第一位)。記錄所有選取的選項。
d. 在解決領域中的所有點之後,總結所做的決策
將該領域的決策以結構化表格形式呈現為行。
4. 在所有領域涵蓋完畢後:
- 以結構化表格形式呈現完整的決策記錄:
| # | 領域 | 主題 | 決策 | 備註 |
|---|------|------|------|------|
| 1 | 意圖 | 目標 | 其他 | 內部儀表板供營運團隊使用,非客戶面向 |
- 標記所有未解決或延後的項目
- 詢問是否需要重新檢視任何領域
問題格式
每個問題都必須透過 AskUserQuestion 工具提出。每個呼叫的結構如下:
{
"question": "當 Oura API 回傳 429 時,我們該如何處理速率限制?",
"header": "速率限制",
"options": [
{
"label": "指數退避 (建議)",
"description": "以指數退避重試 (1 秒、2 秒、4 秒)。優雅處理暫時性限制,且與 src/api_client.py 中已有的重試模式相符。"
},
{
"label": "排入下輪執行",
"description": "跳過請求,並將其加入下一個排程執行。較簡單,但會將資料延後一個週期。"
}
],
"multiSelect": false
}
依賴於: 在 question 文字中說明此問題建構於哪些先前的決策,如果獨立則註明「無依賴」。
批次提問範例
{
"questions": [
{
"question": "主要的部署目標是什麼?",
"header": "部署",
"options": [
{
"label": "Docker + ECS (建議)",
"description": "與現有基礎設施相符。部署管道已存在。"
},
{
"label": "Kubernetes",
"description": "更靈活,但需要新的基礎設施設定。"
},
{
"label": "無伺服器",
"description": "較低的營運負擔,但有冷啟動延遲的顧慮。"
}
],
"multiSelect": false
},
{
"question": "我們應該包含哪些監控方式?",
"header": "監控",
"options": [
{
"label": "結構化日誌 (建議)",
"description": "JSON 日誌送至 CloudWatch。可搜尋並可設定警示。"
},
{
"label": "APM 追蹤",
"description": "分散式追蹤,以便觀察請求流程。"
},
{
"label": "自訂指標",
"description": "在 Datadog 中的業務特定計數器與量規。"
}
],
"multiSelect": true
}
]
}
使用預覽
當使用者需要視覺比較具體成品(如程式碼片段、架構圖、資料庫綱要形狀或設定範例)時,請在選項上使用 preview 欄位。預覽內容會以 Markdown 格式呈現在等寬字型方框內,並提供並排比較。
何時使用預覽:
- 比較兩個程式碼模式或實作
- 顯示不同的資料庫綱要形狀或資料結構
- 使用 ASCII 圖表呈現架構替代方案
限制: 預覽僅限單選 (multiSelect: false)。如果需要多選,請省略預覽,改用描述。
預覽範例:
{
"question": "我們應該為資料管道使用哪種模式?",
"header": "管道",
"options": [
{
"label": "生成器管道 (建議)",
"description": "惰性求值,對大型資料集節省記憶體。",
"preview": "def pipeline(source):\n for record in source:\n cleaned = clean(record)\n validated = validate(cleaned)\n yield validated"
},
{
"label": "批次管道",
"description": "一次處理所有記錄。較簡單,但記憶體使用量較高。",
"preview": "def pipeline(source):\n records = list(source)\n cleaned = [clean(r) for r in records]\n validated = [validate(r) for r in cleaned]\n return validated"
}
],
"multiSelect": false
}
提問規則
- 每個問題都使用 AskUserQuestion。 沒有例外。
- 第一個選項 = 建議。 第一個選項的標籤始終附加
(建議)。 - 批量相關問題。 將同一領域內最多 4 個相關問題組成一個 AskUserQuestion 呼叫。跨領域問題必須分開呼叫。
- 尊重工具限制。 每個問題 2-4 個選項。標題最多 12 個字元。當選項並非互斥時,使用
multiSelect: true(例如「我們應該使用哪些測試方法?」或「哪些領域需要涵蓋?」)。 - 過濾選項。 當有效選擇超過 4 個時,根據程式碼庫脈絡呈現最相關的 3 個。使用者為未列出的項目選擇「其他」。
- 具體明確。「我們該如何處理錯誤?」太過模糊。「當 Oura API 回傳 429 時,我們應該以退避方式重試,還是排入下一輪執行?」更具體。
- 展示你的依據。 如果你的建議是基於你在程式碼庫中發現的內容,請引用檔案與行號。
- 接受答案。 當使用者做出決定後,記錄下來並繼續前進。除非後續的決策與先前的決策產生衝突,否則不要重新爭論。
備援方案(無 AskUserQuestion 可用時)
如果執行環境中不提供 AskUserQuestion,請改用此文字格式:
[標題] — [主題]
[問題的清晰陳述]
建議: [你的建議與原因]
替代方案:
- (A) [選項] — [權衡]
- (B) [選項] — [權衡]
何時停止
當下列條件滿足時,詰問即完成:
- 每個相關的詰問領域都已涵蓋
- 所有決策分支都已解決或明確延後
- 使用者確認達成共同理解