用 Codex 排查报错：从现象到最小复现

先看一个现场

报错最可怕的不是红字，而是不知道从哪里下手

很多人第一次让 Codex 排查报错，都是在一种很急的状态下开始的：页面打不开，客户说提交不了表单，构建突然失败，老板问“刚才不是还好好的吗”。屏幕上有一堆红字，群里有几条截图，开发同事还在路上，产品经理也说不清到底哪一步开始坏。于是最自然的动作就是把报错整段贴给 AI，然后说：“快帮我修一下。”

这句话很像在医院门口只喊“我不舒服，快开药”。AI 也许能猜中，也许能从错误文字里找到明显问题，但真实项目里的报错常常不是一个点。它可能是一个字段缺失、一个路径写错、一个按钮状态没处理、一个线上环境变量没配、一个新内容打破了旧规则，甚至是用户操作路径和开发预想不一样。只看最后一行红字，很容易把症状当原因。

这篇教程训练的是一种能力：用 Codex 把报错从混乱现场整理成可验证的排查流程。读完后，你应该能做出一份“报错排查单”：里面有现象、证据、复现步骤、原因假设、最小修复、回归验证和老板能看懂的结论。无论你是老板、产品经理、网站维护者，还是开发者，这套语言都能让排错从“靠经验猜”变成“按证据推进”。

错误做法

新手排错为什么越修越乱

最常见的错误做法，是只贴报错，不贴触发路径。比如你把终端里的一段错误给 Codex，却没有告诉它这是打开首页时报的、构建时报的、提交表单时报的，还是切换筛选条件时报的。AI 看到的只是结果，不知道问题从哪里开始，自然容易把注意力放到最后一行文字上。

第二种错误，是把“最近改过的地方”直接当成根因。最近改动当然重要，但它只是线索，不是判决。一个页面今天坏了，可能是昨天的代码问题被今天的新数据触发，也可能是线上配置变了，还可能是某个依赖在构建环境里表现不同。如果你让 Codex 只盯着最近修改的文件，它可能会错过真正触发问题的输入条件。

第三种错误，是一边修一边扩大范围。原本只是一个页面报错，修着修着开始重构组件、改样式、换数据结构、顺手清理旧代码。这样就算问题暂时消失，你也很难知道到底是哪一处修好的；如果引入新问题，也很难回退。调试最怕的不是慢，而是每一步都无法解释。

• 只贴红字：缺少触发场景。
• 只猜原因：缺少证据链。
• 只看最近改动：忽略旧问题被新数据触发。
• 边查边大改：无法判断哪一步真正有效。
• 修完不复测：不知道相邻功能有没有被影响。

本质解释

调试的本质：把“坏了”翻译成一条可验证的因果链

用大白话说，调试就是回答六个问题：你看到了什么？它在什么条件下出现？有什么证据？最小怎样能让它再次出现？你猜原因是什么？你怎么证明修好了？这六个问题，比任何高深术语都重要。

报错本身只是一个信号。真正要找的是因果链：某个输入、状态、配置或代码路径，触发了某个异常，最后表现成用户看到的问题。比如“页面空白”只是现象；“某篇文章正文导出名和映射表不一致，详情页加载不到对应内容”才是更接近根因的描述。前者让人焦虑，后者让人知道该检查哪里。

所以，调试不是和红字搏斗，而是把混乱信息整理成可验证的工作单。Codex 很适合帮你做这件事：它能读文件、对比最近改动、解释日志、提出假设、运行检查、整理验证结果。但你要用正确的顺序指挥它，否则它会被你的焦虑带着跑。

1. 现象：用户或系统实际看到了什么。
2. 证据：哪些日志、路径、输入、文件能支持判断。
3. 复现：怎样稳定地让问题再次出现。
4. 假设：最可能的原因是什么，为什么。
5. 修复：用最小改动处理根因。
6. 回归验证：证明原问题消失，相关功能没坏。

角色分工

AI 和人的分工：Codex 负责找线索，人负责定边界和验收

排错时，Codex 最适合做三类工作。第一，整理材料：把报错、日志、文件、最近改动、用户路径整理成证据表。第二，缩小范围：判断问题更像构建、运行时、数据、接口、样式还是配置。第三，执行验证：按照你的确认去读相关文件、跑检查、做最小修复、汇报结果。

