dannys42/design-session

設計會議

在記錄任何內容之前，與擁有者一起仔細思考設計。擁有者主導；代理人拓寬選項，展示每個選項的意涵，並保持對話誠實。在最終的推廣步驟之前，沒有任何內容會進入系統設計，由擁有者選擇哪些要納入。

可在任何時間點使用：在系統設計存在之前、在里程碑規劃期間，或在里程碑進行中。術語（系統設計、附加檢查、可審查表面、settled/working、owner/proposed、里程碑、spike、臨時代碼、擁有者偏好、兩次覆寫規則）定義在 system-design 技能的 terms.md 中；請按照那裡的定義使用。

檔案

<DocDir>/SystemDesign/
  Overview.md                       系統設計 (system-design)；僅由推廣步驟修改
  Sessions/<日期>-<短主題>.md        此技能的暫存筆記，在推廣步驟後刪除

<日期> 為 YYYY-MM-DD；短主題 為 2–3 個單詞，使用底線命名法 (Snake_Case)，例如 2026-11-01-Review_Import.md。筆記為自由形式：無 ID、無狀態、無同意標記、無問題上限。它們記錄擁有者的草稿、考慮過的方案及其圖表、追蹤到的後果、發現的矛盾及其解決方式、spike 結果，以及擁有者的傾向。每當對話有進展時就更新它，這樣一個提前終止的會議可以從檔案中繼續。

工作流程

1. 閱讀，然後讓擁有者主導

讀取系統設計以及主題涉及的任何子系統文件、路線圖的當前里程碑、<DocDir>/Taxonomy.md、專案規則檔案（CLAUDE.md 或同等文件），以及擁有者偏好檔案 ${DANNY_SKILLS_STATE_DIR:-$HOME/.local/state/danny-agent-skills}/owner-preferences.md（如果存在）。如果 Sessions/ 中已存在此主題的筆記檔案，則從它繼續。否則，建立它並說明路徑。

詢問擁有者他們的想法，並用幾行文字以及（當它具有兩個或更多部分時）一個圖表來反映他們的草稿。只問那些會改變方案的問題；永遠不要問那些你可以作為默認值陳述的問題。

2. 提供替代方案

提供 2–3 個方案，擁有者自己的草稿算作一個。對於每個方案：一個遵循 plan-milestone 技能 diagrams.md 的 Mermaid 圖表（節點標籤須完全使用系統設計的元件名稱，新零件標記為 sketched，方案變更的內容標記為 touched）、一個關於該方案在專案中某個案例上如何運作的簡單範例，以及一行優點和缺點。然後推薦其中一個，或者說「無推薦」並說明原因。根據新事物的功能來命名它們 (terms.md, "Names and labels")。按照 diagrams.md 中的說明對每個圖表進行渲染檢查。

3. 追蹤後果

對於擁有者傾向的方案，說明它變更了哪些內容：子系統、接縫 (seams)、資料模型、可審查表面（僅在該處逐欄位說明）、名稱以及威脅和隱私部分。對每個後續里程碑的界線執行附加檢查：如果某個後續里程碑不經過重構就無法新增，則說明哪個接縫必須在此時決定。如果尚無系統設計或無後續里程碑界線，則跳過附加檢查，直到里程碑存在；切勿為了檢查而發明里程碑。指出方案會變更的每個 settled 項目；變更一個就是重新規劃的觸發點。將接縫內部的實作細節保留為未決定；細枝末節放在「執行後再決定」清單中。

4. 找出矛盾

當擁有者所說的內容與本次會議中先前的陳述、一個 settled 項目、一個擁有者偏好、專案規則或 Taxonomy.md 中的名稱衝突時，請明確說出。引用雙方的說法，並詢問哪個成立。將答案記錄在筆記中。

5. 提供一次性實驗原型 (Throwaway Spike)

當唯有執行某個東西才能解決問題時（夠不夠快、API 是否回傳這個、平台能否做到那個），提供能回答該問題的最小執行方案：它做什麼、哪種結果指向哪條路，以及大約需要多長時間。只有在擁有者接受時才實作它，在產品程式碼之外（一個暫存目錄或一個一次性分支），執行它，並將結果記錄在筆記中。程式碼會被丟棄；如果擁有者想要保留它，則在步驟 6 中將其推廣為臨時代碼。

6. 推廣 (Promote)

當擁有者表示他們已完成，或者討論已趨於收斂時，列出筆記中所有可能進入系統設計的項目，採用 presenting-for-review.md 中的形式，每個項目都附上一個建議結果：

• 推廣為 settled 或 推廣為 working 並附上其重新審視註記（「如果…則重新審視」）。
• 擱置 (Park) 以供後續里程碑處理，指出該里程碑名稱。
• 放棄 (Drop)。

在同一則訊息中，根據兩次覆寫規則提出擁有者偏好條款：僅在擁有者於本次會議中兩次覆寫了你提供的同一類型方案，或者明確表達了某種品味時。每個條款一行（偏好、一個範例、日期），說明它是放入跨專案的擁有者偏好檔案還是專案規則檔案。單次裁決是決策，不是偏好；關於此技能行為的回饋應進入回顧會議，而不是這裡。對於擁有者措辭中的每個項目（名稱、結果文字、接縫），在同一則訊息中提出一次 system-design 技能的步驟 4 緊縮提議：列出每個不明確之處，並在原始版本旁邊顯示一個緊縮版本；擁有者接受、編輯或保留它。以一個問題結束。

