摘要一句“帮我修复这个 Bug”很容易换来一次范围失控的修改。本文给出一套证据优先的 Codex 修复流程先固定复现再定位最早出错的位置用最小补丁解决根因补回归测试最后按证据验收。文末附一份可以直接复制的SKILL.md以及经过校验的增强版fix-bug-safelySkill。关键词Codex、Agent Skills、SKILL.md、Bug 修复、回归测试、AI 编程、代码调试“帮我修复这个 Bug。”这句话交给 Codex运气好的时候它很快就能找到问题运气不好的时候一次修复会悄悄变成一次小型重构改了原来的逻辑又顺手调整类型、整理目录、替换写法最后 diff 看起来比 Bug 本身还复杂。更麻烦的是代码能跑并不等于问题真的解决了。原始问题没有稳定复现补丁只是根据报错猜的错误不再出现但异常被吞掉了数据仍然是错的为了让测试通过断言被改成了当前错误行为只运行了新增测试没有重跑最初的复现步骤修改范围扩大以后已经很难判断究竟是哪一行起了作用。这里真正缺少的不是“更长的提示词”而是一条固定的修复证据链。一个 Bug 能否关闭不应该看 Codex 改了多少代码而要看四件事问题能否复现、根因是否有证据、补丁是否足够小、原始场景是否重新通过。所以这次我没有只整理一段提示词而是把完整流程做成了一份可以实际使用的 Codex Skillfix-bug-safely。一套可靠的 Bug 修复需要留下哪些证据这套流程可以压缩成七步把模糊描述变成可检查的 Bug 约定保存修改前的仓库状态在动代码前复现问题找到最早出现错误的状态而不是只处理最终报错先定义最小补丁再开始修改增加能覆盖原始问题的回归测试从小到大运行检查并重新执行最初的复现步骤。它们并不复杂但顺序不能随意交换。尤其是“复现”和“定位”必须发生在修改之前否则后面很容易陷入一种尴尬代码已经变了却说不清原来的问题到底是什么。第一步先把 Bug 描述变成一份可检查的约定“保存失败”“页面卡住”“偶尔报错”都只是现象还不足以支持修复。开始前至少要确认信息要回答的问题实际行为现在具体发生了什么错误信息或错误结果是什么预期行为正确结果应该是什么依据是产品约定、测试还是已有行为最小复现什么命令、输入或操作可以触发是否每次都出现影响环境哪个版本、系统、浏览器、配置或运行模式受到影响修改边界哪些文件或接口可以改哪些行为必须保持不变可以先这样告诉 Codex请先不要修改代码。 实际行为设置页点击保存后显示成功但刷新页面后配置恢复旧值。 预期行为保存成功后刷新页面仍然显示新配置。 复现步骤写出可以执行的步骤 影响环境版本、浏览器或运行方式 请先整理 1. 你能否稳定复现 2. 最小失败输入或操作 3. 目前已有的证据 4. 还缺哪些会影响判断的信息。 这一轮只调查不要修改文件。如果复现信息已经足够Codex 应该继续调查而不是把所有问题都抛回来。只有缺失的信息会真正改变修复方向或安全边界时才有必要停下来追问。第二步修改前先保存一个只读基线Bug 修复经常发生在一个已经有改动的工作区里。没有先看 Git 状态Codex 很可能把用户原来的修改、格式化变化和本次补丁混在一起。最低限度要检查gitstatus--shortgitdiff--statgitdiffgitlog-5--oneline还要从项目文件里确认真实的包管理器、测试框架和验证命令不能看到 JavaScript 项目就默认运行npm test。这次配套的增强版 Skill 包含一个只读脚本。在 Skill 目录中可以这样运行python scripts/collect_debug_context.py--cwd/path/to/repository它会收集当前 Git 根目录与分支已有的工作区变化暂存和未暂存的 diff 统计最近几次提交常见项目标记文件package.json中可能用于测试、构建和检查的脚本。脚本不会读取环境变量、.env内容、源码正文或密钥。它只负责建立修改前的边界不负责自动执行测试和修复。第三步复现失败再谈根因修 Bug 最容易省略、也最不能省略的一步就是在修改前亲自看到失败。理想证据可以是一个稳定失败的现有测试一条最小命令及其输出一个固定输入对应的错误结果一段能说明错误状态从哪里开始出现的调用轨迹可以重复操作的页面路径和网络请求。复现成功后要保留准确的命令、输入和失败输出。后面补丁完成再执行同一条路径前后结果才有可比性。如果无法复现不要立即猜一个“看起来可能”的修复。先判断它属于哪一类情况更合适的下一步稳定出现缩小到最小失败用例开始追踪最早的错误状态偶发问题记录出现频率、并发顺序、时间、随机种子和状态残留只在特定环境出现比较运行时、系统、浏览器、版本和配置差异只对特定数据出现缩减并脱敏输入保留触发问题的必要结构完全无法复现报告已经尝试的步骤说明下一步最小需要什么日志或环境“无法复现”不是失败没有复现却假装已经修好才是。第四步找到最早出错的位置不要只修最终报错页面显示错误根因不一定在页面接口返回空值根因也不一定在接口层。真正要找的是数据或控制流第一次偏离预期的地方。可以沿着失败路径向前追用户操作或调用入口是什么输入在哪一层被转换、校验或丢失状态第一次变错发生在哪里后面的代码只是暴露了错误还是进一步放大了错误哪个最小实验能够验证这个判断。例如“保存成功但刷新后丢失”最终表现发生在 UI根因可能是请求根本没有发送请求字段在序列化时丢失服务端只更新了内存没有持久化保存成功提示没有以真实响应为准读取接口使用了另一份缓存。没有确认是哪一种之前重写前端状态管理只会扩大变量。第五步修改前先说清什么是“最小补丁”根因确认后先列出为什么这是根因需要修改哪些文件哪些现有行为必须保持不变用什么回归测试证明修复哪些看起来可以顺手优化、但明确不属于本次范围。这一步能挡住很多无关修改。在开始修改前请先给出最小补丁说明 - 已确认的根因及证据 - 计划修改的文件和原因 - 明确不修改的内容 - 准备增加或调整的回归测试 - 修复后需要重新执行的原始复现步骤。 不要顺手重构、升级依赖、重命名或统一格式。 如果必须扩大范围先说明为什么当前补丁无法正确解决根因。“最小”不是代码行数越少越好而是每处修改都能由根因和验证目标解释。第六步回归测试要证明原来的 Bug而不是证明新实现一条有价值的回归测试应该满足两个条件没有补丁时它能暴露原始问题应用补丁后它能验证外部行为恢复正确。不要把测试完全绑定到刚写的私有函数或实现细节否则以后代码一重构测试可能失效却没有真正保护用户行为。测试层级可以这样选纯逻辑错误优先单元测试涉及序列化、存储、框架生命周期或多个模块使用集成测试只有通过真实用户路径才能暴露才考虑端到端测试项目已经存在合适测试层时不要为了一个修复引入一套新框架。如果暂时无法自动化也要给出准确的手工验证步骤并明确说明缺失的覆盖而不是用“已验证”带过。第七步验证顺序应该从窄到宽修复完成后不需要一上来就跑整个仓库最慢的流水线。更合适的顺序是新增的回归测试相关包或模块测试受影响的类型检查、Lint 或静态检查最初的复现步骤与改动规模相称的更广检查。最后还要重新检查 diff有没有无关格式化有没有遗留调试输出有没有误改生成文件有没有把密钥、日志或用户数据带进去回归测试保护的是原始行为还是当前实现细节。最终报告至少应该包含结果状态、复现证据、确认的根因、修改文件、实际运行的检查以及仍未验证的风险。为什么这里适合用 Skill而不只是一段 Prompt这套流程当然可以复制到一次 Prompt 里但它有几个很明显的 Skill 特征会在不同项目和不同 Bug 中反复使用步骤顺序相对稳定包含明确的停止条件和安全边界需要固定的报告模板可以附带只读脚本与分诊参考表触发条件可以被清楚描述。AGENTS.md仍然有作用。项目专属的测试命令、目录边界、兼容性约定应该继续留在那里fix-bug-safely只负责通用的修复流程。这样换到另一个仓库时Skill 不会把旧项目的规则一起带过去。OpenAI 当前文档对 Skill 的定位也是“可复用工作流”SKILL.md提供必需的元数据和步骤脚本、参考资料与资产按需加载。Codex 可以根据description自动选择 Skill也可以由用户显式调用。Build skillsfix-bug-safely完整版包含什么增强版 Skill 的目录如下fix-bug-safely/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── scripts/ │ └── collect_debug_context.py ├── references/ │ └── triage-playbook.md └── assets/ └── bug-fix-report.md各文件并不是为了显得完整SKILL.md保存主流程、停止条件与验收要求agents/openai.yaml提供显示名称、简短介绍和默认调用语句collect_debug_context.py只读收集修改前的 Git 和项目上下文triage-playbook.md复现不稳定或无法复现时再读取bug-fix-report.md最终交付时使用的报告模板。这份增强版已经使用官方quick_validate.py完成结构校验采集脚本也在 Git 仓库和普通目录中分别运行过。它不会自动提交、推送、发版或操作生产环境。不想复制多个文件先用这个单文件版下面这份可以直接保存为fix-bug-safely/SKILL.md。它没有附加脚本和模板但已经包含完整的核心流程。--- name: fix-bug-safely description: Diagnose and fix reproducible software bugs with evidence-first triage, minimal scoped patches, regression tests, and explicit verification. Use when Codex is asked to reproduce, investigate, debug, fix, or add a regression test for incorrect behavior in an existing codebase. Do not use for feature development, broad refactors, or speculative performance tuning. --- # Fix Bug Safely Fix the observed behavior with the smallest justified change. Establish evidence before editing and preserve unrelated work. ## Workflow 1. Read the applicable AGENTS.md files and repository documentation. 2. Inspect the working tree and preserve unrelated user changes. 3. Record the observed behavior, expected behavior, smallest reproduction, affected environment, allowed scope, and non-goals. 4. Run the smallest reliable reproduction before editing. Save the exact command, input, and failure output. 5. If the bug cannot be reproduced, do not guess a patch. Report what was tried and identify the smallest missing observation needed next. 6. Trace the failing path to the earliest incorrect state transition. Confirm the root cause with code, logs, a debugger, or a focused experiment. 7. Before editing, state the confirmed cause, files to change, behavior to preserve, and regression test to add. 8. Avoid unrelated refactors, formatting churn, dependency upgrades, renames, and cleanup. 9. Add a regression test that fails for the original bug before the fix and passes after it. Use the narrowest existing test layer that protects user-visible behavior. 10. Implement the smallest patch that repairs the confirmed causal path. 11. Run the focused test, nearby tests, affected static checks, and the original reproduction. Record exact commands and results. 12. Inspect the final diff for unrelated edits, debug output, generated files, secrets, and accidental behavior changes. ## Stop and ask Pause before changing public APIs, schemas, migrations, persisted data, production dependencies, external systems, Git history, or production environments. Pause before expanding the fix into a broad refactor. ## Final report - Status: fixed / partially fixed / not reproduced / blocked - Reproduction and baseline evidence - Confirmed root cause and evidence - Files changed and why this is the minimum patch - Tests and checks actually run - Checks not run and remaining risks怎么安装和调用如果希望只在一个项目里使用把整个目录放到项目根目录/.agents/skills/fix-bug-safely/如果希望在个人的不同项目中都能使用可以放到~/.agents/skills/fix-bug-safely/Codex 通常会自动发现 Skill如果没有出现重新启动当前 Codex 会话。显式调用时可以这样写$fix-bug-safely 设置页点击保存后显示成功但刷新后配置恢复旧值。 请先复现并报告证据再定位根因只做最小修复补回归测试。 不要改 API 结构也不要提交或推送。也可以直接描述“复现并修复这个 Bug”“调查失败原因并补回归测试”。当任务与description匹配时Codex 可以自动选择这项 Skill。这个 Skill 刻意不处理什么它不会把所有代码问题都包装成 Bug 修复。下面这些任务应该单独提出新功能开发没有明确错误行为的架构改造纯粹的代码风格整理没有基准数据的性能“优化”需要写入生产环境的线上事故处置大规模依赖升级或公共 API 迁移。把触发边界写清楚实际使用时反而更可靠。一个什么都想处理的 Skill最后往往只能提供一套很宽泛的步骤。修复和测试还没跑完人要离开电脑怎么办这套 Skill 能让 Codex 的修复过程更可控但它不会缩短所有等待时间。构建、回归测试、偶发问题复现和多轮排查都可能持续很久。人离开电脑以后如果需要查看运行进度、补充新的复现信息或者处理权限确认本地 Agent 的工作仍然容易中断。这也是我们开源Linco Bridge的使用场景之一。Codex、Claude Code、Hermes 等 Agent 继续运行在个人电脑上代码和开发环境仍留在本机Linco Bridge 把会话进度、流式输出、工具调用和权限请求延伸到手机端。你可以让fix-bug-safely在电脑上按证据链排查再通过手机继续查看测试结果和补充要求。想继续了解 Linco Bridge可以从下面几篇开始Linco Bridge 开源在手机端续接 Codex、Claude Code、Hermes 等本地 AI Agent手机端续接 Codex 实战从安装 linco-connect 到跑通第一个跨端会话cc-connect 已经很强了我们为什么还要做 Linco Bridge离开电脑后怎么继续跟进 Codex 任务国内用户的 5 种远程方案项目地址GitHublincotalk/linco-bridge如果你试用了这份 Skill欢迎在评论区说说它在哪类 Bug 上最有帮助或者还有哪个修复环节最容易失控。我们也会继续根据真实使用反馈调整这套流程。Codex 实战系列第一次让 Codex 接手陌生项目我不会先让它写代码7 步完成项目接管AGENTS.md 到底怎么写给 Codex 一份真正有用的项目说明书Codex 改完代码怎么判断能不能提交一套可直接复制的验收流程Codex 改完代码文档还要自己补从 Git Diff 生成 CHANGELOG 和发布说明Codex 每次都要重新教Prompt、AGENTS.md、Skills、MCP 到底怎么选参考资料OpenAIBuild skillsOpenAICustomizationOpenAICustom instructions with AGENTS.mdOpenAIPrompting Codex