目录

不读代码也能在短时间内开发出实用工具。但界面能运行,并不能证明数值正确。在一次仪表盘开发中,Claude Code虽然记录了统计遗漏,却在冗长的回复中推迟处理,让不同界面继续显示不同的合计值。

要点#

  • 两个界面对同一天的Token用量采用不同的统计方式,其中一个在某些日期少显示了20%以上。
  • Claude知道子代理的用量被遗漏了,但对整个仪表盘的修复被推迟了。
  • 重构时的验证只检查新旧输出是否一致,因此保留了错误。
  • 明确的指令有帮助,但已有功能也需要与独立定义的预期值进行核对。

一个指标,两种定义#

Nexta Tech Blog的一篇文章介绍了作者刻意不读代码、使用Claude Code开发个人仪表盘的过程。作者检查界面行为,并提出修改要求。初版约一周完成,不到一个月,代码就达到了约12,000行。

核心问题很简单:“每日Token用量”在不同界面上的含义不同。用量图表包含了与父会话分开记录的子代理消耗的Token,而工作历史和会话日历只统计了父会话的记录。

差距大小取决于子代理的工作量。10月26日,用量图表显示3亿5,070万Token,工作历史则为2亿7,140万,少了约23%。10月29日,两者分别为4亿6,300万和3亿6,610万,相差约21%。修复后,报告中列出的6天里,两个界面的数值全部一致。

Claude早已知道的事#

根据对话记录,Claude在开发用量图表时,就发现了子代理消耗量被遗漏的问题。它报告称,某个5小时区间的统计值仅为实际值的1/8.8,并修改了计算方式,将子代理纳入统计。

随后,Claude明确将工作历史不包含子代理数据列为已知限制。它将这一问题排除在本次修改范围之外,并表示可以等偏低的合计值造成问题时再处理。这一判断埋在冗长的回复中。作者同意的是另一个关于按小时显示的问题,记录中没有找到明确批准此次推迟处理的回复。

由此只能得出一个有限的结论:在记录下来的对话中,问题已被识别,却仍未解决。不能断定存在故意隐瞒。实际工作中的失误在于,涉及准确性的处理范围决策,以一种容易被忽略的方式呈现了出来。

为什么通过了验证#

后续重构将工作历史和会话列表的部分构建逻辑进行了共用化。验证检查的是修改前后的界面数据是否一致。由于原有输出已经排除了子代理,只要维持这一输出,就能通过验证。

这种验证回答了一个有用的问题:“重构是否改变了行为?”但没有回答这种行为是否正确。还需要另一项预期条件:所有显示同一每日合计值的界面,都应包含相同的记录,并使用相同的日期划分边界。

就连调查最初也弄错了日期划分边界。Claude以午夜0点为基准准备了比较数据,但仪表盘默认的一天从早上7点开始。在另一次会话中,将结果与界面显示值核对后,才发现了错误。表格看起来再精确,测量的时段也可能不同。

将前提转化为验证项#

如果不读代码,就应指定可观测、能够据此判定不合格的要求。“让数字一致”留下了太多未明确之处。需要定义“一致”究竟意味着什么。

  • 定义每个指标。 明确时间边界、纳入的记录、排除项以及子代理的处理方式。
  • 核对所有显示。 针对某一天,交叉核对表示同一用量的图表、工作历史、日历和各会话合计值。
  • 要求为断言提供依据。 在接受“有”“没有”“没有变化”之前,要求提供实现检查结果、界面显示或测量值作为支撑。
  • 单独呈现处理范围的决策。 将推迟处理的问题集中放在固定标题下,明确受影响的行为,以及需要用户决定的事项。

对于这个仪表盘,有效的验收验证是:选择子代理活动较多的一天,使用设定的早上7点分界,将根据原始记录算出的合计值与所有每日用量显示进行比较。如果所有界面都存在同样的统计错误,仅仅界面之间一致还不够。

指令也需要涵盖对已有功能的复查#

作者在CLAUDE.md中添加了几项要求:突出需要用户判断的内容,在作出断言前先核实,以及解释报告的数值包含哪些内容。这些规则针对的是回顾48次开发会话时发现的反复出现的问题。

即便如此,Token数量不一致的问题仍然存在。新指令会影响后续工作,却不会自动触发对已完成功能的复查。已有缺陷需要明确的审计任务,并规定审查范围和验收标准。

对于个人仪表盘,合计值略有偏差或许可以接受。但如果是用户会依据这些合计值作出判断的产品,发布前的验证就必须涵盖数值的含义和计算方式。不读代码,会增加可观测验证所承担的责任,而不会让这份责任消失。

下一步#

选择一个在多处显示的指标,要求针对特定日期进行核对。让它将时间边界、纳入的记录、独立计算的预期合计值,以及各界面的实际值整理到同一张表中。

来源: https://zenn.dev/nexta_/articles/42a828ca2b8a02

目录