AI Skills
write-tech-spec

write-tech-spec

熱門

在調查現有程式碼與實作限制後，為重要的 Warp 功能撰寫 TECH.md 規格。當使用者要求與產品規格相關的技術規格、實作計畫或架構文件時使用。

124星標
0分支
更新於 2026/7/10
獲取技能源代碼

相關技能

frontend-ui-engineering7.7萬brainstorming23萬power-bi-performance-troubleshooting3.7萬
SKILL.md
readonlyread-only
name
write-tech-spec
description

在調查現有程式碼與實作限制後，為重要的 Warp 功能撰寫 TECH.md 規格。當使用者要求與產品規格相關的技術規格、實作計畫或架構文件時使用。

write-tech-spec

為 Warp 中的重要功能撰寫 TECH.md 規格。

概述

技術規格應將產品意圖轉化為符合現有程式碼庫的實作計畫，記錄架構選擇，並讓代理人更容易執行、審查者更容易評估。

將規格寫入 specs/<id>/TECH.md，其中 <id> 為下列之一：

  • Linear 票號（例如 specs/APP-1234/TECH.md）
  • GitHub issue ID，加上前綴 gh-（例如 specs/gh-4567/TECH.md）
  • 簡短的 kebab-case 功能名稱（例如 specs/vertical-tabs-hover-sidecar/TECH.md）

若存在對應的 PRODUCT.md，請使用相同的 id。specs/ 目錄下應只包含以 id 命名的子目錄。

票號 / issue 參考為選填。如果使用者有 Linear 票或 GitHub issue，請使用其 id。如果沒有，請向他們詢問一個功能名稱作為目錄名稱。僅在使用者明確要求時才建立新的 Linear 票或 GitHub issue；在這種情況下，請分別使用 Linear MCP 工具或 gh CLI（若團隊、標籤或儲存庫不明確，則使用 ask_user_question）。

使用時機

當實作跨越多個模組、有重要的架構取捨，或審查者希望在看程式碼之前或同時看到計畫時，使用此技能。對於純 UI 變更或簡單的修正，通常不需要技術規格。

建議先有 PRODUCT.md，以便技術計畫能錨定在已確認的行為上。如果實作仍不確定，請先建立端到端原型，再根據學到的經驗撰寫技術規格。

撰寫前的研究

在起草前，請閱讀產品規格（如果有的話），檢查相關程式碼，並找出主要檔案、型別、資料流程與所有權邊界。不要猜測當前的架構，應直接檢查程式碼。
在規格中引用相關程式碼區塊時，建議使用 commit 固定的參考，以便未來讀者能檢查您研究時的確切程式碼。記錄您檢查的每個儲存庫的目前 commit SHA（例如 git rev-parse HEAD），並盡可能將檔案參考製作成 Markdown 連結，指向對應的 GitHub blob/<sha>/...#Lx-Ly URL。使用連結文字保持路徑在規格中可讀。

結構

必要章節：

  1. Context — 正在建構什麼、目前系統在受影響區域的運作方式，以及最相關的檔案與行號參考。將「問題」、「現狀」和「相關程式碼」合併為一個有根據的章節。範例參考：

  2. Proposed changes — 實作計畫：哪些模組會變更、引入的新型別/API/狀態、資料流程、所有權邊界，以及設計如何遵循現有模式。當存在多個合理路徑時，請指出取捨。

  3. Testing and validation — 如何根據產品行為驗證實作。負責所有關於證明功能正常的事項：單元測試、整合測試、手動步驟、截圖、影片以及其他驗證方式。直接參考 PRODUCT.md 中的編號行為不變量，而非重述；每個重要的不變量應對應到具體的測試或驗證步驟。此章節是驗證的所在 — PRODUCT.md 刻意不包含驗證章節。

  4. Parallelization — 積極評估平行子代理人（透過 run_agents 啟動）是否能有效減少實際時間或隔離工作。如果 run_agents 不可用，請跳過此章節。當規提議使用子代理人時，請為每個提議的代理人包含：

    • 簡短的名稱/角色及其擁有的子任務。
    • 執行模式（local 或 remote）與一行理由。
    • 對於本地代理人：應使用的工作目錄或 git worktree，以避免平行代理人衝突到同一個 checkout 或檔案。
    • 對於遠端代理人：要使用的環境，或明確說明代理人將在空環境中執行。
    • 分支與 PR 策略：每個代理人工作的分支、每個代理人將使用的 worktree 路徑，以及他們的工作如何合併（每個代理人一個 PR、單一合併 PR 等）。
    • 協調邊界：每個代理人擁有的檔案/服務，以及如何與同級代理人同步（訊息傳遞、合併點、驗證所有權）。

    區分哪些步驟可以平行執行，哪些必須循序執行。當依賴圖較複雜時，考慮使用簡短的 Mermaid 圖表（graph TD 或 flowchart LR），讓讀者一目了然看到扇出與合併點。

    當不建議平行化時，簡短說明為何沒有好處（例如任務很小，或子任務緊密耦合），以便審查者可以挑戰這個判斷。

    為 worktree、分支名稱和執行模式提出具體的預設值，而非留空。

可選章節 — 僅在能增加資訊時才包含。如果內容為空，請省略標題；不要寫「無」作為佔位符。

  • End-to-end flow — 僅在追蹤系統路徑能告訴您「Proposed changes」列表未提及的資訊時包含。
  • Diagram — 僅在視覺化能比文字更快解釋設計時包含 Mermaid 圖表（資料流程、狀態轉換、跨層序列）。偏好一兩個重點圖表，而非裝飾性圖表。
  • Risks and mitigations — 當存在真實的失敗模式、回歸、遷移問題或部署風險值得提出時包含。
  • Follow-ups — 當有延遲清理或未來工作值得命名時包含。

長度建議

根據功能調整規格大小：

  • 單一檔案變更且方法明確：跳過技術規格或保持在約 40 行以下。
  • 多模組變更且有些模糊：目標約 80–150 行。
  • 大型跨領域或架構新穎的變更：只要每個章節都有其價值，較長也沒問題。

如果 Context 和 Proposed changes 最終從不同角度描述相同的檔案和狀態，請合併它們。

寫作指引

  • 將計畫建立在實際的程式碼庫結構和模式上。
  • 將重要的程式碼參考固定到 commit SHA，並在儲存庫有可存取的遠端時連結到對應的 GitHub 行。
  • 偏好具體的實作指引，而非泛泛的架構語言。
  • 解釋為什麼提議的設計適合此儲存庫。
  • 參考 PRODUCT.md 了解行為，而非重述。
  • 每個章節都應有其價值 — 如果某章節會重複其他章節或僅包含樣板內容，請省略它。

保持規格最新

已核准的規格可以在與實作相同的 PR 中交付。當模組邊界、實作順序、風險、驗證策略或部署假設變更時，請在相同 PR 中更新 TECH.md。簽入的規格應描述實際交付的實作。

對於大型功能，實作者可以選擇保留 DECISIONS.md 檔案，總結具體決策。當它有助於未來代理人時提供；否則跳過。

相關技能

  • implement-specs
  • write-product-spec
  • spec-driven-implementation