概述
规格驱动开发（Spec-Driven Development）要求在编写任何代码之前，先写出一份结构化规格说明。规格是你与人类工程师之间的共享事实来源——它定义我们要构建什么、为什么构建，以及如何知道它已经完成。没有规格的代码就是在猜测。
何时使用
- 启动新项目或新功能
- 需求含糊或不完整
- 变更涉及多个文件或模块
- 即将做出架构决策
- 任务实现预计超过 30 分钟
不适用场景：单行修复、拼写更正，或需求明确且自成一体、无歧义的改动。
带门禁的工作流
规格驱动开发包含四个阶段。当前阶段未经验证之前，不要进入下一阶段。
流程为：SPECIFY（规格） → PLAN（计划） → TASKS（任务） → IMPLEMENT（实现），每个阶段都有 Human（人工）评审环节。
第一阶段：Specify（规格）
从高层愿景开始。向人类提出澄清性问题，直到需求变得具体。
立即暴露假设。在写任何规格内容之前，先列出你正在假设的内容，例如：
ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.
不要悄悄填补含糊的需求。规格的全部目的就是在写代码之前暴露误解——假设是最危险的误解形式。
规格文档需覆盖六个核心领域：
- 目标（Objective）：构建什么、为什么、用户是谁、成功是什么样。
- 命令（Commands）：完整可执行命令（含参数），而不仅是工具名称，如：
Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev
- 项目结构（Project Structure）：源代码、测试、文档所在位置，例如：
src/ → Application source code
src/components → React components
src/lib → Shared utilities
tests/ → Unit and integration tests
e2e/ → End-to-end tests
docs/ → Documentation
- 代码风格（Code Style）：一段真实代码片段胜过三段描述。包含命名约定、格式规则和良好输出示例。
- 测试策略（Testing Strategy）：使用什么框架、测试放在哪里、覆盖期望、不同关注点对应哪一层级测试。
- 边界（Boundaries）：三层体系——始终做（Always do）、先询问（Ask first）、绝不做（Never do）。例如始终做：提交前运行测试、遵循命名约定、校验输入；先询问：数据库结构变更、添加依赖、修改 CI 配置；绝不做：提交密钥、编辑第三方目录、未经批准删除失败的测试。
规格模板包含以下部分：标题（项目/功能名称）、Objective、Tech Stack、Commands、Project Structure、Code Style、Testing Strategy、Boundaries（Always/Ask first/Never）、Success Criteria、Open Questions。
将指示改写为成功标准。收到模糊需求时，将其翻译为具体条件，例如把“让仪表盘更快”改写为：
REQUIREMENT: "Make the dashboard faster"
REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?
这样你可以围绕清晰目标进行循环、重试和解决问题，而不是猜测“更快”意味着什么。
第二阶段：Plan（计划）
在规格获得验证后，生成技术实现计划：识别主要组件及其依赖；确定实现顺序（什么必须先构建）；记录风险与缓解策略；识别哪些可并行、哪些必须串行；定义各阶段之间的验证检查点。
本技能说明中提到，这些步骤背后的依赖图映射与纵向切片机制遵循 planning-and-task-breakdown，它是权威来源；上述要点只是轻量级摘要，若两者出现分歧，以 planning-and-task-breakdown 为准。
计划应可评审：人类应能阅读后表示“是，这是正确的方法”或“不，修改 X”。
第三阶段：Tasks（任务）
将计划拆分为离散、可实施的任务：每个任务应能在一次专注的会话中完成；每个任务有明确验收标准；每个任务包含验证步骤（测试、构建、手动检查）；任务按依赖排序，而非按感知重要性排序；任何任务不应要求修改超过约 5 个文件。
本技能说明中提到，完整的任务粒度与依赖排序机制遵循 planning-and-task-breakdown，它是权威来源；下方模板只是轻量级内联形式，若两者出现分歧，以 planning-and-task-breakdown 为准。
任务模板：
- [ ] Task: [Description]
- Acceptance: [What must be true when done]
- Verify: [How to confirm — test command, build, manual check]
- Files: [Which files will be touched]
第四阶段：Implement（实现）
一次执行一个任务，遵循 skills/incremental-implementation/SKILL.md（增量实现）与 skills/test-driven-development/SKILL.md（测试驱动开发）。使用 skills/context-engineering/SKILL.md（上下文工程）在每一步加载正确的规格章节和源文件，而不是把整份规格一次性灌给智能体。
让规格保持存活
规格是活文档，不是一次性产物：
- 决策变化时更新——若发现数据模型需要变更，先更新规格，再实现。
- 范围变化时更新——新增或砍掉的功能都应反映在规格中。
- 提交规格——规格应与代码一起纳入版本控制。
- 在 PR 中引用规格——链接回每个 PR 所实现的规格章节。
常见辩解与事实
- “这很简单，我不需要规格”：简单任务不需要长规格，但仍需要验收标准。两行规格也可以。
- “我写完代码再写规格”：那是文档，不是规格。规格的价值在于强制在写代码前想清楚。
- “规格会拖慢我们”：15 分钟的规格可防止数小时返工。15 分钟的瀑布胜过 15 小时的调试。
- “需求反正会变”：所以规格是活文档。过时的规格仍胜过没有规格。
- “用户知道他们想要什么”：即使清晰的请求也有隐含假设。规格会暴露这些假设。
危险信号
- 在没有任何书面需求的情况下开始写代码
- 在澄清“完成”意味着什么之前就问“我应该直接开始构建吗？”
- 实现任何规格或任务列表中未提及的功能
- 做出架构决策却不记录
- 因为“要构建什么很明显”而跳过规格
验证
在进入实现之前，确认：规格覆盖全部六个核心领域；人类已审阅并批准规格；成功标准具体且可测试；边界（始终做/先询问/绝不做）已定义；规格已保存为仓库中的文件。
限制
仅当任务明确匹配其上游来源与本地项目上下文时才使用本技能。在应用变更前，验证命令、生成的代码、依赖、凭据与外部服务行为。不要把示例当作环境特定测试、安全审查，或针对破坏性/高成本操作的用户批准的替代品。