claude-code/.claude/skills/fix-issue/SKILL.md

name, description

name	description
fix-issue	处理 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 方式：

# 获取 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 契约变更等破坏性修改

汇报时说明：问题分析结果、可能的修复方向、以及为什么需要用户决策。

阶段三：工作区检查

开始修复前检查工作区状态：

git status
git stash list

• 如果工作区有未提交的更改，提醒用户先处理（stash 或提交），不要自动 stash 或丢弃更改
• 如果工作区干净，直接进入下一步
• 在当前分支上直接修复，不创建新分支

阶段四：代码定位与修复

1. 使用 Explorer subagent（subagent_type: "Explore"）探索代码库，定位问题相关代码。给 Explorer 足够的上下文——把 issue 的关键信息告诉它
2. 阅读相关代码，理解当前实现
3. 制定修复方案并实施代码修改

修复时遵循项目现有的代码风格和约定。参考 CLAUDE.md 中的项目规范。

阶段五：验证

修复完成后自动运行测试：

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. 静默完成