同一个项目连续做几轮后，最有价值的不是更长的对话，而是已经沉淀下来的规则、检查点和交接记录。
反复换命令、重装依赖和重启环境，可能偶然恢复，却会丢掉原始错误和真正原因。
所以这篇文章只解决一件事：用原始输出、环境信息和单变量实验完成可解释的终端排错。重点不是得到一段看起来完整的答案，而是让输入、步骤、结果和检查标准能够彼此对应。
适合谁
适合命令运行失败、依赖报错或环境不一致，需要Claude Code协助定位的人。
不适合的情况也很明确：任务没有边界、原件无法恢复、关键事实无人负责，或最终结果准备直接对外发布。先解决这些前提。
Claude Code进入项目后同样可能读取文件、修改内容和执行命令。开始前要限定权限、保留版本和回滚点，任何不可逆或对外操作都应由人工确认。
开始前准备
- 完整命令与原始输出
- 工作目录、运行时和系统版本
- 最近变更与一条成功对照
- 建立一个测试副本或新目录，不直接操作唯一原件。
- 写下一句验收标准：根因由环境或命令证据支持，原失败命令在同一条件下恢复，未用无关重装掩盖问题
开始前再做一次反向检查：少了哪份材料就无法判断结果？哪一步做错会影响原件？把答案写进当前任务，而不是留在自己脑中。
完整步骤
第一步之前：先做一个最小样本
小样必须足够小，出现问题时能回到具体输入和步骤；也要足够真实，不能只用一个刻意简化、永远不会出错的示例。
第一步：原样记录第一次失败
保留命令、退出码、堆栈和时间，不只截最后一行。
把“失败基线”作为本轮留存证据。后续合并或扩大范围时，都应能用它复盘。
第二步：确认运行环境
检查工作目录、可执行文件路径、版本、环境变量和权限。
先停在这里检查一次。此时应已经形成“环境快照”，并且能回到原始材料说明它从哪里来。
第三步：提出可证伪假设
每个假设对应一个只读或低风险检查，一次只改变一个条件。
这一阶段的完成标志不是工具有回复，而是“假设与检查表”已经可供人工检查。
第四步：修复后重跑原命令
用同一输入和环境验证，并补跑相关业务流程。
继续下一步之前，抽查“修复证据与残余风险”中的边界项和异常项；发现前提不成立就先修正。
第五步：人工验收并沉淀流程
最后把结果与原始材料逐项对照，记录有效步骤、人工判断点和没有解决的问题。重复任务可以继续整理成模板、项目规则或Skill。
实际示例
command not found先查实际可执行路径和当前shell，不直接重装整个项目；access denied要区分文件权限、系统策略和程序锁定。
可以先这样描述任务：
我正在处理“用原始输出、环境信息和单变量实验完成可解释的终端排错”。已有材料包括完整命令与原始输出、工作目录、运行时和系统版本、最近变更与一条成功对照。请先不要扩大任务范围，也不要补造缺失信息。先完成“原样记录第一次失败”，输出可以人工检查的中间结果；我确认后，再继续“确认运行环境”。最终请按照“根因由环境或命令证据支持，原失败命令在同一条件下恢复，未用无关重装掩盖问题”列出验收结果和仍需人工确认的内容。
这个任务描述故意先要求中间结果，再允许继续。对高风险或范围较大的工作，可以在每一步都保留同样的确认点。
常见问题与报错
换一个终端就能运行
比较两个终端的PATH、shell、工作目录、权限和环境变量；把差异记录下来，不能只建议以后换终端。
Claude Code理解了目标，却越做越大
在项目规则和当前任务中写明允许修改、禁止修改和停止条件，要求先提交计划；超出范围时立即停在检查点。
修改文件很多，但缺少可审查记录
让每个阶段列出读取文件、修改文件、执行命令和验证结果，并使用版本控制或副本保留可恢复状态。
先确认项目规则、权限和当前阶段，再比较实际文件与工具自述。没有落到文件或命令的“已完成”不能作为证据。
完成后的检查方法
- 根因由环境或命令证据支持，原失败命令在同一条件下恢复，未用无关重装掩盖问题
- 关键结论能回到原始材料、文件、命令输出或当前控制台。
- 没有把缺失信息、推测内容或示例数字写成已经确认的事实。
- 重要文件保留原件、版本或可恢复副本，敏感信息没有进入公开内容。
- 结果已经由真正负责这项工作的人审阅，而不是只看页面是否生成。
当这套步骤连续在两个真实样本上成立，再考虑扩大范围或做成Skill。第一次跑通不等于流程已经稳定。
资料来源
- Claude Code官方文档
用于核对Claude Code当前官方能力和基本使用边界。
- Claude Code记忆文档
用于核对项目规则与记忆文件的当前说明。
FAQ
可以一次把整个任务交给Claude Code完成吗？
不建议一次交付全部范围。先按本文步骤完成一个小样，用“根因由环境或命令证据支持，原失败命令在同一条件下恢复，未用无关重装掩盖问题”验收，再决定是否扩大范围。
遇到“换一个终端就能运行”应该先检查什么？
比较两个终端的PATH、shell、工作目录、权限和环境变量；把差异记录下来，不能只建议以后换终端
完成后还需要人工检查吗？
需要。AI或执行工具负责推进流程，最终仍要由你根据原始材料、任务规则和“根因由环境或命令证据支持，原失败命令在同一条件下恢复，未用无关重装掩盖问题”完成验收。