用 AI 编程工具修问题时，很多人第一反应是把整段报错复制进去，然后补一句“帮我看看”。这当然有时能解决，但一旦项目稍微复杂，AI 很容易被无关日志带偏：它看见红色报错就改代码，却没有确认触发条件、运行环境、最近改动和验收方式。
更稳的做法，是把报错日志整理成一份可执行的排查材料。它不是写给人看的长报告，而是写给 Cursor、Claude Code、Codex 这类 AI 编程工具的“定位输入”。如果你正在系统学习这类工作流，可以先看 AI编程工具专题 和 老达AI实践专题，再把本文当成排错模板使用。
为什么不能只贴一大段日志
一大段日志的问题，不是信息太多，而是缺少优先级。AI 会看到堆栈、警告、依赖输出、测试失败、构建摘要，但它不知道哪一行是根因，哪一行只是连带结果。尤其是前端构建、Node 依赖、WordPress 接口、Python 脚本这类项目，日志里经常同时出现多个 warning 和 error。
更麻烦的是，报错日志通常缺少上下文。比如同样是 Cannot read properties of undefined，可能是接口字段为空，也可能是异步状态未初始化，还可能是测试数据没准备好。AI 如果不知道你刚改了哪个文件、期望行为是什么，就会倾向于补空判断，而不是解决真正的数据流问题。
所以，报错日志要和“复现步骤、最近改动、期望结果、实际结果”一起交给工具。之前我写过 AI编程调试流程 和 AI编程 Bug 复现报告，这篇更聚焦在日志本身怎么摘、怎么排序、怎么让 AI 少猜。
第一步：先把问题压缩成一句话
日志整理的第一行，不应该是报错原文，而应该是你对问题的描述。可以按这个格式写：
问题：在执行 npm run build 时，文章详情页构建失败；预期是正常生成静态页面，实际在读取 post.excerpt.rendered 时抛出 undefined 错误。这句话的作用，是告诉 AI：当前任务不是“解释日志”，而是“修一个具体流程”。如果你只贴日志，工具可能会先解释错误类型；如果你先写问题，它会更快进入定位和修改。
这一句不要写得太泛。比如“网站报错了”“接口不通”“页面打不开”都不够。至少要包含触发动作、失败位置、期望结果和实际结果。对 AI 编程来说，这比多贴 200 行日志更有价值。
第二步：只摘关键日志，不要全量轰炸
关键日志一般包括三类：第一类是最靠近失败点的 error；第二类是错误前后 20 行左右的上下文；第三类是命令结束时的摘要，比如退出码、失败测试名称、构建目标。
可以这样整理：
命令：
npm run build
关键错误：
TypeError: Cannot read properties of undefined (reading 'rendered')
at renderPostCard (src/components/PostCard.tsx:42:26)
错误前上下文：
- 最近修改了 PostCard 的摘要展示逻辑
- 接口返回中部分文章没有 excerpt 字段
- 本地开发环境可以打开首页，但构建详情页失败
退出结果：
Build failed with exit code 1如果日志很长，可以先让 AI 做一件事：只帮你提取“可能是根因的 5 行”和“可能只是噪声的 warning”。但不要让它直接开始改代码。先让它把判断依据说清楚，再进入修改。
第三步：补齐环境信息，尤其是版本和入口
很多报错不是代码本身错，而是环境不一致。比如本地 Node 版本、包管理器、系统路径、环境变量、测试数据库、WordPress REST API 返回结构不同，都会让 AI 的判断跑偏。
建议至少补这几项：
- 运行命令：例如
npm run test、pnpm build、node scripts/check_post.js。 - 运行位置：项目根目录、子目录、具体服务目录。
- 关键版本：Node、Python、框架版本、CLI 工具版本。
- 输入数据：使用的是本地 mock、线上接口、测试账号还是真实文件。
- 最近改动：刚改过哪些文件、为了实现什么目标。
这一步和 AI编程上下文管理 很像：不是让 AI 读更多，而是让它先读对。环境信息写清楚后，Cursor、Claude Code、Codex 才能判断是代码问题、配置问题，还是数据问题。
第四步：让 AI 先给排查路径，不要直接修
拿到日志后，可以先这样问：
请先不要修改代码。
根据下面的问题描述、关键日志和最近改动，列出 3 个最可能原因。
每个原因要说明证据、需要检查的文件、最小验证命令。
最后给出你建议优先检查的顺序。这个提示词的重点是“先判断，再动手”。如果 AI 一上来就改，很可能把表层报错压下去，却留下更深的问题。排查路径能帮你看出它是否理解了项目，也方便你及时纠正方向。
如果它给出的路径太泛，比如“检查变量是否为空、检查依赖是否安装、检查网络是否正常”，就继续追问：“请把每条检查落到具体文件、函数、命令或数据字段上。”AI 编程最怕泛泛而谈，日志排查尤其如此。
第五步：把复现命令和验收标准写在一起
修报错不是看到红字消失就结束。一个合格的日志排查任务，应该同时写清楚修复后的验收方式：
验收标准：
1. npm run build 可以通过；
2. 文章详情页在 excerpt 缺失时显示默认摘要，不再抛错；
3. 现有文章卡片样式不变化；
4. npm test 中 PostCard 相关用例通过；
5. 修改范围不要扩大到接口层，除非确认返回结构确实不稳定。这样写的好处，是 AI 不会只盯着当前错误行。它会知道哪些地方不能乱动，哪些结果必须验证。之前的 AI编程测试自动化 也提到过：让工具自动跑检查，比让它口头说“应该没问题”可靠得多。
一份可直接复用的报错日志模板
下面这份模板可以直接保存到项目说明、飞书文档或常用提示词里：
【问题一句话】
在什么动作下，哪个功能失败，预期是什么，实际是什么？
【复现步骤】
1. 进入哪个目录
2. 执行什么命令
3. 打开哪个页面或触发哪个动作
【关键日志】
只贴最靠近失败点的 error，以及前后必要上下文。
【环境信息】
系统、Node/Python/框架版本、包管理器、关键环境变量是否已配置。
【最近改动】
本次任务改过哪些文件，为了解决什么问题。
【请 AI 先做什么】
先给可能原因、证据、检查文件和验证命令，不要直接修改。
【修复验收】
需要通过哪些命令、页面检查和回归点。如果项目已经比较大，我建议把这份模板和项目规则放在一起。比如 Cursor Rules、CLAUDE.md、AGENTS.md 里都可以写一条：遇到报错先整理复现和关键日志，再进入修改。这样每次排错的输入会更稳定。
老达点评
AI 编程工具越来越强，但它们依然不是项目里的当事人。你给它一段混乱日志，它会努力猜；你给它一份结构化问题材料，它才更像一个靠谱协作者。
我的经验是，报错日志整理得越具体，AI 改代码的范围反而越小。真正省时间的不是让 AI 多跑几轮，而是第一轮就把问题、证据和验收标准说清楚。以后遇到构建失败、测试失败、接口报错，不妨先花 3 分钟按模板整理，再交给工具处理。
