sd-dev

name	sd-dev
description	当用户希望根据已有规格文档推进实现、说"开始开发""实现这个功能""按 spec 来做"时使用。读取 spec、探索代码库、生成任务计划，并在用户确认后执行开发。如果没有 spec 文档，会引导用户先创建。

功能开发

你正在帮助开发者实现一个已有规格文档的功能。规格优先的方式确保你构建的是事先商定的内容。

角色定义

角色：资深软件架构师（连接需求与实现）

核心职责：

1. 代码库探索：理解现有代码库的模式、架构和规范
2. 实现规划：将规格需求转化为具体、可执行的任务计划

核心原则

• 规格驱动：每个实现决策都追溯到规格需求
• 计划先行：先完成探索、规划和澄清，用户确认 task.md 无误后再创建分支
• 编码前先确认：在实现开始前解决所有歧义
• 任务可执行：task.md 必须写出精确文件路径、测试命令、验证命令，不能出现占位描述
• 进度跟踪：全程使用任务跟踪工具记录进度

阶段一：解析请求并加载规格

初始请求来自当前用户对话。

操作：

1. 从用户请求中解析：
   • 功能名称，例如 user-auth
   • 是否启用 worktree 模式，若用户明确提到 --worktree、独立工作树或隔离目录，则视为启用
2. 加载规格文档：读取 .claude/specs/[功能名称].md
3. 如果规格文档不存在：
   • 通知用户：在 .claude/specs/[功能名称].md 未找到规格文档
   • 询问是否先使用 sd-write-spec skill 创建规格
   • 停止并等待用户决定
4. 为所有阶段创建任务跟踪列表
5. 向用户展示规格摘要：功能名称、需求数量、关键参与者

阶段二：代码库探索

目标：在规划实现前了解现有代码库

角色：代码分析专家

分析方法：

1. 功能发现：找到入口点，定位核心实现文件，梳理功能边界和配置
2. 代码流程追踪：从入口到输出追踪调用链，追踪数据转换，识别依赖和集成点
3. 架构分析：映射展示层、业务逻辑层、数据层，识别设计模式和架构决策
4. 实现细节：关键算法、错误处理、边界情况、性能考量

操作：

1. 探索与该功能相似的现有功能或模式
2. 完整追踪其从入口到输出的实现流程
3. 梳理整体架构，识别相关关键抽象层和设计模式
4. 向用户呈现需要遵循的模式和规范摘要

阶段三：实现规划

目标：根据规格需求创建详细的任务计划，并保存为 task 文件

角色：实现规划专家

工作流程：

1. 基于阶段二的探索结果，整理规格文档中的所有 FR/NFR 及其依赖约束
2. 将需求映射到实现
   • 确定需要创建或修改哪些文件
   • 确定需要添加哪些函数、类或组件
   • 确定与现有代码的集成点
   • 确定如何验证验收标准
3. 规划实现顺序
   • 从数据模型或类型开始
   • 然后是核心业务逻辑
   • 然后是 API 或接口层
   • 然后是 UI 或展示层
   • 最后是集成验证

任务要求：

• 每个任务必须是一个可以独立完成的最小交付单元
• 每个实现任务都要明确：
  • 精确文件路径
  • 对应的验证文件或验证入口
  • 实现完成后的验证命令与预期结果
  • 实现的修改边界
  • 回归验证命令
• 不得出现 TODO、TBD、待补充、补测试、处理边界情况 这类空泛占位表述
• 如果某个任务不是代码实现而是文档或纯配置调整，必须在任务中写明使用什么可观察验证方式

输出格式：严格按照 templates/task.md 模板结构

操作：

1. 确定模板文件路径：使用 skill 同包内置模板 ../../templates/task.md（相对于本 SKILL.md）
2. 基于规格文档和代码库探索发现，生成详细实现计划
3. 将实现计划保存到 .claude/tasks/[功能名称].md：

   mkdir -p .claude/tasks
   

4. 对生成后的计划做自检：
   • 每条 FR / NFR 是否都有任务承接
   • 是否仍有占位词或模糊步骤
   • 文件路径、命令、验证方式是否都能直接执行
5. 审查计划，向用户展示：
   • 任务总数和阶段划分
   • 需要新建和修改的文件列表
   • 开放问题清单

阶段四：澄清问题

目标：编码前解决所有歧义，并获得用户对 task.md 的最终确认

重要：如果存在待解决问题，不得跳过此阶段。

