mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-23 16:55:51 +00:00
140 lines
5.5 KiB
Markdown
140 lines
5.5 KiB
Markdown
---
|
||
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. 静默完成
|