修 Bug 最怕两件事：原因没定位清楚就开始改，以及为了修一个 Bug 改出更多 Bug。修 Bug 的核心不是让 Codex “赶紧修”，而是让它按顺序执行：复现 -> 定位 -> 分析 -> 方案 -> 修改 -> 验收 -> 汇报。

> 前置教程：怎样写一个合格的 Codex 任务

> 如果你还不知道一个合格任务应该包含哪些部分，先完成前置教程。

1. 通用 Bug 修复模板

适合大多数 Bug。

``markdown

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

现象

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

期望

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

复现步骤

  1. 【第一步】

    2. 2. 【看到什么错误或异常】

    错误信息

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

    相关位置

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

    要求

    1. 请先只读分析相关代码，不要立刻修改。

      2. 2. 请先说明你判断的 Bug 原因和依据。

      3. 如果原因不确定，请列出需要继续查看的信息，不要猜。

      4. 确认原因后，请给出最小修复方案。

      5. 修改范围尽量小，不要顺手重构无关代码。

      6. 不要提交 Git。

      7. 不要把密钥、账号、token 写进文件。

      验收标准

      1. 上面的复现步骤不再出现 Bug。

        2. 2. 原有正常流程不受影响。

        3. 修改文件和 Bug 直接相关。

        4. 请根据项目情况做最小必要检查。

        汇报格式

        请按下面格式回复：

        原因定位

        • Bug 原因：
        • 判断依据：

          • 修改摘要

        • 修改文件：
        • 修改内容：

          • 验收结果

        • 检查了什么：
        • 结果：
        • 未检查项及原因：

          • 风险提示

        • 是否可能影响其他功能：
        • 是否建议进入提交前检查：

          • `

        2. 前端 UI/交互 Bug 模板

        适合显示、点击、校验、样式错乱。

        `markdown

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

        页面信息

        • 页面路径：【例如 /login】
        • 浏览器：【例如 Chrome】
        • 屏幕宽度：【例如 1920 桌面】

        现象

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

        期望

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

        复现步骤

        1. 打开页面：

          2. 2. 输入/点击：

          3. 看到的错误：

          要求

          1. 请先定位页面入口和相关组件。

            2. 2. 不要一上来重构页面。

            3. 优先修复最小相关文件。

            4. 如果需要改样式，请说明原因。

            5. 不要修改接口和数据库。

            验收标准

            1. 复现步骤中的问题消失。

              2. 2. 页面没有明显布局错乱。

              3. 相关交互符合期望。

              `

              3. 后端接口 Bug 模板

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

              `markdown

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

              接口信息

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

              现象

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

              期望

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

              报错信息

              【粘贴后端日志或接口返回】

              要求

              1. 请先定位 controller/service/mapper 或相关文件。

                2. 2. 先分析原因，不要立刻修改。

                3. 优先做最小修复，不修改数据库结构。

                4. 不要影响正常请求流程。

                `

                4. 构建与启动失败模板

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

                `markdown

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

                我执行的动作

                【例如：运行 npm run build】

                完整错误输出

                【粘贴完整错误】

                最近做过的改动

                【例如：刚修改了首页组件 / 刚升级依赖】

                要求

                1. 请先阅读错误输出，提取关键错误。

                  2. 2. 判断错误来自代码、依赖、配置、环境还是历史问题。

                  3. 先分析，不要立刻修改。

                  4. 修复后请重新运行同一个失败命令。

                  `

                  5. 线上/生产紧急 Bug 模板

                  线上问题更要谨慎。

                  `markdown

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

                  影响范围

                  • 影响页面/接口：
                  • 影响用户：
                  • 是否持续发生：

                  现象

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

                  要求

                  1. 先只读分析，不要修改文件。

                    2. 2. 先判断可能原因和风险等级。

                    3. 请列出需要确认的信息。

                    4. 请给出最小止血方案和长期修复方案。

                    5. 不要改数据库，不要删除数据，不要执行危险命令。

                    `

                    特殊技巧：信息不全时先补清单

                    如果你手里只有一句“页面报错了”，先让 Codex 帮你补清单：

                    `

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

                    请先不要修改代码。

                    请帮我列一个排查清单，告诉我需要补充哪些信息（按优先级列出）。

                    ``

                    总结

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

                    1. 写清 Bug 现象与期望结果。

                      2. 2. 提供复现步骤。

                      3. 要求 Codex 先定位原因再修改。

                      4. 要求最小修复。

                      5. 要求汇报验证结果和风险。