人必须负责的也有三类。第一，判断业务影响：这个问题影响多少用户，是否要先止血，是否需要通知客户。第二，确认修复边界：这次只修根因，还是顺带处理历史技术债。第三，最终验收：修复是否符合业务目标，是否能上线，是否需要回滚或补公告。这些不是 AI 可以替负责人拍板的事。

把分工说清楚，反而能让 Codex 更快。你不用让它猜老板真正关心什么，也不用让它在没有授权时扩大修改。你可以明确告诉它：“先排查，不修改”；“只允许改这个文件”；“线上正在受影响，先给止血方案”；“修复后按老板视角汇报”。越像带一个靠谱同事，结果越稳定。

工作产物

这篇教程最终要交付一张“报错排查单”

很多团队排错靠聊天记录推进：A 发一张截图，B 贴一段日志，C 说可能是缓存，D 说先重启试试。半小时后，群里信息很多，但没有人能说清楚：现在确认了什么，排除了什么，下一步谁负责。报错排查单就是为了解决这个问题。

一张合格的排查单，不一定很长，但必须让别人接手时看得懂。它要写清现象、影响范围、发生环境、复现步骤、关键证据、原因假设、已经做过的验证、最终修复和回归结果。如果线上有用户受影响，还要加一块：止血动作、对外口径、回滚方案和后续预防。

Codex 可以帮你把零散信息整理成这张单。你可以把它当作排错过程中的工作台：每新增一条证据，就让 Codex 更新一次；每验证一个假设，就标记成立或不成立；修复完成后，再让它生成老板能看懂的汇报。这样排错不再是一串临时动作，而是一条可以复盘的路线。

• 现象：用户看到什么，系统报什么。
• 影响：谁受影响，是否线上紧急。
• 证据：日志、路径、输入、最近改动、文件位置。
• 复现：最短触发步骤和复现成功标准。
• 假设：可能原因、排序和验证动作。
• 修复：最小改动范围和不做事项。
• 验证：原路径、相邻路径、构建或测试结果。
• 复盘：以后如何预防同类问题。

第一步

先描述现象：把“坏了”说成别人能复查的话

“页面坏了”不是一个可调试的描述。“用户在手机 Safari 打开文章详情页，点击目录后页面没有滚动；桌面 Chrome 正常；最近改过目录组件样式”才是可调试的描述。差别在于，后者给了路径、动作、环境、对比和最近改动。

现象描述要尽量贴近用户视角。用户看不到你的代码结构，他只知道点了按钮没反应、保存后数据没变、页面一直转圈、支付后没有跳转、搜索结果少了一半。你先把用户语言记录下来，再让 Codex 翻译成技术排查方向。不要一开始就说“应该是状态管理问题”，这会过早限制 AI 的视野。

描述现象时，还要写清期望结果。很多报错不是系统崩了，而是结果不符合业务预期。比如页面能打开，但推荐文章顺序错了；表单能提交，但后台没有收到；构建能通过，但搜索摘要还是旧的。没有期望结果，Codex 只能判断“有没有报错”，不能判断“有没有做对”。

请帮我用调试工作流排查这个报错。先不要修改任何文件，先整理现象和证据。

业务背景：
[这个页面/功能是给谁用的，正常应该完成什么任务]

我看到的现象：
[页面表现、报错文字、截图描述、用户反馈、发生时间]

触发路径：
[从打开哪个页面开始，点了什么，输入了什么，什么时候出错]

期望结果：
[正常情况下应该看到什么，或者系统应该完成什么动作]

实际结果：
[实际看到什么，是否空白、卡住、跳转错误、数据错、构建失败]

最近改动：
[最近改过哪些文件、上线了什么内容、换了什么配置、改了什么数据]

请先输出：
1. 这是哪类问题：构建、运行时、样式、数据、配置、接口、权限，还是还不能判断。
2. 已有证据有哪些，分别来自哪里。
3. 还缺哪些证据，需要我补充什么。
4. 最可能的 3 个原因，按概率和风险排序。
5. 下一步最小复现怎么做。

要求：没有证据的地方写“不确定”；不要凭经验直接改代码。

第二步

再收集证据：把事实、推断和猜测分开

证据是调试的地基。浏览器控制台、终端输出、构建日志、服务器日志、网络请求状态码、用户操作录屏、最近提交记录、数据文件变化，都可以是证据。证据越清楚，Codex 越不容易凭经验乱猜。

