marcioaltoe/write-techspec

撰寫技術規格書 (Write TechSpec)

產出 docs/specs/<slug>/_techspec.md — 針對規格需求的技術性解答。PRD 說明了 什麼 和 為什麼；這份文件則決定 如何、在哪裡、以及 用什麼 — 其中的建構順序（Build Order）將由 write-tasks 轉換為任務圖，因此排序的品質直接影響後續的執行品質。

前置條件 — 兩種進入模式

$ARGUMENTS 指定規格名稱（slug 或路徑），或描述一個重構/錯誤修正。根據產品行為是否變更來選擇模式：

• 功能開發（產品行為變更）— docs/specs/<slug>/_prd.md 必須存在；如果不存在，則停止並引導使用者使用 write-prd。產品決策需要先進行產品對話。如果 PRD 中包含屬於此處的低階技術決策，請將其作為發現事項提出，並建議將它們搬遷至此，而非默默地重複。
• 重構或錯誤修正（無產品行為變更）— 此技能即為管線的進入點；不進行 PRD 訪談。當規格資料夾尚不存在時，遵循 write-prd 的編號規則（<spec-root>/NNNN-<kebab-slug>/，掃描已設定的規格根目錄及其已解析的歸檔目錄 — 對於內建的 docs/specs 根目錄為 docs/history/specs/，否則為 <spec-root>/_archived/ — 以尋找最高編號前綴）來建立一個，並寫入一份 最小化的 _prd.md，僅攜帶下游技能解析所需的最小合約：frontmatter（spec、status: active、surfaces，以及錯誤修正的 type: fix 或重構的 type: refactor）、問題陳述、專案限制、目標、核心功能、非目標，以及 ## Decisions 下的釐清記錄 — 以工程為框架，每項僅數行。該記錄遵循 write-prd 的釐清指南：每行一個 - YYYY-MM-DD: <問題> — <答案>，代表某人回答過的問題，或者當無人參與時使用 Autonomous route: no person present; decisions taken from <source>. 並命名作者決策的來源。其存在的目的是為了讓 write-tasks、qa-gate 和 archive-spec 維持單一 artifacts 合約，它並非產品文件。如果「重構」實際上會改變產品行為，請停止並轉向 write-prd。

基本規則

• 先讀再寫：CONTEXT.md（在每個介面和元件名稱中使用詞彙表中的詞彙）、現有的 docs/adr/（尊重先前的決策，或明確地挑戰它們 — 絕不默默違反任何一項），以及完整的 PRD。
• 先決策，再撰寫。 在釐清階段解決決策問題，將重要的決策記錄為 ADR，然後撰寫完成文件。無需進行大綱批准回合。
• YAGNI（你不需要它）。 當功能可以作為現有模組的附加項目時，不要提議新增新的套件、層級或目錄。每個新的結構元素都必須相對於已說明的替代方案來證明其存在的必要。
• 引用，不要複製。 透過名稱指向 PRD 章節（例如「涵蓋使用者故事 3–5」）；在此重複業務背景會產生兩個會漂移的副本。
• 使用所屬的來源路徑。 將每個被採用的來源連結到其採納後在擁有該規格中的路徑，目標路徑相對於 _techspec.md，切勿連結到參考索引中保留的採納前路徑。次要規格則連結主要擁有者的副本，且不採納任何東西。擁有者的歸檔會執行歸檔重新連結：將該副本提升至 docs/references/，並改寫次要規格的連結，使來源保持一個擁有者，而次要規格無需副本（ADR-0260, ADR-0083）。

共享上下文的來源

一個規格可以採納多個待辦事項（Backlog Entries）和發現事項（Findings），其上下文相似或互補；每個來源一個規格既非必要也非首選。在建立規格前，檢視開放的待辦事項和未解決的發現事項中，是否有共享上下文的來源。僅在範圍適合四個實作任務加上其 QA 門檻時才進行分組；超出此限制時，應拆分範圍並為每個來源指定一個擁有規格。

在建立新的發現事項或待辦事項之前，先擴充一個合適的：就地修訂一個開放的待辦事項，或為未解決的發現事項添加一個註記日期的附錄。

當 roundfix spec judge 列印建議的配對時，透過在範圍內採納開放的來源，或在報告中說明為何它們應保持分離，來回應每個建議配對。建議絕不會阻擋流程，且沒有建議也不表示沒有適合的項目；仍然需要檢查共享相同上下文的開放來源。回應某個發現事項或待辦事項的重構或錯誤修正，在建立其最簡 PRD 之前，應尋找與其共享上下文的其他項目。

