前言¶
中大型功能往往還沒寫代碼，就已經在口頭需求、零散文檔和「先做着看」之間跑偏：驗收標準說不清，多模塊改動缺少統一設計，Agent 也容易直接改文件而跳過確認。下面介紹騰訊雲 CloudBase 團隊在 SkillHub 發佈的 需求與設計流程 · Spec Workflow（@tencent-adm/spec-workflow-guide），用標準 SKILL.md 把「要不要走規格流程、怎麼走、產出什麼文檔」寫進 Agent 上下文，讓實現前有可覈對的需求、設計與任務清單。
這是什麼¶
Spec Workflow 是騰訊雲 CloudBase 標準軟件開發流程的 Agent Skill，當前版本 2.36.0，在 SkillHub 座標爲 @tencent-adm/spec-workflow-guide，來源標註爲 enterprise，分類爲 dev-programming，發佈者爲騰訊雲 CloudBase 團隊。Skill 標籤標明 requires_api_key=false，安裝後無需額外 API Key。
一句話定位：在實現代碼之前，引導 Agent 按階段產出 需求、技術設計、任務分解 三類文檔，並統一 EARS 風格驗收標準，適合中大型特性與多模塊集成；小範圍、驗收已明確的改動則不必強行套全流程。
核心功能¶
Skill 正文（SKILL.md）把能力拆成「何時啓用」與「四階段工作流」兩部分，下面只列已覈實內容。
啓用條件（Activation Contract）¶
優先使用本 Skill 的情況：
- 新功能、多步驟產品變更、跨模塊集成或架構/設計類任務
- 驗收標準不清晰，需要先寫清楚再寫代碼
- 涉及多文件、用戶流程、數據庫或 UI，需要分階段確認
不必使用的場景： 範圍明確的小 bug 修復、單文件文檔更新、簡單配置、用戶已給出精確實現指令的微小重構。
常見誤區（Skill 原文強調）： 未明確驗收就寫代碼；需求、設計、任務之間缺少用戶確認；任務描述模糊、無法對應用戶可見結果；把 UI 當成純技術實現而不澄清設計意圖。
四階段工作流¶
- 需求（Requirements）
在specs/<spec_name>/requirements.md中寫清問題與範圍、用戶故事、業務規則與約束，並用 EARS 寫驗收標準。句式模板：
While <optional precondition>, when <optional trigger>, the <system name> shall <system response>
-
設計（Design）
產出specs/<spec_name>/design.md：架構與模塊邊界、技術選型與權衡，按需補充數據模型、API、安全與測試策略；僅在有助於理解時使用 Mermaid 圖。 -
任務（Tasks）
產出specs/<spec_name>/tasks.md：把設計拆成可執行、可評審的任務，並關聯到對應需求；執行過程中更新任務狀態。任務條目採用帶複選框的 Markdown 列表，並標註_Requirement: N。 -
執行（Execution）
僅在用戶確認任務計劃後開始改代碼；執行時保持任務狀態與「變更 → 任務 → 需求」的可追溯性。
階段之間需要用戶確認；Agent 在需求含糊時應追問，而不是猜測核心產品行爲。若涉及前端頁面或視覺設計，Skill 要求優先閱讀同目錄下的兄弟 Skill ../ui-design/SKILL.md；複雜數據模型場景則參考 ../data-model-creation/SKILL.md（需一併安裝 CloudBase 插件或對應 Skill，Skill 明確禁止通過 HTTP 拉取遠程 skill 文檔）。
輸出物約定¶
| 文件 | 內容 |
|---|---|
requirements.md |
問題、範圍、用戶故事、EARS 驗收標準 |
design.md |
架構、技術方案、數據/API/安全/測試說明 |
tasks.md |
可執行的實現清單，並關聯需求編號 |
安裝與啓用¶
Skill 基於通用 SKILL.md 格式，alwaysApply 爲 false，需在 Agent 能加載的 skills 目錄中安裝後，在合適任務上由 Agent 按描述觸發。
1、安裝 SkillHub CLI（若尚未安裝）¶
command -v skillhub && skillhub --version
未安裝時可執行（僅 CLI）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2、安裝本 Skill¶
安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認裝到 ./skills/ 可能不會被識別。官方 Skill 頁給出的安裝提示爲：參照 SkillHub 安裝文檔 安裝 @tencent-adm/spec-workflow-guide。
CLI 安裝命令（namespace 與 slug 以 SkillHub 檢索結果爲準）：
skillhub install spec-workflow-guide --namespace tencent-adm --dir <你的 skills 目錄>
常見路徑示例（來自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/ - Claude Code：
~/.claude/skills/
也可將下面提示發給 AI，由其按安裝文檔完成安裝：
請根據 https://skillhub.cn/install/skillhub.md，安裝 `@tencent-adm/spec-workflow-guide`。
安裝完成後，按你所用客戶端要求重啓或刷新 Agent，使新 Skill 生效。
典型用法¶
下面示例來自 Skill 正文，可在倉庫中直接復現目錄結構。
1、判斷是否走全流程
用戶提出「做一個帶表單的預約模塊，涉及前端頁、後端接口和數據庫」——屬於多模塊、驗收需澄清的場景，應先走 Spec Workflow，而不是直接改代碼。
2、需求階段
創建 specs/booking/requirements.md，其中驗收標準可寫成：
When the user submits the form, the booking system shall validate required fields before creating the record.
3、設計與任務
經用戶確認需求後，編寫 specs/booking/design.md，再生成 tasks.md，例如：
# Implementation Plan
- [ ] 1. Task title
- Specific work item
- Another concrete step
- _Requirement: 1
4、執行
用戶確認任務列表後，再按任務逐項實現，並勾選完成狀態、保持與需求編號的對應關係。
適用場景與注意¶
適合誰
- 使用 CloudBase 或同類全棧棧、需要 Agent 協助 中大型功能 的團隊
- 希望把「需求—設計—任務—實現」固化到倉庫
specs/目錄、便於評審與追溯的開發者 - 多模塊集成、架構討論多、驗收邊界常變模糊的項目
限制與注意
- 小改動、目標已非常明確時，Skill 本身建議 跳過 全流程，避免文檔負擔過重。
- 完整 CloudBase 體驗依賴 兄弟 Skill（如
ui-design、data-model-creation）；僅安裝本 Skill 時，涉及 UI/數據建模的指引可能無法本地解析，需按 Skill 說明補裝插件。 - SkillHub 頁面統計（截至資料抓取）：評分 100000，下載約 22743；以 SkillHub 技能頁 爲準。官方介紹地址：https://api.skillhub.cn/tencent-adm/spec-workflow-guide（瀏覽器訪問 Skill 詳情時以 SkillHub 站點爲準）。
結尾¶
Spec Workflow 把 CloudBase 團隊約定的規格化開發步驟寫進 Agent Skill：先判斷規模，再按需求、設計、任務分階段產出文檔並確認，最後才進入實現。若你正在用 Cursor、Codex 或 Claude Code 做中大型特性，可按上文命令安裝 @tencent-adm/spec-workflow-guide，並在 SkillHub 查看版本與說明：https://www.skillhub.cn/skills/tencent-adm/spec-workflow-guide。