这里最重要的动作，是区分事实和推断。事实是“提交接口返回 500”“构建日志指向某个文件第几行”“只有缺少封面图的文章会失败”。推断是“可能是接口参数不完整”“可能是某个字段没有默认值”。猜测是“应该是缓存吧”。三者都可以记录，但不能混在一起。

你可以让 Codex 把材料整理成证据表。表格不是为了好看，而是为了让每条线索都有来源、有意义、有下一步。比如一条 404 证据，只能说明某个资源没找到，不一定说明路由坏了；一条 500 证据，说明服务器处理失败，但还要继续看请求参数和服务器日志。好的调试会克制地解释证据，不会让一条线索承担它证明不了的结论。

• 事实：已经发生、可以复查的内容。
• 推断：基于事实提出的可能解释。
• 猜测：还没有证据支持的直觉。
• 待确认：需要继续查看日志、文件或用户路径的空白点。

请把当前报错整理成一张证据表。

已知材料：
[粘贴报错、日志、终端输出、页面路径、用户操作、最近改动]

请按下面字段输出：
1. 现象：用户或维护者实际看到什么。
2. 证据来源：浏览器、终端、构建日志、服务器日志、用户反馈、代码 diff、数据文件。
3. 证据内容：关键错误文字、状态码、文件路径、时间点、输入值。
4. 能说明什么：这条证据支持哪种判断。
5. 不能说明什么：不要过度推断。
6. 下一步验证：为了确认这条线索，需要做什么。

请把事实、推断和待确认问题分开写。

第三步

还原触发路径：让 Codex 知道错误是怎么被叫出来的

很多报错看起来发生在一个文件里，真正的触发点却在前面几步。用户先登录，选择一个筛选条件，上传一个大文件，点击保存，再跳转到详情页。最后报错也许指向详情页，但根因可能是上传时少写了字段。触发路径就是把这条路补完整。

你可以要求 Codex 用“从用户动作到代码链路”的方式解释。用户点击了哪个入口，页面调用了哪个组件，组件读取了哪些数据，数据来自本地文件还是接口，接口需要什么参数，最终哪里报错。非技术读者不需要背这些名词，只要理解一句话：报错不是凭空出现的，它是被某条路径触发出来的。

还原路径时，尤其要注意对比。哪个路径正常，哪个路径异常？桌面正常、移动端异常？旧文章正常、新文章异常？未登录正常、登录后异常？中文输入正常、带特殊符号异常？这些对比常常比红字本身更有价值，因为它们能帮 Codex 排除大片无关区域。

第四步

做最小复现：用最少条件稳定重现同一个问题

最小复现是调试里的核心动作。它的意思是：不要带着整个项目、所有页面、所有用户路径一起排查，而是找出能稳定触发同一个问题的最小条件。比如一个构建失败，最小复现可能是某一篇文章缺少字段；一个按钮没反应，最小复现可能是某个组件在移动端宽度下被遮住；一个接口失败，最小复现可能是一组特定参数。

最小复现解决的是“到底是不是这个原因”的问题。如果问题只有在很多复杂条件叠加时出现，你就很难判断哪一项关键。把条件一层层拿掉，直到只剩最必要的输入，就像把一间很吵的会议室清空，只留下真正说话的人。

让 Codex 做最小复现时，要让它先给方案，再动手。它应该说明哪些条件必须保留，哪些可以暂时排除，复现成功标准是什么。如果复现失败，也不是白费，它说明之前的假设可能不完整，需要回到证据表继续补线索。

1. 保留能触发问题的关键输入。
2. 移除无关页面、无关样式、无关数据。
3. 记录每一次缩小范围后的结果。
4. 找到最短触发步骤。
5. 用同一套步骤至少复查一次。

请帮我把这个问题缩小成最小复现。

当前问题：
[描述报错或异常表现]

相关材料：
[粘贴页面路径、组件、数据、日志、最近改动]

请输出：
1. 复现前提：需要什么环境、账号、数据、浏览器或命令。
2. 复现步骤：从第 1 步到出错，每一步只写一个动作。
3. 必须保留的条件：哪些输入、字段、状态、配置不能删。
4. 可以暂时排除的条件：哪些页面、样式、数据、流程可能无关。
5. 最小复现版本：用最少页面、最少组件、最少数据复现问题。
6. 复现成功标准：看到什么才算复现了同一个问题。
7. 复现失败时怎么调整：下一步扩大或缩小哪些范围。

先给方案，不要直接修复。

