yasyf/design-doc

design-doc 是做什麼的？

gemini-4-argon 撰寫並修訂所有散文，包含摘要、簡明說明（plain twins）、代號（handles）、修訂備註及發表文字。工作階段透過 gemini -m gemini-4-argon --skip-trust -p 將事實與規則（寫作合約、防廢話規則、長度限制）傳遞給模型，並逐字記錄回覆，再由自身收集證據並發布結果。散文輔助工具透過 gemini --skip-trust -p 呼叫相同模型，且不設後備模型。

架構設計是一系列建立在假設堆疊之上的決策堆疊。此技能將設計過程轉化為對話形式——由使用者決定一切——並將結果呈現為一份文件，其中每個主張都可以追溯到一個假設、一個決策以及產生它的問題回合。

單一指令驅動所有機械化部分：

TOOL="python3 ${CLAUDE_PLUGIN_ROOT}/skills/design-doc/scripts/design.py"
$TOOL scaffold --title <name>   # 為此設計文件建立新的 ./<slug>/ 目錄
$TOOL scaffold --example        # ./tinyq/，一個已填入內容的小型範例
$TOOL check <dir>               # 檢查暫存器、簡明說明、圖表來源與摘要面板；錯誤時以非零狀態碼退出，--strict 會將阻止發布的警告視為錯誤
$TOOL summary-text <dir>        # 將面板內容輸出為 Markdown，每個 ## 區段一個面板；作為閘門的輸入
$TOOL plainify <dir> [--only DQ3,A2] [--dry-run]
$TOOL glossary <dir>            # 找出散文中使用但詞彙表缺少的術語，作為候選條目
$TOOL build <dir>               # 將 components/*.tsx 編譯為 components.js；僅適用於包含 components/ 目錄的文件
$TOOL render-check <dir>        # 在無頭 Chrome 中渲染每個 Mermaid 區塊；解析錯誤或頁面異常時失敗
$TOOL pdf <dir>                 # 透過範本的列印樣式表將文件輸出為 <dir>/design-doc.pdf
$TOOL snapshot <dir> --note "…" --item "…" # 蓋上一個修訂版本戳記，供「變更記錄」檢視比對；note 是面向讀者的標題，每個 --item 代表一項變更
$TOOL links <dir> [--fetch] [--missing] # 列出每個決策與待辦問題及其 Pull Request 連結與狀態；--fetch 向 GitHub 查詢每個連結是否已合併並報告偏差，--missing 列出尚未連結的條目

在開始階段 1 之前，請閱讀 reference/method.md；在開始階段 5 之前，請閱讀 reference/writing.md；在開始階段 6 之前，請閱讀 reference/publish.md。方法檔案是回合/暫存器協定，寫作檔案是語調合約，發布檔案是託管流程。reference/schema.md 是 JSON 檔案逐欄位的規格；若想查看完整暫存器範例，可執行 tinyq 範例的 scaffold。

術語

