规范驱动的功能开发
概述
该技能强制执行 “先规划后编码”门控协议。自主编码代理往往因直接跳入文件编辑而失败，导致上下文漂移、API 幻觉以及试错调试过程中浪费令牌。
当此技能激活时，在未起草、验证并通过仓库约束的正式规范（SPEC.md 或 .specs/<feature-slug>.md）之前，不得修改任何应用代码。
1. 第一阶段：上下文与约束侦察
在起草规范之前：
- 识别项目中现有的约定、数据模型和 API 工具。
- 定位类型定义或模式文件（例如
schema.prisma、drizzle/schema.ts、Zod 模式、OpenAPI 规范）。 - 除非必要，否则不要读取整个文件；检查导出、接口头部和类型。
2. 第二阶段：起草 SPEC.md
阅读 ./references/spec_template.md，并按照以下精确结构创建 .specs/<feature-slug>.md（或仓库根目录下的 SPEC.md，如果要求如此）：
- 目标、成功标准与明确非目标： 清晰的两句问题陈述、确定的通过标准以及明确的范围外边界。
- 数据契约与签名： 确切的 TypeScript 接口、数据库列类型或 API 模式。
- 文件修改边界矩阵： 明确的
创建、修改（附带目标函数/行）和禁止路径。 - 实施清单与验证协议： 确切的测试命令、linter 检查以及边界情况。
3. 第三阶段：门控检查点（强制）
生成规范后：
- 交互模式（用户会话）： 呈现一个总结，链接到规范文件，指出任何架构上的权衡（如果有多种有效方法，则使用
ask_question），并在编写代码前请求确认："我已将规范起草到
SPEC.md中。请审查建议的数据契约和文件边界矩阵。是否可以开始实施？" - 自主子代理模式： 如果由已提供已批准修复计划的主要编排器（例如来自
code-audit-orchestrator）调用，则验证文件边界矩阵与禁止路径没有冲突，然后进入第四阶段。 - 硬停止： 在交互式会话中，等待批准或反馈。在获得明确许可前，不要触碰源文件。
4. 第四阶段：分阶段执行与中途修正协议
获得批准后：
- 可选沙箱隔离： 对于多文件更改或当主工作树包含无关更改时，通过
git-worktree-isolator在修改文件前提供隔离的工作树。 - 按照离散的原子里程碑实施该功能（例如，模式 $\to$ 核心逻辑 $\to$ API 处理器 $\to$ 用户界面/集成）。
- 随着里程碑完成，在规范文件中标记进度复选框。
- 保持 git 提交范围限定在单个里程碑内。
应急方案：中途规范修正
如果实施过程中发现未预见的限制（例如，必须修改 禁止 文件、上游 SDK 类型与草拟数据契约不符、或用户中途修改了需求）：
- 立即停止编辑受影响的里程碑。
- 在规范文件的
## 6. 规范修正（增量日志）中添加条目，记录：- 触发因素/障碍： 为什么原始契约无法维持。
- 修正部分与增量： 数据契约或文件修改边界矩阵的精确变更。
- 如果增量触及了之前
禁止的文件，或更改了公共 API/模式契约，则暂停并请求快速用户确认，然后再继续。如果增量纯粹是内部的（例如提取一个内部辅助文件），则在规范中记录增量并继续。
5. 第五阶段：验证与归档
- 运行第二阶段中指定的确定性测试套件。
- 验证所有类型检查和 linter 均干净通过。
- 将规范状态更新为
已完成，并将其归档到.specs/completed/YYYY-MM-DD-<feature-name>.md（如果仓库不跟踪.specs/，则删除临时规范文件）。