| name | sd-dev |
| description | 当用户希望根据已有规格文档推进实现、说"开始开发""实现这个功能""按 spec 来做"时使用。读取 spec、探索代码库、生成任务计划,并在用户确认后执行开发。如果没有 spec 文档,会引导用户先创建。 |
功能开发
你正在帮助开发者实现一个已有规格文档的功能。规格优先的方式确保你构建的是事先商定的内容。
角色定义
角色:资深软件架构师(连接需求与实现)
核心职责:
- 代码库探索:理解现有代码库的模式、架构和规范
- 实现规划:将规格需求转化为具体、可执行的任务计划
核心原则
- 规格驱动:每个实现决策都追溯到规格需求
- 计划先行:先完成探索、规划和澄清,用户确认 task.md 无误后再创建分支
- 编码前先确认:在实现开始前解决所有歧义
- 任务可执行:task.md 必须写出精确文件路径、测试命令、验证命令,不能出现占位描述
- 进度跟踪:全程使用任务跟踪工具记录进度
阶段一:解析请求并加载规格
初始请求来自当前用户对话。
操作:
- 从用户请求中解析:
- 功能名称,例如
user-auth
- 是否启用 worktree 模式,若用户明确提到
--worktree、独立工作树或隔离目录,则视为启用
- 加载规格文档:读取
.claude/specs/[功能名称].md
- 如果规格文档不存在:
- 通知用户:在
.claude/specs/[功能名称].md 未找到规格文档
- 询问是否先使用
sd-write-spec skill 创建规格
- 停止并等待用户决定
- 为所有阶段创建任务跟踪列表
- 向用户展示规格摘要:功能名称、需求数量、关键参与者
阶段二:代码库探索
目标:在规划实现前了解现有代码库
角色:代码分析专家
分析方法:
- 功能发现:找到入口点,定位核心实现文件,梳理功能边界和配置
- 代码流程追踪:从入口到输出追踪调用链,追踪数据转换,识别依赖和集成点
- 架构分析:映射展示层、业务逻辑层、数据层,识别设计模式和架构决策
- 实现细节:关键算法、错误处理、边界情况、性能考量
操作:
- 探索与该功能相似的现有功能或模式
- 完整追踪其从入口到输出的实现流程
- 梳理整体架构,识别相关关键抽象层和设计模式
- 向用户呈现需要遵循的模式和规范摘要
阶段三:实现规划
目标:根据规格需求创建详细的任务计划,并保存为 task 文件
角色:实现规划专家
工作流程:
- 基于阶段二的探索结果,整理规格文档中的所有 FR/NFR 及其依赖约束
- 将需求映射到实现
- 确定需要创建或修改哪些文件
- 确定需要添加哪些函数、类或组件
- 确定与现有代码的集成点
- 确定如何验证验收标准
- 规划实现顺序
- 从数据模型或类型开始
- 然后是核心业务逻辑
- 然后是 API 或接口层
- 然后是 UI 或展示层
- 最后是集成验证
任务要求:
- 每个任务必须是一个可以独立完成的最小交付单元
- 每个实现任务都要明确:
- 精确文件路径
- 对应的验证文件或验证入口
- 实现完成后的验证命令与预期结果
- 实现的修改边界
- 回归验证命令
- 不得出现
TODO、TBD、待补充、补测试、处理边界情况 这类空泛占位表述
- 如果某个任务不是代码实现而是文档或纯配置调整,必须在任务中写明使用什么可观察验证方式
输出格式:严格按照 templates/task.md 模板结构
操作:
- 确定模板文件路径:使用 skill 同包内置模板
../../templates/task.md(相对于本 SKILL.md)
- 基于规格文档和代码库探索发现,生成详细实现计划
- 将实现计划保存到
.claude/tasks/[功能名称].md:
mkdir -p .claude/tasks
- 对生成后的计划做自检:
- 每条 FR / NFR 是否都有任务承接
- 是否仍有占位词或模糊步骤
- 文件路径、命令、验证方式是否都能直接执行
- 审查计划,向用户展示:
- 任务总数和阶段划分
- 需要新建和修改的文件列表
- 开放问题清单
阶段四:澄清问题
目标:编码前解决所有歧义,并获得用户对 task.md 的最终确认
重要:如果存在待解决问题,不得跳过此阶段。
操作:
- 审查规格需求和实现计划,找出所有缺口或歧义
- 列出所有未解决问题,例如边界情况、集成细节、设计偏好
- 向用户呈现问题列表并等待答复
- 如果用户说“用你认为最好的方式”,在继续前确认你的决策
- 等待用户明确确认 task.md 任务详情无误,收到确认后才进入下一阶段
阶段五:创建分支或 worktree
目标:用户确认任务详情后,在正式编码前隔离开发工作
普通模式:
git checkout -b feature/[功能名称]
Worktree 模式:
git worktree add [worktree路径] -b feature/[功能名称]
Worktree 目录选择优先级(严格按顺序):
- 检查项目中是否存在
.worktrees 或 worktrees/ 目录,有则使用
- 检查项目配置文件(如 CLAUDE.md、.cursorrules 等)中是否配置了 worktree 目录偏好
- 询问用户,提供两个选项:
.worktrees/[功能名称](项目内)或 ../[功能名称](项目外)
Worktree 安全检查:
操作:
- 执行对应的 git 命令
- 如果是 worktree 模式,运行基线测试验证环境干净:
cd [worktree路径] && [项目测试命令]
如果基线测试失败,停止并告知用户,不要在有问题的基线上开始开发
- 更新规格文档
.claude/specs/[功能名称].md,在顶部添加开发元数据:
## 开发信息
- **分支**:feature/[功能名称]
- **Worktree 路径**:[worktree路径]
- **开始时间**:[当前日期]
- **状态**:进行中
- 告知用户当前使用的模式以及创建的分支或 worktree
阶段六:实现
目标:按照规格文档构建功能
未经用户确认,不得开始实现
操作:
- 按阶段依次完成任务列表
- 如果是 worktree 模式:
- 在采取任何操作前,先切换到
../[功能名称]
- 之后所有命令、文件读写都必须基于该工作树内执行
- 禁止在未切换目录前修改主工作区文件
- 对于每个子任务:
- 先阅读相关现有文件
- 先完成当前任务要求的实现
- 再运行该任务约定的验证命令
- 然后执行回归验证
- 遵循阶段二发现的代码库规范进行实现
- 将实现追溯到规格需求
- 完成每个任务后更新任务跟踪状态和 task.md 勾选状态
- 完成验证门禁:每个子任务声称完成前,必须满足:
- 验证命令在当前步骤中实际执行(不能引用之前的输出)
- 检查命令退出码和实际输出
- 预期结果与实际输出逐项对比
- 如果验证失败,任务状态保持未完成,不得跳过
- 如果某一步无法直接验证,必须向用户说明阻碍原因,并明确替代验证方式后再继续
阶段七:总结
目标:记录完成情况
操作:
- 标记所有任务为完成
- 回写规格文档
.claude/specs/[功能名称].md 的"开发信息"区块:
- 分支:当前功能分支名
- Worktree 路径:worktree 路径(如适用)
- 开始时间:开发开始日期
- 完成时间:当前日期
- 状态:已完成
- 总结:
- 构建了什么,实现了哪些规格需求
- 创建和修改的文件
- 包含改动的分支或 worktree 路径
- 下一步:使用
sd-review skill 对照规格审查代码
常见陷阱
- 跳过代码库探索直接规划:导致文件路径、模式和集成点不准确
- 未等用户确认 task.md 就开始实现:用户可能有不同的拆分思路
- Worktree 模式下在主工作区操作文件:所有操作必须在 worktree 目录内
- 验证命令失败但标记任务完成:"差不多能用"不等于完成
必须停止
遇到以下情况时,停下来重新评估:
- 你在说"应该能行"而非实际运行验证命令 — 执行命令,看真实输出
- 计划自检发现占位词但你想"先继续后面再补" — 现在就补完
- 验证失败但你想标记完成"因为核心逻辑已经对了" — 不对就是不对
- 你在主工作区修改了文件但当前是 worktree 模式 — 切换目录
- 基线测试失败但你想"先开始做,测试的问题之后修" — 先修基线