【Claude Code実践入門 第7回】検証で終わらせる ― 検証を強制する4段階、要約ではなく差分から読む、差分ビュー、フックで止める、新しい目のレビュー、Ansibleの検証の型、連載の早見表と持ち帰り

生成AI
スポンサーリンク
スポンサーリンク

「Claude Code が “NTPの参照先を3台にしました。lintも通りました” と報告してきたので、そのままマージしました。後で見たら、頼んでいない設定も変わっていました」
「変更が多くて、どこから確認すればよいか分かりません。要約を読めば十分ですか」

Claude Code は、作業の最後に、何をしたかを整った文章でまとめてくれます。しかし、きれいな説明は、正しい変更の証拠ではありません。任せる範囲が広がるほど、人の仕事は「書く」から「確かめる」へ移っていきます。

第7回では、連載の5つの柱（作業範囲・操縦・CLAUDE.md・権限・検証）の最後、検証を扱います。検証を強制する4段階、要約ではなく差分から読む順番、Code タブの差分ビュー、フックで止める方法、新しい目でレビューする方法、Ansible での検証の型を見ます。後半は連載全体のまとめとして、チームで使うなら決めておくこと、連載の早見表、持ち帰りの3点を載せます。

検証を強制する4段階

検証を「頼めば通る」状態から「抜けない」状態へ近づける方法は、強さの違う4段階に整理できます。

段階やり方強さ
1プロンプトで「実行して、通るまで直して」と頼む頼むのを忘れると抜ける
2/goal で完了の条件にする（第3回の「/goal：「完了」を条件で渡す」）別の評価役が毎ターン確かめる
3Stopフックで、テストが通らなければ終われないようにする（「フックで止める」の節）コードで強制する
4検証用のサブエージェントやワークフローに反証させる（「新しい目でレビューする」の節）別の目で確かめる

出典は公式のベストプラクティスの節「Give Claude a way to verify its work」です（https://code.claude.com/docs/en/best-practices#give-claude-a-way-to-verify-its-work ）。公式は、Claude は仕事が終わったように見えると止まる、実行できる確認が無いと「終わったように見える」が唯一の手掛かりになり、人が検証の役（verification loop）を担うことになる、と書いています。検証手段を渡す考え方は、連載「Claude活用入門」第5回の「検証手段を渡す」でも扱いました。

どの段階でも、「できました」という報告ではなく、実行したコマンドとその結果を見せさせてください。

Haiku 5.5 を使うとき（軽い作業やサブエージェントなど）は特に注意が要ります。Anthropic のガイドは、Effort が low・medium のとき、Haiku 5.5 は変更を確かめずに「完了」と報告することがある、と注意しています（https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5 の節「Tell coding agents to verify their changes」）。

筆者が第8回・第9回の演習を試したとき、Claude は実装の報告の最初の段落で「stg への --check --diff は接続できず、実際の差分はまだ確認できていない」「lint も1件で不合格」と書いてきました。「できました」で終わらせず、確かめられていないことを分けて書く。この報告を引き出す指示が、段階1〜4の目的です。

要約ではなく差分から読む

Claude は作業の最後に、何をしたかを整った文章でまとめてくれます。しかし、Claude Academy のレッスン「信頼する：監視なしの実行を検証する」は、確認を要約から始めないよう勧めています。読みやすい要約の裏で、実際の差分は予想していなかったファイルに触れていた、ということが起こりうるからです。要約はそれを教えてくれませんが、差分は教えてくれます。

上の枠「Claudeの要約」に、吹き出しのアイコンと「NTPの参照先を3台にしました。lintも通りました。」の文がある。下の枠「実際の差分（git diff）」に3行が並ぶ。1行目は roles/ntp/tasks/main.yml で、右に緑の「計画どおり」。2行目は site.yml（hosts: ntp → all）で、赤い枠の「計画外！」。3行目は --check --diff：changed 3件 で、右に青い「数を確かめる」。その下に赤字で「要約は、予定外の変更を教えてくれない」、黒字で「計画にあったファイル → 計画になかった変更、の順に読む」とある。要約は整っているのに、実際の差分には計画にない site.yml の変更が含まれている例を示す図

確認は、次の順番で進めます。

  • 要約から確認を始めない。要約は予定外の変更を教えてくれない
  • まず、計画に入っていたファイルの差分を読む
  • 次に、計画になかった変更がないかを探す（図の site.yml の hosts: ntp → all が、ここで見つかる）
  • インフラでは、ファイルの差分に加えて、--check --diff の結果がホストに対する差分にあたる。こちらも、changed になった項目が計画どおりかを1つずつ確かめる

きれいな説明は、正しい変更の証拠にはなりません。冒頭の2つ目の相談（どこから確認するか）の答えがこの順番です。

