# CC-03｜Claude Code 的调试、测试与评审

核验日期：2026-10-10。目标：从“不能用”走到可复现原因、针对性修复和有证据的交付。流程不依赖测试数量。

![失败到交付的逻辑架构图](<../../图表/CC-03_架构.svg>)

## 1. 写清问题

问题报告至少有触发动作、输入、预期、实际、环境与复现条件。例如“Python 3.12 读取四行清单时，T_Rock.PNG 被漏检；团队规定 PNG 扩展名忽略大小写；原数据含中文路径”。

先分清代码缺陷、配置、数据错误和需求理解。一个教学政策规定拒绝大写扩展名时，拒绝就是正确行为；不能拿另一套规则判断它错。代码修复前必须确认实际要求。

## 2. 最小复现与基线

在 [学习实验](<../../示例/学习实验/lab.py>) 中，只用 `Path('资产/T_Rock.PNG').suffix` 就能复现大小写条件。保留一个正常小写样本与一个大写样本，可以看出变化影响哪些情况。

对 CSV 报告，先固定四项预期问题，再加缺列样本。中文路径作为文本应保留；它存在于 CSV 不表示对应磁盘文件已存在，因为程序没有做存在性查询。

最小复现删除无关数据，但不能删除导致故障的条件。带空字段的 CSV、带 BOM 的编码、末尾逗号或重复值都可能影响解析，需保留问题所需的具体输入。

## 3. 用假设组织调查

可能原因包括扩展名大小写、路径解析、CSV 读取或规则错误。分别用单独 suffix 输出、字段打印、规则文档和最小样本区分它们。

| 假设 | 检查 | 对结论的作用 |
|---|---|---|
| 大写后缀未归一化 | 查看 suffix 与比较条件 | 能直接解释该样本 |
| 中文路径编码损坏 | 读取并比较完整字符串 | 排除错误数据传递 |
| CSV 字段缺失 | 检查 fieldnames | 区分格式错误与规则问题 |
| 团队政策不允许大写 | 回查任务规则 | 确定什么才是正确结果 |

每次调查应减少不确定性。不断增加重试次数、同时改多个模块或猜测缓存，都可能让结果更难解释。

## 4. 修复范围与兼容

若要求忽略后缀大小写，就归一化后比较；若要求区分大小写，就保留原值。名称前缀、重复判定和路径存在性有各自规则，不应顺手改变。

配套旧样例用另一项故障演示相反方向：buggy 版本错误接受大写，fixed 版本恢复区分大小写。九个固定答案在修复前能识别三项违反政策的结果，修复后全部符合。两项演示说明“修复以需求为准”，不是“lower 永远正确”。

差异检查关注行为改变、依赖与异常路径。一次小规则修复不应无依据地加入新数据库、UI 或全仓重构。

## 5. 有价值的验证

测试的答案应来自需求与独立分析，不能直接抄实现的判断逻辑。对问题报告核对行号、规则、正常行与总数；仅断言“四项问题”不足以发现报错行错位。

可以按风险选择层次：函数样本验证规则；CLI 验证读取与退出码；集成验证下游报告；视觉检查验证页面能读与操作可用。只改静态文字时不必创造复杂单测；真实行为变化需要能发现原问题的检查。

本次已有真实结果：[学习实验](<../../检查记录/学习实验结果.json>) 的四项行号／规则、缺列错误和 before/after；[ClaudeCode 示例检查](<../../检查记录/CC-02-04_示例检查.json>) 的九项扩展名、七项 CLI 和十二项 Hook 输入。

## 6. 与真实环境的距离

Hook 输入 fixture 验证脚本，不能证明当前会话触发。模型替身验证事件链，不证明模型决策质量。静态读取 UE 调用不能证明引擎生成与地图保存通过。报告应准确标出已运行、仅静态读和未实测。

长任务还要分清超时、进程退出和工具成功。Cindy 的 Pi 研究记录证明一种退出通知缺陷，并明确没有证明原用户打包问题的全部根因。它体现了把受控实验与真实事故分别说明的做法，详见 CY-02。

## 7. 组织评审

评审先看需求与触发条件，再看代码和产物，最后看验证记录。意见应说明哪种输入触发什么行为、为什么违反条件、依据在哪里。例如“缺少 kind 列仍生成成功报告”比“错误处理不够好”更可执行。

重点包括正确性、数据影响、接口、复杂度、兼容与可读性。自动评审也可能误判，重要发现应复现或指向可证实逻辑。独立评审不以开发 Agent 的自述替代产物。

## 8. 从问题到证据的交付

```text
问题：允许大写 PNG 的教学任务被大小写比较漏检。
改动：比较前将 suffix 归一化，其他规则保持各自政策。
验证：大写样本修复前 False、修复后 True；四项清单答案匹配。
范围：只读教学数据；无模型调用、无真实资产和引擎检查。
产物：lab.py、样本与检查记录/学习实验结果.json。
```

这个格式同时说明行为和实测范围。需要接续时补充未完成项、文件位置与复现命令。重复故障再考虑加规则或可复用检查，不把一次经验无限扩大。

## 9. 练习与验收

复制样例后引入一项规则缺陷；先让固定答案检查发现问题，再做修复。提交最小输入、原因、差异、实际结果和评审说明。至少一项检查在修复前失败、修复后通过，同时正常样本保持符合需求。

另外写一条评审意见，明确触发条件与证据；把“脚本已跑”“模型未调用”“引擎未启动”分开记录。模板见 [任务与交接](<../../模板/任务与交接.md>)。

![本章思维导图](<../../图表/CC-03_思维导图.svg>)

## 来源

[官方常用工作流](<https://code.claude.com/docs/en/common-workflows>)、[最佳实践](<https://code.claude.com/docs/en/best-practices>)、[Python 3.12 pathlib](<https://docs.python.org/3.12/library/pathlib.html#pathlib.PurePath.suffix>)，2026-10-10 核对。详细历史稿见 [V1 调试参考副本](<../../sources.html#ref-0ad4c92f504836>)。源码与验证结果均位于 V2.0 内。