第五步

提出假设：不要让第一个解释直接变成结论

调试里的假设，就是“我怀疑问题可能出在这里”。假设不是结论，它需要被验证。一个成熟的 Codex 排查，不应该只给一个原因，而应该给出两到四个可能原因，并说明每个原因为什么可能成立、需要什么证据确认、验证成本高不高、如果成立影响范围多大。

假设排序很重要。你通常应该优先验证“概率高、成本低、风险小”的线索。比如日志已经指向某个缺失字段，那就先检查数据；如果只是隐约怀疑架构问题，就不要一上来重构。很多调试事故不是因为人不会修，而是因为跳过低成本验证，直接做了高风险修改。

Codex 在这里的优势，是可以帮你同时整理多条线索。但你要要求它克制：每个假设必须绑定证据，每个验证动作必须可执行，每个不确定项必须写出来。这样即使第一个假设被否定，团队也知道下一步去哪，而不是重新陷入“是不是缓存”的循环。

请基于现象、证据和最小复现，制定调试假设和最小修复计划。

现象：
[粘贴现象描述]

证据：
[粘贴证据表或关键日志]

最小复现：
[粘贴复现步骤]

请输出：
1. 假设列表：每个假设说明为什么可能成立。
2. 排序依据：按概率、影响范围、验证成本排序。
3. 每个假设的验证动作：先看文件、跑命令、改临时输入，还是加日志。
4. 推荐的最小修复：只改哪些文件，为什么这些是最小范围。
5. 明确不做什么：哪些重构、顺手优化、风格调整先不做。
6. 修复后验证清单：复现路径、相邻路径、构建/测试、线上风险。
7. 如果修复失败，下一步回到哪个假设。

在我确认前，不要扩大修改范围。

第六步

做最小修复：只处理根因，不顺手装修整栋楼

最小修复不是将就，而是专业。它的意思是：确认根因后，用能解决问题的最小改动处理它，避免把排错任务扩大成重构任务。比如问题是某个字段缺默认值，就先补默认值和必要校验；问题是某个导出名不一致，就先修正导出和引用；问题是线上环境变量缺失，就先补配置或给出缺失提示。

为什么不建议顺手改很多？因为调试需要可解释。你一次改十个地方，即使问题消失，也不知道真正有效的是哪一处。更麻烦的是，如果上线后出现新问题，你很难判断是修复引入的，还是顺手优化引入的。最小修复让每一步都能被复查，也让回退更简单。

当然，最小修复不等于忽略长期问题。如果你在排错时发现代码结构确实脆弱，可以把它写进“后续预防”或“技术债清单”，但不要混进紧急修复。先止住当前问题，再安排更稳的改进，这是对团队负责。

• 只改和根因直接相关的文件。
• 不顺手改样式、命名、结构和无关逻辑。
• 必要时加小范围保护：默认值、空状态、错误提示、输入校验。
• 把长期优化单独记录，放到后续任务。

第七步

回归验证：证明原问题消失，也证明旁边没被撞坏

回归验证是很多新手最容易省掉的一步。看到红字没了、页面能打开了，就急着说完成。但真实工作里，修复一个问题可能影响相邻路径。比如给文章封面图加默认值，旧文章好了，新文章上传逻辑会不会受影响？修了移动端按钮点击，桌面端悬停状态还正常吗？改了接口参数，后台导出还可用吗？

回归验证至少要看三层。第一，原复现路径：刚才那个最小复现步骤是否不再报错。第二，相邻路径：同一功能的正常输入、边界输入、旧数据、新数据是否还正常。第三，机器检查：构建、测试、类型检查、静态检查或项目已有检查是否通过。不同项目检查命令不一样，Codex 应该先读项目脚本，再说明它跑了什么。

老板和产品经理不需要看懂每一行测试输出，但要看懂验证结论。好的汇报不是“已修”，而是“原来不上传封面图会保存失败，现在可保存；上传封面图路径仍正常；案例列表和详情页可打开；构建通过；没有修改 URL、权限和数据结构”。这才叫可验收。

请用负责人能看懂的方式汇报这次报错修复和回归验证。

请按下面结构输出：
1. 问题一句话：发生了什么，影响谁。
2. 根因：真正原因是什么；证据是什么。
3. 修复范围：改了哪些文件或配置；没有改哪些地方。
4. 验证结果：原复现路径是否恢复；相关路径是否正常；构建/测试是否通过。
5. 线上风险：是否需要止血、回滚、补数据、通知用户。
6. 剩余不确定项：还有什么没有完全确认。
7. 后续预防：需要补测试、补检查清单、补监控、补团队规则吗。