Codeタブの差分ビュー

差分は、Code タブの画面と Git の両方から見られます。出典は https://code.claude.com/docs/en/desktop です。

  • 開き方：Claude がファイルを変えると、セッションの詳細パネルの「Changes」のカードに、+12 -1 のような増減した行数が出る。クリックすると差分ビューが開き、ファイルごとの変更が表示される。キーボードでは Ctrl＋Shift＋D（Mac は Cmd＋Shift＋D）で差分のペインを開閉でき、セッションのタイトルバーの「Changes」からも開ける
  • 行にコメントする：差分の中の気になる行をクリックするとコメント欄が開く。複数書いてから、まとめて送ると、Claude が直す。公式のページは、送るキーを Windows では Ctrl＋Enter と書いている
  • コードのレビューを頼む：公式は、コミットの前に Claude に変更を見直させるには、入力欄に /code-review と入れると案内している。ローカル・SSH・WSL のセッションでは、指摘がファイルごとにまとまった「Code review」のカードに出て、「Walk through in diff」で差分の中を順に見たり、「Apply fixes」でまとめて直させたりできる。「Review code」ボタンで、コンパイルエラー・論理の誤り・脆弱性・明らかなバグに絞って確認させる（書き方の好みは指摘しない）という説明も見かけるが、筆者は公式のページでこのボタンも「絞る」という説明も見つけられていない
  • 「手動」モード：ファイルを変える前に確認の画面が出る。筆者の Code タブの記録では、その場で差分も表示され、選択肢は「拒否」「常に許可」「一度だけ許可」だった
  • 返答の下のまとめ：ファイルを編集した返答の下に「ファイルをN件編集しました」と増減の行数が出て、ファイルごとの差分を開ける（「元に戻す」もできる）、という説明もある。ただし、公式のページにはこのまとめも Undo も見つからず、筆者の個人のアカウントの「ローカル」でも確かめられていない。巻き戻しは第3回の「巻き戻しメニュー」（Code タブは Esc 2回。CLI は /rewind、別名 /undo）
  • Gitで確かめる：Bash で変えたものは、このまとめや差分ビューに出ないことがある（公式の desktop のページは、差分ビューに何の変更が出るかを書いていない）。最後は必ず git status と git diff で確かめる
  • CLI では：公式のコマンド一覧に /diff があり、「作業ツリーの変更（Claude がここまでに行った編集を含む）を確認する」と説明されている

画面の出方は環境で違います。筆者は、Code タブの「ローカル」のセッションで +n -n の表示と差分ビューを確かめられませんでした。CLI の演習では git diff で差分を見ました（第9回の手順5）。差分ビューが出ない環境でも、git diff で同じ内容を見られます。

フックで止める

「たいてい守る」を「飛ばせない」に変えるのがフックです。フックは、決まったタイミングで動くコードです。公式の説明では、同じフックのイベントが、ターミナル・IDE の拡張・デスクトップアプリ（Code タブ）・クラウドのセッションのどこでも動きます。

フックいつ動くか使い道の例（筆者の例）
PreToolUseツールを使う前本番のインベントリを指す実行を止める（確実に止めたいルール）
PostToolUseツールを使った後playbookを編集するたびに ansible-lint を実行する
StopClaudeが作業を終えようとするときlintや構文確認が通らなければ、終わらせない
SessionStartセッションの開始時（compactの後も）作業中の状態の要約をコンテキストに戻す
  • 止めるには、フックが終了コード2で終わる。公式は、ブロックできるイベントで終了コード2を返すと、Claude Code がその動作を止めると書いている。Stop フックの場合は、Claude が止まるのを防ぎ、会話を続けさせる
  • 終了コード1では止まらず、Claudeはそのまま続けます（間違えやすい点です）。公式は、Unix では1が失敗の慣習的なコードだが、フックでは、有効な JSON を出さずに1で終わると止めないエラーとして扱われる（失敗したら動作を止める扱いのフックを除く）、ポリシーを強制したいなら終了コード2を使うと書いている
  • SessionStart は、セッションの開始のしかた（startup・resume・clear・compact・fork）で絞れる。compact の後にも動くので、コンパクトで失われた「作業中の状態」を戻すのに使える

出典は公式のフックのページ（https://code.claude.com/docs/en/hooks ）と、Claude Academy の「Hooks」です。フックの作り方は、続きの連載「Claude Codeフック入門」（全12回、2026年11月28日から）の第2回「フックの仕組み」と、第3・4回「本番を止める」で扱います。公式のドキュメントと、連載「Claude活用入門」第5回の「拡張の仕組み」も参考になります。第6回の「前方一致の落とし穴と、denyの限界」では、確実に止めたいときはサンドボックスか PreToolUse フックを使う、と書きました。deny のルールは境界ではないからです。

