write-product-spec

write-product-spec

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

概述

產品規格應使期望行為足夠明確，讓代理程式能正確實作並避免回歸。純粹從使用者角度描述功能——使用者看到、執行和體驗的內容，以及必須為他們維持的不變量。不要包含實作細節（內部型別、狀態佈局、模組邊界、資料流程、演算法）。

「使用者」不限於 Warp 應用程式的終端使用者。它指的是消費所設計表面的任何人：

• 對於 UI / UX 功能：使用 Warp 的人類。
• 對於資料模型：讀寫該模型的程式碼。
• 對於 API、協定或函式庫：該 API 的呼叫者——其他服務、客戶端程式碼、外掛或代理程式。
• 對於 CLI 工具或開發者面向表面：呼叫它的開發者。

規格應從該消費者的視角描述行為：表面的形狀、他們可以執行的操作、他們看到的回應、他們可以依賴的不變量，以及他們必須處理的邊界情況——而不規定表面在底層如何實作。

實作細節、驗證和測試規劃位於配套的 TECH.md 中，由 write-tech-spec 技能產生。撰寫產品規格通常是兩步驟流程的第一步：一旦 PRODUCT.md 達成共識，就呼叫 write-tech-spec 為相同功能產生 TECH.md（或讓使用者知道這是預期的下一步）。產品規格應撰寫成可直接從中撰寫技術規格。

將規格寫入 specs/<id>/PRODUCT.md，其中 <id> 是以下之一：

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

specs/ 應只包含以 ID 命名的目錄作為直接子目錄——沒有以工程師命名的子目錄。

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

撰寫前

僅收集所需的上下文：目錄 ID（Linear 工單、GitHub issue 或功能名稱）、功能摘要、目標使用者、關鍵行為、邊界情況，以及功能將如何驗證。對於遺失的上下文，使用 ask_user_question 而非猜測。

Figma 模型

如果功能有任何 UI 或互動設計，請在草擬行為章節前詢問使用者是否有 Figma 模型，並在提供時將連結包含在規格中。模型通常是視覺狀態、間距和邊界情況佈局最可靠的真相來源——不詢問可能導致行為章節猜測設計師已確定的意圖。

• 如果使用者提供連結，請將其放在簡短的 ## Figma 章節下（或內聯在 Behavior 頂部附近），格式為 Figma: <link>。
• 如果使用者確認沒有模型，請註明 Figma: none provided，以便明確表示不存在而非模糊。
• 如果功能純粹是後端（資料模型、API、無視覺表面的 CLI），則跳過問題並省略該章節。

不要默默丟棄設計上下文；在通常預期有設計的功能上，明確的「無」勝過完全未提及。

結構

必要章節：

1. Summary — 1–3 句話描述功能和期望結果。
2. Behavior — 規格的核心。詳盡的英文描述功能如何運作，寫成編號的、可測試的不變量。請參閱下方的「Behavior 章節」——這是規格展現長度的地方，其他所有內容應保持精簡以避免重複。

選用章節——僅在它們提供核心之外的額外訊息時才包含。如果為空則完全省略標題；不要寫「None」作為佔位符。

• Problem — 僅在動機從 Summary 不明顯時包含。
• Goals / Non-goals — 在範圍模糊或有爭議時包含。
• Figma — 當存在連結時包含，或當設計重要但沒有模型時包含明確的 Figma: none provided 註記。對於非視覺功能完全省略。請參閱上方的「Figma 模型」。
• Open questions — 偏好將 **Open question:** … 內聯在相關行為旁邊。僅在有多個未解決問題值得收集時才包含專門章節。

不要包含驗證、成功標準或測試章節。驗證和測試規劃位於配套的 TECH.md（由 write-tech-spec 產生）。將 Behavior 寫成可自行測試的編號不變量——技術規格可以直接引用它們。

Behavior 章節

Behavior 就是規格。其他一切都是框架。

Behavior 的目標是對功能如何運作的完整英文描述，詳細到可以直接從中撰寫技術規格，而無需作者猜測或重新推導產品意圖。如果讀者在讀完 Behavior 後仍對功能在某些情況下的行為有疑問，則該章節尚未完成。

至少描述：

• 預設行為和快樂路徑使用者流程。
• 每個使用者可見的狀態以及它們之間的轉換。
• 使用者可以提供的所有輸入以及功能如何回應。
• 空狀態、錯誤狀態、載入/等待狀態和取消。
• 合理的實作者不會想到要問的邊界情況——權限拒絕、離線、超時、狀態變更之間的競爭、多個並發實例、過時或遺失資料、互動中途失去焦點、與相鄰功能的互動。
• 鍵盤、無障礙和焦點期望（如果相關）。
• 必須始終保持的不變量以及不得回歸的行為。

Behavior 的長度應與功能匹配。簡單功能可能只需要少數不變量；複雜功能可能需要很多，每個流程或狀態有子章節。規格的其餘部分應保持精簡，以便 Behavior 可以根據功能需要盡可能詳盡，而不會產生整體臃腫的文件。寧可多列舉一個邊界情況，也不要少列一個。

長度啟發式

Behavior 應根據功能需要盡可能長——不要為了達到行數目標而截斷邊界情況。以下啟發式適用於 Behavior 周圍的所有內容（Summary、選用章節）：保持框架精簡，以便規格的總長度反映功能的實際複雜性，而非結構性開銷。

• 簡單修復或狹窄的 UI 調整：無需規格。
• 小型功能（單一模組，少數邊界情況）：框架加上 Behavior 通常總共約 30–60 行。
• 中型功能（跨模組，多個狀態）：通常總共約 80–150 行。
• 大型或行為豐富的功能：更長也可以，大部分長度應在 Behavior 中。