要求：不要只写“已修复”，要给出可复查证据。

线上止血

线上正在出事时，先稳住用户，再谈优雅修复

如果问题已经在线上影响用户，排查顺序要多一层：先止血，再根因分析。止血的目标不是写出最漂亮的代码，而是尽快减少损失。比如隐藏有问题的入口、回滚上一版、临时关闭某个筛选条件、恢复旧配置、补一条兜底文案、切换到备用表单、暂停投放入口。这些动作要由负责人确认，因为它们影响真实用户和业务承诺。

让 Codex 参与线上止血时，提示词要很清楚：“线上受影响，请先列止血选项，不要直接改。每个选项说明恢复速度、影响范围、风险、是否可回退。”这样它会从“修代码”切换到“协助应急决策”。老板或负责人再根据业务影响选择方案。

止血之后，仍然要回到调试流程。很多团队的坏习惯是：临时绕过去以后就忘了根因。结果同类问题下次再来。正确做法是把止血和根因修复分开记录：临时动作什么时候做的，解决了什么影响，留下什么风险，最终修复什么时候完成，临时动作什么时候撤掉。

1. 判断影响范围：多少用户、哪些页面、哪些交易或线索受影响。
2. 列止血选项：回滚、隐藏入口、关闭功能、补配置、切备用流程。
3. 负责人确认：选择临时方案和对外口径。
4. 执行并验证：确认用户路径恢复或损失停止扩大。
5. 回到根因：不要把临时绕路当成最终修复。

老板验收

老板不看代码，也能验收一次报错排查

老板验收排错，不需要问“改了哪一行代码”。更有用的问题是五个：第一，问题影响谁，严重到什么程度？第二，真正原因是什么，有什么证据？第三，修复改了什么，是否只改必要范围？第四，怎么证明原问题好了，相关功能没坏？第五，下次如何预防？

如果 Codex 或开发同事只回答“已经修好了”，这个汇报不够。你要让它补齐证据。比如：“影响文章详情页的新教程；根因是正文导出名和元数据 slug 不一致；只修改了对应正文导出名；已重新打开详情页和列表页，构建通过；后续建议新增文章时检查 slug、导出名和映射关系。”这样的汇报，老板不用懂代码也能判断是否稳。

老板验收的重点，是把技术修复翻译成业务可控。线上有没有恢复？客户还会不会遇到同样问题？有没有误伤其他页面？有没有需要通知用户？有没有补检查动作？一旦这些问题能回答，排错就不是技术黑箱，而是可管理的交付。

案例一

案例一：教程站构建失败，根因不是框架，而是一篇正文导出错

一个内容团队准备上线新教程，构建时突然失败。终端里红字很多，提到了模块找不到、导入失败、某个页面生成不出来。新手第一反应可能是怀疑框架升级、依赖坏了、构建环境不稳定。产品经理把整段报错贴给 Codex，差点让它直接重装依赖。

更稳的做法是先整理证据。Codex 看到报错路径集中在某个教程 slug，最近改动也只有一篇新教程正文和一条元数据。它没有先动依赖，而是要求还原内容链路：文章元数据如何指向正文，正文导出名如何被映射，详情页如何读取 body。最小复现也很快：只要保留这篇新教程，构建就失败；移除它，构建恢复。

最终假设排序后，最可能原因是导出名不匹配。Codex 检查正文文件，发现导出的变量名和映射表期望的名字不一致。最小修复只改正文文件的导出名，不改文章元数据、不改页面生成逻辑、不改构建配置。修复后重新构建，通过；打开教程详情页、列表页和学习路径，内容都正常。

案例二

案例二：移动端按钮点不了，红字没有出现但用户就是走不下去

不是所有报错都会给你一段红字。有一次活动页上线后，桌面端报名正常，移动端用户却反馈“点不了提交”。浏览器控制台没有明显报错，接口也没有请求失败。如果只把“按钮点不了”交给 Codex，它可能会去查表单逻辑、接口权限、输入校验，排查范围很大。

这时关键是现象和对比。产品经理补充：只有手机宽度下出现，按钮看得见，但点击无反应；桌面正常；最近改过活动页顶部浮层。Codex 据此把假设分成三类：按钮 disabled 状态错误、点击事件没绑定、浮层或元素遮挡。由于移动端特有且没有接口请求，遮挡假设概率最高、验证成本最低。

