前言¶
中大型功能往往还没写代码，就已经在口头需求、零散文档和「先做着看」之间跑偏：验收标准说不清，多模块改动缺少统一设计，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。
