独立安装说明

若当前环境仅安装了本技能，请从 CloudBase 主入口启动，并对同级技能使用已发布的 cloudbase/references/... 路径。

• CloudBase 主入口：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
• 当前技能原始源文件：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/spec-workflow/SKILL.md

对于随当前技能目录一同发布的文件，保留本地 references/... 路径。当本文件引用了同级技能（例如 auth-tool 或 web-development）时，请使用该引用旁标注的独立回退 URL。

Spec Workflow

激活契约

首次使用此流程的适用场景

• 请求涉及新功能、多步骤产品变更、跨模块集成，或架构/设计类任务。
• 验收标准尚不明确，需在实施前明确定义。
• 工作涉及多个文件、用户流程、数据库设计或 UI 设计，且需分阶段确认。

编码前请先阅读（如符合以下任一情况）

• 不确定该任务应直接进入编码阶段，还是应先完成需求分析、设计与任务规划。
• 请求中提及新建页面、新建系统、重构设计、工作流定义，或多模块重构。

还需同步阅读

• 前端页面或视觉设计相关工作 → ../ui-design/SKILL.md（独立回退 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/ui-design/SKILL.md）
• 高级数据模型相关工作 → ../data-model-creation/SKILL.md（独立回退 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/data-model-creation/SKILL.md）

不适用于以下情形

• 范围明确的小型缺陷修复。
• 单文件文档更新。
• 直截了当的配置修改。
• 用户已给出精确实现指令的微小重构。

常见错误 / 注意事项

• 未明确验收标准即开始编码。
• 在需求、设计与任务各阶段之间跳过用户确认环节。
• 编写含糊不清的任务项，无法映射到用户可感知的结果。
• 将 UI 工作视为纯技术实现，未事先澄清设计意图。

最小化检查清单

• 判断变更是否确实需要完整的 spec 流程。
• 如需，则暂停并优先产出需求文档。
• 若变更规模小、风险低，且验收标准已足够清晰，允许跳过 spec 文档，直接执行。
• 采用 EARS 风格编写验收标准。
• 进入下一阶段前，须获得用户确认。

何时使用本技能

当需要结构化开发时，请使用本工作流：

• 定义或细化新功能
• 设计复杂架构
• 协调跨模块的变更
• 规划数据库或 UI 密集型工作
• 提升需求质量与验收边界清晰度

决策规则

应启用完整工作流的情形

• 任务规模为中等或大型
• 影响范围覆盖多个模块
• 验收边界模糊
• 用户明确要求在实施前进行严谨的规划

可跳过完整工作流的情形

• 任务规模小、风险低，且已具备明确性
• 目标、范围与验收标准已足够清晰，可直接执行
• 用户明确要求跳过规划阶段，直接进行代码变更

核心工作流

第一阶段：需求分析

创建 specs//requirements.md。

需完成内容：

• 重述问题与范围
• 撰写用户故事
• 按 EARS 风格撰写验收标准
• 厘清业务规则、约束条件及非目标项

EARS 模式：

While <可选前置条件>, when <可选触发事件>, the <系统名称> shall <系统响应>

示例：

When the user submits the form, the booking system shall validate required fields before creating the record.

第二阶段：设计

创建 specs//design.md。

需完成内容：

• 描述架构与模块边界
• 说明技术选型及其权衡考量
• 按需定义数据模型、API、安全与测试策略
• 仅当图表能显著提升理解清晰度时，才使用 Mermaid 绘制

第三阶段：任务分解

创建 specs//tasks.md。

需完成内容：

• 将设计方案拆解为可执行任务
• 确保任务具体、可评审
• 为每项任务关联对应的需求条目
• 随工作进展实时更新任务状态

任务格式示例：

# Implementation Plan

- [ ] 1. Task title
  - Specific work item
  - Another concrete step
  - _Requirement: 1

第四阶段：执行

仅在用户确认任务计划后，方可启动实施。

执行过程中需遵守：

• 持续更新任务状态
• 每次完成一个具有实际意义的单元
• 保持“变更 → 任务 → 需求”的可追溯性

代理（Agent）工作准则

1. 当请求描述不充分时，主动提出追问；不得擅自猜测核心产品行为。
2. 必须在需求、设计与任务分解各阶段之间获取用户确认。
3. 若变更涉及终端用户页面或视觉决策，应尽早引入 ui-design 技能。
4. 文档应简洁，但内容须可验证、可测试。
5. 任务命名应优先体现用户可感知的结果，而非实现细节。

输出预期

• requirements.md → 问题描述、范围界定、用户故事、EARS 验收标准
• design.md → 架构设计、技术方案、数据/API/安全/测试相关说明
• tasks.md → 关联需求的可操作实施清单