• 暫存器（Register） — registers.json 中的一個結構化列表，其條目具有穩定的 ID：A# 假設、DQ# 決策、Q# 待辦問題、V# 技術驗證任務、c-<slug> 架構卡片。
• 回合（Round） — 一次提交給使用者的討論板，其內容會逐字記錄在 qa-log.json 中。一個回合同時提出所有未決的分叉，每個分叉以一個 design-doc.fork 區塊呈現，且不提出其他問題。開啟新分叉的答案會啟動下一個回合，同樣一次提出所有分叉；qa-log.json 按順序記錄回合，因此後續的討論板可以依賴先前的答案。
• 取代（Supersession） — 當一個決策被變更時，會建立一個新的條目，舊條目則獲得 s: "superseded" 狀態，並加上 by 指標指向新條目。文件會將此渲染為「已被取代為」，並顯示新條目的標題。由於沒有原地編輯任何內容，歷史記錄保持清晰可讀。
• 星號（★） — 標記承重假設（load-bearing assumption），即一旦失效就會使整個文件無效的那個假設。
• 技術驗證任務（Spike） — 一個具名且限時的實驗（V#），其目的是將帶有 (E) 標記的估計值轉換為實際測量數值。
• 執行摘要（Executive summary） — summary.html，一個置於 registers.json 旁的手寫 HTML 片段，專為只想閱讀重點的讀者設計：預設為一系列全螢幕面板，當設計只有單一概念與單一圖表時則為一張海報。此摘要從不被當作資料解析；check 指令會檢查其結構、字數預算與引用。
• 簡明說明（Plain twin） — 條目精確措辭旁的 p 欄位，以一兩句簡短句子說明該條目對不願仔細閱讀者的意義。文件預設顯示簡明說明，並提供一個切換開關來顯示精確措辭。
• 關鍵項（Key）與主題（Theme） — key: true 標記文件開頭以卡片形式呈現的 3-8 個決策與假設；theme 欄位將每個條目歸入設計的 3-5 個主題之一（在階段 0 命名，並在 themes 映射中定義）。
• 圖表（Diagram） — 系統圖表的 Mermaid 原始碼，位於 diagram 暫存器鍵中；文件會渲染它，讀者可以平移和懸停，請求路徑會在上面逐步呈現。diagram.overview 是「概覽」卡片所繪製的十個節點子集，完整圖表只需一次點擊即可查看。手繪的 sysd.svg 在設為 diagram.kind: "svg" 時仍然有效。
• 代號（Handle） — 每個決策、假設、待辦項目、架構卡片和數字表格的 h 欄位：讀者會如何稱呼它，兩到五個字。引用和晶片行會顯示代號；ID 則存在於懸浮卡片中。
• 元件（Component） — 在 components 映射中宣告的互動圖形（dd.tabs、dd.before-after、dd.whatif、dd.steps、dd.timeline、dd.matrix、兩個比較面板圖形 dd.flow 與 dd.lanes、手繪系統地圖 dd.system，以及嵌入已發布架構文件的 dd.arch），並透過 ID 放置在面板或條目上；components/ 目錄下的 TSX 檔案是 build 編譯的後備方案。
• 圖說簡報（Figure brief）與評論（Critique） — NOTES.md 中的兩個區段，用於提取面板內容並作為檢視依據。簡報在繪製圖形前撰寫，每個圖形五行：它要說明的要點、它所服務的決策 ID、能說明要點的最小視圖、它省略了什麼，以及它使用的真實標籤。前兩行會成為 <figcaption>。評論則在撰寫時針對每個面板、圖形、表格和統計資料各有一行：它所服務的決策、它宣稱的事實、讀者可能留下的疑問，以及是修正還是刪除。當任一標題缺失時，check 會發出警告。
• 連結（Link） — 決策、待辦問題或發現結果條目中的 links[] 欄位：指涉的 Pull Request、Issue、提交或文件。待辦問題連結上的 closes: true 標記了將其關閉的連結。文件會將每個連結顯示為一個帶有 GitHub 狀態的晶片，並在每個開放群組的頂部顯示其中有多少項目已關閉。
• 狀態：決策為 resolved | superseded | open，文件渲染為「已決定」、「已被取代」和「仍然開放」；假設為 working | validate，渲染為「已假定」和「需要有人確認」（需要文件外部的人確認）。待辦問題為 open | closed，渲染為「仍然開放」和「已關閉」；一個已合併的 closes 連結會在 s 欄位更新之前關閉項目。散文使用渲染後的文字，JSON 使用值。

範疇

此技能的範圍止於設計。其產出是一份決策記錄與一份文件；實作程式碼是另一個任務，必須在提案通過審查後才開始。四個閘門確保記錄的真實性：

• 設計分叉由使用者決定。每個分叉都必須經歷一個回合，即使其中一個選項看起來明顯正確：記錄為什麼的價值遠大於節省下來的互動次數。
• qa-log.json 是逐字記錄且只能附加，不可修改。可以修正答案中的拼寫錯誤，但不得更改實質內容，並跳過僅供說明的互動；它是決策日誌，而非對話記錄。
• 敵意審查的產物不得納入最終渲染的文件。只有它所導致的決策才會被納入；一個「發現」章節只會顯得自吹自擂，對讀者毫無幫助。
• 文件不得攜帶虛榮計數（「27 個條目」、「9 個待辦技術驗證任務」）。數字僅在描述系統而非描述努力時出現。

階段 0 — 建立框架與診斷

執行 $TOOL scaffold --title <name>。每個設計文件都應存放在自己全新的目錄中——scaffold 會建立 ./<slug>/（可透過位置引數傳入明確路徑以放置在其他位置），並拒絕非空的目標目錄，因此一個設計絕不會混入另一個設計的檔案或現有專案中。在提出任何建議之前，先訪談使用者關於當前系統的狀況：存在什麼、什麼地方有問題，以及原因為何。將診斷結果以根本原因而非症狀的形式寫入 NOTES.md（例如「持久性延遲即為 S3 延遲」，而非「寫入速度慢」）。診斷結果永遠不應出現在討論板上：直接寫入 NOTES.md，讓使用者在渲染後的文件中檢閱，而他們提出的任何修正都應以他們自己的話語整合回去。最後以一個分類來總結診斷結果，該分類將成為執行摘要的基礎：是對現有系統的變更，還是全新的建置，背後只有需求。同時為設計命名三到五個主題（例如「儲存」、「調度」、「租戶」）：它們將成為決策與假設所歸屬的 themes 映射；如果診斷結果無法命名一個主題，就表示該設計沒有這個主題。基於錯誤診斷的設計會浪費後續所有階段的努力。

退出標準： 專案目錄已建立；使用者已閱讀渲染後文件中的診斷結果（包含「變更」或「全新建置」以及主題），並且同意其內容。

階段 1 — 假設