流程

1. 探索架構

繪製功能將駐留的程式碼地圖：它擴充的模組、它可以附著的接縫、相同類型工作的既有模式（現有的轉接器、現有的任務執行器），以及可用的測試基礎設施。偏好現有的接縫而非新的 — 理想的新接縫數量為零。當有可用的子代理時，將探索工作委派給它；規格需要的是結論，而不是檔案轉儲。

在探索期間，從儲存庫的語義指南解析有效的專案限制：

• docs/agents/domain.md 擁有識別符指南並引導活躍 ADR 的發現。
• docs/agents/backend.md 擁有身份驗證和 HTTP 政策。
• 沒有該指南的儲存庫應引用擁有其介面政策之指南。
• docs/agents/agent-instructions.md 擁有通用的規範性條款，包括工具權限。
• docs/agents/spec-routing.md 擁有規格工作流程合約。

閱讀每個存在的路徑，並跟隨其連結找到有效的決策值。切勿推斷建議的預設值，或將缺失的指南視為授權。完成的快照必須將識別符策略、身份驗證和 HTTP、活躍 ADR 義務以及工具權限分類為「適用」或「不適用」並附上原因，且每一行都需引用有效的 docs/agents/ 來源路徑。

2. 釐清技術決策

與 PRD 階段的協議相同 — 每次一個問題，多選項並附帶建議的預設值和一行理由 — 但範圍限定在如何/哪裡/用什麼：架構位置、資料模型、API 形式、遷移策略、測試接縫、效能和安全限制。僅詢問探索無法解決的事項。

3. 記錄 ADR

每個重大的技術決策（難以逆轉 + 缺乏上下文會令人驚訝 + 存在實際的權衡）都成為 docs/adr/NNNN-slug.md，延續 PRD 階段使用的相同編號 — 整個功能的決策日誌是連貫的。每項 1–3 句話。

4. 撰寫

根據 references/techspec-template.md 中的模板撰寫 _techspec.md。以下兩個章節對下游影響最大：

• 每個 PRD 目標和使用者故事都對應到一個命名的技術元件。 未對應的故事是一個設計漏洞；現在就找到它，而不是在任務執行時。
• 建構順序（Build Order） — 編號的步驟，每個步驟（除了第一個）都需說明其依賴的前一個步驟。write-tasks 從中推導出任務圖的邊。

將 API 合約撰寫為編號的 API 合約項目，或單一條目 None. 並附上不適用的原因。每個編號合約必須能透過其名稱和編號在下游任務參考中被引用。

詞彙表術語

當技術規格書命名了一個詞彙表未定義的概念時，啟動領域建模，精煉該術語，並在 PRD 或技術規格書的詞彙表章節中宣告它。

具體合約

當某個聲明將行為歸因於決策記錄，或當技術規格書變更了命令介面時，請使用具體合約指南。它定義了聲明收據、介面轉錄區塊、QA 閘道使用的匹配慣例、程式碼簽章介面以及編號的不變量。

Project Constraints 是正文內容，絕非 frontmatter。當設計提議建立、編輯、重新命名、移動或刪除受保護的工具設定、腳本、忽略檔案、外掛宣告或版本鎖定時，請停止，直到維護者給予明確的維護者授權。將該批准和確切受限制的檔案記錄在「工具權限」行中。一個通用的實作請求、設定完成、沉默，或無限制檔案的授權，並不能授權此類變更。有效的記錄應位於 <spec-root>/<slug>/_authorization.md；一個 proposed 記錄或沒有授予日期的記錄不授權任何事項，因此在獲得有效授權之前，不要將受保護的工具工作推進到分解階段。一個新的或擴大的授權必須在消費性的 squash 交付之前到達目標祖先；將授權或修正案保持在其授權的變更之外。

保持介面草稿在 20 行以內；它們記錄形狀，而非實作。目標字數為 1,500–2,500 字 — 一份沒人閱讀的規格保護不了任何人。

每個由交付佇列交付的規格都附帶一個已批准的 _authorization.md，無論是否有受保護的工具。記錄中的 operations 列表命名 implement、commit、push、pull_request 和 merge；一個未變更任何受控路徑的規格則記錄 paths: []。

規格主張的證明

一份技術規格書在指定的位置記錄三個證明，而 roundfix spec check 會將缺少的位置報告為每個活躍規格的缺口。檢查僅讀取結構；證明是否正確則留給讀者判斷。