最小复现是打开移动端视口，滚动到表单区域，点击按钮，观察点击是否落到按钮上。Codex 检查样式后发现，一个透明浮层在移动端高度计算错误，覆盖了按钮区域。最小修复是调整浮层在表单区域的布局边界，而不是重写表单。回归验证包括移动端点击、桌面端报名、不同屏幕宽度和浮层显示状态。

案例三

案例三：线索表单线上 500，先切备用入口再查参数

一家 B2B 公司投放落地页后，销售发现线索突然变少。运营测试表单，提交后页面提示失败。这个问题已经在线上影响获客，不能只在本地慢慢研究。负责人先让 Codex 列止血方案：暂时切换到备用表单链接、隐藏异常字段、回滚上一版落地页、或者在失败时展示人工联系方式。

老板选择了最快可控的方案：先在页面上切备用表单链接，并保留人工联系方式。止血后，Codex 回到证据表：失败请求返回 500，只在选择“公司规模”为空时出现；最近新增了一个非必填字段；后台接口实际要求该字段传入固定枚举。最小复现就是不选公司规模直接提交。

根因不是服务器整体坏了，而是前端表单和后端参数约定不一致。最小修复有两个：前端给未选择状态传默认值，或者把字段改成必填并给清晰提示；同时后端最好也增加更友好的错误返回。修复完成后，团队验证了空值、正常选择、不同浏览器、线索后台入库和备用入口撤销条件。最后复盘把“新增表单字段必须同步前后端约定和空值测试”写进上线清单。

• 线上影响业务时，先止血再深挖。
• 500 不等于服务器全坏，可能是某组参数触发。
• 表单字段新增后，必须检查必填、默认值、枚举和后台入库。
• 临时备用入口要有撤销时间，不能永久挂着不管。

案例四

案例四：老板说“数据不对”，先定义什么叫对

有些报错不是系统崩溃，而是业务结果不符合预期。比如老板打开运营看板，说“这个月线索数不对”。这类问题很容易陷入口水仗：销售说 CRM 是 120 条，运营表格是 98 条，网站后台是 105 条，没人知道以哪个为准。

Codex 在这里不能替老板定义业务口径，但可以帮团队把口径差异找出来。第一步不是查代码，而是问“正确数字应该按什么规则算”：是否按创建时间、分配时间、有效线索、去重手机号、排除测试数据、按渠道归因。只有定义了期望结果，才谈得上排错。

最小复现可以是一小段时间窗口，比如某一天的 10 条线索。Codex 对比网站后台、CRM 导出和运营表，找出差异来自哪里：有 3 条测试数据被网站后台计入，CRM 排除了；有 2 条重复手机号被运营表手动去重；还有 1 条跨天线索按不同时区归属。最终修复不是“改一个 bug”，而是统一统计口径，并把看板说明写清楚。

常见错误

排错时最容易踩的十二个坑

第一个坑，是把错误文字当成完整事实。错误文字很重要，但它只是证据之一。第二个坑，是没有复现就修。修之前都不能稳定看到问题，修之后也很难证明好了。第三个坑，是把所有问题都归因于最近改动。最近改动只是线索，还需要证据确认。

第四个坑，是让 Codex 一次性改太多。第五个坑，是遇到线上问题只顾根因，不先止血。第六个坑，是止血之后忘记撤销临时方案。第七个坑，是修完只看原页面，不看相邻路径。第八个坑，是构建通过就以为业务正确。第九个坑，是页面看起来正常就以为机器检查不重要。

第十个坑，是把 AI 的猜测发给老板当结论。第十一个坑，是不记录已排除的假设，导致团队反复查同一个方向。第十二个坑，是修完不沉淀检查清单，同类问题下次继续发生。排错能力不是一次猜中，而是每一步都能解释、能复查、能交接。

模板库

五个可复制模板：从接诊到复盘

下面五个模板可以直接保存为团队排错提示词。它们不是为了让你显得专业，而是为了让每次排错都从同一套动作开始：先接诊，后证据，再复现，再假设和最小修复，最后回归汇报。

使用模板时，要把方括号里的背景补全。尤其是业务影响、触发路径、最近改动和期望结果。没有这些信息，Codex 很容易只围着错误文字转。模板提供结构，真实材料决定质量。