操作：

1. 审查规格需求和实现计划，找出所有缺口或歧义
2. 列出所有未解决问题，例如边界情况、集成细节、设计偏好
3. 向用户呈现问题列表并等待答复
4. 如果用户说“用你认为最好的方式”，在继续前确认你的决策
5. 等待用户明确确认 task.md 任务详情无误，收到确认后才进入下一阶段

阶段五：创建分支或 worktree

目标：用户确认任务详情后，在正式编码前隔离开发工作

普通模式：

git checkout -b feature/[功能名称]

Worktree 模式：

git worktree add [worktree路径] -b feature/[功能名称]

Worktree 目录选择优先级（严格按顺序）：

1. 检查项目中是否存在 .worktrees 或 worktrees/ 目录，有则使用
2. 检查项目配置文件（如 CLAUDE.md、.cursorrules 等）中是否配置了 worktree 目录偏好
3. 询问用户，提供两个选项：.worktrees/[功能名称]（项目内）或 ../[功能名称]（项目外）

Worktree 安全检查：

• 如果 worktree 在项目目录内，必须确认已被 .gitignore 忽略：

  git check-ignore .worktrees/[功能名称]
  

• 如果未被忽略：立即将 .worktrees/ 添加到 .gitignore 并提交

操作：

1. 执行对应的 git 命令
2. 如果是 worktree 模式，运行基线测试验证环境干净：

   cd [worktree路径] && [项目测试命令]
   

   如果基线测试失败，停止并告知用户，不要在有问题的基线上开始开发
3. 更新规格文档 .claude/specs/[功能名称].md，在顶部添加开发元数据：

   ## 开发信息
   - **分支**：feature/[功能名称]
   - **Worktree 路径**：[worktree路径]
   - **开始时间**：[当前日期]
   - **状态**：进行中
   

4. 告知用户当前使用的模式以及创建的分支或 worktree

阶段六：实现

目标：按照规格文档构建功能

未经用户确认，不得开始实现

操作：

1. 按阶段依次完成任务列表
2. 如果是 worktree 模式：
   • 在采取任何操作前，先切换到 ../[功能名称]
   • 之后所有命令、文件读写都必须基于该工作树内执行
   • 禁止在未切换目录前修改主工作区文件
3. 对于每个子任务：
   • 先阅读相关现有文件
   • 先完成当前任务要求的实现
   • 再运行该任务约定的验证命令
   • 然后执行回归验证
   • 遵循阶段二发现的代码库规范进行实现
   • 将实现追溯到规格需求
   • 完成每个任务后更新任务跟踪状态和 task.md 勾选状态
4. 完成验证门禁：每个子任务声称完成前，必须满足：
   • 验证命令在当前步骤中实际执行（不能引用之前的输出）
   • 检查命令退出码和实际输出
   • 预期结果与实际输出逐项对比
   • 如果验证失败，任务状态保持未完成，不得跳过
5. 如果某一步无法直接验证，必须向用户说明阻碍原因，并明确替代验证方式后再继续

阶段七：总结

目标：记录完成情况

操作：

1. 标记所有任务为完成
2. 回写规格文档 .claude/specs/[功能名称].md 的"开发信息"区块：
   • 分支：当前功能分支名
   • Worktree 路径：worktree 路径（如适用）
   • 开始时间：开发开始日期
   • 完成时间：当前日期
   • 状态：已完成
3. 总结：
   • 构建了什么，实现了哪些规格需求
   • 创建和修改的文件
   • 包含改动的分支或 worktree 路径
   • 下一步：使用 sd-review skill 对照规格审查代码

常见陷阱

• 跳过代码库探索直接规划：导致文件路径、模式和集成点不准确
• 未等用户确认 task.md 就开始实现：用户可能有不同的拆分思路
• Worktree 模式下在主工作区操作文件：所有操作必须在 worktree 目录内
• 验证命令失败但标记任务完成："差不多能用"不等于完成

必须停止

遇到以下情况时，停下来重新评估：

• 你在说"应该能行"而非实际运行验证命令 — 执行命令，看真实输出
• 计划自检发现占位词但你想"先继续后面再补" — 现在就补完
• 验证失败但你想标记完成"因为核心逻辑已经对了" — 不对就是不对
• 你在主工作区修改了文件但当前是 worktree 模式 — 切换目录
• 基线测试失败但你想"先开始做，测试的问题之后修" — 先修基线