fix-bug

# Bug 修复流水线 从 Bug 描述出发，自动完成：Bug 分析与定位 → 创建隔离 Worktree → 代码修复 → 补充测试 → 全量验证 → 合入主分支 → 清理 Worktree。 适用于 **tapd-ai-cli** 项目——一个纯 Go CLI 工具，无前端、无 E2E 测试。 --- ## 流程总览 ``` 用户输入 Bug 描述 | v [阶段 1] Bug 分析与定位 | v 确认修复方案 | v [阶段 2] 创建 Worktree（隔离工作区） | v [阶段 3] 代码修复 | v [阶段 4] 补充单元测试 | v [阶段 5] 全量验证（fmt / lint / build / test / coverage） | ← 失败则修复代码并重新验证 v [阶段 6] 合入主分支并清理 Worktree | v 完成 ``` --- ## 步骤 ### 阶段 1：Bug 分析与定位 1. **获取 Bug 信息** 用户在调用此 SKILL 时应附带 Bug 描述。如果未提供，使用 **AskUserQuestion tool** 询问： > "请描述您遇到的 Bug，包括复现步骤、期望行为和实际行为。" 2. **阅读项目上下文** 阅读以下文件获取项目背景： - `CODEBUDDY.md` — 项目架构、构建命令、代码规范 - `docs/requirement.md` — 需求规格 3. **分析 Bug 根因** 使用 **Agent tool**（subagent_type=Explore）深入分析 Bug： - 根据 Bug 描述定位相关代码文件 - 项目目录结构：`cmd/tapd/`（入口）、`internal/cmd/`（命令层）、`internal/client/`（API 客户端层）、`internal/config/`（配置层）、`internal/output/`（输出层）、`internal/model/`（数据模型层） - 追踪数据流：参数解析 → API 调用 → 响应转换 → 格式化输出 - 分析可能的根因 - 检查是否有相关的已有测试覆盖该场景 4. **提出修复方案并确认** 使用 **AskUserQuestion tool** 向用户展示分析结果并确认修复方案： - Bug 根因分析 - 受影响的文件和模块 - 修复方案（如有多种方案，列出各方案的优缺点） - 可能的影响范围 等待用户确认修复方案后再继续。 ### 阶段 2：创建 Worktree（隔离工作区） 5. **确认当前分支状态** 在创建 worktree 前，先检查当前分支状态： ```bash git status git branch --show-current ``` - 如果当前有未提交的更改，使用 **AskUserQuestion tool** 提醒用户并询问是否继续（worktree 是独立的，不影响当前工作区的更改）。 - 记录当前所在的主分支名称（通常是 `main` 或 `master`），后续合入时使用。 6. **创建隔离 Worktree** 使用 git 命令在项目父目录下创建 worktree，避免在项目内部产生额外目录： ```bash # 获取项目根目录的父目录路径 PROJECT_ROOT=$(git rev-parse --show-toplevel) WORKTREE_DIR="$(dirname "$PROJECT_ROOT")/worktree/fix-<bug简述>" # 基于主分支创建新分支和 worktree git worktree add -b fix-<bug简述> "$WORKTREE_DIR" <主分支名> ``` - 分支命名：使用 `fix-<bug简述>` 格式，例如 `fix-auth-token-error` - Worktree 路径：`../worktree/fix-<bug简述>`（相对于项目根目录） - 基于步骤 5 中记录的主分支创建 创建成功后，使用 `cd` 切换到新的 worktree 目录中。后续所有代码修改和测试都在此工作区中进行。 ### 阶段 3：代码修复 7. **创建任务列表** 使用 **TaskCreate tool** 根据确认的修复方案创建详细的任务列表，将修复工作拆分为可跟踪的小任务。 8. **实现代码修复** 按照任务列表逐一修复代码： - 使用 **Read tool** 阅读需要修改的文件 - 使用 **Edit tool** 进行精确修改 - 遵循项目编码规范（参见 `CODEBUDDY.md` 代码规范章节）： - 代码注释和文档用中文，错误消息用英文 - 每个导出函数/结构体/接口必须有中文文档注释 - 函数不超过 80 行，文件不超过 800 行，嵌套不超过 4 层 - 错误作为最后一个返回值，必须处理 - `switch` 必须有 `default` - 业务逻辑禁止 `panic` 和 `goto` - 命令层（`internal/cmd/`）只做参数解析和输出格式化，禁止直接构造 HTTP 请求 - API 调用必须经过客户端层（`internal/client/`） - 每完成一个任务，使用 **TaskUpdate tool** 标记为完成 注意： - 保持修改范围最小化，仅修复 Bug 本身，不做无关的重构 - 确保修改不引入新的问题 ### 阶段 4：补充单元测试 9. **判断是否需要补充测试** 如果 Bug 场景已有测试覆盖且测试本身无误，可跳过。否则必须补充。 10. **编写单元测试** - 查看对应包下已有的 `*_test.go` 文件作为参考 - 编写针对本次 Bug 修复的测试用例，确保： - 测试覆盖 Bug 的复现场景（修复前该测试应失败） - 测试验证修复后的正确行为 - 测试边界条件和异常情况 - API 客户端层测试使用 `net/http/httptest` 做 mock server - 命令层测试验证参数解析和输出格式 - 测试文件命名：`xxx_test.go`，测试函数命名：`TestXxx` ### 阶段 5：全量验证 11. **代码格式化和静态检查** ```bash make fmt make lint ``` 如果 lint 报错，修复后重新检查。 12. **构建** ```bash make build ``` 如果构建失败，分析错误并修复代码，然后重新构建。 13. **运行全量测试** ```bash make test ``` 如果测试失败，分析失败原因并修复代码/测试，然后重新运行。 14. **检查测试覆盖率** ```bash make coverage ``` 确保覆盖率 >= 60%。如果低于阈值，补充测试用例。 15. **验证循环** 如果步骤 11-14 中任何一步失败： - 分析错误日志 - 修复代码或测试 - 从步骤 11 重新开始完整验证流程 - 最多重试 3 轮。如果 3 轮后仍有失败，暂停并报告问题，等待用户指导。 ### 阶段 6：合入主分支并清理 Worktree 仅在阶段 5 的所有验证步骤全部通过后才执行此步骤。 16. **在 Worktree 中提交变更** 在当前 worktree 中提交所有修复代码： ```bash git add <相关文件> # 不要添加无关文件 git commit -m "fix: <Bug 简述> <详细描述修复内容和根因>" ``` 17. **合入主分支** 使用 **AskUserQuestion tool** 询问用户是否将修复合入主分支： > "所有验证已通过并已提交。是否将修复合入主分支（<主分支名>）？" 如果用户确认： a. **切回主工作区** ```bash cd <项目根目录> # 切回原来的主工作区 ``` b. **合并修复分支到主分支** 使用 fast-forward 优先的合并策略，避免无冲突时产生多余的 merge commit： ```bash git merge <worktree分支名> --ff ``` - 如果修复分支是主分支的直接后继（无分叉），git 会自动 fast-forward，不产生 merge commit - 如果存在分叉但无冲突，会产生 merge commit（这是必要的） - 如果合并冲突，手动解决冲突后继续 c. **删除 Worktree 和修复分支** 合并成功后，清理 worktree 目录和修复分支： ```bash # 删除 worktree PROJECT_ROOT=$(git rev-parse --show-toplevel) git worktree remove "$(dirname "$PROJECT_ROOT")/worktree/fix-<bug简述>" # 删除修复分支 git branch -d <worktree分支名> ``` 18. **推送到远程仓库（可选）** 使用 **AskUserQuestion tool** 询问用户是否需要推送到远程仓库： > "修复已合入主分支。是否需要推送到远程仓库？" 如果用户确认，执行推送。 --- ## 完成时的输出 ``` ## Bug 修复完成 **Bug：** <Bug 简述> **根因：** <根因分析> **修复方案：** <方案简述> ### 修改的文件 - <文件列表及修改说明> ### 新增/修改的测试 - <测试文件及覆盖场景> ### 验证结果 - fmt/lint 通过 - 构建通过 - 全量测试通过 - 覆盖率 >= 60% ### Git 信息 - 修复分支：<分支名> - 已合入：<主分支名> - commit: <commit hash> - worktree 已清理 Bug 修复全流程已完成。 ``` --- ## 护栏 - **严格按阶段顺序执行**：每个阶段必须完成后才能进入下一阶段 - **修复方案必须经用户确认**：不得跳过用户确认直接修改代码 - **必须在 Worktree 中修改代码**：所有代码修改必须在隔离的 worktree（`../worktree/` 目录）中进行，不得直接在主工作区修改 - **修改范围最小化**：仅修复 Bug 本身，不做无关重构或功能增强 - **Bug 场景必须有测试覆盖**：确保 Bug 不会回归 - **验证必须全部通过**：fmt、lint、build、test、coverage 全部通过后才能提交 - **失败时修复而非跳过**：验证失败时必须修复代码并重新验证 - **重试有上限**：验证循环最多 3 轮，超过后暂停等待用户指导 - **合入前确认**：合入主分支前必须征求用户同意 - **合入后清理**：合并成功后必须删除 `../worktree/` 下的 worktree 目录和修复分支，保持仓库整洁 - **合并策略**：使用 `--ff` 合并，能 fast-forward 时不产生 merge commit，保持提交历史简洁 - **推送前确认**：推送前必须征求用户同意 - **使用 Task tool 跟踪进度**：创建任务跟踪每个阶段的进度 - **遵循项目编码规范**：Go 代码遵循 `CODEBUDDY.md` 中的代码规范和 Go 编码规范 - **架构分层约束**：命令层不直接构造 HTTP 请求，API 调用必须经过客户端层 - **错误处理规范**：使用明确的退出码（0=成功，1=认证错误，2=未找到，3=参数错误，4=API 错误）