企业官网建设流程全解析

摘要：一句“帮我修复这个 Bug”，很容易换来一次范围失控的修改。本文给出一套证据优先的 Codex 修复流程：先固定复现，再定位最早出错的位置，用最小补丁解决根因，补回归测试，最后按证据验收。文末附一份可以直接复制的SKILL.md，以及经过校验的增强版fix-bug-safelySkill。

关键词：Codex、Agent Skills、SKILL.md、Bug 修复、回归测试、AI 编程、代码调试

“帮我修复这个 Bug。”

这句话交给 Codex，运气好的时候，它很快就能找到问题；运气不好的时候，一次修复会悄悄变成一次小型重构：改了原来的逻辑，又顺手调整类型、整理目录、替换写法，最后 diff 看起来比 Bug 本身还复杂。

更麻烦的是，代码能跑并不等于问题真的解决了。

• 原始问题没有稳定复现，补丁只是根据报错猜的；
• 错误不再出现，但异常被吞掉了，数据仍然是错的；
• 为了让测试通过，断言被改成了当前错误行为；
• 只运行了新增测试，没有重跑最初的复现步骤；
• 修改范围扩大以后，已经很难判断究竟是哪一行起了作用。

这里真正缺少的不是“更长的提示词”，而是一条固定的修复证据链。

一个 Bug 能否关闭，不应该看 Codex 改了多少代码，而要看四件事：问题能否复现、根因是否有证据、补丁是否足够小、原始场景是否重新通过。

所以这次我没有只整理一段提示词，而是把完整流程做成了一份可以实际使用的 Codex Skill：fix-bug-safely。

一套可靠的 Bug 修复，需要留下哪些证据？

这套流程可以压缩成七步：

1. 把模糊描述变成可检查的 Bug 约定；
2. 保存修改前的仓库状态；
3. 在动代码前复现问题；
4. 找到最早出现错误的状态，而不是只处理最终报错；
5. 先定义最小补丁，再开始修改；
6. 增加能覆盖原始问题的回归测试；
7. 从小到大运行检查，并重新执行最初的复现步骤。

它们并不复杂，但顺序不能随意交换。尤其是“复现”和“定位”必须发生在修改之前，否则后面很容易陷入一种尴尬：代码已经变了，却说不清原来的问题到底是什么。

第一步：先把 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 最容易省略、也最不能省略的一步，就是在修改前亲自看到失败。

理想证据可以是：

• 一个稳定失败的现有测试；
• 一条最小命令及其输出；
• 一个固定输入对应的错误结果；
• 一段能说明错误状态从哪里开始出现的调用轨迹；
• 可以重复操作的页面路径和网络请求。

复现成功后，要保留准确的命令、输入和失败输出。后面补丁完成，再执行同一条路径，前后结果才有可比性。

如果无法复现，不要立即猜一个“看起来可能”的修复。先判断它属于哪一类：

“无法复现”不是失败；没有复现却假装已经修好，才是。

第四步：找到最早出错的位置，不要只修最终报错

页面显示错误，根因不一定在页面；接口返回空值，根因也不一定在接口层。

真正要找的是：数据或控制流第一次偏离预期的地方。

可以沿着失败路径向前追：

1. 用户操作或调用入口是什么；
2. 输入在哪一层被转换、校验或丢失；
3. 状态第一次变错发生在哪里；
4. 后面的代码只是暴露了错误，还是进一步放大了错误；
5. 哪个最小实验能够验证这个判断。

例如“保存成功但刷新后丢失”，最终表现发生在 UI，根因可能是：

• 请求根本没有发送；
• 请求字段在序列化时丢失；
• 服务端只更新了内存，没有持久化；
• 保存成功提示没有以真实响应为准；
• 读取接口使用了另一份缓存。

没有确认是哪一种之前，重写前端状态管理只会扩大变量。

第五步：修改前，先说清什么是“最小补丁”

根因确认后，先列出：

