修正をどう裏付けるか

スコア加算の不具合を修正しました。回答にはターミナル出力、スコアボードのスクリーンショット、短い"完了"が添えられています。ファイルはたくさんありますが、知りたいことはひとつです。どれがタスクの要件を裏付けているのでしょうか。

証拠とは、修正のそばにたまたま置かれたファイルのことではありません。何を、どのコードの状態で確認し、何が起きたかを示す、具体的な検証結果です。資料ごとに答えられる問いは異なり、ひとつですべてを証明できるものはありません。

要件を検証可能な主張に変える方法、コマンド実行について記録する内容、ログ・diff・画面キャプチャがそれぞれ裏付けるものを見ていきます。最後に、6項目からなる短いEVIDENCE_LOGにまとめ、手元の資料で十分かを確認します。

基準から検証方法を決める

記事全体を通して使う例は、スコアボード付きの小さなボーナスゲームです。開始時のスコアは0で、3回そろうと3点加算されるはずですが、修正前は30点加算されていました。この加点ルールはこのゲーム用に設定したものです。別のプロジェクトではまったく違うかもしれないので、そのまま持ち込まないでください。

"スコアを修正した"という文だけでは検証できません。何を実行し、何を見ればよいのか分からないからです。検証可能な主張は、初期状態、操作、期待する観察結果の3つで組み立てます。たとえば"スコアが0のとき、3回そろえると3点加算され、スコアボードに3と表示される"。これなら検証できます。

この主張は、さらに個別の観察結果に分けられます。計算結果とプレイヤーに見える表示は別物で、それぞれ異なる証拠で裏付けます。表の3行目はリーダーボードへの保存についてです。タスクにその要件がない場合もありますが、あるなら独自の観察結果が必要です。

ここでは3列目が特に役立ちます。証拠が裏付ける範囲は、期待より狭いことがほとんどです。その境界は、実際に行った操作の終わりにあります。この例では、計算のテストはスコアボードを確認しませんし、スコアボードのキャプチャから変更されたコード行は分かりません。

要件と結果は分けて考えましょう。要件は最後に満たされているべきこと、結果は実際に得られたものです。同じ段落に混ぜてしまうと、"3点加算されるはず"が、何も実行していないのにいつの間にか"3点加算される"に変わってしまいます。

コマンドと実行結果

検証の実行記録には、次の5点が必要です。1週間後に同じ検証をやり直す人には、どれも自明ではありません。

• コマンドを実行したフォルダー
• 実行したコマンドそのもの。省略せず記録します
• コードの状態: 修正前か修正後か、どのような未コミットの変更があったか
• 終了時の状態: 終了コードと集計値
• 実際に実行した検証と、実行しなかった検証

"npm testを実行してください"と"npm testを実行しました。出力はこちらです"は区別しましょう。前者は指示で、これから行う予定です。後者は事実です。特に、回答に確認すべきことがきちんと書かれていると、意図を結果と取り違えやすくなります。

npm testは"存在するテストをすべて"実行するわけではありません。npmが選んだプロジェクトのpackage.jsonにあるscriptsセクションのtestフィールドに記述された処理を実行します。どのプロジェクトが選ばれたか迷わないよう、そのルートからコマンドを実行し、フォルダーも記録してください。隣のプロジェクトでは、同じ名前でも別のツールや手順を指すことがあります。何も設定されていないこともあります。

コマンドの終了時には終了コードが返ります。0は通常、"ツールが実行成功と判断した"ことを意味します。bashではコマンドの直後にecho $?で確認できます。PowerShellでは、npmのような外部プログラムの場合、$LASTEXITCODEを使います。ただし、0でも確認したいテストが実行されたとは限りません。スキップされたり、名前で絞り込まれたり、そもそも書かれていなかったりする可能性があります。終了コードと合わせて、集計値と対象のテスト名も記録しましょう。

ログから残すもの

実行出力は長くなることがあり、すべてを記録に転記する必要はありません。短い抜粋には、失敗したテスト名、期待値と実際の値、失敗の理由、集計値の4点を含めます。残りはリンク先のファイルに保存します。以下は学習用に短くした出力例で、実際の実行記録ではありません。

