Claude Codeの「完了しました」を確かめる：報告と実際の変更が合っているかの検証

手順1：作業を頼む前に「完了の条件」を渡す

確認は、頼む段階から始まります。完了の定義が曖昧だと、報告も曖昧になります。次のように、実行するコマンドと合格基準を依頼文に入れます。以下は説明用の例で、コマンドは自分のプロジェクトのものに置き換えてください。

ログイン失敗時のエラーメッセージ表示を修正してください。

完了の条件:
- `npm test` が成功すること（失敗していた tests/login.test.js を含む）
- `npm run lint` がエラー0件であること
- 変更するのは src/auth/ と対応するテストだけ。それ以外のファイルは触らないこと

完了報告には次を含めてください:
1. 実際に実行したコマンドと、その出力の要点
2. 変更したファイルの一覧と、各ファイルで何を変えたか
3. 実行できなかった確認、または確認していないこと

3つ目の「確認していないこと」を明示的に求めるのがコツです。報告に書かれなかった未確認事項を、後から探す手間が減ります。

手順2：作業前の状態を残してから、差分を見る

差分で裏取りするには、比較の基準が必要です。作業を頼む前に git status で作業ツリーがきれいか確認し、きれいでなければコミットかstashで退避しておきます。基準が曖昧だと、Claudeの変更と自分の変更が混ざります。

完了報告のあとは、ターミナルで次の順に見ます。

git status            # 変更・新規（未追跡）ファイルの一覧
git diff --stat       # ファイルごとの変更行数の規模
git diff              # 実際の変更内容（新規ファイルは別途開く）

見るポイントは三つです。

• 報告にないファイルが変わっていないか：許可していない設定ファイルやロックファイルの変更は、特に注意します。
• 報告にある変更が実在するか：「Aを修正した」と書かれているのに、差分にAがない場合は差し戻しです。
• 未追跡ファイルの存在：git diff だけでは新規ファイルが出ません。git status で必ず確認します。

なお、Claude Codeには /rewind（空の入力欄でEscを2回）によるチェックポイントがありますが、これは差分確認の代わりにはなりません。公式ドキュメントによると、Bashコマンドだけが変更したファイルは追跡されません。サブエージェントの編集も、通常は復元されません。公式はこうした場合にGitなどのバージョン管理で戻すよう案内しています（Checkpointing）。確認と巻き戻しの土台は、Gitで持つのが安全です。

手順3：実行結果は自分の手元で再現する

Claudeが貼った出力は、証拠として読む価値があります。ただ、重要な変更では同じコマンドを自分で一度実行し、同じ結果になるか見ます。出力が再現できれば、報告と実態が一致している強い根拠になります。

テストが通ったという報告では、テスト自体の差分も必ず確認します。通すためにテストの期待値を書き換えたり、skip を付けたりしていても、「全部通りました」という報告は成立してしまうからです。git diff -- tests/ のように、テスト側の変更だけを絞って見ます。

画面や挙動の変更は、テストが無ければ実際に動かして目で見るしかありません。依頼文に「手順を書き出して」と添えると、人間が追試しやすくなります。

検証チェックリスト：報告の文言と確認方法の対応表

完了報告に出がちな文言ごとに、何を見ればよいかをまとめました。編集部で整理した確認項目の例で、特定のプロジェクトで検証した結果ではありません。

• 「テストが通りました」、確認方法：実行コマンドと出力の提示を求め、自分でも同じコマンドを実行、合格の目安：自分の環境でも成功。件数が妥当、見落としやすい点：テストの削除、skip、期待値の書き換え（git diff -- tests/）
• 「バグを修正しました」、確認方法：修正前に失敗するテストか再現手順があるか確認、合格の目安：修正前は失敗、修正後は成功、見落としやすい点：再現できていない状態での「修正」
• 「ビルド／lintは問題ありません」、確認方法：自分で実行し、終了コードと警告数を見る、合格の目安：エラー0。警告が増えていない、見落としやすい点：lintルールの無効化コメントの追加
• 「◯◯だけ変更しました」、確認方法：git status と git diff --stat、合格の目安：変更ファイルが報告と一致、見落としやすい点：未追跡の新規ファイル、設定やロックファイル
• 「依存関係は追加していません」、確認方法：package.json などの依存定義とロックファイルの差分、合格の目安：差分なし、見落としやすい点：ロックファイルだけの更新
• 「不要なコードを削除しました」、確認方法：削除した名前を grep で検索、合格の目安：参照が残っていない、見落としやすい点：動的な呼び出し、他ファイルからの参照
• 「画面が正しく動きます」、確認方法：実際に起動して操作、またはスクリーンショットを求める、合格の目安：手順どおりに期待の結果、見落としやすい点：正常系だけの確認
• 「確認できませんでした」、確認方法：未確認項目として一覧にし、自分で担当を決める、合格の目安：未確認が残ったまま完了にしない、見落としやすい点：報告の末尾に小さく書かれがち

表の使い方は単純です。報告を文ごとに区切り、該当する行の確認方法を実行します。該当する行がなければ、その文は根拠のない主張として扱い、Claudeに証拠を求めます。

報告が合っていなかったときの依頼文

差分や出力が報告と食い違っていたら、感想ではなく食い違いの事実を渡して再確認を求めます。

報告では「src/auth/ だけを変更」とありましたが、git status には
package-lock.json の変更があります。
1. この変更の理由を説明してください。
2. 不要なら元に戻してください。
3. 戻したあと `npm test` を再実行し、コマンドと出力を貼ってください。

「もう一度ちゃんと確認して」だけの依頼は、Claudeが何を確認し直すかが決まらないため避けます。ファイル名、コマンド、期待する結果を指定します。

毎回の確認を軽くする：条件を仕組みにする

同じ確認を何度も頼むなら、テストコマンドをプロジェクトの指示ファイル（CLAUDE.md）に書いておく方法があります。さらに、Claudeが応答を終える時点で任意のシェルコマンドを走らせるStopフックがあります。公式リファレンスによると、フックが終了コード2を返すか、JSONで decision: "block" を返すと、Claudeは止まらずにフィードバックへ対応して作業を続けます（Hooks reference）。「テストが失敗している間は完了にしない」という条件を、依頼文ではなく仕組みで担保できます。設定の書き方は手元のバージョンの公式ガイドで確認してください。

ただし、自動化しても最終確認は人に残ります。差分の中身が意図に合っているかは、テストでは判定できないからです。Stopフックは終了コード2、またはJSONの decision: "block" でClaudeに作業を続けさせます。フックの入力には stop_hook_active があり、公式リファレンスは停止条件が解消しない場合に備えてこの値の確認などを案内しています（Hooks reference）。

まとめ：確認の最短ルート

1. 依頼文に、完了条件のコマンドと「確認していないこと」の報告を入れる。
2. 作業前に作業ツリーを整理し、完了後は git status と git diff で報告と突き合わせる。
3. 重要な実行結果は自分の手元で再現し、テスト側の差分も見る。

この3つを、上の対応表で報告の文ごとに実行すれば、「完了しました」を根拠のある完了に変えられます。