第十二章：常见问题与排障清单（跑偏/命令失败/诊断）

12.1 输出跑偏：像是没看代码

优先排查：

• 任务是否写清楚目标/约束/验收
• 是否提供了入口文件与关键调用链
• 是否要求先查证据再修改

建议修复（可直接复制）：

先不要改代码。
请基于代码库实际搜索与阅读结果，定位入口与证据链（文件/函数/调用链）。
只在你能指出明确证据后再给最小改动方案。

12.2 改动扩散：动了不该动的目录

根因通常是边界没写清楚。把边界写死并坚持“先 diff 再继续”：

边界：
- 只允许修改 src/ 与 tests/
- 禁止修改 .github/、infra/、deployment/、terraform/、docs/
每轮修改先输出 diff，我确认后再继续

12.3 命令失败：tests/lint/typecheck/build 不通过

排查顺序：

1. 命令是否正确（项目不一定是 npm test）
2. 是否缺少必要配置/环境变量（不要粘贴密钥）
3. 失败是否可复现（在项目根目录执行）

建议修复（可直接复制）：

请先从项目配置文件中找出正确的 tests/lint/typecheck/build 命令（如 package.json、pom.xml、pyproject.toml）。
然后按顺序执行，并把失败日志（脱敏后）贴出，定位根因并给出最小修复方案。

12.4 诊断不清零：编辑器里还有编译/类型错误

建议你把“诊断为 0”作为最终门禁：

• 先修到 tests 通过
• 再修到 lint/typecheck 通过
• 最后确保诊断为 0（无编译/类型/语法错误）

12.5 本章小结

排障的关键是“按层定位”：

• 上下文与规则 → 证据链（搜索/阅读）→ 改动范围（diff）→ 验收命令 → 诊断清零

至此，《Trae从入门到精通》系列完结。建议你从第 3 章的首次任务模板开始，把目标/约束/验收写清楚，然后用“先证据、后改动；先审阅、后合入；先验证、再交付”把效率变成稳定能力。