feat: 添加 fix-issue skill 处理 GitHub issue 修复工作流

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-15 12:55:51 +00:00 · 2026-04-22 08:41:23 +08:00
parent bfd14206a9
commit d8e33935db
1 changed files with 139 additions and 0 deletions
--- a/.claude/skills/fix-issue/SKILL.md
+++ b/.claude/skills/fix-issue/SKILL.md
@@ -0,0 +1,139 @@
+---
+name: fix-issue
+description: 处理 GitHub issue 的完整修复工作流。当用户提到 issue 编号、粘贴 GitHub issue URL、说"修一下这个 bug"、"处理一下这个 issue"、或需要根据 bug 报告修复代码时使用此 skill。即使用户只是提到了一个 GitHub 问题的链接或编号，也应该触发此 skill。
+---
+
+# fix-issue: GitHub Issue 修复工作流
+
+你是一个专门处理 GitHub issue 的修复助手。收到 issue 后，你将自主完成从分析到提交的全流程。
+
+## 输入格式
+
+支持两种输入方式：
+
+1. **URL 方式**：用户提供 GitHub issue URL（如 `https://github.com/owner/repo/issues/123`）
+2. **描述方式**：用户直接描述问题（如 "登录页面点击提交按钮后崩溃" 或 "issue #456 的分页有问题"）
+
+如果是 URL 方式，用 `gh` 命令获取 issue 信息。如果是描述方式，直接基于描述工作。
+
+## 工作流程
+
+### 阶段一：信息收集
+
+**URL 方式：**
+
+```bash
+# 获取 issue 内容和元信息
+gh issue view <number> --repo <owner/repo> --json title,body,labels,assignees,comments,state
+```
+
+提取以下信息：
+- 问题标题和描述
+- Labels（bug、enhancement、documentation 等）
+- 评论中的补充信息（复现步骤、环境、错误日志、截图描述）
+- 是否有关联的 PR 或重复 issue
+
+**描述方式：**
+
+基于用户提供的描述理解问题。如果信息不足，用 AskUserQuestion 补充询问（只问一次，不要反复追问）。
+
+### 阶段二：问题分析与复杂度评估
+
+分析收集到的信息，评估问题：
+
+1. **问题本质**：这是一个什么类型的问题？（bug / 文档 / 性能 / 安全 / 重构）
+2. **影响范围**：大概涉及哪些模块或文件？
+3. **复杂度**：简单（单文件修复） / 中等（多文件但逻辑清晰） / 复杂（多模块耦合、需求不明确、或无法定位根因）
+
+**复杂度判断规则：**
+
+如果满足以下任一条件，判定为"复杂"，**必须停下来向用户汇报**，等用户决定下一步：
+- 无法确定问题的根因（多个可能的嫌疑点）
+- 修复可能影响 3 个以上模块
+- issue 描述模糊，存在多种理解方式
+- 需要添加新功能而非修复现有缺陷
+- 涉及数据库迁移、API 契约变更等破坏性修改
+
+汇报时说明：问题分析结果、可能的修复方向、以及为什么需要用户决策。
+
+### 阶段三：工作区检查
+
+开始修复前检查工作区状态：
+
+```bash
+git status
+git stash list
+```
+
+- 如果工作区有未提交的更改，提醒用户先处理（stash 或提交），**不要自动 stash 或丢弃更改**
+- 如果工作区干净，直接进入下一步
+- 在当前分支上直接修复，不创建新分支
+
+### 阶段四：代码定位与修复
+
+1. 使用 Explorer subagent（`subagent_type: "Explore"`）探索代码库，定位问题相关代码。给 Explorer 足够的上下文——把 issue 的关键信息告诉它
+2. 阅读相关代码，理解当前实现
+3. 制定修复方案并实施代码修改
+
+修复时遵循项目现有的代码风格和约定。参考 CLAUDE.md 中的项目规范。
+
+### 阶段五：验证
+
+修复完成后自动运行测试：
+
+```bash
+bun test
+```
+
+**测试失败处理：**
+- 分析失败原因，判断是否由本次修复引起
+- 如果是本次修复引起的，重新分析问题并修复，然后重跑测试
+- 最多重试 **2 次**（总共最多 3 次测试运行：初次 + 2 次重试）
+- 如果 2 次重试后仍然失败，停下来汇报失败原因和已尝试的方案，交给用户处理
+
+### 阶段六：提交
+
+测试通过后提交修复。
+
+**提交策略：**
+- 涉及多文件修改时，按逻辑分组提交（例如："修复数据层校验逻辑" 和 "修复 UI 层错误提示" 分开提交）
+- 单文件或逻辑简单的修复直接一次提交
+
+**Commit message 格式：**
+
+```
+fix: 简短描述 (#issue编号)
+```
+
+示例：
+- `fix: 修复登录页提交按钮点击后崩溃的问题 (#123)`
+- `fix: 修正分页组件页码计算逻辑 (#456)`
+- `fix: 更新 API 文档中的错误返回值描述 (#789)`
+
+对于非 bug 类型，对应调整 type：
+- 文档问题：`docs: 修正 xxx 描述 (#issue)`
+- 性能问题：`perf: 优化 xxx 性能 (#issue)`
+- 重构：`refactor: 重构 xxx (#issue)`
+
+提交后不自动创建 PR，也不输出完成提示。静默完成。
+
+## 错误处理
+
+- **`gh` 命令失败**：可能是 issue 不存在或权限不足。把错误信息展示给用户，让他们检查
+- **找不到相关代码**：扩大搜索范围，如果仍然找不到，停下来告诉用户，附上已搜索的范围
+- **测试超时**：如果是测试本身的问题（非修复引起），告知用户并跳过测试环节
+- **合并冲突**：不会发生（在当前分支直接修复），但如果 `git status` 显示冲突，停下来让用户处理
+
+## 全流程示例
+
+用户说：`帮我修一下 https://github.com/owner/repo/issues/42`
+
+1. 运行 `gh issue view 42 --repo owner/repo --json ...`，获取 issue 信息
+2. 分析：issue 标题是"用户注册时邮箱校验失败"，评论中有复现步骤和错误日志。复杂度评估：简单（单文件修复）
+3. `git status` 检查工作区干净
+4. 用 Explore agent 搜索 "email" "validate" "register" 相关代码
+5. 阅读 `src/services/auth/register.ts`，发现邮箱正则表达式不完整
+6. 修复正则表达式
+7. `bun test` → 通过
+8. `git commit -m "fix: 修复用户注册时邮箱校验正则表达式不完整的问题 (#42)"`
+9. 静默完成