中大型功能/多模块/架构变更且验收标准不清时，用 Spec…

适用于新功能、多步骤产品变更、跨模块集成、架构/设计任务，或验收标准不清、涉及多文件/用户流/数据库/UI 设计并需要分阶段确认的中大型工作。

适用场景

解决思路

1. 同级技能使用本地相对路径，例如 `../auth-tool-cloudbase/SKILL.md`。
2. 如果引用的同级技能文件缺失，要求用户安装完整的 CloudBase 插件（或缺失的技能）。
3. 不要通过 HTTP 把远程技能或协议 markdown 拉取到 agent 上下文。
4. 决定变更是否真的需要完整 spec 流程。
5. 如果需要，停下先产出需求。
6. 如果变更小、低风险、验收已清楚，允许直接执行，不强制 spec 产物。
7. 使用 EARS 风格验收标准。
8. 进入下一阶段前获得用户确认。
9. 根据决策规则执行完整工作流：当任务中/大、影响跨多个模块、验收边界模糊、用户想要实现前有纪律的规划时。
10. 根据决策规则跳过完整工作流：当任务小、低风险、已精确，目标/范围/验收已清楚可直接执行，或用户明确想要直接改代码无规划阶段时。
11. 对于前端页面或视觉设计工作，读取 `../ui-design/SKILL.md`。
12. 对于高级数据模型工作，读取 `../data-model-creation/SKILL.md`。
13. Phase 1: Requirements：创建 `specs/<spec_name>/requirements.md`。
14. 重述问题与范围。
15. 写用户故事。
16. 用 EARS 风格写验收标准。
17. 澄清业务规则、约束、非目标。
18. EARS 模式：`While <optional precondition>, when <optional trigger>, the <system name> shall <system response>`。
19. 示例：`When the user submits the form, the booking system shall validate required fields before creating the record.`
20. Phase 2: Design：创建 `specs/<spec_name>/design.md`。
21. 描述架构和模块边界。
22. 解释技术选型和权衡。
23. 按需定义数据模型、API、安全、测试策略。
24. 仅当图表能实质提升清晰度时使用 Mermaid。
25. Phase 3: Tasks：创建 `specs/<spec_name>/tasks.md`。
26. 将设计拆成可执行任务。
27. 保持任务具体可评审。
28. 将每个任务链接回相关需求。
29. 随工作进展更新任务状态。
30. 任务格式：使用 `# Implementation Plan`、`- [ ] 1. Task title`、` - Specific work item`、` - Another concrete step`、` - _Requirement: 1`。
31. Phase 4: Execution：仅当用户确认任务计划后开始实现。
32. 执行期间保持任务状态最新。
33. 一次完成一个有意义的单元。
34. 保持变更 -> 任务 -> 需求的可追溯性。
35. 请求不充分时提出追问；不要猜测核心产品行为。
36. 在需求、设计、任务拆解之间要求确认。
37. 当变更包含终端用户页面或视觉决策时，尽早引入 `ui-design`。
38. 保持文档简洁但可测试。
39. 优先用户可见结果而非实现细节任务名。
40. 避免在验收标准未明确时跳入编码。
41. 避免在需求、设计、任务之间跳过用户确认。
42. 避免写模糊任务不映射到用户可见成果。
43. 避免把 UI 工作当纯技术实现而不澄清设计意图。
44. `requirements.md` 输出：问题、范围、用户故事、EARS 验收标准。
45. `design.md` 输出：架构、技术方案、数据/API/安全/测试说明。
46. `tasks.md` 输出：与需求关联的可执行实施清单。

适用边界 · 注意事项

• 范围清晰的小 bug 修复、单文件文档更新、直接配置更改、用户已给出精确实现说明的小重构，不要使用完整 spec 流程。
• 任务小、低风险、已精确，或目标/范围/验收已清楚可直接执行，或用户明确想要直接改代码无规划阶段时，跳过完整工作流。