---

name: technical-spec-template language: zh-TW description: "撰寫連線產品需求和工程實現的結構化技術規格文件。當撰寫技術規格、工程規格、系統設計文件或 API 規格時使用。產出完整的規格：問題陳述、建議方案、資料模型、API 設計、考慮過的備選方案、安全考量、測試計劃和上線策略。"

technical-spec-template 的繁體中文翻譯，英文版本為規範版本。

技術規格模板

寫出工程師真正會讀的技術規格：清楚的問題框定、沒有歧義的需求、明確的決策，以及記錄下來的取捨。

所需輸入

如未提供，請向使用者詢問：

• 功能或系統描述（要寫規格的是什麼）
• 相關的 PRD 或產品說明（如有）
• 工程評審人（需要誰簽字確認）
• 已知約束（技術限制、安全要求、效能目標）

什麼時候寫技術規格

在以下情況寫技術規格：

• 功能需要改動 2 個以上系統
• 有重大的架構決策要做
• 不止一名工程師參與實現
• 功能涉及安全、隱私或合規
• 估計工作量超過 5 個故事點

修復簡單缺陷或 1 到 2 小時的改動，跳過規格。

---

技術規格輸出格式

技術規格：[功能名稱]

作者： [姓名] 狀態： 草稿 | 評審中 | 已批准 | 已實現 建立： [日期] | 最後更新： [日期] 評審人： [技術負責人、架構師、產品經理，需要時加安全] 相關 PRD： [連結] | Jira 史詩： [連結]

---

1. 問題陳述

[2 到 3 句。我們在解決什麼問題，為什麼是現在？這裡不出現方案用語。]

2. 目標與非目標

目標（在範圍內）：

• [具體、可衡量的結果]
• [具體、可衡量的結果]

非目標（明確不在範圍內）：

• [這份規格不包括什麼]
• [需要儘早否定的常見假設]

3. 背景

[工程師理解決策空間所需的任何已有方案、相關係統或背景。連結到以前的規格、ADR 或研究。]

4. 建議方案

整體思路： [2 到 4 句描述選定的方案。為什麼選這個而不是備選方案？]

系統架構圖： [描述或嵌入：涉及哪些服務、資料如何流動、呼叫哪些 API]

資料模型變更：

-- 新表或表結構變更
[寫出 DDL 或表結構定義]

API 設計：

[介面] [方法]
請求：{ [欄位及型別] }
響應：{ [欄位及型別] }
錯誤碼：[列表]

關鍵實現細節：

• [重要的技術約束或做法]
• [邊界情況處理]
• [第三方依賴及版本]

5. 考慮過的備選方案

選項	優點	缺點	為什麼否決
[備選 1]	[好處]	[缺點]	[沒選的原因]
[備選 2]	[好處]	[缺點]	[沒選的原因]

6. 安全與隱私考量

• 儲存的資料：[涉及哪些個人資訊或敏感資料]
• 認證：[如何控制訪問]
• 授權：[需要什麼許可權]
• 加密：[儲存和傳輸的要求]
• 合規影響：[GDPR、SOC2、個人資訊保護法等，如相關]

7. 效能與可擴充套件性

• 預期負載：[每秒請求數、資料量]
• 延遲要求：[P50 / P95 目標]
• 快取策略：[如適用]
• 資料庫索引：[需要新增的索引]
• 已知瓶頸：[需要關注的地方]

8. 測試計劃

• 單元測試：[要覆蓋的關鍵場景]
• 整合測試：[要測試的系統邊界]
• 壓力測試：[如果效能關鍵]
• 邊界情況：[已知的棘手場景]
• 回滾計劃：[出問題時如何回退]

9. 上線計劃

• 功能開關：[是 / 否，開關名稱]
• 上線階段：[每個階段的使用者比例]
• 監控：[要設定的指標和告警]
• 推進上線的成功標準：[什麼條件必須成立]
• 回滾觸發條件：[什麼情況會立即回滾]

10. 待定問題

問題	負責人	截止日期	結論
[未解決的問題]	[姓名]	[日期]	[待定]

11. 實施時間表（粗略）

階段	工作	估計工作量
[階段 1]	[要做什麼]	[X 天 / 點]
[階段 2]	[要做什麼]	[X 天 / 點]
合計		[X 個故事點]

---

指南

• 規格是決策記錄，不是任務清單：記錄為什麼做出這些決策
• 所有待定問題都必須有負責人和截止日期
• 涉及使用者資料的功能，安全與隱私部分永遠不是可選的
• 建議非同步評審：工程師先讀，然後開 30 分鐘同步會解決問題
• 隨實現進展更新規格：過時的規格比沒有規格更糟

延伸材料

這個技能附帶支援檔案，可用時請使用：

• references/spec-decisions.md：規格是用來做什麼的：決策、備選方案和影響範圍。在產出時應用它；它包含上面方法摘要壓縮掉的校準和判斷。
• templates/spec-skeleton.md：可填寫的成果模板，品質關卡寫在裡面。當使用者想自己完成文件而不是生成時提供。

評分量表（0 到 40）

交付前給這個技能的任何產出打分；32 分以上才算可以交付。

維度	0	5	10
問題框定	問題陳述只是換個說法的方案（"我們需要一個佇列"），或缺失；沒有非目標	寫了問題，但混入了方案用語；有非目標但很籠統（"不在範圍內：其他一切"）	用使用者或業務語言並帶數字描述問題，獨立於任何方案；目標可衡量；至少 2 個能否定真實範圍假設的非目標
決策記錄	只有一個方案，沒有備選：是設計描述，不是決策記錄	有備選方案表，但是稻草人（只有缺點、沒人支援的選項）；否決理由是喜好而不是證據	至少 2 個真正的備選方案，優點寫得誠實，否決理由基於證據，有分歧時記錄了反對意見，有爭議的決定寫明重新評估的條件
安全與隱私深度	在涉及使用者資料的功能上跳過或寫"不適用"	套話式回答（儲存和傳輸加密），沒有分析這個功能具體的資料暴露	列舉了涉及的資料，點出設計中最大的隱私風險，具體處理了認證、授權和合規，未解決的風險明確作為批准的前提
運營就緒	沒有測試計劃、上線計劃或回滾觸發條件；沒有待定問題或全是"待定"	簡要寫了測試和上線，但回滾只是沒測試過的意圖；部分待定問題缺負責人或日期	測試覆蓋棘手的邊界情況，上線分階段並有推進標準，回滾觸發條件具體（且不會讓資料處於中間狀態），每個待定問題都有具名負責人和截止日期

品質檢查

• 問題陳述不含方案用語
• 非目標明確列出至少 2 件可能被預設在範圍內的事
• 至少記錄了 2 個備選方案及否決理由
• 涉及使用者資料的功能都完成了安全與隱私部分
• 所有待定問題都有具名負責人和截止日期（不是"待定"）

反模式

• 不要在問題陳述中加入方案用語：問題必須獨立於建議的方案來描述
• 不要省略考慮過的備選方案：只考慮一種方案的規格沒有經過恰當評估
• 不要把待定問題寫成沒有具名負責人和截止日期的"待定"：未解決的問題就是阻礙
• 涉及使用者資料的功能不要跳過安全與隱私部分
• 不要讓非目標部分為空：總是列出至少兩件可能被預設在範圍內的事

示例觸發語

• “寫一份技術規格。”
• “替這個功能寫工程規格。”
• “寫系統設計文件。”
• “寫 API 規格說明。”