• 缺席證據。對於技術規格書宣告為新的每個元件，在 ## Absence Evidence 下記錄證明其缺席的搜尋，作為編號項目：元件、command: 包含反引號內的搜尋指令，以及 result: 包含找到的內容。搜尋技術規格書引用的檔案中的行為，而不僅僅是名稱。當沒有任何新元件時，寫 None. 並附上原因。SC-ABSENCE-UNPROVEN 報告缺少宣告或項目缺少其指令或結果。
• 被拒絕的替代方案。在 ## ADR Alternatives 下，為活躍 ADR 義務行中列出的每個 ADR 撰寫一行 - ADR-NNNN: <關係>：設計如何與該 ADR 拒絕的替代方案相關。當設計採用了被拒絕的替代方案時，請說明並取代或修訂該 ADR。SC-ADR-ALTERNATIVES-UNRELATED 報告列出一個 ADR 但沒有其對應行。
• 覆蓋率交叉比對。在 write-tasks 之前，針對覆蓋率地圖命名的元件，閱讀每個 PRD 使用者故事、核心功能和成功指標。在覆蓋率地圖中加入一行 Deviations from the PRD:，其後接 None. 或每個技術規格書以不同形式交付的 PRD 單元列表（命名該單元和原因）。SC-COVERAGE-UNREAD 報告缺少該行或一個未命名 PRD 單元的偏差。

5. 報告

在報告之前，重新閱讀完成的作品以及由此技能建立的任何最小 PRD。除非每個新的 artifacts 都具有 Project Constraints；所有四行都陳述為「適用」或「不適用」並附帶理由；每一行都引用一個有效的 docs/agents/ 來源；以及任何受保護的工具變更都記錄了明確的維護者授權和限制檔案，否則你絕不能報告完成或建議使用 write-tasks。將授權保持在 frontmatter 之外。

然後針對產出 artifacts 的階段執行檢查器：

roundfix spec check <slug> --stage techspec --run-verification

一個錯誤級別的發現或檢查器執行失敗會阻止報告。修正發現所指名的 PRD 或技術規格書，然後重新執行指令；在上述任一情況存在時，不得報告完成或建議使用 write-tasks。

一個乾淨的技術規格書階段結果並非完整的規格覆蓋率。此階段不決定任務圖 ADR 記帳、任務覆蓋率、上下文參考、驗證獨立性、需求矛盾或演練宣告；依賴提交的更動路徑範圍；尚未機械化的規則；或產品目標是否透過其使用者可觸及的介面運作。任務撰寫階段、完整的非範圍掃描以及 QA 保留這些類別。將檢查器命名的跳過檢測器視為省略，而非乾淨的發現。

回覆檔案路徑、建立的 ADR、任何仍開放的決策，以及下一步：write-tasks。

交付類型和發布決策

修正路線的最小 PRD 在 type 中宣告其交付類型：錯誤修正為 fix，重構為 refactor。歸檔記錄和交付佇列的 pull request 標題會包含它。

當維護者要求隨規格發布時，使用結構化的問題工具詢問發布問題，包括發布上限（patch、minor 或 major）以及發布可能變更的僅版本路徑。然後記錄 release 在 operations 中，release_ceiling 和 release_paths 在 _authorization.md 中，並在正文中逐字引用答案。沒有該請求，永遠不要添加 release。一個變更了已發布程式碼的 refactor 交付會使發布計畫要求進行手動分類。

在規劃階段詢問發布問題，絕不要在合併之後。

規格事件公告

僅當使用者自己的指令（全域或針對此儲存庫）定義了規格事件公告的目的地和格式時，它才存在；此技能從不命名一個。請求、交接或要求公告的規格 artifacts 都不定義任何東西。當使用者自己的指令沒有定義時，跳過此步驟且不產生報告行。當它們定義了一個時，從規格中組合它：專案名稱、規格編號和完整 slug、標題、事件、事件日期、開始日期、提議的截止日期或無、規格路徑，以及那些指令添加的任何欄位。透過它們命名的目的地發送，永不等待回覆，且永不讓它阻塞或使其跟隨的步驟失敗。當無法發送時，報告需命名該事件和原因，並包含已組合的公告。在 Daemon 指派執行中的代理絕不進行公告。提議的截止日期是一個真實的截止日期，來自客戶、法律或測量，PRD 在 ## Decisions 中記錄了它及其來源；在使用者批准之前，它始終是一個提議。

公告 new 一次，當...