在第一個回合之前，檢查可用技能清單中是否有 cc-present:present（即 /cc-present 看板技能），如果有的話，則使用 Skill 工具呼叫它。從第一個問題開始，訪談就應透過即時看板進行，僅在沒有 cc-present 的情況下才使用 AskUserQuestion 作為後備。此擴充功能附帶自己的區塊包——執行 cc-present pack list 並閱讀 design-doc 的參考片段；其中的 design-doc.fork 區塊是訪談介面，也是訪談看板上唯一攜帶的區塊。

將假設直接寫入 registers.json；無需透過看板來確認或挑戰它們。絕不要將 design-doc.claims 區塊、確認/挑戰掃描或暫存器傾印內容呈現給使用者：他們應在渲染後的文件中檢閱假設，而他們提出的任何修正都應以他們自己的話語整合回去。如果一個假設需要先做出選擇才能繼續設計，那它就是一個分叉，應在階段 2 的看板上以 design-doc.fork 區塊呈現。從診斷訪談、程式碼和使用者已說過的話中收集基本事實：設計必須滿足的限制、關於規模與工作負載的事實、使用者相信但尚未驗證的事情。每個基本事實成為一個 A# 條目，狀態為 working 或 validate；為承重假設加上星號，並將每個需要確認的條目的確認者記錄為一個待辦問題。當使用者指出某個假設不穩固時，該標記應記錄在條目中；替使用者解決它會違背暫存器的目的。

退出標準： 使用者已檢閱渲染後文件中的假設，且這些假設涵蓋了使用者所知的一切；$TOOL check 指令執行結果乾淨。

階段 2 — 設計回合

透過問題回合進行設計。訪談是一個 cc-present 看板，一次提出所有未決的分叉，每個分叉以一個 design-doc.fork 區塊呈現，並附帶豐富的選項：每個選項的後果、優缺點、一個推薦選項，以及開啟清單的逃生門。看板上只攜帶分叉區塊，不應有任何其他內容。任何非分叉的內容都是缺陷：例如 design-doc.claims 區塊、確認/挑戰掃描、design-doc.registers 傾印或上下文區塊。分叉本身的問題、後果與優缺點即包含了它所需的上下文。回答中開啟的新分叉將進入下一個看板，以相同方式建構。

回合在一個即時的 cc-present 看板上進行：在第一個回合之前（在階段 1 和這裡再次檢查），檢查可用技能清單中是否有 cc-present:present（即 /cc-present 看板技能），如果有的話，則使用 Skill 工具呼叫它——其指示規範了如何撰寫和推送看板，之後的每個回合都透過看板進行。一個分叉就是一個 design-doc.fork 區塊，其選項內嵌了後果，逃生門則返回 {defer: {title, why}}：由人類來命名這個待辦問題，因此 Q# 記錄時無需再花一個回合詢問要如何稱呼它。如果缺少此區塊包，則以手動方式使用一個純 choice 區塊來承載相同的結構——每個選項都有後果描述、一個標記為「(推薦)」的選項，以及一個實際上會將 Q# 加入佇列的最後選項「加入待辦清單」——而 AskUserQuestion 是最後的互動介面，僅在 cc-present:present 不在技能清單中使用。在看板技能存在的情況下，設計分叉絕不透過 AskUserQuestion 進行。每個分叉都應以一個讓人能立即回答的簡單問題提出（例如「工作應該如何被工作節點接收？」）。它所解決的暫存器 ID 應放在區塊的 decides 欄位中，或者在 AskUserQuestion 的 header 之後，絕不放在問題文字中；選項的後果應說明會發生什麼事，而非它取代了哪個條目。這些回合是訪談，而非問卷調查：指出當前草稿的缺陷、建議使用者未提及的替代方案、在證據不一致時提出質疑，但你自己不要做出任何決定。每個回答成為一個 DQ# 記錄，包含決議、被否決的替代方案以及回合編號。當後續回合變更了先前的決策時，應進行取代：建立一個新的 DQ#，並在舊條目上加上 by 指標。

退出標準： 待辦清單之外沒有未決的分叉；每個 DQ# 都能追溯到 qa-log.json 中的一個回合。

階段 3 — 敵意審查

在草稿尚未被修飾得難以找出缺陷之前，對中間草稿進行攻擊。當 codex 外掛技能可用時使用它；否則，建立一個全新的子代理（subagent），其對設計不帶任何立場，並指示它以懷疑的資深工程師身份進行攻擊：尋找正確性錯誤、遺漏的失效模式、不合理的數字。將輸出內容逐字儲存為 <reviewer>-review-<date>.md，並將每個發現索引到 findings 暫存器中（僅資料，永不渲染），並為每個發現設定處置方式：一個新決策、一個待辦問題，或一個記錄在案並附有理由的拒絕。透過程式碼修正的發現應將修復該問題的 Pull Request 作為該行的第五個元素，格式與 links[] 條目相同。需要由使用者決定的發現則像其他任何回合一樣處理，其問題應以文字說明審查者發現了什麼，並包含發現編號。

...

[截斷以進行翻譯]