资料核验日期：2026-10-10。公开版保留整理正文与必要证据；原始资料通过来源链接回查。验证范围在正文中分别说明。
Claude Code 的调试、测试与评审
核验日期：2026-10-10。目标：从“不能用”走到可复现原因、针对性修复和有证据的交付。流程不依赖测试数量。
1. 写清问题
问题报告至少有触发动作、输入、预期、实际、环境与复现条件。例如“Python 3.12 读取四行清单时，T_Rock.PNG 被漏检；团队规定 PNG 扩展名忽略大小写；原数据含中文路径”。
先分清代码缺陷、配置、数据错误和需求理解。一个教学政策规定拒绝大写扩展名时，拒绝就是正确行为；不能拿另一套规则判断它错。代码修复前必须确认实际要求。
2. 最小复现与基线
在 学习实验 中，只用 Path('资产/T_Rock.PNG').suffix 就能复现大小写条件。保留一个正常小写样本与一个大写样本，可以看出变化影响哪些情况。
对 CSV 报告，先固定四项预期问题，再加缺列样本。中文路径作为文本应保留；它存在于 CSV 不表示对应磁盘文件已存在，因为程序没有做存在性查询。
最小复现删除无关数据，但不能删除导致故障的条件。带空字段的 CSV、带 BOM 的编码、末尾逗号或重复值都可能影响解析，需保留问题所需的具体输入。
3. 用假设组织调查
可能原因包括扩展名大小写、路径解析、CSV 读取或规则错误。分别用单独 suffix 输出、字段打印、规则文档和最小样本区分它们。
| 假设 | 检查 | 对结论的作用 |
|---|---|---|
| 大写后缀未归一化 | 查看 suffix 与比较条件 | 能直接解释该样本 |
| 中文路径编码损坏 | 读取并比较完整字符串 | 排除错误数据传递 |
| CSV 字段缺失 | 检查 fieldnames | 区分格式错误与规则问题 |
| 团队政策不允许大写 | 回查任务规则 | 确定什么才是正确结果 |
每次调查应减少不确定性。不断增加重试次数、同时改多个模块或猜测缓存，都可能让结果更难解释。
4. 修复范围与兼容
若要求忽略后缀大小写，就归一化后比较；若要求区分大小写，就保留原值。名称前缀、重复判定和路径存在性有各自规则，不应顺手改变。
配套旧样例用另一项故障演示相反方向：buggy 版本错误接受大写，fixed 版本恢复区分大小写。九个固定答案在修复前能识别三项违反政策的结果，修复后全部符合。两项演示说明“修复以需求为准”，不是“lower 永远正确”。
差异检查关注行为改变、依赖与异常路径。一次小规则修复不应无依据地加入新数据库、UI 或全仓重构。
5. 有价值的验证
测试的答案应来自需求与独立分析，不能直接抄实现的判断逻辑。对问题报告核对行号、规则、正常行与总数；仅断言“四项问题”不足以发现报错行错位。
可以按风险选择层次：函数样本验证规则；CLI 验证读取与退出码；集成验证下游报告；视觉检查验证页面能读与操作可用。只改静态文字时不必创造复杂单测；真实行为变化需要能发现原问题的检查。
本次已有真实结果：学习实验 的四项行号／规则、缺列错误和 before/after；ClaudeCode 示例检查 的九项扩展名、七项 CLI 和十二项 Hook 输入。
6. 与真实环境的距离
Hook 输入 fixture 验证脚本，不能证明当前会话触发。模型替身验证事件链，不证明模型决策质量。静态读取 UE 调用不能证明引擎生成与地图保存通过。报告应准确标出已运行、仅静态读和未实测。
长任务还要分清超时、进程退出和工具成功。Cindy 的 Pi 研究记录证明一种退出通知缺陷，并明确没有证明原用户打包问题的全部根因。它体现了把受控实验与真实事故分别说明的做法，详见 CY-02。
7. 组织评审
评审先看需求与触发条件，再看代码和产物，最后看验证记录。意见应说明哪种输入触发什么行为、为什么违反条件、依据在哪里。例如“缺少 kind 列仍生成成功报告”比“错误处理不够好”更可执行。
重点包括正确性、数据影响、接口、复杂度、兼容与可读性。自动评审也可能误判，重要发现应复现或指向可证实逻辑。独立评审不以开发 Agent 的自述替代产物。
8. 从问题到证据的交付
问题：允许大写 PNG 的教学任务被大小写比较漏检。
改动：比较前将 suffix 归一化，其他规则保持各自政策。
验证：大写样本修复前 False、修复后 True；四项清单答案匹配。
范围：只读教学数据；无模型调用、无真实资产和引擎检查。
产物：lab.py、样本与检查记录/学习实验结果.json。
这个格式同时说明行为和实测范围。需要接续时补充未完成项、文件位置与复现命令。重复故障再考虑加规则或可复用检查，不把一次经验无限扩大。
9. 练习与验收
复制样例后引入一项规则缺陷；先让固定答案检查发现问题，再做修复。提交最小输入、原因、差异、实际结果和评审说明。至少一项检查在修复前失败、修复后通过，同时正常样本保持符合需求。
另外写一条评审意见，明确触发条件与证据；把“脚本已跑”“模型未调用”“引擎未启动”分开记录。模板见 任务与交接。
来源
官方常用工作流、最佳实践、Python 3.12 pathlib，2026-10-10 核对。详细历史稿见 V1 调试参考副本。源码与验证结果均位于 V2.0 内。