fix-bug

star 25

Bug 修复流水线。当用户报告 Bug 或想要修复已知问题时使用。调用时需附带 Bug 描述或复现步骤。自动串联：Bug 分析 → 创建 Worktree → 代码修复 → 集成测试 → E2E 测试 → 全量验证 → 合入 main。

studyzy By studyzy schedule Updated 4/17/2026
play_arrow Run Skill in Manus View GitHub

name: fix-bug description: "Bug 修复流水线。当用户报告 Bug 或想要修复已知问题时使用。调用时需附带 Bug 描述或复现步骤。自动串联：Bug 分析 → 创建 Worktree → 代码修复 → 集成测试 → E2E 测试 → 全量验证 → 合入 main。" argument-hint: "[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（隔离工作区）

  1. 确认当前分支状态

    在创建 worktree 前，先检查当前分支状态：

    git status
git branch --show-current
    • 如果当前有未提交的更改，使用 AskUserQuestion tool 提醒用户并询问是否继续（worktree 是独立的，不影响当前工作区的更改）。
    • 记录当前所在的主分支名称（通常是 main 或 master），后续合入时使用。

  2. 创建隔离 Worktree

    使用 git 命令在项目父目录下创建 worktree，避免在项目内部产生额外目录：

    # 获取项目根目录的父目录路径
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：代码修复

  1. 创建任务列表

    使用 TaskCreate tool 根据确认的修复方案创建详细的任务列表，将修复工作拆分为可跟踪的小任务。

  2. 实现代码修复

    按照任务列表逐一修复代码：

    • 使用 Read tool 阅读需要修改的文件
    • 使用 Edit tool 进行精确修改
    • 遵循项目编码规范（参见 CODEBUDDY.md 代码规范章节）：
      • 代码注释和文档用中文，错误消息用英文
      • 每个导出函数/结构体/接口必须有中文文档注释
      • 函数不超过 80 行，文件不超过 800 行，嵌套不超过 4 层
      • 错误作为最后一个返回值，必须处理
      • switch 必须有 default
      • 业务逻辑禁止 panic 和 goto
    • 命令层（internal/cmd/）只做参数解析和输出格式化，禁止直接构造 HTTP 请求
    • API 调用必须经过客户端层（internal/client/）
    • 每完成一个任务，使用 TaskUpdate tool 标记为完成

    注意：

    • 保持修改范围最小化，仅修复 Bug 本身，不做无关的重构
    • 确保修改不引入新的问题

阶段 4：补充单元测试

  1. 判断是否需要补充测试

    如果 Bug 场景已有测试覆盖且测试本身无误，可跳过。否则必须补充。

  2. 编写单元测试

    • 查看对应包下已有的 *_test.go 文件作为参考
    • 编写针对本次 Bug 修复的测试用例，确保：
      • 测试覆盖 Bug 的复现场景（修复前该测试应失败）
      • 测试验证修复后的正确行为
      • 测试边界条件和异常情况
    • API 客户端层测试使用 net/http/httptest 做 mock server
    • 命令层测试验证参数解析和输出格式
    • 测试文件命名：xxx_test.go，测试函数命名：TestXxx

阶段 5：全量验证

  1. 代码格式化和静态检查

    make fmt
make lint

    如果 lint 报错，修复后重新检查。

  2. 构建

    make build

    如果构建失败，分析错误并修复代码，然后重新构建。

  3. 运行全量测试

    make test

    如果测试失败，分析失败原因并修复代码/测试，然后重新运行。

  4. 检查测试覆盖率

    make coverage

    确保覆盖率 >= 60%。如果低于阈值，补充测试用例。

  5. 验证循环

    如果步骤 11-14 中任何一步失败：

    • 分析错误日志
    • 修复代码或测试
    • 从步骤 11 重新开始完整验证流程
    • 最多重试 3 轮。如果 3 轮后仍有失败，暂停并报告问题，等待用户指导。

阶段 6：合入主分支并清理 Worktree

仅在阶段 5 的所有验证步骤全部通过后才执行此步骤。

  1. 在 Worktree 中提交变更

    在当前 worktree 中提交所有修复代码：

    git add <相关文件>   # 不要添加无关文件
git commit -m "fix: <Bug 简述>

<详细描述修复内容和根因>"

  2. 合入主分支

    使用 AskUserQuestion tool 询问用户是否将修复合入主分支：

    "所有验证已通过并已提交。是否将修复合入主分支（<主分支名>）？"

    如果用户确认：

    a. 切回主工作区

    cd <项目根目录>   # 切回原来的主工作区

    b. 合并修复分支到主分支

    使用 fast-forward 优先的合并策略，避免无冲突时产生多余的 merge commit：

    git merge <worktree分支名> --ff
    • 如果修复分支是主分支的直接后继（无分叉），git 会自动 fast-forward，不产生 merge commit
    • 如果存在分叉但无冲突，会产生 merge commit（这是必要的）
    • 如果合并冲突，手动解决冲突后继续

    c. 删除 Worktree 和修复分支

    合并成功后，清理 worktree 目录和修复分支：

    # 删除 worktree
PROJECT_ROOT=$(git rev-parse --show-toplevel)
git worktree remove "$(dirname "$PROJECT_ROOT")/worktree/fix-<bug简述>"
# 删除修复分支
git branch -d <worktree分支名>

  3. 推送到远程仓库（可选）

    使用 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 错误）
Install via CLI
npx skills add https://github.com/studyzy/tapd-ai-cli --skill fix-bug
Repository Details
star Stars 25
call_split Forks 9
navigation Branch main
article Path SKILL.md
More from Creator
studyzy
studyzy Explore all skills →