本文目录 13 节
Claude 完成报告核查心法
首次记录：2026-05-12 来源：B 站直播弹幕插件项目反复出现的”宣称已实现 vs 实测可用”鸿沟 状态：规律已确立，跨项目都适用
核心观察
Claude（Code 或 Cowork）写完成报告时对自己的产出过度自信。常见表现：
| 报告里写的 | 实际状况 |
|---|---|
| ”git status clean” | 主工作树 60+ 文件 M（worktree 视角盲区） |
| “默认 NSIS 中文化已生效” | addLangs 宏仍 insert 27 种语言（schema 静默忽略错字段） |
| “7 种中文音色可切换” | UI/IPC/setConfig 链路完整，但底层 edge-tts 服务对部分 voice 失效 |
| ”规则文案随便改” | UI 只支持改文字模板，新增规则 modal 早就被裁剪掉了 |
| ”完整链路通了” | 接口实现但运行时表现 ≠ 文档承诺 |
通用规律：Claude 的”已实现”判定基于”代码路径完整”，但用户看到的是”运行时表现”。两者之间有结构性鸿沟。
三种典型盲区
盲区 1：视角错位
例：Claude Code 在 git worktree 里 self-verify，看到 git status clean 就如实写”工作树干净”。他没有错——只是看错了工作树。
通用形态：
- “我自己测试过了” = 在自己的环境里测过，不等于用户环境
- “代码 typecheck 过” = 静态类型对，不等于运行时行为对
- “我看了源码” = 读了，但没真的跑过
盲区 2：实现等价于可用
例：edge-tts 多音色接口完整、UI 下拉框生效、IPC 传到主进程、Communicate({voice}) 用了新 voice——但运行时对某些 voice 微软服务端返回空音频。代码 100% 对，运行时 50% 失败。
通用形态：
- “接口已经接好” = 调用方能 call，但被调方不一定能 respond
- “默认值是 X” = 默认值确实是 X，但用户改了之后有可能不生效
- “UI 有这个开关” = 有，但开关 → 主进程的链路某段没绑事件
盲区 3：宣传过度
例：UI 上 select 列出 7 个音色 → 主播看到 “7 种音色”。教程里写”7 种中文音色随便切换”，忽略了”只有 1 种实测稳定”的事实。
通用形态：
- “随便改” “完全自定义” “无限制” —— 99% 是夸大
- 任何”已实现”列表都要问：“用户实际操作时怎样？”
- UI 占位 ≠ 完整功能
盲区 4：宣称”已修复”，但那个 bug 根本不存在（2026-08-02 新增）
前三种盲区都是「做得比说的少」。第四种反过来：修了一个不存在的问题，并当成战功上报。
例（LiveLink 迭代）：截图工具 DPI-unaware 导致图右侧被裁，据此判定「布局在窄窗口被撑破」，
写了 CSS 修复、写进 commit message、还写进了已发布的 GitHub release notes。
后来用第二种手段（CDP 量 scrollWidth）加对照实验证明：该 bug 从不存在。
通用形态：
- 观测工具有缺陷 → 假象被当成 bug → “修复”被写进对外文案
- “我修好了 X” 之前没人问过 “X 真的坏过吗？”
- 越是「一眼就看出问题」的现象，越容易跳过复现直接进修复
为什么比前三种更难发现：前三种用户一用就露馅；这种用户永远不会发现 （那个 bug 本来就不存在，功能一直是好的），只会留下一条虚假的修复记录， 以及一段没人知道为什么存在的防御性代码。
→ 完整案例与工具侧根因见 Windows下编码与DPI的所见非真相_v1 陷阱三·第三次验证
心法：四问核查
完成报告读完后，写”宣称已实现”列表前问四个问题：
- 这条 Claude 在哪验过？ worktree / dev 模式 / prod 模式 / 用户实机？
- 从用户操作到生效，链路有几跳？ 跳数越多，越要单独验
- 接口有没有可能”接通但下游失败”？ 比如 TTS / API / OAuth / cookie 时效
- “随便 X” 是真随便还是 X 的子集？ 测试边界
- （2026-08-02 增）这条”已修复”，对应的 bug 有没有被独立复现过？ 没复现过就修的，先降级成”防御性改动”，不要写成修复。
实操步骤
收到完成 patch 报告后：
-
bash 验证关键 token 真打进 bundle（不只是 commit 里有）：
for tok in feature_A feature_B; do grep -c "$tok" out/main/index.js done -
bash 在主工作树视角下跑 git status（不信报告的”clean”）
-
跑用户工作流的最短路径（比如本项目装 exe 后看图标变没变）
-
核查”现在能用”列表：每一项真的能用才进列表。部分功能或接口存在但运行时表现存疑的要降级到”即将到来”或加显式 caveat（如”待实测确认”）
在交接 / 教程类文档里的应用
写给跳蛛先生 / 主播朋友的”功能列表”必须经过这套核查。降级措辞模板：
| 实际状态 | 措辞 |
|---|---|
| 100% 实测过、用户可重复触发 | ”X 功能” |
| 代码路径完整但部分场景失败 | ”X 功能（默认配置可用，其他选项待稳定）“ |
| 接口实现但跳蛛先生本人未实测 | ”X 功能（链路已接通，待实测确认）“ |
| UI 占位但内部裁剪掉了 | 不进”已实现”列表，挪到”即将到来” |
宁可少列 1 项，不要列错 1 项。用户实测后发现宣传过度比”没听说过这个功能”扣分得多。
关联现象
这个心法同样适用于：
- PR 自评估 —— “这个 PR 做了 A B C”，实际 C 只 stub 了
- API 文档自动生成 —— OpenAPI schema 写了，但 endpoint 没实现
- AI 写完代码后的 self-review —— “我已经处理了所有 edge case” 大概率假
- CI 通过 ≠ 功能对 —— CI 跑 unit test 过，但 UI 行为没人验
跟”完成报告必读”的关系
Claude 写的完成报告仍然要读——它是了解”做了什么”的最快路径。但要带核查心态读，不要带”信任心态读”。
读法：
- 先读 TL;DR 和”自拍板决策” → 了解大方向
- 再核查”宣称已实现”列表 → 哪些真的能用、哪些是接口、哪些是 UI 占位
- 最后看 §“已知 leftover” → Claude 自己 acknowledge 的盲区（这部分往往是真诚的）
如何使用
- 写用户教程 / 功能宣传 / Release notes 前过这套核查
- 反过来：写Bug 修复完成报告 / 内部交接时不必这么严——内部读者会自己核查
- 把”诚实降级”当作优势而非缺点 —— 用户对”实诚说存在 leftover”的产品更信任
关联文档
- Claude_Code_Worktree隔离的协作陷阱_v1 —— 盲区 1 的典型例子
- Windows下编码与DPI的所见非真相_v1 —— 本心法在 Windows 工具链的具体形态:发 Release notes / 截图核查 UI 时,编码层与 DPI 层会制造「所见非真相」
- Claude_Opus_4.8行为实测_v1 —— 4.8 更诚实(“偷懒”不良率近 0%),但”搞定了”仍建议沿用本心法核查
- MJ出图绕开抠图陷阱_v1 —— Claude 自述”已完成”但执行路径绕开了真实需求的另一型例
- 2026-08-02_LiveLink断线重连重做与视觉系统_迭代复盘_v1 —— 盲区 4「宣称已修复但 bug 根本不存在」的来源案例；另贡献「开工前先对基线」这条前置检查
- 主线交接:
{AIGC工作站}/跨会话协作\B站直播弹幕插件_全局进度_交接给_下一次Cowork.md§四 第 5 条 - 现役 LiveLink 教程图 v2 → v3 的修订记录(教训化过程)