← LeaderboardThe Skill Leaderboard

technical-spec-template

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

Published by mohitagw15856 ↗mohitagw15856/pm-claude-skills

Try your first task

technical-spec-template

Start a fresh conversation. Replace the highlighted placeholders.

Use technical-spec-template to 請根據 [功能或系統描述及相關 PRD]、[已知技術約束與安全/效能目標] 以及 [工程評審人名單]，撰寫一份完整的技術規格文件，包含問題陳述、目標與非目標、建議方案（含架構與 API 設計）、備選方案分析、安全隱私考量、測試計劃及上線策略。

Required inputs

  • [功能或系統描述及相關 PRD]
  • [已知技術約束與安全/效能目標]
  • [工程評審人名單]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: technical-spec-templatelanguage: zh-TWdescription: "撰寫連線產品需求和工程實現的結構化技術規格文件。當撰寫技術規格、工程規格、系統設計文件或 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 分以上才算可以交付。

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

品質檢查

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

反模式

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

示例觸發語

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