修 Bug 任务模板

修 Bug 任务模板

这一篇是 Bug 场景的提示词模板库。

修 Bug 最怕两件事：

原因没定位清楚就开始改
为了修一个 Bug 改出更多 Bug

所以修 Bug 的核心不是让 Codex “赶紧修”，而是让它按顺序做：

复现现象
-> 定位范围
-> 分析原因
-> 提出最小修复方案
-> 修改
-> 验收
-> 汇报风险

前置教程：怎样写一个合格的 Codex 任务
如果你还不知道一个合格任务应该包含哪些部分，先完成前置教程，再回到本篇。

模板 1：通用 Bug 修复

适合大多数 Bug。

我遇到了一个 Bug，请你帮我定位并修复。

## 现象
【这里写实际发生了什么】

## 期望
【这里写本来应该发生什么】

## 复现步骤
1. 【第一步】
2. 【第二步】
3. 【看到什么错误或异常】

## 错误信息
【粘贴完整报错；如果没有就写“暂无报错”】

## 相关位置
- 页面路径：
- 接口路径：
- 相关文件或模块：
- 我不确定的位置：

## 要求
1. 请先只读分析相关代码，不要立刻修改。
2. 请先说明你判断的 Bug 原因和依据。
3. 如果原因不确定，请列出需要继续查看的信息，不要猜。
4. 确认原因后，请给出最小修复方案。
5. 修改范围尽量小，不要顺手重构无关代码。
6. 不要提交 Git。
7. 不要把密钥、账号、token 写进文件。

## 验收标准
1. 上面的复现步骤不再出现 Bug。
2. 原有正常流程不受影响。
3. 修改文件和 Bug 直接相关。
4. 请根据项目情况做最小必要检查。
5. 如果没有运行检查，请说明原因。

## 汇报格式
请按下面格式回复：

### 原因定位
- Bug 原因：
- 判断依据：

### 修改摘要
- 修改文件：
- 修改内容：

### 验收结果
- 检查了什么：
- 哪些通过：
- 哪些失败：
- 未检查项及原因：

### 风险提示
- 是否可能影响其他功能：
- 是否建议进入提交前检查：

模板 2：前端页面 Bug

适合页面显示、按钮点击、表单校验、样式错乱。

我遇到了一个前端页面 Bug，请你帮我定位并修复。

## 页面信息
- 页面路径：【例如 /login】
- 浏览器：【例如 Chrome】
- 屏幕宽度或设备：【例如 1920 桌面 / iPhone 14】

## 现象
【例如：点击登录按钮没有任何反应】

## 期望
【例如：手机号为空时显示“请输入手机号”】

## 复现步骤
1. 打开页面：
2. 输入/点击：
3. 看到的错误：


## 要求
1. 请先定位页面入口和相关组件。
2. 不要一上来重构页面。
3. 优先修复最小相关文件。
4. 如果需要改样式，请说明原因。
5. 不要修改接口和数据库。
6. 修复后请检查 diff，并说明是否影响其他页面。

## 验收标准
1. 复现步骤中的问题消失。
2. 页面没有明显布局错乱。
3. 相关交互符合期望。
4. 如果项目有前端检查命令，请运行最小必要检查；否则说明原因。

模板 3：后端接口 Bug

适合接口报错、参数校验、返回结构不对。

我遇到了一个后端接口 Bug，请你帮我定位并修复。

## 接口信息
- 请求方法：【GET/POST/PUT/DELETE】
- 接口路径：【例如 /api/login】
- 请求参数：
【粘贴示例】

## 现象
【例如：手机号为空时报 500】

## 期望
【例如：手机号为空时返回 400，并提示“请输入手机号”】

## 报错信息
【粘贴后端日志或接口返回；没有就写“暂无”】

## 要求
1. 请先定位 controller/service/mapper 或相关文件。
2. 先分析原因，不要立刻修改。
3. 优先做最小修复。
4. 不要修改数据库结构。
5. 不要影响正常请求流程。
6. 如果已有测试，请运行相关测试；没有测试请说明原因。

## 验收标准
1. 异常请求返回符合预期。
2. 正常请求不受影响。
3. 不引入无关重构。
4. Codex 最后需要说明修改文件、原因和验证结果。

模板 4：构建或启动失败

适合 npm run build、npm run dev、mvn test、项目启动失败。

项目现在构建或启动失败，请你帮我排查。

## 我执行的动作
【例如：运行 npm run build】

## 完整错误输出
【粘贴完整错误，不要只贴最后一行】

## 最近做过的改动
【例如：刚修改了首页组件 / 刚升级依赖 / 不确定】

## 要求
1. 请先阅读错误输出，提取关键错误。
2. 请判断错误更可能来自代码、依赖、配置、环境还是历史问题。
3. 先分析，不要立刻修改。
4. 如果需要修改，请给出最小修复方案。
5. 不要升级依赖，除非你先说明原因并得到确认。
6. 修复后请重新运行同一个失败命令。

## 汇报格式
- 失败命令：
- 关键错误：
- 可能原因：
- 修改文件：
- 重新验证结果：
- 是否还有残留问题：

模板 5：线上或生产问题

线上问题更要谨慎。

这是一个线上/生产相关问题，请先帮我分析，不要直接修改。

## 影响范围
- 影响页面/接口：
- 影响用户：
- 是否持续发生：
- 是否有临时处理方式：

## 现象
【写清楚线上发生了什么】

## 日志或监控
【粘贴脱敏后的日志、错误码、时间点】

## 要求
1. 先只读分析，不要修改文件。
2. 先判断可能原因和风险等级。
3. 请列出需要确认的信息。
4. 请给出最小止血方案和长期修复方案。
5. 不要改数据库，不要删除数据，不要执行危险命令。
6. 等我确认后再进入修复。

## 输出格式
- 可能原因：
- 风险等级：
- 需要补充的信息：
- 临时止血建议：
- 长期修复建议：
- 不建议现在做的事：

Bug 信息不完整时怎么问

如果你手里只有一句：

页面报错了

不要直接让 Codex 修。

先让 Codex 帮你补问题清单：

我现在只知道页面报错，但信息不完整。

请先不要修改代码。
请帮我列一个排查清单，告诉我需要补充哪些信息。
要求按优先级列出：
1. 必须提供的信息。
2. 有了会更好的信息。
3. 可以暂时没有的信息。

修 Bug 时不要这样说

不要说：

帮我修一下。

不要说：

把所有报错都修了。

不要说：

你看着办。

更好的说法是：

请先定位这个 Bug 的最小原因，先解释，不要立刻改。确认原因后只修复和这个现象直接相关的代码。

验收结果

做到这里，如果满足下面 6 条，就说明你会用这篇模板：

1. 你能写清 Bug 现象。
2. 你能写清期望结果。
3. 你能提供复现步骤或说明暂时没有。
4. 你会要求 Codex 先定位原因再修改。
5. 你会要求 Codex 最小修复。
6. 你会要求 Codex 汇报验证结果和风险。

下一篇学什么

下一篇可以看：国内模型配置排障总表。

那一篇专门处理 API Key、Base URL、模型名、环境变量、额度和权限等配置问题。