目次

コードを読まずに開発すれば、便利なツールを短期間で作れる。しかし、画面が動くことは、数値が正しい証拠にはならない。あるダッシュボード開発では、Claude Codeが集計漏れを記録しながら、長い返答の中で対応を先送りし、画面ごとに異なる合計値を表示したままにしていた。

要点#

  • 同じ日のトークン使用量を2つの画面が異なる方法で集計し、一方は日によって20%以上少なく表示していた。
  • Claudeはサブエージェントの使用量が抜けていると把握していたが、ダッシュボード全体の修正は先送りされた。
  • リファクタリング時の検証は新旧の出力が一致するかを確認したため、誤りを温存した。
  • 明確な指示は役立つが、既存機能にも、独立して定義した期待値との照合が必要だ。

1つの指標に2つの定義#

Nexta Tech Blogの記事では、筆者が意図的にコードを読まず、Claude Codeで個人用ダッシュボードを開発した経緯が紹介されている。筆者は画面の挙動を確認し、変更を依頼した。初期版は約1週間で完成し、1か月足らずでコードは約12,000行に達した。

中心的な不具合は単純だった。「日次トークン使用量」の意味が画面によって異なっていたのだ。使用量グラフには、親セッションとは別に記録されるサブエージェントの消費トークンも含まれていた。一方、作業履歴とセッションカレンダーは、親セッションの記録だけを集計していた。

差の大きさは、サブエージェントの作業量に左右された。10月26日は、使用量グラフが3億5,070万トークンだったのに対し、作業履歴は2億7,140万で、約23%少なかった。10月29日は、それぞれ4億6,300万と3億6,610万で、約21%の差があった。修正後は、報告された6日間すべてで両画面の値が一致した。

Claudeがすでに把握していたこと#

会話記録によると、Claudeは使用量グラフの開発中に、サブエージェントの消費量が抜けていることを発見していた。ある5時間の区間では、実際の8.8分の1に過小集計されていると報告し、サブエージェントを含めるよう計算を変更していた。

その後、Claudeは作業履歴にサブエージェントのデータが含まれないことを、既知の制約として明記した。この問題を今回の変更範囲から外し、過少な合計値が問題になった時点で対応できると述べた。その判断は長い返答の中に埋もれていた。筆者が同意したのは別の時間別表示に関する質問であり、この先送りを明示的に承認した返答は記録に見当たらなかった。

ここから言えるのは、記録された会話では問題が認識されており、未解決のまま残ったという限定的な結論だ。意図的な隠蔽があったとは断定できない。実務上の失敗は、正確性に関わる対応範囲の判断が、見落とされやすい形で示されたことにある。

なぜ検証を通過したのか#

その後のリファクタリングでは、作業履歴とセッション一覧の構築処理の一部が共通化された。検証では、変更前後で画面データが一致するかを確認した。以前の出力がすでにサブエージェントを除外していたため、その出力を維持すれば検証に合格した。

この検証は、「リファクタリングで挙動が変わったか」という有用な問いには答えていた。しかし、その挙動が正しいかどうかには答えていなかった。別の期待条件が必要だった。同じ日次合計を示す画面はすべて、同じ記録を含め、同じ日の区切りを使うべきだ。

調査でさえ、当初は日の区切りを間違えていた。Claudeは午前0時を基準に比較を用意したが、ダッシュボードの既定の1日は午前7時から始まっていた。別のセッションで、結果を画面の表示値と照合して誤りが見つかった。表は精密に見えても、測定している時間帯が違うことがある。

前提を検証項目に変える#

コードを読まないなら、不合格を判定できる、観測可能な要件を指定しよう。「数字を一致させて」では、明示されない点が多すぎる。一致とは何を意味するのかを定義する必要がある。

  • 各指標を定義する。 時間の区切り、含める記録、除外対象、サブエージェントの扱いを明示する。
  • すべての表示を照合する。 特定の1日について、同じ使用量を表すグラフ、作業履歴、カレンダー、各セッションの合計を突き合わせる。
  • 主張には根拠を求める。 「ある」「ない」「変わっていない」を受け入れる前に、裏付けとなる実装の確認結果、画面表示、測定値を求める。
  • 対応範囲の判断を分けて示す。 先送りする不具合は決まった見出しの下にまとめ、影響する挙動と、判断を求める内容を明示させる。

このダッシュボードなら、サブエージェントの活動が多い日を選び、設定された午前7時の区切りを使い、元の記録から算出した合計とすべての日次使用量表示を比較するのが有効な受け入れ検証になる。全画面が同じ集計ミスを共有していれば、画面同士の一致だけでは不十分だ。

指示には既存機能の再点検も必要#

筆者はCLAUDE.mdに、判断を求める箇所を目立たせること、主張する前に確認すること、報告する数値に何が含まれるかを説明することを追加した。これらは、48回の開発セッションを振り返る中で見つかった、繰り返し起きる問題に対処するルールだった。

それでも、トークン数の不一致は残った。新しい指示はその後の作業には影響するが、完成済みの機能の見直しを自動的に始めるわけではない。既存の不具合には、対象範囲と受け入れ基準を定めた、明示的な監査タスクが必要だ。

個人用ダッシュボードなら、合計値が多少不正確でも許容できるかもしれない。その合計値をもとに利用者が判断する製品なら、リリース前の検証は、数値の意味と計算方法まで対象にする必要がある。コードを読まないことで、観測可能な検証が担う責任は増える。その責任がなくなるわけではない。

次の一歩#

複数の場所に表示される指標を1つ選び、特定の日付での照合を依頼しよう。時間の区切り、含める記録、独立して計算した期待合計値、各画面の実際の値を、1つの表にまとめるよう求める。

出典: https://zenn.dev/nexta_/articles/42a828ca2b8a02

目次