请帮我用调试工作流排查这个报错。先不要修改任何文件，先整理现象和证据。

业务背景：
[这个页面/功能是给谁用的，正常应该完成什么任务]

我看到的现象：
[页面表现、报错文字、截图描述、用户反馈、发生时间]

触发路径：
[从打开哪个页面开始，点了什么，输入了什么，什么时候出错]

期望结果：
[正常情况下应该看到什么，或者系统应该完成什么动作]

实际结果：
[实际看到什么，是否空白、卡住、跳转错误、数据错、构建失败]

最近改动：
[最近改过哪些文件、上线了什么内容、换了什么配置、改了什么数据]

请先输出：
1. 这是哪类问题：构建、运行时、样式、数据、配置、接口、权限，还是还不能判断。
2. 已有证据有哪些，分别来自哪里。
3. 还缺哪些证据，需要我补充什么。
4. 最可能的 3 个原因，按概率和风险排序。
5. 下一步最小复现怎么做。

要求：没有证据的地方写“不确定”；不要凭经验直接改代码。

请把当前报错整理成一张证据表。

已知材料：
[粘贴报错、日志、终端输出、页面路径、用户操作、最近改动]

请按下面字段输出：
1. 现象：用户或维护者实际看到什么。
2. 证据来源：浏览器、终端、构建日志、服务器日志、用户反馈、代码 diff、数据文件。
3. 证据内容：关键错误文字、状态码、文件路径、时间点、输入值。
4. 能说明什么：这条证据支持哪种判断。
5. 不能说明什么：不要过度推断。
6. 下一步验证：为了确认这条线索，需要做什么。

请把事实、推断和待确认问题分开写。

请帮我把这个问题缩小成最小复现。

当前问题：
[描述报错或异常表现]

相关材料：
[粘贴页面路径、组件、数据、日志、最近改动]

请输出：
1. 复现前提：需要什么环境、账号、数据、浏览器或命令。
2. 复现步骤：从第 1 步到出错，每一步只写一个动作。
3. 必须保留的条件：哪些输入、字段、状态、配置不能删。
4. 可以暂时排除的条件：哪些页面、样式、数据、流程可能无关。
5. 最小复现版本：用最少页面、最少组件、最少数据复现问题。
6. 复现成功标准：看到什么才算复现了同一个问题。
7. 复现失败时怎么调整：下一步扩大或缩小哪些范围。

先给方案，不要直接修复。

请基于现象、证据和最小复现，制定调试假设和最小修复计划。

现象：
[粘贴现象描述]

证据：
[粘贴证据表或关键日志]

最小复现：
[粘贴复现步骤]

请输出：
1. 假设列表：每个假设说明为什么可能成立。
2. 排序依据：按概率、影响范围、验证成本排序。
3. 每个假设的验证动作：先看文件、跑命令、改临时输入，还是加日志。
4. 推荐的最小修复：只改哪些文件，为什么这些是最小范围。
5. 明确不做什么：哪些重构、顺手优化、风格调整先不做。
6. 修复后验证清单：复现路径、相邻路径、构建/测试、线上风险。
7. 如果修复失败，下一步回到哪个假设。

在我确认前，不要扩大修改范围。

请用负责人能看懂的方式汇报这次报错修复和回归验证。

请按下面结构输出：
1. 问题一句话：发生了什么，影响谁。
2. 根因：真正原因是什么；证据是什么。
3. 修复范围：改了哪些文件或配置；没有改哪些地方。
4. 验证结果：原复现路径是否恢复；相关路径是否正常；构建/测试是否通过。
5. 线上风险：是否需要止血、回滚、补数据、通知用户。
6. 剩余不确定项：还有什么没有完全确认。
7. 后续预防：需要补测试、补检查清单、补监控、补团队规则吗。

要求：不要只写“已修复”，要给出可复查证据。

检查清单

开始前检查清单：别让排错从缺材料开始

很多排错效率低，不是因为技术难，而是开始时材料太少。你让 Codex 看一个孤立报错，它只能猜；你给它页面、步骤、环境、最近改动、期望结果和日志，它就能排查。开始前清单的目的，就是在 AI 动手前把上下文补齐。

这张清单适合产品经理、运营、网站维护者在找开发或 Codex 前先填。哪怕填不全，也要明确哪些未知。写“不知道用户浏览器”比假装知道更好；写“没有服务器日志权限”也比让 AI 瞎猜更好。调试接受未知，但必须标出未知。

