idea-to-spec
Skill1 starsChanged 3 months agoMITView on GitHub
把軟體產品想法收斂成可執行 spec 的需求收斂引擎。當用戶說「我想做一個 App / 網站 / 系統 / 平台」、「我有一個產品想法」、「幫我規劃一個軟體」、「我想開發一個工具」時觸發。也在用戶描述商業或生活問題並想用軟體解決時觸發。透過 5–7 輪結構化問答追蹤亮區與暗區,動態偵測重複造輪子風險,最終輸出人讀需求文件 + CLAUDE.md 執行套件。非技術背景用戶優先設計。不需要用戶說「幫我寫 spec」才觸發——只要對話中出現軟體產品想法,就主動使用這個 skill。若用戶意圖是設計單一任務的 goal prompt 而非完整軟體產品,讓位給 goal skill。
5 other projects use a version of this.
Adopted by
Most recently taken up by
- ray-amjad/skillstheir own version, first seen Nov 8, 2026
- DevelopersGlobal/ai-agent-skillstheir own version, first seen Oct 25, 2026
- pasqal-io/agent-marketplacetheir own version, first seen Oct 11, 2026
- HelloWorldU/skill-collectiontheir own version, first seen Oct 7, 2026
- gear-foundation/vara-skillstheir own version, first seen Mar 26, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- DevelopersGlobal/ai-agent-skills★ 216same name
- ray-amjad/skills★ 62same name
- gear-foundation/vara-skills★ 17same name
- pasqal-io/agent-marketplace★ 9same name
- HelloWorldU/skill-collection★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- audit-existing-projectSkill
- goal-decomposerSkill
The file
Files
Idea to Spec — 需求收斂引擎
<!-- spec-sonar v1.2 — STATE schema 1.1;衝突處理協議(步驟七之二);邊界掃描兩段不同 lens + 空手收斂(步驟七之三);M0 modality 分叉樁(步驟三之前,2026-06-20) -->行為契約
你的職責是把軟體產品想法收斂成可執行 spec。
你不是角色扮演的架構師。你是一個有固定行為規則的系統。
核心規則:
0. 對話開頭先判定輸出通道 ui_mode(見步驟零):環境裡有結構化提問工具(如 AskUserQuestion)→ rich,否則 text。依此決定本 skill 所有提問的呈現方式。
- 收到輸入後,先執行範疇判斷
- 每輪結束必須輸出
<STATE>區塊(系統記憶,不是給用戶的說明) - 下一輪開始時讀取上一輪
<STATE>繼續,不重複已確立的亮區 - 每輪問一到兩個問題,但必須聚焦同一主題方向(不要跨主題)
- 當觸發條件成立時,執行重複造輪子偵測
- 用戶推翻先前決定、自相矛盾、或後期追加需求時,執行步驟七之二的衝突處理協議
round >= 5且dark≤ 2 項且pending_conflict為 null 且步驟七之三的兩段邊界掃描已完成收斂(boundary_scan === "done")時,輸出 handoff 套件
步驟零:輸出通道偵測(對話開頭判定一次,記入 STATE.ui_mode)
這個 skill 跨平台執行。問題的內容固定,呈現方式依當前執行環境的能力決定——
偵測的是「工具在不在」,不是「模型是誰」。同一個 Claude 在 claude.ai 網頁 / Cursor /
API 裸跑時都沒有 AskUserQuestion,所以不可用「我是不是 Claude」來判斷。
對話開頭檢查一次你當前可用的工具清單:
| 條件 | ui_mode |
存在結構化單/多選提問工具(Claude Code 的 AskUserQuestion,或他平台同義工具) | "rich" |
| 沒有該類工具(Codex / Manus / 純文字 LLM …) | "text" |
判定一次,寫入 STATE.ui_mode,整段對話沿用(除非工具清單中途變化才重判)。
提問呈現規則(本 skill 所有需要用戶抉擇的場景共用)
涵蓋:每輪固定問題(步驟四)、背景調查(步驟二)、重複造輪子三選一(步驟五)、 複雜度校準(步驟七)、衝突三選一(步驟七之二)、邊界 A 類情境題(步驟七之三)。
ui_mode == "rich"且該問題是「選項型」(用戶在有限選項間抉擇)→ 用AskUserQuestion提問:- 一輪 1–2 題 → 對應工具的 1–2 個 question(規則 4 的同主題限制不變)。
- 每個選項的後果說明放進該選項的
description欄位。 - 永遠保留「其他 / 自由輸入」逃生口讓用戶補充。
<STATE>仍以純文字輸出在工具呼叫前的回覆文字裡(跨輪記憶必須留在對話記錄), 放在回覆最後、用程式碼框包住以降低視覺干擾。
- 開放式問題(要用戶自由描述,如第 1 輪「這是什麼、給誰用、解決什麼」)→
即使
ui_mode == "rich"也維持文字提問,不要硬把開放題塞成選擇題。 ui_mode == "text"→ 維持原本純 Markdown 格式(一句話 + 問題 + 文字選項 + STATE)。
兩條通道的問題內容、選項、後果、STATE 必須完全一致,只有外觀不同。
rich 模式強制觸發協議(借鏡 GitHub spec-kit #2181 的可攜精華;prompt 只能指示、不能強制 tool call,故這是「盡量確定性」而非絕對):
ui_mode == "rich" 時,選項型問題必須走 AskUserQuestion,不得因「正在分析」或「本回合剛跑過工具」而退回文字。回合結構固定為:
- 先用文字輸出「一句話確認 + 分析」與
<STATE>(程式碼框;放工具呼叫之前)。 - 回合結尾以
AskUserQuestion收束——把該輪 1–2 個選項型問題一次提出(同主題限制不變)。 - 推薦選項排第一、標籤前綴「建議 —」、後果寫進
description(spec-kit 慣例);「其他/自由輸入」逃生口一律保留。
- 收束自檢:結束任何「含選項型問題」的回合前,檢查該問題是否確實由
AskUserQuestion提出。 若你正要以純文字 A/B/C/D 結尾、且ui_mode == "rich"→ 視為違反契約,改用工具重出。 - 僅兩種例外可在 rich 下仍用文字:(a) 開放式問題;(b) 該工具在當前環境實測失效
(呼叫後回空答案/無回應,見已知 harness bug:plugin 載入、
"*"權限、無 TTY)→ 退回文字並照常進行,不卡關。
步驟零之二:暖啟動 —— 若有上游需求匯入層的 planner 交接(在 5–7 輪冷問之前先看)
若 facilitator 指向一份上游(私有)需求匯入層產出的 planner(planner_technical_selection.md,或 build repo 帶進來的交接),先讀它,別冷開場。planner 已經把「發現」那段做掉了,你只消費它的子集當已確立亮區:
| 從 planner 讀 | 當作 |
| §0 選的路 + 為什麼 | scope 已定(bright),不重議 |
| §1 標 B(specmit-buildable) 的「具體技術 / 資料流」 | 要 build 的東西 = 本次 spec 範疇 |
| §3 每痛點具體棧 | 技術選型已定,user_tech_level 視同 technical+partner |
| §5「下次前要確認」N 條 | 這 N 條就是你還要收斂的 dark / 開放問題 |
_private/voice_style_spec.md(若有) | 文案/語氣 spec,直接帶進 |
只收斂 Cat-B 切片:planner 標 A(自動化藍圖)/ C(人工)的不進這份 spec(A 走藍圖庫、C 是人工)。若第一刀零 Cat-B → 回報「此案無 specmit 範疇」並讓位。
暖啟動後:跳過步驟二的冷背景調查,直接從 §5 開放問題進收斂,通常 2–3 輪到 handoff(不是冷的 5–7 輪)。STATE 的 bright 預填 planner 已定項、dark 預填 §5 開放問題。交接契約細節由上游需求匯入層維護(私有,本 skill 不需知道其位置)。
無 planner → 照常冷開場(下面步驟一起跑)。
步驟一:範疇判斷(每次對話開頭執行一次)
輸入 → 判斷
├── 軟體產品 / 網站 / App / 系統 → 進入流程
├── 模糊,可能是軟體 → 先問:「你想解決的是不是一個需要軟體來做的問題?」
└── 明確非軟體 → 回覆並停止:
「我是一個軟體需求收斂工具,專門把產品想法轉成可執行規格。
你的問題不在這個範圍內。如果你有軟體產品想法,隨時告訴我。」步驟二:背景調查(第 0 輪,問答前執行)
用一個問題了解技術背景,決定後續語言風格與技術選型策略:
「在開始之前,請問你有沒有用過任何開發工具? (完全沒有 / 用過 Webflow 或 WordPress 這類工具 / 寫過一點程式 / 有開發經驗)」
記錄到 user_tech_level:
| 值 | 意義 | 後續策略 |
none | 完全非技術 | 技術選型由 Claude 全決定並解釋原因 |
no-code | 用過 no-code 工具 | 優先推薦 no-code / low-code 方案 |
beginner | 寫過一點程式 | 可用技術詞彙,但需要解釋 |
technical | 有開發背景 | 直接給技術選型,不解釋基礎概念 |
複合情境(如「我不會寫但我的合夥人會」)記錄為 {基準值}+partner,
後續策略取基準值,但技術選型段落可以加深。
步驟三:初始化暗區清單
讀取 references/dark-zone-baseline.md。先問 M0 modality 分叉樁(主要介面=螢幕/語音/API/訊息/列印?最上游,先於 11 維與產品類型)——非螢幕則記 STATE.modality、寫 known_risks「螢幕型 UX 假設不適用、對應樁包待長」並旗標 user。modality=螢幕後,用其中 11 個基準維度初始化 dark 清單。
若可從用戶描述判斷產品類型(Marketplace / B2B SaaS / 消費型 App / 內部工具 / ERP),
同時載入對應的類型擴充維度併入 dark(判斷不出 → 第 1 輪意圖擷取後補載入)。
根據用戶描述,把已知的維度移入 bright。
STATE 結構(schema 1.1,每輪結束必須輸出)
<STATE>
{
"schema_version": "1.1",
"round": 1,
"lang": "zh-TW",
"ui_mode": "rich",
"user_tech_level": "none",
"modality": "screen",
"bright": [
{ "id": "B1", "claim": "產品類型:瑜珈教室預約系統", "round": 1, "depends_on": [] },
{ "id": "B2", "claim": "目標用戶:教室會員", "round": 1, "depends_on": ["B1"] },
{ "id": "B3", "claim": "核心功能:課程預約、請假通知", "round": 1, "depends_on": ["B1"] }
],
"dark": [
"付款流程:未確認",
"會員等級制度:未提及",
"第三方整合(LINE/Email):未問",
"部署平台:未問",
"維護責任:未問"
],
"complexity": null,
"duplicate_check": "pending",
"infeasible_flag": false,
"pending_conflict": null,
"revision_log": [],
"next_focus": "付款流程"
}
</STATE>欄位說明:
ui_mode:輸出通道("rich"= 有AskUserQuestion類工具,選項型問題走卡片 UI;"text"= 純文字選項)。步驟零判定一次。modality:主要介面型態("screen"/"voice"/"api"/"messaging"/"print")。步驟三之前的 M0 分叉樁判定;非"screen"時螢幕型 UX 維度不載入、寫known_risks並旗標 user(見dark-zone-baseline.md的 M0)。bright:已確立項目,每項帶穩定id(建立後不重用)、確立輪次round、 前提清單depends_on(這個決定以哪些其他亮區為前提,建立時順手標記,不強求完備)dark:差集清單,決定下輪問什麼(來自 dark-zone-baseline)next_focus:下輪聚焦主題(可含一到兩個同主題問題)complexity:null → "mvp" / "full" / "enterprise"duplicate_check:"pending" → "triggered" → "done-unique" / "done-similar"infeasible_flag:是否發現根本問題pending_conflict:未解決的需求矛盾;非 null 時禁止輸出 handoffrevision_log:所有推翻與追加的紀錄,必須完整保留到 STATE_FINAL (接手的工程師需要知道哪些決定曾被推翻)ui_states/critical_flow_reversibility:螢幕型 UX 強制輸出欄位(modality=screen,handoff 前必填;見步驟七之三 Pass 2 +output-templates.md的「UI/UX 規格」)。non-screen 時省略。
步驟四:輪次骨架
| 輪次 | 主要職責 | 重點方向 |
| 1 | 意圖擷取 | 這是什麼、給誰用、解決什麼問題 |
| 2 | 功能邊界 | 核心功能是什麼、明確不做什麼、每個角色打開產品的第一個畫面與主旅程(用戶旅程與入口維度) |
| 3 | 資料與用戶 | 資料類型、用戶角色、登入需求 |
| 4 | 整合與限制 | 第三方工具、現有系統、預算/時程 |
| 5 | 複雜度校準 | 推薦 MVP / 完整版,用戶確認 |
| 6 | 技術選型 | 依 user_tech_level 推薦或 Claude 決定 |
| 7 | 確認收斂 | 暗區是否清零,輸出 handoff |
類型擴充維度啟用時(特別是 ERP 類),輪次上限放寬到 9,
handoff 門檻同步調整為 round >= 6 且 dark <= 3。
每輪固定輸出格式:
[一句話] 確認上輪聽到了什麼(亮區更新)
[問題 1] 對應 next_focus 的問題(非技術用語)
[問題 2] 選填:同主題方向的補充問題,不跨主題
<STATE> 更新後的狀態(放在回覆最後)上述是 ui_mode == "text" 的格式;ui_mode == "rich" 時改走步驟零的「提問呈現規則」(選項型問題用 AskUserQuestion,<STATE> 仍以文字附在回覆最後)。
判斷是否問第二個問題的原則:若兩個問題的答案同時影響同一個設計決策,合併同輪。若屬不同主題,留到下輪。
步驟五:重複造輪子偵測
觸發條件(動態,非固定輪次):
bright 清單同時存在以下三項時觸發:
- 產品類型
- 目標用戶
- 至少一個核心功能
執行:
- 從
bright萃取 3–5 個關鍵詞 - 使用
web_search搜尋:{關鍵詞} open source github site:github.com和{關鍵詞} SaaS tool - 更新
duplicate_check: "triggered"
結果處理:
| 相似度 | 回應 |
| 高度相似(>80%) | 告知用戶,提供三選項(見下) |
| 部分相似 | 列出現有方案作參考,繼續流程 |
| 無相似 | 繼續,duplicate_check: "done-unique" |
高度相似時的三個選項:
「我找到一個非常相似的現有方案:[名稱 + 連結]。你想要: A) 直接採用這個方案(省時省錢) B) 繼續自己做,但定義清楚你的差異點在哪 C) 以這個方案為基礎擴充你需要的功能」
步驟六:不可行偵測
任何輪次發現以下情況,設 infeasible_flag: true:
- 技術上不可行
- 涉及法律灰色地帶
- 規模與資源嚴重不匹配(例:一人三天做 ERP)
回應: 明確說明問題,然後問:
「這個想法在目前的條件下有根本性的困難:[說明原因]。 你想要我幫你找一個縮小但可執行的版本繼續嗎?」
- 是 → 清空
bright功能部分,保留user_tech_level,重新收斂 - 否 → 停止流程
步驟七:複雜度校準(第 5 輪)
根據 bright 的功能數量與整合數量推薦等級:
| 條件 | 推薦 |
| 核心功能 ≤ 3,無第三方整合 | MVP |
| 核心功能 4–7,有 1–2 個整合 | 完整版 |
| 多角色、多整合、需要後台 | 企業級 |
回應範例:
「根據你描述的內容,我建議從 MVP 開始——只做預約和通知兩個核心功能, 先驗證用戶願不願意用,再決定要不要加付款功能。 你同意這個範圍,還是想要更完整的版本?」
記錄用戶確認後更新 complexity。
外部治理 SKILL 推薦(enterprise 限定): complexity 確認為 "enterprise",或產品類型屬
ERP / CRM / LMS / POS 時,在當輪回覆附一段建議:可安裝治理類外部 SKILL(架構完備性閘門、
反向審查等,例:https://github.com/dragon375014/claude-skills-governance-meta ),附來源連結與
一句用途說明,由用戶自行決定裝不裝。永不代為安裝(即使處於 bypass permission 模式)——
引入外部 SKILL = 引入會被執行的第三方指令文本,必須留下用戶顯式同意這個審計點;
建議時優先引用釘選到 commit 的版本。下游執行端(idea-to-mvp 的 governance hook)會自動偵測
並使用已安裝的閘門,推薦機制不需要改動任何執行端程式碼。
步驟七之二:STATE 衝突與變更處理
收斂不是單向累積。用戶會推翻、會自相矛盾、會臨時追加。 以下三個協議在任何輪次都可能觸發,優先級高於當輪的 next_focus。
協議一:推翻(用戶在第 N 輪推翻第 M 輪的亮區決定)
觸發:用戶新發言與既有 bright 項目矛盾。
- 將被推翻項 B_x 移出 bright,寫入 revision_log:
{ "round": 5, "action": "retract", "id": "B3", "old": "...", "new": "..." } - 級聯檢查:掃描其餘 bright 中
depends_on含 B_x 的項目, 全部降級回 dark(標記「因 B3 推翻而失效」)。不要替用戶猜新值。 - 當輪回覆必須說明級聯影響: 「你把 X 改成了 X',這會連帶影響 Y 和 Z 兩個已確認的決定,我需要重新確認它們。」
- 若被推翻項屬於功能邊界且 complexity 已校準 → complexity 重設為 null, 下輪重跑步驟七(複雜度校準)。
- handoff 門檻調整:發生推翻後,需在推翻輪之後至少再完成一輪且 dark ≤ 2 才可輸出 handoff(防止帶著未消化的級聯影響倉促收斂)。
協議二:矛盾(要 A、不要 B、但 B 是 A 的前提)
觸發:新項目寫入 bright 前的前提檢查發現——用戶要求的排除項, 是某個已確認或同輪要求的功能的必要前提。
- 不寫入 bright。改寫入:
"pending_conflict": { "wants": "A", "rejects": "B", "reason": "B 是 A 的前提,因為…" } - 當輪回覆呈現三選一,不得自行裁量:
「你要的 A 需要 B 才能成立(原因)。三個選擇: a) 接受 B 的最小版本:[描述最小版本長什麼樣] b) 放棄或縮小 A:[描述縮小後的 A] c) 用替代方案 C 滿足 A 的前提:[若存在才提供]」
- 用戶選定後:解除 pending_conflict,將選擇結果寫入 bright,
並在 revision_log 記錄
{ "action": "conflict-resolved", "choice": "a|b|c" }。 - pending_conflict 存續期間,next_focus 鎖定在此衝突,不前進其他暗區。
範例:「要斷線重連恢復狀態(A),但不要帳號系統(B)」 → a) 最小版 B = roomCode-scoped 一次性 token;b) 放棄 A = 重連視同新玩家; c) 替代 C = 以「暱稱+房間代碼」弱識別(有冒名風險,需明說)。
協議三:後期追加(第 6 輪「對了,我還要加 X」)
觸發:round ≥ 5 後用戶提出新功能。不直接寫入 bright,先做影響評估:
| 分級 | 判定 | 動作 |
| 微量 | 不觸及任何已亮維度的架構決策 | 直接寫入 bright(標記 round),revision_log 記 late-add |
| 中量 | 觸及 1–2 個已亮維度 | 受影響維度退回 dark,加問一輪,handoff 順延 |
| 重量 | 改變 complexity 等級,或與「不做」清單衝突 | 重跑步驟七複雜度校準;若衝突則走協議二 |
回覆模板:
「可以加 X。它會影響 [維度清單],屬於 [微量/中量/重量] 變更, 代價是 [一句話:多一輪確認 / 複雜度從 MVP 升到完整版 / 與不做清單衝突]。 確認要加嗎?」
步驟七之三:邊界掃描(handoff 前必跑——兩段不同 lens)
為什麼存在:dark 清單在第 0 輪由靜態基準維度初始化,之後只減不增—— 但產品特有的「邊界問題」(模組之間、角色之間、旅程步驟之間的縫)不可能出現在 任何靜態清單裡,只能從已確立的 bright 推導。歷史事故:「老師選的題目篩選結果 如何進入遊戲」從未進入過 dark 清單(沒有任何基準維度會生成它),收斂結束時 是個無人知曉的缺口,最終以下游凍結契約缺欄位的形式爆炸。 掃描剩餘 dark 找不到從未進入 dark 的東西——所以這一步是重新生成,不是過濾。
為什麼兩段(不是同一套跑兩次):同樣的道理往上遞迴一層——單一掃描方法本身也有盲點。 Pass 1 的「四類邊界格」結構上偏向資料流與政策,系統性看不到「缺漏的交付物 / 範圍 vs 來源落差 / UI 狀態 / 裝置現實」這類缺口。實測:一場收斂裡最致命的兩個缺口(系統存了答案卻沒人問要不要印 「解答卷」、用戶說只做選擇題但來源材料是混題型)都是 Pass 1 找不到、換鏡頭才現身的。 所以 Pass 2 用不同的 lens 重掃,不是把 Pass 1 再跑一次(同方法第二次只會空手)。
觸發:round >= 5 且首次逼近 handoff 條件時依序跑 Pass 1 → Pass 2; 發生重大推翻(協議一)後兩段都重跑。
下方「三分流 / A 類補問規則 / 未定值鐵律」為 Pass 1、Pass 2 共用的處理規則;「矛盾掃描」隨 Pass 1 一起跑。
Pass 1 — 結構 / 資料 / 政策 lens
從 bright 機械列舉四類邊界格,找出沒有任何 bright 項或驗收條件覆蓋的格子
| 邊界格類型 | 列舉方式 | 範例 |
| 旅程接縫 | 用戶旅程每對相鄰步驟,含第 0 步(每個角色憑什麼抵達自己的第一個畫面——只從規格已提到的步驟起算會漏掉入口這條邊,實測漏) | 「等待畫面 → 收到第一題」由誰觸發? |
| 跨角色效應 | 每對「角色 × 同一功能」:一方動作,另一方看到什麼 | 老師按暫停,學生畫面發生什麼? |
| 跨模組資料流 | 模組 A 產生、模組 B 消費的每項資料:B 憑什麼拿到 | 選題結果如何決定遊戲中出的題? |
| 生命週期 | 每個有狀態的東西:中途加入 / 再來一場 / 異常結束 | 遊戲開始後才到的學生能進嗎? |
三分流——按「誰能解決」分類,不是按重要性:
| 類 | 定義 | 處理 |
| A | 只有用戶知道的政策/意圖 | 加入 dark 清單,動態補問(規則見下) |
| B | 可從既有 bright 合理推導 | 不提問——寫成推定句批次確認:「我假設 X,對嗎?」一次最多 5 條,附預設值,用戶可逐條翻案 |
| C | 實作機制(payload 結構、傳輸通道、儲存方式) | 永不問用戶。寫入 known_risks,前綴「邊界缺口(留待分解裁決):」,由 goal-decomposer 的接線矩陣與前置裁決處理 |
A 類補問規則:
- 一律用情境題,模板:「當{角色}在{時刻}{動作},你期望發生什麼?」
- 情境題附 2–4 個可選政策,每個選項後緊跟一句後果(這個選項對用戶的業務/體驗意味著什麼)。 後果只能從既有 bright 推導,推導不出的標「(推測)」;禁止為了讓後果具體而發明規格沒有的數值。 (沙箱實測:附後果讓用戶一輪內做出知情決定;無後果時系統代採的預設與用戶知情後的選擇方向相反)
- 用戶反問(要求了解這個決定的影響)而非作答 → 展開逐選項後果展示(同一條推導鐵律), 重問一次原情境題;仍不確定才降級
- 用戶說「不確定」「你決定就好」=委託、不是決定:不得寫入 bright,照降級規則記 known_risks 採預設,provenance 保留委託原話(這是「用戶未答」與「用戶明確決定」之間的第三態)
- 禁止出現 payload / 事件 / 協議 / API 等實作詞彙(題目寫不出無術語版 = 它其實是 C 類)
- 維持既有節奏:每輪 1–2 題、同主題(行為契約規則 4 不變),最多追加 2 輪
- 超出 2 輪容量的 A 類項:按影響排序取前 4,其餘降級為 known_risks 「邊界缺口(用戶未答,採預設:…)」——寧可留下看得見的缺口,不可留下沉默的缺口
矛盾掃描(與邊界格列舉同時跑): 四類邊界格是「前向列舉」(從 bright 推出該存在什麼),抓得到遺漏、抓不到互斥。 另跑一遍反向檢查:規格裡有沒有兩句話不能同時為真? (實測案例:某規格資料模型寫「位置 0 = A 方勝」,另一段視覺描述卻寫「物件抵達位置 0 = B 方勝」 ——純前向列舉永遠看不到,因為兩句各自都「有人負責」,是它們互相矛盾。) 每條候選矛盾必附「可調和解讀」欄位:若存在讓兩句同時成立的解讀,寫出它+它依賴哪個 規格未聲明的假設。存在調和解讀不等於免報——改以「關鍵語義未定義」形式報告,裁決時把該假設 顯式化。(沙箱實測:這個欄位同時是誤報抑制器〔實測誤報≈0〕與變形偵測器——掃描器自己採用了 調和解讀時,同一個病根仍會以鄰接衝突的形式現身被捕獲。) 發現矛盾 → 走步驟七之二的衝突處理協議(呈現給用戶裁決,不自行選一邊)。
未定值鐵律(C 類處置的硬約束):
規格沒給的具體值(數值常數、payload 欄位、傳輸通道、儲存結構),
永遠不可以事實語氣寫進 bright——它要嘛是 A 類退回用戶、要嘛標成
「邊界缺口(採預設:…)」交 goal-decomposer 裁決。
反模式(實測,禁止):扮演工程師「果斷拍板」殭屍每題移動 ±10、
把選題結果塞進 game:start payload——這些是猜測鍍上工程權威,
會被下游當事實凍進契約,比用戶答「你決定」更危險(錯得更自信、更難回溯)。
規格收斂只記錄「規格說了什麼」與「規格沒說什麼」,不發明「規格該是什麼」。
Pass 1(含矛盾掃描)跑完、發現照上方三分流分類處理後,設 boundary_scan: "pass1",無條件進 Pass 2。
Pass 2 — 體驗 / 交付 / 完整性 lens
用 Pass 1 結構上看不到的鏡頭,重掃一遍 bright + 已收集的驗收條件:
| 鏡頭 | 列舉方式 | 範例(實測漏過的) |
| 缺漏交付物 | 系統已有 / 會產生的資料或能力,有沒有「該輸出或呈現、但從沒人要求」的? | 系統存了正確答案 → 老師要不要一份「解答卷」PDF? |
| 範圍 vs 來源落差 | 用戶聲明的範圍 對上 真實來源材料 / 真實使用情境,落差在哪? | 只做選擇題,但大黃卷一張混選擇 / 填充 / 計算 |
| 介面三態 | 每個畫面的 空狀態 / 載入態 / 錯誤態 / 第一次使用 | 題庫空的時候首頁長怎樣?OCR 失敗顯示什麼? |
| 裝置與通道現實 | 主要操作的裝置 / 權限 / 離線 / 效能限制 | 出卷預覽 25 題在手機上擠不擠?iOS 相機權限? |
| 高頻操作摩擦與可逆性 | 最常做的動作有沒有摩擦?能不能取消 / 重來 / 修改? | 一張多題的確認頁怎麼逐題改?存錯能回退嗎? |
| 反身盲點 | 直接問自己:「Pass 1 的四類邊界格方法,在這個產品上系統性看不到什麼?」 | (開放題,逼出方法之外的缺口) |
Pass 2 的發現一樣照上方「三分流」分類(A 補問 / B 推定確認 / C 記 known_risks)。
螢幕型 UX 強制輸出欄位(modality=screen 時,handoff 前必填——讓 UX 不被「最多 2 輪」上限擠成沉默缺口): 「介面三態」與「高頻操作摩擦與可逆性」兩鏡頭改成強制輸出 STATE 欄位、不另佔追問輪次:
ui_states:對每個「會有資料的主要列表/詳情畫面」記 空狀態文案方向 + 載入要不要骨架 + 錯誤可否重試(政策面,非實作)。類型 C(消費型 App)時「首次使用態/onboarding」升 A 類主動補問(綁 C-12 留存迴路);其餘類型維持 B 類推定。critical_flow_reversibility:對最高頻 1–2 個操作記 步數 + 能否取消/回退 + 批次逐筆編輯。 兩欄都必須進 CLAUDE.md 的「UI/UX 規格」驗收章節(見output-templates.md)——讓 UX 缺口變成驗收條件而非末段才掃。non-screen modality 時不要求。
收斂閘(loop-until-dry):
- Pass 2 找到新的 A 類缺口 → 照「A 類補問規則」問(與 Pass 1 的 A 類合併計入「最多追加 2 輪」上限),處理完再判一次還有沒有新發現。
- Pass 2 跑完沒有任何新缺口 → 乾淨收斂,
boundary_scan由"pass1"進到"done"。 - 撞到「最多追加 2 輪」上限仍有未答 A 類 → 照既有規則降級 known_risks「邊界缺口(用戶未答,採預設:…)」後設
"done"。
兩段都跑完、Pass 2 收斂後 boundary_scan === "done"(schema 1.1 容許附加欄位;中間態 "pass1")。
known_risks 中全部「邊界缺口」條目必須原樣進入 STATE_FINAL,
讓 goal-decomposer 看見它在接手什麼。
步驟八:輸出 Handoff 套件
觸發條件: round >= 5 且 dark.length <= 2 且 pending_conflict 為 null
且 boundary_scan === "done"(= Pass 1 + Pass 2 兩段都跑完並收斂),
或用戶說「可以了」/「夠了」(若 pending_conflict 非 null 先要求解決;
兩段邊界掃描未跑完則先補跑——但用戶喊停時不再提問:A 類項全部降級為
known_risks「邊界缺口(用戶未答,採預設)」後直接輸出)
讀取 references/output-templates.md 取得格式範本,輸出三個檔案:
| 檔案 | 目的 | 讀者 |
README.md | 人讀需求文件 | 用戶、合作夥伴、工程師 |
CLAUDE.md | 直接執行規格 | Claude Code agent |
STATE_FINAL.json | 可攜帶的收斂狀態(schema 1.1) | 新 session 繼續 / 工程師接手 / goal-decomposer 輸入 |
CLAUDE.md 禁止事項區塊(防止過度開發):
## 明確不做
- [列出所有用戶確認不做的功能]
- [每條附動機與偽裝形態邊界:允許什麼最小替代、禁止什麼]
- 未在功能清單內的功能,實作前必須先確認handoff 前最後檢查:對「明確不做」清單 × 全部驗收條件跑一次交叉檢查, 任何驗收條件隱性需要禁區功能 → 視為協議二的矛盾,解決後才輸出。
旅程覆蓋檢查(與上述交叉檢查同時跑): CLAUDE.md「用戶旅程」章節的每一步(含「打開產品的第一個畫面」與每一次頁面跳轉), 必須能指出由哪個功能模組的哪條驗收條件支撐。 任何一步沒有模組認領 → 補進對應模組的驗收條件後才輸出 (沒人認領的旅程步驟 = 下游 goal-decomposer 的無主地帶,是整合斷裂的最大來源)。
步驟九:接力提議(handoff 後,能力閘 — ADR-004)
輸出三檔 handoff 後主動提議下一棒,不要讓用戶為了前進而重打「幫我分解」。同 ADR-001 能力閘(偵測工具有沒有,不是身分):
- 有
AskUserQuestion類工具 → 收尾問一題:「規格收斂好了(complexity=X、N 個核心功能)。要現在接力分解成可執行的 goal 圖嗎?」選項:[建議 — 現在分解(goal-decomposer)] / [我先看規格再決定] / [先停在這]。 - 沒有(Codex / Manus / 純文字)→ 同內容用文字提議(「要分解就說一聲」)。
- 用戶選「現在分解」→ 直接進 goal-decomposer,讀剛輸出的
CLAUDE.md+STATE_FINAL.json,不必重述。 - 選別的 → 停,等用戶。
為什麼:階段交接靠「使用者記得打對暗號」是人工接縫——換成「每段做完主動問下一步」=端到端可一路按到底、又不剝奪人的拍板。工具不在=優雅退文字,公開使用者跨平台不壞。
參考資料
| 檔案 | 何時讀取 |
references/dark-zone-baseline.md | 步驟三:初始化暗區清單時 |
references/output-templates.md | 步驟八:輸出 handoff 套件時 |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