• 为什么这是根因；
• 需要修改哪些文件；
• 哪些现有行为必须保持不变；
• 用什么回归测试证明修复；
• 哪些看起来可以顺手优化、但明确不属于本次范围。

这一步能挡住很多无关修改。

在开始修改前，请先给出最小补丁说明： - 已确认的根因及证据； - 计划修改的文件和原因； - 明确不修改的内容； - 准备增加或调整的回归测试； - 修复后需要重新执行的原始复现步骤。 不要顺手重构、升级依赖、重命名或统一格式。 如果必须扩大范围，先说明为什么当前补丁无法正确解决根因。

“最小”不是代码行数越少越好，而是每处修改都能由根因和验证目标解释。

第六步：回归测试要证明原来的 Bug，而不是证明新实现

一条有价值的回归测试，应该满足两个条件：

1. 没有补丁时，它能暴露原始问题；
2. 应用补丁后，它能验证外部行为恢复正确。

不要把测试完全绑定到刚写的私有函数或实现细节，否则以后代码一重构，测试可能失效，却没有真正保护用户行为。

测试层级可以这样选：

• 纯逻辑错误，优先单元测试；
• 涉及序列化、存储、框架生命周期或多个模块，使用集成测试；
• 只有通过真实用户路径才能暴露，才考虑端到端测试；
• 项目已经存在合适测试层时，不要为了一个修复引入一套新框架。

如果暂时无法自动化，也要给出准确的手工验证步骤，并明确说明缺失的覆盖，而不是用“已验证”带过。

第七步：验证顺序应该从窄到宽

修复完成后，不需要一上来就跑整个仓库最慢的流水线。更合适的顺序是：

1. 新增的回归测试；
2. 相关包或模块测试；
3. 受影响的类型检查、Lint 或静态检查；
4. 最初的复现步骤；
5. 与改动规模相称的更广检查。

最后还要重新检查 diff：

• 有没有无关格式化；
• 有没有遗留调试输出；
• 有没有误改生成文件；
• 有没有把密钥、日志或用户数据带进去；
• 回归测试保护的是原始行为，还是当前实现细节。

最终报告至少应该包含：结果状态、复现证据、确认的根因、修改文件、实际运行的检查以及仍未验证的风险。

为什么这里适合用 Skill，而不只是一段 Prompt？

这套流程当然可以复制到一次 Prompt 里，但它有几个很明显的 Skill 特征：

• 会在不同项目和不同 Bug 中反复使用；
• 步骤顺序相对稳定；
• 包含明确的停止条件和安全边界；
• 需要固定的报告模板；
• 可以附带只读脚本与分诊参考表；
• 触发条件可以被清楚描述。

AGENTS.md仍然有作用。项目专属的测试命令、目录边界、兼容性约定应该继续留在那里；fix-bug-safely只负责通用的修复流程。这样换到另一个仓库时，Skill 不会把旧项目的规则一起带过去。

OpenAI 当前文档对 Skill 的定位也是“可复用工作流”：SKILL.md提供必需的元数据和步骤，脚本、参考资料与资产按需加载。Codex 可以根据description自动选择 Skill，也可以由用户显式调用。Build skills

fix-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 种远程方案

项目地址：GitHub｜lincotalk/linco-bridge

如果你试用了这份 Skill，欢迎在评论区说说它在哪类 Bug 上最有帮助，或者还有哪个修复环节最容易失控。我们也会继续根据真实使用反馈调整这套流程。

Codex 实战系列

• 第一次让 Codex 接手陌生项目，我不会先让它写代码：7 步完成项目接管
• AGENTS.md 到底怎么写？给 Codex 一份真正有用的项目说明书
• Codex 改完代码，怎么判断能不能提交？一套可直接复制的验收流程
• Codex 改完代码，文档还要自己补？从 Git Diff 生成 CHANGELOG 和发布说明
• Codex 每次都要重新教？Prompt、AGENTS.md、Skills、MCP 到底怎么选

参考资料

• OpenAI：Build skills
• OpenAI：Customization
• OpenAI：Custom instructions with AGENTS.md
• OpenAI：Prompting Codex