新しい目でレビューする

作った本人は、自分の間違いに気づきにくいものです。Claude も同じです。

  • 作った本人は気づきにくい：同じセッションの Claude は、自分のやり方に納得してしまっている
  • 新しい目に頼む：作業の経緯を知らない新しいセッションやサブエージェントにレビューさせると、見落としに気づきやすい
  • 重要な変更ほど：任せきりにした作業、本番に関わる作業では、この手順を省かない
  • 注意：組み込みの Explore サブエージェントは CLAUDE.md を読まない。守ってほしいルールは、頼むときのプロンプトに書く

頼み方の例です。

この差分を、作った経緯を知らないレビュアーとして確認して。
計画にない変更、冪等でないタスク、本番に影響する変更を探して。

公式のベストプラクティスにも、「Add an adversarial review step」の節があります。「タスクを完了とみなす前に、サブエージェントに新しいコンテキストで差分をレビューさせ、抜けを報告させる」という趣旨のヒントです。Explore の件は、公式のサブエージェントのページに、Explore と Plan は CLAUDE.md と git status のスナップショットを読み込まずに始まる（調査を速く安く保つため）と書かれています。

出典：Academy「信頼する：監視なしの実行を検証する」、https://code.claude.com/docs/en/best-practices 、https://code.claude.com/docs/en/sub-agents です。

Ansibleでの検証の型

これまでの内容を、Ansible の作業に当てはめた型です。任せてよい所と、人が決める所を分けます。

検証の手順を6段で示した縦の流れ図。左の列は上から「① ansible-lint」「② --syntax-check」「③ stgに --check --diff」「④ 差分を読む」「⑤ 本実行（prodはaskで確認）」「⑥ 結果の確認・Gitにコミット」で、下向きの矢印でつながる。右の列は担当を示し、①〜③は「Claude」、④は「人」、⑤は「人が承認」、⑥は「Claude＋人」。下の赤い注記は「①〜③は、Claude Codeでは 2>&1 | cat を付けて実行する」、結びは「この手順は、Skillsで「検証スキル」にできる」。
  • ①静的検査：ansible-lint（Claude に任せてよい）
  • ②構文確認：ansible-playbook --syntax-check（Claude に任せてよい）
  • ③差分確認：stg に ansible-playbook --check --diff（Claude に任せてよい）
  • ④差分を人が読む：changed の項目が計画どおりかを確かめる（人）
  • ⑤本実行：人が承認してから実行する。prod は ask で必ず確認が出る（人が承認）
  • ⑥結果の確認と記録：実行後の状態を確かめ、Git にコミットする（Claude と人）
  • 次の一歩：この手順を CLAUDE.md の「完了の定義」に書く（第4回の「チームで共有するCLAUDE.mdのひな形（筆者の例）」）。さらに、Skills にまとめて「検証スキル」にできる

①〜③のコマンドは、Claude Code から実行すると「Ansible requires blocking IO」で止まることがあります（筆者は Code タブと CLI の claude -p の両方で確認しました）。2>&1 | cat を付けるか、出力をファイルにリダイレクトすると動きます。終了コードは cat の0になるので、成否は PLAY RECAP で判断させてください。この癖を CLAUDE.md の「環境の癖」に書いておくと、毎回言わずに済みます（第4回の「書くこと・書かないこと」の表と、ひな形の「環境の癖」）。なお、端末から自分で打つときは起きませんでした。この現象は、公式の ansible-core の porting guide や変更履歴、Claude Code の issue では記述を見つけられていません。

Academy のレッスン「Verification skills」（講座「Claude Code in action」。日本語版は「Claude Codeを実践する」のレッスン3「検証スキル」、5分）は、最初に作るスキルとして検証を取り上げています。日本語版のレッスンの本文には、「経験則としては、同じ複数ステップの指示を2回タイプしたなら、それはスキルだということです」とあります（2026年10月17日に確認）。playbook の作成と実行の依頼の書き方は、連載「Claude活用入門」第4回の「ユースケース② playbookの作成と実行」にあります。

チームで使うなら決めておくこと

ここから先は連載全体のまとめです。チームで Claude Code を使うなら、次の4点を決めておくと役に立ちます。連載「Claude活用入門」第6回の「チームで使うなら決めておきたいこと」と合わせて使ってください。

  • ①CLAUDE.md のひな形：第4回の「チームで共有するCLAUDE.mdのひな形（筆者の例）」に、何を足し、何を削るか。演習（第8回の手順1）で削った行は、チームで持ち寄って比べる
  • ②権限設定のひな形：第6回の「Ansibleの作業での設定例（筆者の例）」を、チームの標準にしてよいか。本番のインベントリの扱い
  • ③フックにすべきルール：作業で、絶対に飛ばしてはいけないものは何か
  • ④共通のスキルにしたい手順：チームで共通のスキルにしたい手順は何か（候補：playbook のレビュー、検証、pptx の作成）