如果你發現自己在 Summary、Problem、Goals 和 Behavior 中寫了相同的想法，請壓縮框架——而不是 Behavior 內容。

撰寫指引

• 偏好具體、可觀察的行為，而非抱負性的措辭。
• 盡可能將 Behavior 寫成不變量列表而非散文。
• 捕捉不得回歸的不變量和容易遺漏的邊界情況。
• 除非 UX 無法避免，否則避免實作細節。
• 每個章節都應有其存在的理由——如果某個章節會重複另一個或僅包含樣板，則省略它。

保持規格最新

已批准的規格可以在與實作相同的 PR 中交付。隨著實作演進，當使用者面向行為或 UX 細節變更時，在同一 PR 中更新 PRODUCT.md。簽入的規格應描述實際交付的功能。

對於大型功能，實作者可以選擇保留一個 DECISIONS.md 檔案，總結設計和實作過程中做出的具體決策。當它有助於未來的代理程式時提供它；否則跳過。

相關技能

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

Behavior 章節範例

一個假設功能的 Behavior 章節範例：在 Warp 區塊列表中渲染 GitHub 風格的 Markdown 表格。它展示了預期的形狀——編號的、可測試的、使用者視角的不變量，列舉了預設值、邊界情況、格式錯誤的輸入、串流、選取/複製、搜尋、分享、主題化和跨表面一致性，並包含一個內聯的開放問題。

## Behavior

1. 當終端機輸出區塊包含 GitHub 風格的 Markdown 表格（一個標題行、一個由一個或多個 `---` 段組成的分隔行，以及一個或多個主體行，全部由 `|` 分隔）時，該表格在區塊中渲染為視覺格式化的表格——而不是原始的 pipe 分隔文字。

2. 表格渲染時具有：
   - 視覺上不同的標題行。
   - 基於分隔行的對齊欄位：`|:---|` 左對齊，`|:---:|` 居中，`|---:|` 右對齊。沒有冒號的 `|---|` 回退到預設對齊（文字左對齊，數值型值右對齊）。
   - 與當前主題一致的可見行分隔線（或等效間距）。

3. 儲存格內的內聯 markdown 會內聯渲染：粗體、斜體、內聯程式碼、刪除線和連結都以與周圍區塊輸出相同的方式渲染。儲存格內的換行（`<br>` 或跳脫的 `\n`）渲染為儲存格內換行。

4. 欄位寬度選擇為在區塊內適合表格的自然內容。如果單個儲存格的內容很長，該儲存格會在其欄位內換行文字，而不是強制欄位達到不合理的寬度。
   - **Open question:** 當換行的儲存格會產生不合理的高行時，我們是使用「展開」功能進行裁剪，還是讓行無限制增長？

5. 水平捲動：當表格總寬度超過區塊寬度時——許多欄位，或無法合理縮窄的寬欄位——表格在區塊內變成可水平捲動。水平捲動顯示螢幕外的欄位，而不會裁剪或截斷它們。區塊的垂直捲動繼續獨立於表格捲動運作。

6. 當區塊調整大小時（終端機調整大小、面板分割、側邊欄開啟/關閉），表格會重新流動到新寬度，而不會遺失行或欄位順序。

7. 空儲存格渲染為視覺上空白（與周圍儲存格相同行高，無佔位符文字）。所有儲存格都為空的行仍然渲染為一行。

8. 只有標題和分隔行（零個主體行）的表格渲染為僅標題表格，而不是原始文字。

9. 單欄位表格渲染為單欄位表格（不會摺疊為項目符號列表或類似形式）。

10. 格式錯誤的表格優雅地回退：
    - 缺少分隔行 → 渲染為預格式化文字，而不是表格。
    - 參差不齊的行（某些行的儲存格少於或多於標題）→ 缺少的儲存格渲染為空；額外的儲存格顯示，如果可能，標題行會視覺上擴展。區塊絕不應默默丟棄資料。
    - 未閉合的表格（最後一行在串流中被截斷）→ 渲染為部分表格；請參閱 (11)。

11. 串流輸出：當指令仍在產生行時，表格會增量渲染。新行到達時附加。標題行在收到分隔行後立即鎖定；分隔行之前的行在表格被識別之前渲染為純文字。

12. 選取和複製：
    - 使用滑鼠或鍵盤跨儲存格選取會選取其可見文字內容。
    - 複製選取內容預設產生 tab 分隔的純文字（每行一行，儲存格以 tab 分隔）。一個功能（右鍵選單、快捷鍵）讓使用者改為複製原始 markdown 原始碼。
    - 複製整個區塊會逐字保留原始 markdown 原始碼。

13. 在區塊內搜尋（區塊內尋找）會比對儲存格文字內容。匹配項在渲染的儲存格中原地高亮；導航匹配項會將表格捲入視野，包括水平捲動（如果匹配項在螢幕外的欄位中）。

14. 分享或匯出區塊（Warp Drive、分享連結、另存為檔案）會保留原始 markdown 原始碼，而不是渲染形式。

15. 主題化：表格邊框、標題背景、交替行陰影（如果有的話）以及連結/程式碼樣式都來自當前 Warp 主題。沒有硬編碼的顏色。

16. Markdown 表格在區塊列表 markdown 已渲染的任何地方都一致渲染——指令輸出、代理程式回應，以及任何其他支援內聯 markdown 的區塊類型。相同的輸入在每個表面產生相同的表格。

17. 非表格的 pipe 內容不會被錯誤渲染為表格。包含 `|` 字元但沒有有效標題-分隔行的文字保持為純文字，即使它在視覺上類似於表格。