bugfix-worktree
Skill2 starsChanged 5 months agoMITView on GitHub
从要修复的业务项目 issues CSV 中领取一个 bug,为该 bug 创建或恢复独立 git worktree 和分支,只修这个 bug;修复后先做 AI 自证验证,再构建待验证 APK 并复制到 issues/<版本>/apks/<bug_id>.apk;只有用户明确要求安装验证时才通过 adb 安装;用户确认通过后,合并到用户指定目标分支并清理 worktree。适用于用户提到 bug worktree、按 BUG id 修复、每 bug 独立分支、APK 待验证包、按需安装验证、人工验证后合并清理等流程。
In this repository12 other files it gives its agents.
- bug2csvSkill
- bugbatch-prepareSkill
- bugfix-comment-contextSkill
- bugfix-doneSkill
- debug-tag-addSkill
- debug-tag-clearSkill
- feature-doneSkill
- feature-prepareSkill
- feature-worktreeSkill
- plan-csv-executeSkill
- planSkill
- plan-to-issues-csvSkill
The file
Files
Bugfix Worktree
目的
建立一个半自动 bug 修复流程:一个 bug 对应一个分支、一个 worktree、一个独立修复窗口。
issues/<版本>/*.csv 是任务控制表,放在要修复的业务项目根目录里,例如 /path/to/business-project/issues/2026-06-25-test/bug_batch.csv。它不要放进任何单个 bug 的 worktree,也不要放到全局 skill 项目里。
单个 bug 的详细过程记录放在外部版本目录,例如 issues/<版本>/tasks/BUG-013-TASK.md。不要只放在 worktree 里,因为 worktree 是临时代码现场,合并后还可能需要回看任务记录。
这个 skill 不负责把模糊 bug 猜成真相。优先使用用户已经人工确认过的描述和明确的验证方法。
职责边界:本 skill 主要负责领取 bug、创建 worktree、修复、AI 自证验证、构建待验证 APK、按需安装。用户验证通过后的合并和 worktree 清理,优先交给 $bugfix-done。
Issues 表
推荐文件位置:
issues/<版本>/bug_batch.csv
例如:
issues/2026-06-24/bug_batch.csv
推荐列:
bug_id标题或title问题描述人工确认描述状态branchworktree_pathbase_repotarget_branch复现场景验收标准ai_verify_planai_verify_cmdai_verify_resultai_verify_evidenceapk_pathinstall_devicehuman_verify_resulthuman_verify_notecommittask_file备注
推荐状态:
draft, ready, needs_info, in_progress, fixed, ai_verified, apk_built, installed, human_verified, merged, integration_verified, worktree_removed, blocked
如果 CSV 缺少流程列,先备份,再补列。保留原始 bug 字段,不要破坏用户从腾讯文档导出的内容。
写入 CSV 前,在同目录创建简单锁文件,例如 <csv>.lock。如果锁文件很新,停止并提示可能有另一个窗口正在更新。只有确认锁已陈旧时,才说明原因后移除。
准备阶段
$bugfix-worktree 不应该在真正开始修 bug 时才频繁追问用户。应在从 $bug2csv 导出文件生成 issues/<版本>/bug_batch.csv 时,先把每条 bug 整理到可执行状态。
准备阶段推荐做法:
- 保留原始
问题描述。 - 用户或 AI 补充
人工确认描述,尽量写清楚真实复现过程。 - AI 根据人工确认描述生成
复现场景和验收标准草案。 - 用户只需要确认明显不对或缺关键条件的行。
- 信息足够开始修的行标记为
ready。 - 信息明显不足、会导致 AI 猜测的行标记为
needs_info,先不要领取修复。
字段含义:
复现场景:这个 bug 在什么条件下发生。写设备、系统、账号状态、连接方式、前置操作等。它回答“在哪里、怎么触发”。验收标准:修好后怎样算通过。写可观察结果,例如“只出现一个弹窗”“点击后跳到系统权限页”“PC 端持续有声音”。它回答“怎么判断修好了”。
示例:
bug_id,人工确认描述,复现场景,验收标准,状态
BUG-013,等待接收设备同意超时会出现两个弹窗,安卓发起端向 PC 接收端发起投屏,PC 不点击同意,等待请求超时,超时后安卓端只出现一个超时提示,不同时出现普通超时弹窗和连接失败超时弹窗,ready单 bug TASK 文件
每个 bug 必须维护一个单 bug 过程记录文件,放在当前版本目录:
issues/<版本>/tasks/<bug_id>-TASK.md
例如:
issues/2026-06-24/tasks/BUG-013-TASK.md
这个文件是当前 bug 的工作记忆,用来防止上下文超长或窗口中断后丢失信息。它不放入业务 worktree,也默认不提交到业务分支。
推荐内容:
# BUG-013 <标题>
## 目标问题
<原始问题和人工确认描述>
## 复现场景
<设备、系统、账号、连接方式、前置操作>
## 验收标准
<修好后怎样判断通过>
## 修复方案选择
- 选择方案:
- 为什么选择:
- 放弃方案:
## 修改记录
- <时间> <修改了什么、为什么改>
## 修改文件
- `path/to/file`
## AI 自证验证
- 验证计划:
- 测试/脚本:
- 命令:
- 结果:
- 证据:
## 待验证 APK
- APK:
- 生成结果:
## APK 安装
- 设备:
- 安装结果:
## 用户人工验证
- 结果:
- 备注:
## 阻塞/风险
- ...
## 下一步
- ...更新时机:
- 领取 bug 后创建。
- 每次重要设计选择、代码修改、测试失败、阻塞、构建安装、用户验证结果后追加。
- 上下文即将变长或任务中断前,先更新它。
- 合并后发现问题时,继续在同一个 TASK 文件里追加集成验证失败、回滚或二次修复记录。
工作流程
1. 领取或恢复 bug
触发示例:
$bugfix-worktree BUG-013
步骤:
- 定位业务项目里的 issues CSV;如果当前工作目录不是业务项目,以用户提供的
base_repo或 CSV 里的base_repo为准;如果有多个候选文件,询问用户用哪个。 - 读取匹配
bug_id的行。 - 执行前检查
base_repo:- 必须是 git 仓库。
- 读取
git status --porcelain,把变更分成两类:- 可忽略流程文件:
issues/**/*.md、issues/**/*.csv、features/**/*.md、features/**/*.csv、features/**/*.json。 - 阻塞文件:除上述流程文件外的任何未提交、未暂存或未跟踪文件。
- 可忽略流程文件:
- 如果存在阻塞文件,停止,不创建分支和 worktree;提醒用户先 commit、stash 或清理这些业务代码/配置改动。
- 如果只存在可忽略流程文件,可以继续;在 TASK 或回复里说明本次忽略了哪些流程文件。
- 记录当前
HEAD分支/commit,worktree 必须从这个业务代码干净的基线创建。
- 如果
worktree_path已存在,恢复这个 worktree。 - 如果还没有 worktree,创建:
- 分支:
codex/<bug_id>-<short-slug> - worktree:
<parent>/worktrees/<bug_id> - worktree 文件夹名必须和
bug_id一致,例如/path/to/worktrees/BUG-013
- 分支:
- 更新该行:
状态=in_progressbranchworktree_pathbase_repo- 在
备注写入开始时间和领取信息
- 在
issues/<版本>/tasks/里生成<bug_id>-TASK.md,包含原始描述、人工确认描述、禁止改无关 bug、复现场景和验收标准。 - 更新 CSV 的
task_file为外部 TASK 文件路径。
只修当前 bug。不要把 issues CSV 放进业务修复 commit,除非用户明确要求提交任务表。
2. 修复 bug
只在该 bug 的 worktree 里工作。先读取该 worktree 内的项目说明,例如 AGENTS.md。
修复要求:
- 先理解并尽量复现问题。
- 优先写一个能证明问题或保护修复的测试/脚本。
- 做最小必要修改。
- 把方案选择、修改文件和关键决策写入外部
<bug_id>-TASK.md。 - 本地提交修复,commit message 使用中文业务描述:
- 格式:
<bug_id> fix: <中文问题描述或修复内容> - 中文描述优先取 CSV 的
人工确认描述,其次取标题或问题描述,过长时压缩成一句话。 - 示例:
BUG-013 fix: 等待接收设备同意超时只显示一个提示弹窗
- 格式:
- 只有代码已提交后,才能把状态更新为
fixed。
3. AI 自证验证
这是用户人工验证之前的必经阶段。不能只说“我觉得修好了”。
AI 应尽量完成以下验证:
- 回归测试:优先新增或更新单元测试、状态机测试、UI 逻辑测试、资源文案检查脚本等。
- 相关测试命令:运行与修改范围相关的测试,例如
./gradlew test、模块测试、lint 或静态检查。 - 构建验证:确认目标 Android 包能构建。
- 可脚本化场景验证:能用 adb、uiautomator、截图、日志或脚本验证的,尽量自动验证。
- 不能自动验证的部分:明确写出原因和仍需人工确认的观察点。
写回 CSV:
ai_verify_plan:AI 打算验证什么ai_verify_cmd:实际执行的命令ai_verify_result:pass/fail/partialai_verify_evidence:测试结果、日志摘要、截图路径或无法自动验证的说明
同时把完整验证过程写入外部 <bug_id>-TASK.md,包括失败重试、不能自动验证的原因和仍需用户观察的点。
只有 AI 验证通过或明确为部分通过且原因已说明时,才能进入构建待验证 APK。状态更新为:
状态=ai_verified
如果测试失败、构建失败或自动验证发现问题,设置:
状态=blocked
并在 备注 写清楚失败原因。
4. 构建待验证 APK
默认只构建 APK,不自动安装到用户手机。这样多个 bug 并行修复时,不会互相抢占设备。
步骤:
- 从项目结构或文档判断 Android Gradle module 和 variant。
- 构建 debug 或用户指定的 APK,例如:
./gradlew :app:assembleDebug./gradlew assembleDebug
- 在
build/outputs/apk/...下找到生成的 APK。 - 创建
issues/<版本>/apks/。 - 将 APK 复制为:
issues/<版本>/apks/<bug_id>.apk- 例如
issues/2026-06-25-test/apks/BUG-001.apk
- 更新 CSV:
状态=apk_builtapk_pathcommit备注写入构建命令和 APK 输出摘要
- 把 APK 路径和构建结果写入外部
<bug_id>-TASK.md。
如果打包失败,设置 状态=blocked,并记录原因。
5. 按需安装验证
只有用户明确说“安装验证”“安装到手机”“adb install 这个 bug 包”时,才执行安装。
步骤:
- 读取 CSV 的
apk_path,确认待验证 APK 存在。 - 运行
adb devices。如果有多个设备,询问用户选择哪个 serial。 - 安装:
adb install -r <apk_path>
- 可做基础 smoke test,例如启动应用、观察进程、查看 logcat 是否有明显崩溃。
- 更新 CSV:
状态=installedinstall_device备注写入安装和 smoke test 摘要
- 把安装设备、安装结果和 smoke test 结果写入外部
<bug_id>-TASK.md。
如果安装失败,设置 状态=blocked,并记录原因。
6. 用户人工验证门禁
只有用户能把真实业务场景标记为通过。
当用户说某个 bug 验证通过时,更新:
状态=human_verifiedhuman_verify_result=passhuman_verify_note写入用户确认内容和时间- 在外部
<bug_id>-TASK.md记录用户确认内容
如果用户说验证失败:
状态=in_progress或blockedhuman_verify_result=failhuman_verify_note写入失败现象- 保留 worktree,继续修复
- 在外部
<bug_id>-TASK.md记录失败现象和下一步
验证记录应尽量包含设备型号、系统版本、PC/接收端、账号状态、连接方式、权限状态和具体复现场景。
7. 合并并清理 worktree
推荐使用 $bugfix-done 执行本阶段。本节仅说明状态边界和安全要求。
触发示例:
BUG-013 验证通过,合并到 develop
前置条件:
- CSV 状态是
human_verified,或用户在当前消息中明确确认人工验证通过。 - 用户明确指定目标分支,例如
develop、main、release/x.y。 - bug worktree 没有未提交改动。
- bug 分支包含记录的 commit。
合并要求:
- 从主仓库或干净的集成仓库执行合并,不要在脏的 bug worktree 里合并。
- 切到用户指定目标分支。
- 仅在用户预期且项目策略允许时拉取远端更新。
- 默认使用非 fast-forward merge,除非用户要求其它策略;merge commit message 使用中文业务描述,例如
Merge BUG-013 fix: 等待接收设备同意超时只显示一个提示弹窗。 - 合并后运行聚焦检查;高风险修复建议在目标分支再构建一次 APK。
- 合并成功后更新
状态=merged,并在 TASK 中记录 merge commit。 - 合并后不要立刻删除 worktree。等待用户在目标分支/集成包上再次人工验证。
- 用户确认合并后的目标分支验证通过后,更新
状态=integration_verified。 - 只有
integration_verified且没有未保存数据时,才执行git worktree remove <path>。 - worktree 删除成功后,默认用
git branch -d <branch>安全删除已合并的本地 bug 分支。 - 如果
git branch -d因未合并、分支被占用或其它安全原因失败,不要使用-D强删;保留分支,更新blocked_reason=branch_cleanup_failed或在备注写清原因和下一步。 - worktree 和本地 bug 分支都清理成功后,更新
状态=worktree_removed,并在备注写入 merge commit、TASK 路径、worktree 清理和分支清理信息。
如果合并冲突,不要删除 worktree。设置 状态=blocked,说明冲突文件和下一步。
复现场景与验收标准
每个可执行 bug 最好在准备阶段就有 复现场景 和 验收标准。如果缺失,不要等到领取 bug 后才阻塞;应尽量在生成 issues CSV 时标记为 needs_info 并让用户补齐。
这里的定义:
复现场景:复现 bug 所需的场景和条件,例如手机型号、系统版本、PC 接收端、账号/会员状态、连接方式、权限状态、前置操作。验收标准:证明修复生效的可观察结果,例如“点击后台权限按钮后应跳转系统权限页”、“等待投屏超时后只出现一个弹窗”、“合并后目标分支 APK 安装到小米 13 上复测通过”。
推荐记录:
- Android 设备型号和系统版本
- 涉及的鸿蒙/iOS 设备
- PC/Mac 接收端标识
- USB、ADB、局域网投屏等连接路径
- 账号、会员、登录状态
- app flavor / build variant
- 必要权限
- 期望可观察结果
阻塞分类
blocked 应配合 blocked_reason 或 备注 使用,避免只写“卡住了”。
推荐分类:
missing_repro:缺少可复现步骤或人工确认描述missing_env:缺少必要设备、账号、权限或连接环境build_failed:构建失败test_failed:AI 自证验证失败device_unavailable:ADB/真机不可用verification_failed:用户人工验证失败merge_conflict:合并冲突integration_failed:合并后目标分支人工验证失败
收尾检查
每次 $bugfix-worktree 窗口准备结束前,都要做一次轻量收尾,保证下次打开能接着干。
必须检查:
issues/<版本>/bug_batch.csv中当前 bug 的状态、branch、worktree_path、task_file已更新。- 外部
issues/<版本>/tasks/<bug_id>-TASK.md已记录本轮目标、修改内容、验证结果、阻塞和下一步。 - 如果已有代码修改,说明是否已 commit;已 commit 时记录
commit。 - 如果跑过测试/构建/安装,记录命令、结果和证据。
- 如果已构建待验证包但未安装,状态应停在
apk_built,并写清楚 APK 路径和“等待用户决定是否安装验证”。 - 如果已安装等待用户验证,状态应停在
installed或merged,并写清楚用户下一步要验证什么。 - 如果失败或卡住,状态应是
blocked,并记录blocked_reason。 - worktree 中的未提交改动要明确说明,不能悄悄留下半成品。
- 如果状态已到
worktree_removed,确认 bug worktree 目录已不存在,且本地 bug 分支已通过git branch -d安全删除;删除失败时记录原因,不要静默保留。
不要为了收尾创建额外报告文件;单 bug 过程记录以 TASK 文件为准,批次总览以 CSV 为准。
安全规则
- 未经过 AI 自证验证,不要构建待验证 APK。
- 不要自动安装 APK;只有用户明确要求安装验证时才 adb install。
- 未经用户人工验证,不要合并,除非用户明确 override。
- 合并前不要删除 worktree。
- 合并后也不要立刻删除 worktree;等用户完成目标分支集成验证后再删。
- TASK 文件放在
issues/<版本>/tasks/,不要只放在 worktree 里。 - 多窗口更新 issues CSV 必须使用锁。
- 创建 worktree 前,base repo 的业务代码必须是干净 git 状态;
issues/**/*.md、issues/**/*.csv、features/**/*.md、features/**/*.csv、features/**/*.json这类流程文件可以忽略,但其它未提交内容必须停止。 - worktree 默认放在 issues 项目外部,文件夹名使用
bug_id,例如/path/to/worktrees/BUG-013。 - 最终回复聚焦:bug_id、状态、worktree、branch、AI 验证结果、待验证 APK 路径、安装设备如有、下一步需要用户做什么。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