✖ three matches give 3 points (2.4108ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  30 !== 3
      at TestContext.<anonymous> (src/bonus-game/score.test.js:8:10)
ℹ tests 1
ℹ pass 0
ℹ fail 1
ℹ skipped 0

これは抜粋で、完全な出力はたとえばlogs/test-fail.txtに保存します。これだけでも重要な点が分かります。3回そろえるテストが失敗し、期待値は3、実際の値は30で、スキップされた検証はありません。

生の出力はそのまま記録に入れます。"乗数が間違っていたためテストに失敗した"のように自分の言葉で要約すると分かりやすくなりますが、それは観察結果ではなく結論です。記録を見ても確かめられません。ツールの出力と自分の説明は並べて残しましょう。先に出力、そのあとに説明です。

スタックトレースの行にある場所は、アサーションが実行されたテストファイルです。原因はゲームのコードから探します。そこで見つけた乗数はコードを読んだ結果であって、ログの一行ではありません。後から数値10の出どころを見失わないよう、記録ではこの2つの情報源を分けて示します。

diffで裏付けられること

diffは、ファイルの2つの状態の差分を示します。修正後のコードを一度でも実行したか、期待どおりに動作が変わったかまでは分かりません。

--- a/src/bonus-game/score.js
+++ b/src/bonus-game/score.js
@@ -1,5 +1,5 @@
-const POINTS_PER_MATCH = 10;
+const POINTS_PER_MATCH = 1;

 function calcScore(matches) {
   return matches * POINTS_PER_MATCH;
 }

この抜粋には、どの状態を比較したかを示す短い説明を付けます。たとえば"修正前のコミットa1b2c3dと作業ツリーを比較。コマンドはgit diff HEAD"のようにします。この識別子は学習用なので、記録には実際のものを使ってください。このコマンドは、ステージ済みの変更も含め、現在の追跡対象ファイルとHEADを比較します。HEADを付けない通常のgit diffはステージ済みの状態との差分だけを表示するため、git add後には空になることがあります。説明がなければ、diffは"何かと何かの比較"にしか見えず、同じ比較を再現できません。

テストの期待値が3のままかも確認してください。コードと一緒に期待値まで変わっていたら、話は別です。検証側が動作に合わせてしまい、動作を要件に合わせたわけではありません。

もうひとつ、間違えやすい技術的な点があります。修正をまだコミットしていない間は、作業ツリーと直近のコミットを比較すれば変更が見えます。コミット後に同じ比較をすると差分は空になりますが、タスクで何も変わっていないという意味ではありません。変更が履歴に入ったので、コミットとその直前の状態を比べる必要があるということです。空のdiffだけでは何も証明できません。重要なのは、どの2つの状態を比較しているかです。

スクリーンショットから分かること

状態と操作

スコアボードに3と表示された画面から分かるのは、撮影時点でスコアボードに3と表示されていたことだけです。"3回そろえると3点加算された"とは異なります。この2つの主張の間には、画面に写っていない情報があります。開始時のスコアや、実際に行った操作です。

画面を証拠として使うには、シナリオを一緒に記録します。

1. 開いたもの: ページのアドレスまたは起動方法、修正前か修正後か
2. 初期状態: 開始時のスコアは0で、古いデータは読み込まれていない
3. 操作: 3回そろえた
4. 観察結果: 操作直後に撮影した画面で、スコアボードに3と表示されている

この記録がなければ、同じような画面はさまざまな方法で作れてしまいます。昨日から開きっぱなしの古いバージョンのタブ、別の起動方法、すでに0以外のスコアが表示されていた場合など、どれも説得力がありそうで、実際には何も証明しない画像になり得ます。

この記事にスコアボードのスクリーンショットがないのは意図的です。検証用のスクリーンショットは、対象バージョンでシナリオを再現した後に、手動または自動化ツールで撮影します。説明用に描いたり組み立てたりしたスコアボードは、そっくりに見えても証拠にはなりません。実際に撮影するときはスコアボード全体を写し、シナリオの記録にページのアドレスを書き、記録と一緒に保存してください。そうしないと、1週間後にはどの実行の画像だったか思い出せなくなります。

モデルが読み取れること

画像をセッションに渡して読み取ってもらうことができます。依頼の仕方が重要です。あらかじめ決めた結論への同意を求めるのではなく、見えている数値と不確かな点（"初期状態が見えるか"、"どのバージョンか分かるか"）を挙げてもらいましょう。"不具合が修正されたと確認して"と頼むと、何も検証していないのに丁寧に同意されることがあります。

画像を渡せるかどうかは、利用しているモデルと環境によります。Claude Codeでは、保存した画像のパスを指定して読み取るよう依頼できます。画像が読み込まれなかった場合は、まずパスとファイルへのアクセスを確認してください。モデルを変えれば必ず解決するわけではありません。

同じシナリオを修正前後で実行する

有効な比較は、同じ検証が不具合のある実装では失敗し、修正後の実装では成功することです。失敗すれば、その検証が不具合を検出できると分かります。成功すれば、修正後のコードでは検証したシナリオに不具合がないと分かります。

ただし、同じ入力データと同じ期待値を使うことが条件です。開始時のスコアも、そろえる回数も、期待値の3も同じにします。修正後に同じテストを実行した結果は次のとおりです。

✔ three matches give 3 points (1.3983ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0
ℹ skipped 0

実行の間に変えるのは実装だけです。テスト、入力データ、期待値、実行条件は同じにします。要件やテストの期待値を変更した場合は、その検証について新たに実行結果を1組そろえてください。言葉での説明だけでは、両方のコード状態で実行したことにはなりません。この場合、"赤だったものが緑になった"とだけ記録すると誤解を招きます。

before.txtとafter.txtという名前の2つのファイルがあるだけでは、何も保証されません。ファイル名は証拠ではありません。中身を見て、コマンド、テスト、期待値が同じか確認しましょう。不具合のある状態に戻す確認（git stashを使う方法）には別のルールがあります。ここでは、修正前の失敗が記憶ではなく実際の実行結果に基づいていることを押さえておけば十分です。

短いEVIDENCE_LOG

この記事でいうEVIDENCE_LOGは、次の順序で6項目を記録するシンプルなテキストログです。症状、ログの手掛かり、不具合のある状態での失敗、修正、修正後の成功、スクリーンショット。症状、修正、結果を照らし合わせやすくなります。ただし、項目の順番だけで記録の信頼性が保証されるわけではありません。

ここまで集めた情報は、すべてこの項目に整理できます。コマンドとフォルダーは失敗の項目に、比較したコード状態は修正の項目に記載します。完全なファイルへのリンクは、それぞれの情報源の項目に添えます。別の資料一式を作る必要はありません。

以下は記入例です。実際に検証した結果の報告ではなく、各項目に何を書くかを示しています。自分のログでは、説明を実際の結果に置き換えてください。

症状: ボーナスゲームで、開始時のスコアが0なのに3回そろえると
3点ではなく30点加算されます。毎回再現します: ゲームを開き、
3回そろえて、スコアボードを確認します。

ログの手掛かり: 実行出力のテスト
"three matches give 3 points"に"30 !== 3"とあります。
完全な出力はlogs/test-fail.txtに保存されています。
別途、コードを読んで確認した内容: src/bonus-game/score.jsでは
乗数POINTS_PER_MATCHが10です。これはコードを読んだ結果であり、
テスト出力には数値10はありません。

不具合のある状態での失敗: HEAD a1b2c3d（学習用の識別子）。
作業ツリーはクリーンで、コミットには誤った計算とテストがあります。
フォルダーは/project/bonus-game、コマンドはnpm testです。
package.jsonのscripts.test = node --testです。
"three matches give 3 points"が失敗し、理由は"30 !== 3"、
tests 1、pass 0、fail 1、skipped 0、終了コード1です。
出力の抜粋は上記のとおり。完全な出力はlogs/test-fail.txtです。

修正: src/bonus-game/score.jsでPOINTS_PER_MATCHを10から1に変更。
ほかの変更はありません。HEADは同じa1b2c3dです。
Diff: git diff HEADで作業ツリーとこのコミットを比較し、
diffs/score-fix.diffに保存しました。
テストの期待値は3のままです。

修正後の成功: 上記の修正を加えたコードで、同じフォルダーから
同じnpm testコマンドを実行しました。同じテストが成功しました。
tests 1、pass 1、fail 0、skipped 0、終了コード0です。
完全な出力はlogs/test-pass.txtです。
5回そろえるシナリオは実行していません。

スクリーンショット: screenshots/bonus-score-3.png。
修正後、同じ作業ツリーからhttp://localhost:3000でゲームを開き直しました。
開始時のスコアは0で、3回そろえた後、スコアボードに3と表示されました。
リーダーボードへの結果の保存は確認していません。

例にあるパスはあくまで一例です。完全なログ、diff、画像は、プロジェクト内で同様のファイルを置いている場所に保存します。そのためだけに必須のフォルダー構成を作る必要はありません。

5番目と6番目の項目の最後の行に注目してください。未実施の内容は"未実行"、"未確認"のように、ひとことで明記します。これは怠けたという告白ではなく、結論の範囲を示すものです。こうした行がないログは情報がそろっているように見えて、実際には誰も行っていないことに触れずに済ませてしまいます。

理解度を確認する

タスクには2つの基準があります。初期スコア0から3回そろえると3点加算されること、そして3回そろえた後にインターフェース上で3と表示されることです。手元には次の6つの資料があります。

1. エージェントからの"完了。不具合を修正しました"というメッセージ
2. npm testを実行するよう指示する文
3. 同じテストの実際の実行結果。修正前は失敗し、修正後は成功
4. 乗数の変更を示すdiff
5. 実行方法の説明がない、数値3だけが写った画面
6. 再現したシナリオの記録と、それに紐付いた画面

2つの基準を満たすには、どの資料が十分でしょうか。未検証のまま残ることは何でしょうか。先を読む前に考えてみてください。

解説です。1つ目の基準は3番で確認できます。同じテストを実際に2回実行した結果です。4番のdiffはコードの変更内容を説明しますが、実行結果の代わりにはなりません。変更することと実行することは別です。2つ目の基準は6番で確認できます。初期状態と操作が分かるシナリオ記録に、画面が添付されています。1番と2番は何も裏付けません。完了メッセージには検証可能な根拠がなく、指示はこれから行う操作を説明しているだけです。5番から分かるのは数値が3だったことまでで、加点の理由は確認できません。そして、資料が6つそろっていてもリーダーボードへの保存は未検証です。保存した値を読み戻すシナリオが含まれていません。

このようなログはセッション内で作ることもできます。プロンプトの例を示します。

6項目のEVIDENCE_LOGを作成してください。各結論について、
実際に行った検証、コードの状態、結果の情報源を記載してください。
未実行の検証は別に明記してください。スクリーンショットについては
見えているものだけを挙げ、内部の計算が正しいとは結論づけないでください。

Claude Codeで証拠を集める

作業の流れは次のようになります。

1. エージェントが各基準を具体的な検証に結び付けます。何を、どのコード状態で実行し、何を結果とみなすかを決めます。
2. この環境で実行できる検証を行い、コマンドと生の出力を提示します。
3. 観察結果を添えます。出力の抜粋、完全なファイルへのリンク、再現したシナリオの説明などです。
4. 結論の範囲を明示します。未実行の検証や、手元の資料からは主張できないことを示します。

証拠そのものを確認するのはご自身です。添付ファイルを開いて中身を見て、シナリオが基準に書かれた内容と一致するか照合し、検証結果が見当たらない項目について、ひとつ踏み込んだ質問をしましょう。たいていはこれで、実際に集めた証拠と、きれいに整えられただけの要約を見分けられます。

技術資料: git diff、git stash、Node.js test runner、npm test、Claude Codeでの画像の扱い。