連載の早見表

テーマ押さえること
任せる前に（第1回）コンテキストは毎ターン送り直される。作業ごとに /clear。見ていなかった分だけ検証する
作業範囲（第2回）複雑な作業は「プラン」（Code タブは Ctrl＋Shift＋M、CLI は Shift＋Tab）。計画は実際に読んで直す。1文で言える変更なら計画は省く
操縦（第3回）早めにEsc。2回だめなら /clear。/compact には指示を付ける。Bashの変更は巻き戻せない
CLAUDE.md（第4回）200行未満。具体的に、代わりを示し、強調は少なく。間違えたら「CLAUDE.mdに追加して」
権限（第5・6回）deny→ask→allowの順で、最初に一致したものが決める。前方一致に注意。denyは境界ではない
検証（第7回）要約ではなく差分から読む。証拠を見せさせる。絶対のルールはフックで強制する

持ち帰りの3点

  1. 任せる前に作業範囲を決める：走り出したら早めに止めて直し、2回だめなら /clear
  2. CLAUDE.md は短く、具体的に：間違えたら「CLAUDE.mdに追加して」。絶対のルールはフックに
  3. 「できました」ではなく、証拠と差分で完了を判断する：見ていなかった分だけ検証する

演習は、自分の検証用ホストで、第8回・第9回の手順を試すことです。削った行と詰まったところは、自分の CLAUDE.md や設定に反映してください。

次に学ぶなら

この連載では、Skills の作り方までは扱いませんでした。続きの連載「Claude Codeスキル入門」（全12回、2026年11月3日から）で扱います。次に学ぶなら、Claude Academy の次の教材が公開されています（題と所要時間は、2026年10月20日に日本語版のページで確かめた値です）。

  • コース「Agent Skills入門」（英語では「Introduction to agent skills」。6レッスン、約1時間）：https://academy.claude.com/ja/courses/introduction-to-agent-skills 。英語版のページは https://anthropic.skilljar.com/introduction-to-agent-skills （Skilljar の「Anthropic Academy」）
  • チュートリアル「最初のスキルを作成する」「スキルの共有」（英語では「Creating your first skill」「Sharing skills」。どちらも4分の動画）：https://academy.claude.com/ja/tutorials/creating-your-first-skill 、https://academy.claude.com/ja/tutorials/sharing-skills
  • コース「Claude Codeを実践する」のレッスン3「検証スキル」（英語では「Verification skills」。5分）：https://academy.claude.com/ja/courses/claude-code-in-action/verification-skills

考えてみよう

  1. 最近 Claude Code に任せた作業で、確認を要約から始めていませんでしたか。差分から読むとしたら、計画に入っていたファイルは何で、計画になかった変更はどこを見れば分かりますか。
  2. 作業の中で「絶対に飛ばしてはいけない」ルールは何ですか。プロンプトの頼み、CLAUDE.md、フックのどれで守らせるのが合っていますか。
  3. 検証を強制する4段階のうち、今の使い方はどこまで来ていますか。次に1段上げるなら、何を足しますか。

ヒント：1つ目は「要約ではなく差分から読む」、2つ目は「フックで止める」、3つ目は「検証を強制する4段階」の節を見直してください。

まとめ

  • 「できました」は証拠ではない。実行したコマンドとその結果を見せさせる
  • 検証は4段階で強くする：頼む→/goal→Stop フック→新しい目の反証。頼むだけでは抜ける
  • 確認は要約ではなく差分から。計画にあったファイルを読み、次に計画になかった変更を探す。インフラでは --check --diff がホストへの差分
  • Bash で変えたものは差分ビューにも出ない。最後は git status と git diff
  • 絶対のルールはフックで強制する。止めるのは終了コード2で、1では止まらない
  • 作った本人は気づきにくい。重要な変更は、経緯を知らない新しい目に頼む。Explore は CLAUDE.md を読まない
  • Ansible は、lint・構文確認・stg の --check --diff までを Claude に、差分を読むことと本実行の承認を人に

次回の第8回と第9回は演習です。これまでの内容を、練習用のリポジトリで手を動かして確かめます。

連載「Claude Code実践入門」全9回

  1. 任せる前に知っておくこと
  2. 作業範囲を決める
  3. 走らせながら操縦する
  4. CLAUDE.mdを育てる
  5. 権限モードとauto mode
  6. allow・ask・denyのルールと設定ファイル
  7. 検証で終わらせる（この記事）
  8. 演習（前編）：準備から実装と検証まで
  9. 演習（後編）：巻き戻し・差分・権限と振り返り

コメント

タイトルとURLをコピーしました