检查清单

修复后检查清单：不要让“看起来好了”代替验收

修复后检查清单，是把一次排错从技术动作变成可交付结果的关键。它要覆盖原问题、相邻功能、机器检查、线上风险和后续预防。尤其是在网站、表单、支付、登录、内容发布这些面向用户的功能里，不能只看一个按钮现在能不能点。

你可以让 Codex 按这张清单逐项汇报。如果某项没有做，就写未做和原因。未做不一定不能上线，但负责人要知道风险。比如没有真实线上账号、没有移动端设备、没有服务器日志权限，这些都应该作为剩余风险写出来，而不是被“已修复”三个字盖过去。

团队沉淀

把一次报错变成团队以后少犯一次错

排错结束后，很多团队会松一口气，然后立刻忘掉过程。下一次同类问题出现，还是从截图、猜测和群聊开始。真正有价值的做法，是把这次报错沉淀成团队资产：一条检查清单、一个测试用例、一段上线前提醒、一条 AGENTS.md 规则，或者一份常见问题处理说明。

不是每个 bug 都值得开长会复盘，但每个反复出现的问题都值得补一个防线。内容导出名经常错，就加新增文章检查项；表单字段经常前后端不一致，就加字段变更模板；移动端经常漏测，就加固定视口检查；线上配置经常漏，就加部署前环境变量核对。

Codex 可以帮你做复盘草稿。你把排查单、修复结果和验证过程给它，让它输出“以后如何避免”的建议。但最后要由团队负责人决定哪些规则真正写进流程。预防动作太多会没人执行，太少又没有意义。好的沉淀，是抓住最容易复发、最容易造成损失、最容易通过清单避免的那几类问题。

• 补检查清单：把本次漏掉的检查加入上线前流程。
• 补测试用例：让机器以后能自动发现类似问题。
• 补模板：让需求、字段、内容、配置变更有固定格式。
• 补监控或告警：线上问题不要只靠用户反馈。
• 补团队规则：让下次 Codex 或同事先读到禁区和流程。

课后练习

四个练习，把“会问 AI”变成“会排查报错”

练习一：找一个你过去遇到过的报错，不要让 Codex 修，只让它用报错接诊模板整理现象、证据和缺失信息。这个练习训练的是“把混乱现场说清楚”。如果你发现很多字段填不出来，说明以前排错靠的是记忆和直觉，不是可交接材料。

练习二：选一个可复现的小问题，让 Codex 帮你写最小复现步骤。然后你按步骤亲自跑一遍，看是否稳定触发同一个问题。这个练习训练的是“把问题缩小”。如果步骤里夹杂太多无关条件，就让 Codex继续删除无关条件。

练习三：让 Codex 对同一个问题提出三个假设，并按概率、验证成本、风险排序。你只验证第一个低成本假设，不允许它直接大改。这个练习训练的是“先验证再修”。练习四：拿一次已经修好的问题，让 Codex 写回归汇报，再用老板验收清单检查它是否说清影响、根因、修复、验证和预防。

1. 用报错接诊模板整理一次旧问题。
2. 把一个小问题缩成最小复现步骤。
3. 让 Codex 提出并排序三个假设，只验证低成本假设。
4. 把一次修复写成老板能验收的回归汇报。

最后总结

会调试的人，不是猜得快，而是证据走得稳

用 Codex 排查报错，最重要的不是让 AI 立刻给答案，而是让它按正确顺序工作。先把现象讲清楚，再把证据收集起来，再找到最小复现，再提出假设，再做最小修复，最后回归验证。这个顺序看起来慢，实际上比反复猜快得多。

对老板和产品经理来说，这套流程让技术问题变得可管理。你不必看懂每一行代码，但你可以要求影响范围、根因证据、修复边界、验证结果和后续预防。对网站维护者和开发者来说，这套流程能防止越修越乱，也能让修复更容易交接和复盘。

记住一句话：报错不是命令 AI 立刻动手的信号，而是提醒团队开始收集证据的信号。AI 会干活，但真正让它干对活的，是你把问题讲成了可复现、可验证、可验收的工作流。

• 现象要具体，别只说坏了。
• 证据要分层，别把猜测当事实。
• 复现要最小，别拖着整个项目跑。
• 修复要克制，别顺手大改。
• 验证要完整，别让红字消失就结束。