將擁有者的裁決應用到系統設計中（overview-template.md），作為一次普通編輯：

推廣的項目	去處
一個元件	一個元件行（sketched、建置目標、協議）和一個僅具有其深度類別的圖表節點，從不使用 touched
一個接縫	一個接縫與介面行及其協議
一個表格、API 或公開符號	可審查表面，逐欄位，帶有標記
一個實體或關係	資料模型
一個名稱	名稱，然後是 <DocDir>/Taxonomy.md，與其餘部分一起作為一組審查
方案間的選擇	一個決策行：下一個可用的 D ID，類別 choice，協議 settled 或 working (revisit if …)，原因說明被拒絕的方案
會議發現的一個未知數	一個風險行及其最低成本實驗
對後續里程碑的變更	其範圍和里程碑行以及附加檢查儲存格
擁有者保留的 Spike 程式碼	一個臨時代碼行，以及程式碼中的 PROVISIONAL 標記
一個被擱置的結構性項目	一個開放問題行，指出它所等待的里程碑，例如 "Q4 (parked until M3, record changes): …"
一個被擱置的細枝末節	"執行後再決定"清單，位於將解決它的里程碑之下

協議標記遵循模板：由擁有者撰寫或編輯的項目標記為 owner（例如 settled · owner）；擁有者未經修改接受的項目不帶 proposed 標記。新的 ID 繼續文檔的序列，且永不重用。對已協議項目的變更需要通過決策日誌，而非靜默編輯。當一個推廣的項目變更了一個 settled 項目（例如一個接縫），或者擁有者請求為當前里程碑增加了結構時，請明確說明需要重新規劃，並在以下提交之後撰寫一個交接備註，以便 /rung 可以在後續的任何會議中路由此重新規劃：<DocDir>/Handoff/replan-<日期>.md，內容包括 Route: replan、Model: opus、Waiting on: re-plan after the design session on <主題>、Date:，以及一個說明變更的項目和提交記錄的內文 (handoff.md)。放棄的項目不記錄；筆記檔案在 git 歷史中保留它們。將被接受的偏好條款寫入擁有者選擇的檔案。

如果系統設計尚不存在，則將推廣的項目寫入一個新的 Overview.md，使用模板的標頭（Status: draft），並且只填入它們所填寫的章節；system-design 會從這裡繼續。

提交（透過明確路徑暫存）系統設計、Taxonomy.md（如果已變更）、專案規則檔案（如果已變更）以及筆記檔案，提交訊息為 Design session: <主題>，以便歷史記錄保留筆記。然後執行 git rm 刪除筆記檔案，並提交該操作，提交訊息為 Remove design session notes: <主題>。記錄一個 step 事件，包含 skill design-session 1.0.1 和 kind design-session（其他欄位請參閱 tasklist-run 的指標日誌），以及你提議進行推廣的項目計數：proposed、accepted（未修改）、edited 和 rejected。

以一句簡單的話結束，說明哪些內容已變更以及下一步是什麼，然後是 Next: /rung，如果該步驟需要 Opus，則加上 (Opus: /model opus)：一個仍需協議的系統設計、里程碑規劃，或者步驟 6 說明的需要進行的重新規劃。

如果擁有者在推廣之前停止，則將筆記檔案保留在原處，不要提交，並說明其路徑；下次關於該主題的設計會議將從它繼續。

如果連結的檔案或技能缺失

當連結的檔案缺失時，不要停止：使用此處的最低限度內容，並用一兩行說明哪些內容缺失以及如何安裝它（claude plugin install project-planning@danny-sung-agent-skills，或 npx skills add dannys42/agent-skills --skill <技能名稱> 安裝到同一個技能目錄，以便相對連結可以解析）。

• 無 terms.md：settled 預期會保持不變；working 表示足夠好可以開始，並且說明什麼會讓我們重新審視它；owner 項目是擁有者的話，proposed 是代理人的。附加檢查詢問每個後續里程碑是否可以在不重構的情況下新增。
• 無 diagrams.md：Mermaid flowchart，引用每個標籤，標籤是元件名稱，每個深度一個類別（sketched 虛線、designed 細線、built 粗體）。
• 無 presenting-for-review.md：重要的項目優先（最多 5 個，難以逆轉或影響廣泛），每個項目附帶選項、一個簡單範例、一個優點和缺點以及一個推薦；以一個問題結束。
• 無 overview-template.md：將項目推廣到系統設計的現有章節中，匹配它們的表格和標記。

判斷取捨

• 擁有者主導。 提供方案和後果；不要盤問或引導到你偏好的方向。一個不會改變方案的提問不值得提出。
• 自由探索，狹義推廣。 會議中可以討論任何內容，但只有結構會進入系統設計：子系統、接縫、資料模型、可審查表面、名稱、決策和風險。內部實作細節則不納入。
• 一次實驗原型 (Spike) 勝過爭論。 當擁有者和代理人對一個可以透過短時間執行來解決的事實有分歧時，提供執行方案，而不是繼續辯論。