ハンズオンガイド Day2

目的

CLAUDE.md の文章で守っている制約を、フックの機械検査へ移せるようになります。対象のバージョンは設定に書く値として扱い、自社の版に差し替えて持ち帰れる形にします。

準備

このリポジトリが対象とする版は PHP 7.4 です。検査で止めるのは、7.4 に無い 8.x の構文です。どれも AI が指示なしで素で書く書き方なので、放っておくと混ざります。

自分で考える　[3min]　AI に触る前に、手元のメモへ3つ書き出してください。自社の CLAUDE.md を持ち込んだ方は、その制約節を横に開いてください。

• 1自社の基幹システムで、これを書かれたら本番で落ちる、という構文を3つ挙げてください。バージョン番号ではなく構文の名前で書きます。
• 2その3つを、禁止の列挙ではなく代替の書き方で1行ずつ書き直してください。「match は使わない」ではなく「switch で書く」の形です。
• 33つのうち、機械で検査できるものに丸を付けてください。丸が付かなかったものは人が見る側に残ります。その理由も1行書きます。

手順

Step 0　代替の書き方を1行足す　[2min]

VSCode で CLAUDE.md の「実行環境の制約」の表を開き、自分で挙げた3つのうち表に無い構文を1行足してください。左の列に使えない書き方、右の列にこの環境での書き方を書きます。3つとも載っていた方は、右の列の言い方を自社の言葉に直してください。

Step 1　フックが無い状態で頼む　[3min]

• 1VSCode で dl-training-app を開き、画面左下のステータスバーのブランチ名が ex/p3-yamada になっていることを確かめてください。違う名前なら、ブランチ名をクリックして一覧から ex/p3-yamada を選びます。main から切ると、Day1 に足した deny と PreToolUse が入りません。
• 2もう一度ブランチ名をクリックし、「新しいブランチの作成」で ex/p4-yamada を作ってください。yamada はご自身のユーザー名に置き換えます。いま乗っている ex/p3-yamada から切られます。
• 3VSCode で .claude/settings.json を開き、"hooks" の中に "PostToolUse" がまだ無いことを確認してください。
• 4Claude Desktop を開き、セッション開始時のプロンプト領域で Project folder に dl-training-app を選んでください。入力欄に次をそのまま送ります。

  app/libraries/util.php の h() を、引数が null のとき空文字を返すように match 式で書き直してください。

• 5編集が通ったことを確認してください。差し戻しは起きません。CLAUDE.md には制約が書いてありますが、止める力は持っていません。

こう見えていれば正しい状態です。h() は util.php の冒頭にある3行の関数で、書き換わるのはこの1行です。差分は VSCode のソース管理ペインでファイル名をクリックすると開きます。

- return htmlspecialchars((string)$s, ENT_QUOTES, 'UTF-8');
+ return match (true) {
+     $s === null => '',
+     default => htmlspecialchars((string)$s, ENT_QUOTES, 'UTF-8'),
+ };

Step 2　PostToolUse に登録する　[3min]

• 1VSCode で .claude/settings.json の "hooks" に次のブロックを足してください。.claude/settings.example.jsonc の同じブロックと一字一句同じです。

    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-phpver.ps1"]
          }
        ]
      }
    ]

足す場所は "hooks": { と、それを閉じる } の間です。プチ演習3 で PreToolUse を入れた方は、"PreToolUse": [ ... ] を閉じる ] の直後にカンマを1つ置いてから、その下に貼ります。"matcher": "Edit|Write" は「Edit と Write の2つのツールの後だけ走らせる」という意味です。command に実行ファイル、args に引数を分けて書く形なので、パスに空白や日本語が入っても引用符の問題が起きません。

• 2保存したら、Claude Desktop で Ctrl+N を押して新しいセッションを開いてください。settings.json はセッションの開始時に読まれます。登録されているかは、VSCode で settings.json を開き、"hooks" の中に PreToolUse と PostToolUse が1つずつ並び、赤い波線が無いことで確かめます。

Step 3　同じ依頼をもう一度出す　[3min]

• 1ソース管理ペインで app/libraries/util.php の行にカーソルを合わせ、右側の矢印アイコン(変更の破棄)で Step 1 の変更を戻してください。戻さないと、Claude が編集せずに「対応済みです」と答えることがあります。
• 2Step 1 と同じ文をもう一度送ってください。文面は変えません。
• 3編集の直後にフックが走り、標準エラーの内容がモデルへ返ります。Edit ツールの結果の下に、終了コード 2 で止めた旨と、フックが標準エラーに書いた次の4行が返ります。2行目の先頭のパスと行番号は、ご自身の clone 先で変わります。

[check-phpver] code that PHP 7.4 cannot run:
  C:\...\app\libraries\util.php:9  match expression (8.0)  ->  use switch and assign in each branch
Rewrite these lines with the form shown after the arrow, then edit again.
Arrow functions, typed properties, ?? and the spaceship operator are all fine on 7.4.

• 4そのまま待つと、モデルが switch の形へ書き直して編集をやり直します。人が指示を足さずに戻ることを確認してください。書き直しが終わったら、ソース管理ペインの差分に match が残っていないことを見ます。

Step 4　検査そのものにテストを足す　[3min]

• 1VSCode で .claude/hooks/tests/fixtures/ に、str_ends_with() の呼び出しを1行だけ含む見本を ng_str_ends_with.php.txt という名前で作ってください。隣にある ng_str_contains.php.txt を開くと形が分かります。1行目が <?php、2行目以降は ASCII だけで数行です。中身は例えば次の形です。

  <?php
  // str_ends_with() arrived in PHP 8.0. php -l on 7.4 does not report it.
  function has_suffix($haystack, $needle)
  {
      return str_ends_with($haystack, $needle);
  }

• 2.claude/hooks/tests/cases.json の cases 配列へ、次の1件を足してください。

{
  "id": "phpver-ng-str-ends-with",
  "hook": "check-phpver",
  "fixture": "ng_str_ends_with.php.txt",
  "input": { "tool_name": "Write", "tool_input": { "file_path": "__FIXTURE__" } },
  "expect_exit": 2,
  "note": "str_ends_with is 8.0+. On 7.4 it parses but dies at runtime."
}

この1件は、配布済みの phpver-ng-str-contains と同じ側の性質を持ちます。str_ends_with() の呼び出しは構文としては正しいので php -l を通ります。7.4 には関数が無いので、落ちるのは実行時です。構文検査を通り抜けるものがあるので、フック側は関数名の一覧も見ています。正規表現の列挙だけで守ろうとすると、ここが抜けます。

• 3直前の要素の末尾にカンマが入っているかを見てください。JSON の配列は要素の間をカンマで区切り、最後の要素の後ろには付けません。
• 4Claude Desktop の統合ターミナルを開いてください。右上の >_ アイコンか、Ctrl とバッククォートです。セッションの作業ディレクトリで開くので、移動は要りません。ここでテストランナーを回します。

  powershell -NoProfile -ExecutionPolicy Bypass -File .claude\hooks\tests\run_cases.ps1

Step 5　MR を出す　[3min]

• 1ソース管理ペインで変更されたファイルを確かめてください。app/libraries/util.php は Step 3 で switch に戻った形のはずです。差分に match が残っていないことを見たら、util.php は 変更の破棄 で元に戻します。h() の書き換えは差し戻しを見るための題材なので、コミットには入れません。
• 21つの変更意図ごとに1コミットで、3回に分けます。ソース管理ペインでファイル名の右の + を押して1つだけステージし、メッセージを書いてコミットします。順は、Step 0 の制約節、フックの登録、テストの追加です。
• 33回コミットし終えたら、ソース管理ペインの「変更の同期」（または「ブランチの発行」）を押して push してください。
• 4ブラウザで GitLab のプロジェクトを開き、Merge requests から New merge request を選んでください。ソースに自分のブランチ、ターゲットに main を指定します。
• 5MR の Pipelines タブで、パイプラインが動き出したことだけ確認して次へ進みます。結果はプチ演習5 の途中で見に戻ってください。

達成状態

テストランナーの末尾がこう出ていれば、検査側は完成です。配布時点の22件に、プチ演習3 で足した1件と今回の1件が乗ります。プチ演習3 のケースを足していない方は23件です。

PASS  phpver-ng-str-ends-with  (exit 2)

24 cases: 24 passed, 0 failed

解説と補足

なぜこれをやるか　CLAUDE.md に制約を書いても、数ターン進むと対象外の構文が戻ってきます。CLAUDE.md は文脈なので、会話が伸びるほど制約が薄れます。同じ制約を PostToolUse フックへ移すと、書き換えられた瞬間に差し戻されます。D2-01 の言い方では、[A] だけで守っているものを [M] へ移す作業です。移した後も CLAUDE.md の制約節は消しません。フックは止めるだけで、代わりの書き方までは教えないためです。

設定はどちらから使っても同じ　Claude Desktop と CLI は同じ設定ファイルを読みます。.claude/settings.json に登録したフックと CLAUDE.md は、どちらで起動しても同じように効きます。Desktop 用と CLI 用に分けて書く必要はありません。

PostToolUse の動き　Edit や Write でファイルを書き換えた直後に自動で走る小さなスクリプトです。終了コード 2 を返すと、標準エラーに書いた文がそのままモデルへ差し戻され、モデルは書き直しを始めます。終了コード 0 なら何も起きません。登録先は .claude/settings.json の "hooks" で、プチ演習3 の PreToolUse と同じ場所に並べます。

Mac または bash を正にする方　"command" を "bash" に、"args" を ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-phpver.sh"] に差し替えてください。判定の中身は .ps1 と同じです。bash 版は jq を使うので、入っていないと標準エラーに1行出して素通りします。テストランナーも bash .claude/hooks/tests/run_cases.sh で、出力の形は同じです。

見本ファイルに日本語を入れない理由　.ps1 側が CP932 で読み違えて誤検知します。.ps1 と見本ファイルは ASCII だけで書く約束です。

症状	手当て
登録したのにフックが動かない	settings.json の JSON が壊れていると、ファイルごと黙って無視されます。カンマの付け忘れが大半です。VSCode の赤い波線と、止まるはずの操作が止まるかの2つを見てください。保存前に開いたセッションで試している場合は、Ctrl+N で新しいセッションを開いてから試します。
編集していないのに反応しない	フックは編集の直後にしか走りません。Edit ツールの表示が出たかを先に見てください。
FAIL ... (expected 2, got 0)	見本に str_ends_with( が入っていないか、コメント行の中にだけ書いています。コメントは検査の前に取り除かれます。
fixture not found	ファイル名の綴りが cases.json と合っていません。
パイプラインが pending のまま	全員が同時に push すると順番待ちに入ります。異常ではありません。待ち方は「困ったとき」の pending の項にあります。

追加と考察　時間が余った方は、Claude に「sed で同じ行を書き換えてください」と頼んでください。Edit|Write の matcher は Bash 経由のファイル変更を拾わないため、フックは走りません。この抜け道を塞ぐなら、Stop フックで作業ツリーを走査する、FileChanged を使う、CI の lint-phpver に任せる、の3つのどれに置くかを決めて台帳に書いてください。3つ目を選ぶのは手抜きではありません。手元で全部塞ごうとすると、検査の実行時間だけが伸びます。

発展課題　PowerShell 5.1 の既定エンコーディングは CP932 で、.ps1 に非 ASCII を1文字でも書くと実行時のメッセージが壊れます。セッション開始時の sessionstart_verify は非 ASCII のバイト数を数えて報告しますが、報告が出るのは次にセッションを開いたときです。ASCII だけでできているかを検査する処理を、同じ PostToolUse に足してください。対象は .ps1 に限ります。破ると実害が出る契約は、気づける場所ではなく止まる場所に置く、という原則をフック自身へ適用する形です。

影響範囲

自社ハーネスへ持ち帰るときの置き場所は、次の表で決めてください。D2 と smart3pm のどちらを正にするかは D1-12 の台帳に書いた判断に合わせます。

目的

レビューを読んで判断していた部分を、数えるだけの作業に変えられるようになります。止める線を自分で決め、手元と CI で同じ判定になる状態にします。

準備

API キーは使いません。判定スクリプトに流す入力は、配布の見本ファイルと、Claude Desktop に書き出させたレビューの2つです。

自分で考える　[3min]　スクリプトを触る前に、メモへ3つ書き出してください。

• 1自社の MR を止めてよい指摘はどれかを、重大度の言葉で決めてください。.claude/review.schema.json では、P0 が動かないか壊す、P1 が実環境で落ちるか外部入力が素通し、P2 が指示との不一致と波及漏れ、P3 がそれ以外です。
• 2判定できない入力（重大度が知らない値、findings が無い）を、通すか落とすかを決めてください。
• 3止める線を1段下げたとき、1日あたり何件の MR が止まると困るかを見積もってください。

手順

Step 1　見本ファイルを置く　[2min]

• 1Windows のエクスプローラーで、配布物一式の 20_Day2の演習/プチ演習5_レビュー出力のJSONゲート を開いてください。
• 2findings_sample.json を、VSCode のエクスプローラーの dl-training-app のいちばん上（ルート）へドラッグしてコピーしてください。
• 3VSCode でそのファイルを選んで F2 を押し、名前を findings.json に変えてください。中身は P0 1件、P1 1件、P2 2件で、最後の1件の confidence が 0.5 です。

Step 2　既定の閾値で回す　[3min]

• 1統合ターミナルで、次の2行を上から順に打ってください。既定は findings.json と閾値 P1 です。

  powershell -NoProfile -ExecutionPolicy Bypass -File ci\gate.ps1
  $LASTEXITCODE

• 21行目を Enter で実行してから、2行目を打ってください。2つを1行につなげると、$LASTEXITCODE が判定スクリプトの引数として渡り、1 という名前のファイルを探しにいきます。
• 31行目の出力の先頭が gate: threshold=P1 total=4 blocking=2、2行目の終了コードが 1 であることを確認してください。CI はこの数字だけを見て、0 なら通し、それ以外なら落とします。

Step 3　閾値を1段下げる　[2min]

• 1閾値を P2 にして、同じ findings.json で回してください。

  powershell -NoProfile -ExecutionPolicy Bypass -File ci\gate.ps1 -Threshold P2

• 2blocking が 2 から 4 に増えることを確認し、増えた2件を読んでください。
• 3増えた指摘のうち、自社なら本当に MR を止めるものが何件あったかを数え、台帳に書いてください。

Step 4　判定できない入力を流す　[2min]

• 1VSCode で findings.json の P2 の1件の "severity": "P2" を "severity": "high" に書き換えて保存し、Step 2 の2行をもう一度打ってください。blocking が 3 に増えます。知らない重大度は落とす側に数えるためです。
• 2書き換えを "P2" に戻してください。

Step 5　自分の差分のレビューを流す　[3min]

• 1Claude Desktop の入力欄に次をそのまま送ってください。書き出しまで1分前後かかります。

  main との差分をレビューしてください。判定の基準は REVIEW.md、出力の形は .claude/review.schema.json に従い、結果をリポジトリのルートに findings-mine.json として書き出してください。説明は本文に書かず、ファイルだけを作ってください。

• 2Write ツールの確認が出たら承認してください。
• 3統合ターミナルで、書き出したファイルを判定にかけてください。

  powershell -NoProfile -ExecutionPolicy Bypass -File ci\gate.ps1 -Path findings-mine.json
  $LASTEXITCODE

• 4キーの欠けや形の崩れがあれば、判定スクリプトが終了コード 1 で落とします。落ちた場合は、標準エラーの1行で何が足りなかったかを読んでください。findings.json と findings-mine.json はコミットしません。

達成状態

見本ファイルを閾値 P1 で回すと、1行目がこう出て終了コードが 1 になります。続く2行は、止めた P0 と P1 の指摘です。

gate: threshold=P1 total=4 blocking=2

閾値 P2 では gate: threshold=P2 total=4 blocking=4 になり、終了コードは同じく 1 です。止めたときの最後の行は gate: blocked. fix the findings above or lower the threshold on purpose. です。.ps1 は ASCII だけで書く決まりなので、スクリプトが出す文が英語なのは正常です。

解説と補足

なぜこれをやるか　AI のレビューを文章で受け取っている限り、通すか止めるかは毎回人が読んで決めます。出力を JSON に固定すると、そこから先は数えるだけの作業になります。同じ判定が D2-05 で CI のゲートジョブ ai_gate になります。

判定の置き場所　3本ありますが、考え方は1つです。ci/ai_gate.sh が CI 側、ci/gate.ps1 が手元の PowerShell 版、ci/gate.sh がその bash 版です。3本とも、入力が無い・壊れている・findings の配列が無い・知らない重大度、のどれでも落とします。

受け取る JSON の形　必須キーは severity、confidence、file、line、message、category の6つで、それを findings の配列に入れます。Step 5 で指摘が0件だった方は、判定を確かめるために手で1件書いてください。

{
  "summary": "設定ファイルとフックの登録を中心に4点を確認し、1件指摘しました。",
  "findings": [
    {
      "severity": "P1",
      "confidence": 0.9,
      "file": "app/libraries/util.php",
      "line": 18,
      "message": "h() の引数が未定義のときの扱いが変わっています。呼び出し側のビューで未定義キーが通るようになるため、影響範囲を確認してください。",
      "category": "spec-mismatch"
    }
  ]
}

bash 側で回す場合　bash ci/gate.sh findings.json のあと echo $? で同じ数字が見えます。閾値は引数の位置で bash ci/gate.sh findings.json P2 です。jq が要ります。

症状	手当て
gate: cannot parse JSON で落ちる	ファイルを PowerShell の > で書き出しています。PowerShell 5.1 の > は UTF-16 で書き出すので、Out-File -Encoding utf8 で作り直してください。
gate: no findings array in ... で落ちる	JSON の一番外側に findings の配列がありません。Step 5 の書き出しでキー名が変わったか、別の形で包まれています。
引数 'findings.json' を受け入れる位置指定パラメーターが見つかりません	2つのコマンドが1行につながっています。別の行に分けます。
gate: findings file not found: 1	$LASTEXITCODE を同じ行に続けています。次の行で単独で打ちます。
gate: findings file not found: findings.json	見本ファイルがまだ findings_sample.json の名前のままか、ルート以外のフォルダに置かれています。Step 1 の2と3をやり直してください。
引用符が全角になっている	チャットやメールを経由すると自動で変換されることがあります。貼り付け後に半角か確かめます。

この時点の REVIEW.md は4つの見出しだけで中身が空です。中身を書くのはハンズオン2 の Step 1 です。ここでは基準のファイルを渡す形だけを作り、判定の中身はスキーマの重大度の説明に任せます。

研修後に自分の API キーで CLI から試す場合

研修では API キーを配らないので、当日はこの経路を使いません。スキーマを守らせること自体をツール側に任せたいときの形です。--bare を付けると ANTHROPIC_API_KEY が要ります。

Windows PowerShell 5.1 では、そのままでは2か所で壊れます。1つは文字コードで、git diff main からパイプで渡す差分の日本語が ? になります。先頭の1行で UTF-8 に揃えます。もう1つは引数の " で、5.1 はネイティブコマンドへ渡す引数の中の " をそのまま渡さないので、REVIEW.md やスキーマの JSON を文字列で引数に入れると途中で割れます。

$OutputEncoding = [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false
git diff main | claude --bare -p "この差分をレビューし、指摘をスキーマの形で返してください。" --output-format json --json-schema ((Get-Content .claude\review.schema.json -Raw -Encoding UTF8) -replace '"','\"') | ConvertFrom-Json | Select-Object -ExpandProperty structured_output | ConvertTo-Json -Depth 10 | Out-File -Encoding utf8 findings-cli.json

--output-format json の出力は外側に包みがあり、指摘は structured_output の中に入ります。包みのまま判定スクリプトに渡すと、findings の配列が無いので落ちます。

追加と考察　同じ差分を、履歴を切った新しいセッションでもう一度レビューさせてください。読むのは1点だけです。同じ差分で重大度が揺れていないかどうか。揺れているなら、揃えるのは基準の文面です。D2-05 の前半で Important の定義を書くときに、ここが1つ決まります。

発展課題　2つあります。1つ目は確信度の下限です。いまの gate.ps1 は confidence を見ていません。param に [double]$MinConfidence = 0.0 のような引数を足し、重大度を数える前に下限に満たない指摘を除き、除いた件数を1行出す形にしてください。見本ファイルで下限を 0.8 にすると、確信度 0.5 の1件が外れます。CI の ai_gate.sh は GATE_MIN_CONFIDENCE で同じことをしています。2つ目は、閾値に届かなかった指摘の残し方です。P2 以下を MR のコメント1本にまとめて残す処理を考えてください。指摘のたびにコメントを増やすと、小さな改修ほど読む量が増えるという、いま解こうとしている課題そのものを再生産します。

影響範囲

Day1 では、同じ変更を3通りで読ませると指摘の中身が変わることを見ていただきました。ここではその先で、指摘の置き場所を変えます。機械で判定できるものは CI へ、人の判断が要るものだけを AI の出力に残します。終わると、レビュー基準の実物(REVIEW.md)、観点を分けた3本のレビュアー、P0/P1 で合流を止める CI ゲートが、同じ1本の MR の上でつながります。

• REVIEW.md の4つの見出しが埋まり、.claude/known_issues.md に3件ある
• 3本のレビュアーの findings が別々に残り、検出率とノイズ率の数字が出ている
• 足したテストが、実装前のパイプラインで赤だった履歴が MR に残っている
• ai_gate が1回赤になり、その出力と指摘ごとの採否と理由が MR に書いてある
• 最後の push で走った2本のパイプラインが緑になっている。ブランチ用(lint と test の4ジョブ)と MR 用(ai_review と ai_gate)の2本です

提出先は GitLab の Merge Request です。ブランチ名は共通の進め方 STEP 2「ブランチ名の形」に合わせて ex/h2-<ユーザー名> にし、Step 1 から Step 3 までの成果物を同じブランチに載せて1本の MR で出します。

紙かメモに書き出してください。ここを AI に相談してから始めると、出てきた案を評価する基準が手元に残りません。

• 1機械判定できる観点を3つ挙げます。CI の lint-phpdev と lint-phpver が既に見ているものは、AI に重ねて言わせる必要がありません。
• 2直近の改修で見送った指摘を3件思い出し、見送った理由を1行ずつ書きます。
• 3「機能テストの無い変更は Important として報告する」を自社の基準に入れるかどうかを決めます。
• 4合流を止める重大度の下限を決めます。P0 だけか、P1 までか。Step 3 の GATE_LEVEL がこの値になります。

演習リポジトリの REVIEW.md は、4つの見出しだけがあって中身が空です。ここが AI レビューの正になります。

• 1VSCode の画面左下の表示が ex/p4-<ユーザー名> で、ソース管理ペインに未コミットの変更が残っていないことを確認します。違うブランチなら、ブランチ名を押して一覧から ex/p4-<ユーザー名> を選びます。そのあとブランチ名を押し、新しいブランチの作成 で ex/h2-<ユーザー名> を作ります。
• 2VSCode で REVIEW.md を開きます。埋める順番は Do not report、Nit の上限、Important の定義、Always check です。
• 3Do not report に、自分で考える(1)で挙げた3つを移します。CI の lint が見ている範囲は、ここに入れます。
• 4Nit の上限 に件数を数字で書きます。「5件までを1つのコメントに」のように、まとめ方も書きます。
• 5Important の定義 を3件から5件に絞ります。lint-phpver が見ている範囲(PHP 7.4 に無い構文と関数)は手順3で Do not report に入れたので、ここには入れません。書き出しに迷ったら、下の折りたたみ「Important の出発点の例」を開いてください。
• 6Always check に、差分に出ていなくても毎回見させることを書きます。自分で考える(3)の判断をここに入れます。
• 7.claude/known_issues.md を新規に作り、自分で考える(2)の3件を K-001 から番号を振って書きます。1件は「場所」「指摘の内容」「見送った理由」の3行です。
• 8REVIEW.md の Do not report から、この台帳を1行で参照します。
• 9VSCode の ソース管理 ペイン(左サイドバーの枝分かれアイコン)を開き、REVIEW.md と .claude/known_issues.md の2つだけをステージに上げます。メッセージ欄に「handson2: レビュー基準の初版と既知の許容の台帳」と書いて コミット を押します。

当てる先は、実装後の差分ではなく今の main のコードです。Issue #2 と #3 の欠陥が入ったままの状態に当てるので、既に分かっている欠陥をどれだけ拾うかが、そのまま数字で出ます。

• 1VSCode で .claude/agents/ の3本を開きます。security-reviewer.md、spec-reviewer.md、test-gap-reviewer.md です。frontmatter の model と effort が3本とも違うことを確認してください。
• 23本の「見るもの」節を、Step 1 の REVIEW.md に合わせて直します。Do not report に入れたものが「見るもの」に残っていたら消します。
• 3手順2 を保存し、Claude Desktop でこのプロジェクトを開きます。画面左上のプロジェクト名から演習フォルダを選びます。
• 4Claude Desktop の入力欄に、次をそのまま貼って送信します。

  security-reviewer と spec-reviewer と test-gap-reviewer の3つを並列で起動してください。
  対象は app/controllers/stock_ctl.php の assign() と、
  app/controllers/estimate_ctl.php の index() です。
  関連する Issue は _issues/issue-2.md と _issues/issue-3.md にあります。
  3本の findings を、レビュアーごとに分けてそのまま出してください。
  要約もまとめもしないでください。
  出し終えたら、3本の結果をそれぞれ findings-security.json、findings-spec.json、
  findings-testgap.json という名前でリポジトリのルートに保存してください。

• 5動いている間に、右上の ⋮ メニューの バックグラウンドタスク を開きます。3本が同時に動いていることと、モデル名が3本とも違うことを確認します。終わるまで数分かかります。
• 63本の結果が返ったら、VSCode で3つの JSON を開き、file と line で突き合わせます。同じ場所を何本が指摘したかを数えます。この3ファイルは Step 3 の手元判定でも使います。コミットには入れません。
• 7検出率とノイズ率を出します。検出率は、Issue #2・#3 の「現状」節に挙がっている欠陥の件数を分母、当てた件数を分子にします。欠陥として数えるのは、直さないと誤動作するものです。「条件の組み立てが index() の中にしかない」「CSV の入口がまだ無い」のような設計と未実装の話は数えません。ノイズ率は、指摘の総数を分母、仕込み欠陥以外の件数を分子にします。何を分母に入れたかも記録に残してください。
• 8VSCode で .claude/skills/review-route/SKILL.md を新規に作り(フォルダも新規)、変更規模でレビュアーを選ぶ手順を書きます。50行未満は review-light、50行以上または DB・権限・外部連携に触る変更は review-full、観点を分けたいときは3本を並列、の3分岐です。先頭に次の frontmatter を置き、その下に本文を書きます。

  ---
  name: review-route
  description: 変更の規模でレビュアーを選びます。
  ---

• 9ソース管理ペインで .claude/agents と .claude/skills/review-route をステージに上げ、「handson2: 観点別レビュアーと振り分けの skill」でコミットします。findings-*.json は手元の記録なのでステージに上げません。

{
  "summary": "外部入力の経路を 6 箇所追い、到達するものが 3 件ありました",
  "findings": [
    {
      "severity": "P0",
      "confidence": 0.9,
      "file": "app/controllers/estimate_ctl.php",
      "line": 23,
      "category": "sql-injection",
      "message": "date_from を SQL へ文字列連結しています。db_select の第2引数にプレースホルダで渡してください"
    }
  ]
}

順番を1つだけ入れ替えます。実装より先にテストを送って、赤くなるところを見ます。赤くならないテストは、通っても何も保証しません。CI の履歴に赤が残っていることが、そのテストが今のコードを見ていた証拠になります。

• 1VSCode の画面左下で、ブランチが Step 1 で切った ex/h2-<ユーザー名> のままであることを確認します。
• 2VSCode で .gitlab-ci.yml を開き、ai_gate: で始まるブロック(# --- gate --- の見出しの下)の最後の行 allow_failure: true を1行まるごと消します。他の行のインデントは変えません。
• 3同じファイルの先頭近く、variables: の下にある GATE_LEVEL: "P1" を、一度だけ GATE_LEVEL: "P2" にします。ゲートが本当に止めることを1回見るための仮の値で、手順11 で戻します。

• 4Issue #3 の受入条件3を読み、date_from の値が条件として使われないとき一覧に何件出るかを、先に紙に書きます。db/seed.sql の見積は15件です。
• 5Claude Desktop にテストを1本頼みます。

  tests/phpunit/EstimateSearchTest.php に1本足してください。
  date_from に 2026-09-02' AND '1'='1 を入れたとき、一覧が15件(全件)出ることを確認します。
  修正前のコードでは3件になって落ちます。
  既存の5本と同じ書き方にそろえてください(capture_view と count_list_rows を使う、$_GET は setUp で初期化済み)。
  実装側のファイルは、この手順では変更しないでください。

• 6ソース管理ペインで、.gitlab-ci.yml だけをステージして1コミットにします。Step 2 の成果物は Step 2 の手順9 でコミット済みです。.gitlab-ci.yml を入れ忘れると CI 側は allow_failure: true のままで、ゲートは一度も落ちません。メッセージは「handson2: ai_gate の allow_failure を外し GATE_LEVEL を仮に P2 にする」です。
• 7テストだけをさらに別のコミットにして、ソース管理ペインの 変更の同期 を押します。メッセージは「handson2: 期間検索が条件として使われないことのテストを追加」です。
• 8ブラウザで GitLab の演習プロジェクトを開き、画面上部に出る Create merge request を押します。出ていない場合は左のメニューの Code から Merge requests を開き、New merge request で元を自分のブランチ、先を main にして作ります。
• 9MR の Pipelines タブを開きます。branch のラベルが付いた行で test-phpunit が赤になっていることを確認します。赤いジョブ名をクリックするとジョブの画面が開くので、落ちた出力を MR の説明の「テスト」欄に貼ってください。
• 10Issue #3 の受入条件1と、受入条件2 のうち private メソッドの切り出しまでを実装します。そのメソッドが返す2つの値(WHERE 句の文字列とパラメータ配列)の形を、先にご自身で紙に書いてから Claude Desktop に渡してください。依頼文に入れるのは、対象ファイル(app/controllers/estimate_ctl.php だけ)、Issue #3 の「期待する振る舞い」の 1 から 3 をそのまま、紙に書いたメソッドの戻り値の形、テストファイルは触らないこと、の4点です。
• 11ソース管理ペインでコミットして 変更の同期 を押します。branch の行で test-phpunit が緑になり、merge request の行で ai_review が MR にコメントを1本置き、ai_gate が赤になります。緑のままなら下の「ai_gate が緑のままで、一度も落ちません」を開いてください。

• 12落ちた指摘を1件ずつ、即修正・要調査・将来課題・意図した設計の4つに仕分け、MR の説明の「人が判断した採否」の表に書きます。直すものを直し、「意図した設計」にしたものは Do not report に入れるかどうかを検討します。
• 13.gitlab-ci.yml の GATE_LEVEL を "P1" に戻し、修正と合わせてコミットして同期します。この push で2本のパイプラインが走ります。branch の行のブランチ用(lint-phpdev、lint-phpver、test、test-phpunit)と、merge request の行の MR 用(ai_review と ai_gate)の両方が緑になったことを確認します。

1) EstimateSearchTest::testIgnoresMalformedDateFrom
Failed asserting that 3 matches expected 15.

/builds/dlive-training/dl-training-app/tests/phpunit/EstimateSearchTest.php:81

FAILURES!
Tests: 6, Assertions: 9, Failures: 1.

しきい値 P2 以上、確信度 0.0 以上の指摘を数えます。
confidence の無い指摘は 1.0、P0〜P3 以外の severity は P0 として数えます。
P1: 1 件 / P2: 3 件 / P3: 2 件

ゲートで止めた指摘 4 件
  [P1] app/controllers/estimate_ctl.php:36 date_to が条件に使われず、範囲の上限が効きません
  [P2] app/controllers/estimate_ctl.php:41 条件の組み立てが index() の中にしかありません
  ...

直すか、直さない理由をMRのコメントに書いてから再実行してください。
ERROR: Job failed: exit code 1

powershell -NoProfile -ExecutionPolicy Bypass -File ci\gate.ps1 -Path findings-security.json -Threshold P2

ai_gate が緑のままで、一度も落ちません

先に、.gitlab-ci.yml の変更がブランチに載っているかを見てください。GitLab の MR の Changes タブに .gitlab-ci.yml が出ていなければ、手順6 のコミットが抜けています。次に allow_failure: true の行が残っていないかを確認してください。残っていると、ジョブは赤くなりますがパイプラインは緑のまま通り、ジョブ名の横に Allowed to fail と出ます。

ai_review のログに ANTHROPIC_API_KEY が未設定 と出ている場合は、指摘が 0 件なので落ちません。その間は、上の「手元で先に同じ判定をかける方法」で進めてください。

行を消しても落ちない場合は、GATE_LEVEL を "P2" にして回し直してください。それでも落ちないのであれば、REVIEW.md の Do not report が広すぎます。何を書かせないと決めたかを読み直すところが、この演習の本題です。

「機能テストを足せばリファクタを安全に進められる」という見立てを、ここで1回だけ実測します。緑が出たあとに壊してみる手順です。

• 1手順10 で入れた「YYYY-MM-DD の形に合わない値を条件に使わない」判定を、1行だけ外したコミットを作ります。他は変えません。
• 2同期してパイプラインを見ます。lint-phpdev、lint-phpver、test は緑のままです。既存の5本のテストも緑で、手順5で足した1本だけが赤になります。
• 3この1本が無ければ、同じ壊れ方が合流まで届いていたことを確認します。
• 4確認できたら戻します。ここはコマンドを使います。コミット単位の打ち消しは画面から行えないので、Claude Desktop の中のターミナルで打ちます。

  git revert --no-edit HEAD

  --no-edit を付けると、コミットメッセージを編集する画面を開かずに打ち消しのコミットができます。そのあとソース管理ペインで 変更の同期 を押します。

マージまでは進めません。マージの判断は Day2 の最後にまとめて扱います。

演習リポジトリでの置き場所と、自社ハーネスへ写すときの置き場所です。D2 は PowerShell が正、smart3pm は bash が正なので、判定スクリプトだけ行き先が分かれます。

Step 2 で数えた値を、配布の 計測表_Day1_Day2.md の「Day2 検出率」の表へ書き込んでください。表の行と列は次のとおりです。記入は計測表側で行います。

書き終えたら、次の3つを1行ずつ書いてください。全体共有ではここを聞きます。

• 1Day1 の3通りレビューで数えた指摘件数と比べて、増えたか減ったか。減ったのであれば、それは REVIEW.md のどの行が効いた結果か。
• 23本のうち、既知の欠陥を1件も拾えなかったレビュアーがいたか。いた場合、観点の書き方と当てた対象のどちらに原因があるか。
• 3ゲートで止まった指摘のうち、直さない判断をしたものの割合。この割合が高いのであれば、GATE_LEVEL か Important の定義 のどちらかが現場に合っていません。

早く終わった方から、上から順に進めてください。全部やる必要はありません。

• 1Issue #3 の受入条件4(tests/phpunit/EstimateCsvTest.php の3本)を満たすところまで実装します。ここで受入条件2 の残り(csv_text() から条件組み立てのメソッドを呼ぶ)も満たします。テストを先に出して赤を見る順番は同じです。
• 2Issue #2(在庫引当のトランザクションと行ロック)を、同じ流れで MR まで通します。ai_review は MR の差分しか読まないので、stock_ctl.php の指摘が出るのはこの MR からです。
• 3.gitlab-ci.yml の variables: に GATE_MIN_CONFIDENCE: "0.6" を1行足して回し直し、止まる件数の差を見ます。確信度で切る運用が使えるかどうかの判断材料になります。
• 4AI_REVIEW_DIFF_THRESHOLD を 80 から動かし、ai_review が使うモデルが切り替わる境界を測ります。
• 5レビュアーの4本目を作ります。対象の PHP 7.4 に無い構文だけを見る1本です。プチ演習4で書いた check-phpver のフックと役割が重なるので、どちらを残すかまで決めてください。
• 6構造化出力を CLI で扱います。ここはコマンドを使います。Claude Desktop の中のターミナルで、スキーマを指定してレビュー結果を JSON に落とし、そのまま判定スクリプトへ渡す形を作ります。研修の端末には claude の CLI を入れていないので、研修後に CLI を入れた環境で試してください。PowerShell 5.1 の > は UTF-16 で書き出すので、Out-File で UTF-8 にします。

  claude -p --output-format json "REVIEW.md の基準で app/controllers/estimate_ctl.php を読み、.claude/review.schema.json の形で返してください" | Out-File -Encoding utf8 findings-cli.json

  --output-format json の出力は外側に包みがあるので、そのまま判定スクリプトに渡すと findings の配列が無いとして落ちます。中身の取り出し方はプチ演習5 の「研修後に自分の API キーで CLI から試す場合」にあります。Claude Desktop は画面で結果を見るところまでで、ファイルを作って次の処理へ渡す形は CLI のほうが組みやすくなります。自動化に載せる段階でここに戻ってきてください。

目的

応答を終わらせてよいかの判定を機械に移し、止まらなくなる作りとの差を説明できるようになります。あわせて、戻す手間を減らすために変更の範囲を先に絞る考え方を持ち帰ります。

準備

自分で考える　[2min]　メモへ2つ書き出してください。

• 1自社で、AI の応答を終わらせてはいけない状態を1つ挙げてください。テストが赤い以外で書きます。
• 2その判定にかかる時間を秒で見積もってください。フックは応答のたびに走ります。1回30秒かかる検査を置くと、会話の速度がその分だけ落ちます。

手順

Step 1　止まらない版を見る　[3min]

講師が2つの版を並べて回します。受講者は手を動かさずに画面を見てください。止まらない版は各自の端末では回しません。止まらない版は、次の3行だけでできています。

# demo only. do not register this one.
$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
Write-Output '{"decision":"block","reason":"tests are red. fix and finish."}'

配布の版は、同じ処理の前に通す条件を置いています。どれかに当たった時点で、何も返さずに終わります。主な3つは次のとおりです。

# Guard 1: already continued by this hook.
if ($payload.stop_hook_active -eq $true) { exit 0 }

# Cap: continuations counted per session in .stop-gate.state
if ($count -ge $max) { ...; exit 0 }

# Guard 2: nothing changed in the working tree
if ([string]::IsNullOrWhiteSpace(($changes | Out-String))) { ...; exit 0 }

Step 2　正しい版を登録する　[3min]

• 1VSCode で .claude/settings.json の "hooks" に Stop のブロックを足してください。.claude/settings.example.jsonc の同じブロックと一字一句同じです。プチ演習4 と同じく、"PostToolUse": [ ... ] を閉じる ] の直後にカンマを置いてから貼ります。Stop に matcher はありません。応答の終わりは1種類しか無いためです。

    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-gate.ps1"],
            "timeout": 300
          }
        ]
      }
    ]

• 2統合ターミナルを開き（右上の >_ アイコン、または Ctrl とバッククォート）、門の1つ目だけを単体で確かめてください。

  echo '{"stop_hook_active":true,"session_id":"check"}' | powershell -NoProfile -ExecutionPolicy Bypass -File .claude\hooks\stop-gate.ps1
  $LASTEXITCODE

• 3何も表示されず、終了コードが 0 であることを確認してください。ここで decision を返す版が、Step 1 の止まらない版です。
• 4Claude Desktop で Ctrl+N を押して新しいセッションを開き、VSCode の settings.json で Stop に1本入っていて赤い波線が無いことを確認してください。JSON が壊れていると読まれないので、カンマを見直します。

Step 3　継続の経路を見る　[4min]

• 1Claude Desktop で何か1つファイルを編集させてから応答を終わらせてください。内容は何でも構いません。例えば「README.md の末尾に、今日の日付を1行足してください」です。
• 2手元に PHP がある方は、継続が1回入ってから応答が終わることを見てください。PHP が無い方の端末では継続が入らずに終わるので、同じ場面を講師の投影画面で見ます。

Step 4　上限の効き方を確かめる　[3min]

• 1VSCode で .claude/settings.json を開き、先頭の { の次の行に次の1行を足して保存してください。settings.json の env に書いた値は、Claude Code が起動するフックにも環境変数として渡ります。0 は継続そのものを止める値です。

    "env": { "STOP_GATE_MAX": "0" },

• 2Claude Desktop で Ctrl+N を押して新しいセッションを開き、Step 3 と同じようにファイルを編集させて応答を終わらせてください。PHP がある方の端末では、継続が入らずに応答が終わります。PHP が無い方は、講師の投影画面で同じ場面を見ます。
• 3確認が済んだら、手順1 で足した "env" の1行を消して保存し、Ctrl+N で新しいセッションを開いてください。消さないと、この後のハンズオン3 で継続が1回も入りません。
• 4ソース管理ペインで .claude/settings.json だけをステージし、メッセージ欄に「プチ演習6: Stop フックを登録」と書いてコミットしてください。"env" の行が差分に残っていないこと、.claude/hooks/.stop-gate.state をステージに上げていないことを先に見ます。Step 3 と手順2 で書かせた README.md などの1行は、変更の破棄 で戻してください。
• 5自社で使うときの上限を決め、台帳に書いてください。検査を残したまま継続だけ切りたいときが 0 です。

達成状態

Step 2 の単体確認では、何も出力されずに終了コードが 0 になります。Step 3 で継続が入る端末は、次の reason が画面に出てセッションが続きます。exit code の数字は環境で変わります。

{"decision":"block","reason":"php tests/run_tests.php failed with exit code 1. Run it, read the failing case, fix the code, then finish. (stop-gate continuation 1 of 2)"}

PHP が無い端末では、フックは標準エラーに次の1行目を書いて終えます。Step 4 で上限を 0 にしたときは、PHP の有無にかかわらず2行目を書いて終えます。上限の判定は PHP を探す手前にあるためです。どちらも標準エラーなので、Claude Desktop の画面には出ないことがあります。

[stop-gate] php not found on PATH, letting the session stop
[stop-gate] already continued 0 time(s), the cap is 0. Letting the session stop.

解説と補足

なぜこれをやるか　夜間に無人で回す構成では、応答を終える直前に走る Stop フックが最後の門になります。テストが落ちたまま終わらせない、という一言を機械にするのがこの演習です。あわせて、このフックが自動化で一番事故を起こす部品でもあることを、講師の画面で先に見ます。止まらなくなる原因は1か所です。フックが自分で継続させたセッションかどうかを見ずに止めると、そのたびに継続が入り、同じ判定がまた走ります。

Stop フックの動き　応答を終えようとした瞬間に走ります。標準出力に {"decision":"block","reason":"..."} を返すと応答は終わらず、reason の文が次の指示として渡って作業が続きます。何も返さなければそのまま終わります。継続で再び呼ばれたときは、入力の JSON に stop_hook_active が true で入ります。プチ演習3 の PreToolUse、プチ演習4 の PostToolUse、この演習の Stop で、手元のフックは3イベントになります。4本目の SessionStart はハンズオン3 の Step 1 で足します。

タイムアウト　フックの既定はコマンド種別で600秒で、ここではテストの実行時間に合わせて300秒へ縮めています。自社の検査がこれを超える場合は、フックではなく CI 側へ寄せてください。

Mac または bash を正にする方　"command" を "bash" に、"args" を ["${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-gate.sh"] に差し替えてください。手動検査も bash .claude/hooks/stop-gate.sh に、$LASTEXITCODE を echo $? に読み替えます。

素通りの1行が画面に出ないとき　標準エラーの1行は、通常の画面には出ないことがあります。素通りの経路は「何も起きない」が正しい姿なので、見えないこと自体は不具合ではありません。フックだけを確かめたいときは、Step 2 の手順2 の JSON の true を false に変えて stop-gate.ps1 に流すと、統合ターミナルに標準エラーの行が出ます。

継続回数の記録　セッションごとに .claude/hooks/.stop-gate.state へ書かれ、テストが通ると消えます。手元の作業メモなので、コミットしないでください。ソース管理ペインにこのファイルが出たら、.gitignore に1行足します。回数を数えた文が出るのは、同じセッションで継続が積み上がったときです。1本の連鎖では stop_hook_active が必ず1回で切るので、既定の2に当たるのは同じセッションで依頼を繰り返した先になります。起動し直すと session_id が変わり、回数は 0 に戻ります。

追加と考察　Stop フックは、応答を終える判断を機械に移す部品です。移した結果、人の側に何が残るかを1行書いてください。夜間ループで人が持つのは Issue の粒度決め、マージ承認、指摘の採否の3つです。この3つのどれかが、テストの合否判定で置き換わっていないかを確かめてください。置き換わっているなら、それは機械化ではなく、判断の放棄です。

発展課題　いまの版はテストの合否だけを見ています。ここに lint-phpver 相当の検査を足すと、対象バージョンで動かない構文を残したまま応答が終わることも防げます。ただし、応答のたびに2つの検査が走ります。会話の速度と、合流前に気づけることのどちらを取るかを決めてから足してください。足さない判断も、理由を書けば持ち帰り物になります。

変更範囲の事前制限　Stop フックが止めるのは、終わり方です。戻す手間そのものを減らすなら、先に範囲を絞るほうが効きます。AI が20ファイルを書き換えた後に、どれを戻すか選ぶ作業は人の手に残ります。絞り方は2つあります。1つは PreToolUse で、決めたディレクトリの外を書こうとしたら止める形です。もう1つは Stop フックの判定に「作業ツリーの変更ファイル数」を足し、決めた数を超えたら継続させずに止める形です。どちらも、部分ロールバックと対で考えるものです。上限の数は、1回の依頼で触らせるつもりのファイル数から決めてください。普段の改修で5ファイルなら、8や10あたりが最初の線になります。超えたときに止まるのは事故ではなく、依頼が大きすぎた合図です。

影響範囲

ここで登録したフックは、Claude Desktop から起動しても CLI から起動しても同じ設定ファイルが読まれ、同じように効きます。効く範囲が広いぶん、設定を別の環境へ持っていったときの差がそのまま出ます。同じフックを別の環境へコピーすると、次の4つで黙って効かなくなります。

4つとも「止まらずに通る」方向に倒れます。フックが動いていないことに気づかないまま、止めたかった操作が通ります。画面には何も出ません。環境は、AI ツールが動く場所とコードが置いてある場所とランタイムの版の3つの軸で別々に見てください。判定と実行を分け、止める対象を設定ファイルに出しておくと、環境が増えても入口を1本足すだけで済みます。組み合わせ別の設計は、配布物の 50_環境別のフック設計/環境別のフック設計.md にまとめてあります。

Issue 1本を無人で流し、止まった場所を1つ選んで直し、夜間に回せる範囲を1枚に書くところまで進みます。

• 1Issue 1本を無人で実装させ、MR が立つところまでを自分の手で1回通す。
• 21回目に止まった箇所を記録し、止め金の4層のどれで直すかを選んで再実行する。
• 3今のハーネスで夜間に回せる範囲と、人が残る3点を自分の言葉で1枚に書く。

Step 3 は講師が main で1本だけ流し、全員が同じログを読んで Step 4 の記録を書きます。Step 5 は、各自が自分のブランチのパイプラインで手動ジョブを押します。

コマンドを打つ場面が3か所あります。いずれも Claude Desktop の中のターミナルから実行します。右上の >_ アイコン、または Ctrl とバッククォートで開きます。セッションの作業ディレクトリで開くので、フォルダを移動する必要はありません。

設定ファイルを開く前に、紙かエディタに書き出してください。5分で構いません。ここを飛ばすと、この後の Step 1 が設定を写すだけの作業になります。

• 1Issue #4 を無人で流したとき、止まってほしい操作を3つ書き出します。
• 2その3つを止める層を、下の4つから1つずつ指定します。
• 3翌朝に最初に見る画面を1つ決め、そこで何を見てマージの可否を判断するかを3つ書きます。

この演習で触るファイルは4つです。すでにリポジトリに入っています。

手元では Claude Desktop で対話しながら進め、夜間は CI が同じ設定のまま非対話で回します。Claude Desktop は非対話実行(-p)を持たないので、無人で回る部分は CI 側の CLI が受け持ちます。人が横にいる作業と無人で回る作業の境目が、そのままツールの使い分けに重なります。止め金をどこに置くかは、この境目のどちら側で効かせたいかで決まります。

[ schedule または手動実行 ]

  implement
  nightly_implement
  ci/nightly_implement.sh
  ├ ブランチ nightly/issue-4 を作る
  ├ claude -p "/implement-issue 4" --permission-mode dontAsk --max-turns 15
  ├ コミット(エージェントが済ませていなければスクリプト側で)
  └ push  →  ここで MR のパイプラインが動く
             マージだけ人が判断する

「考える」で書き出した3つが、実際にどこで止まるかを4か所で確かめます。

手順

• 1VSCode の左下の表示が ex/h2-<ユーザー名> で、未コミットの変更が残っていないことを確認します。違うブランチなら、ブランチ名を押して一覧から ex/h2-<ユーザー名> を選びます。そのあとブランチ名を押し、新しいブランチの作成 で ex/h3-<ユーザー名> を作ります。名前の決め方は共通の進め方 STEP 2「ブランチ名の形」にあります。
• 2VSCode で .claude/settings.json を開き、permissions.deny に次の13行があることを確認します。無ければ足します。

      "Bash(git reset --hard *)",
      "PowerShell(git reset --hard *)",
      "Bash(git push --force *)",
      "PowerShell(git push --force *)",
      "Bash(git push -f *)",
      "PowerShell(git push -f *)",
      "Bash(git checkout -- *)",
      "PowerShell(git checkout -- *)",
      "Bash(git clean *)",
      "PowerShell(git clean *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/credentials*)"

• 3足した場合は、ソース管理ペインでメッセージに 夜間ループの止め金: deny 13行 と入れてコミットします。
• 4同じ settings.json の hooks に、PreToolUse(block-destructive)、PostToolUse(check-phpver)、Stop(stop-gate)の3本が並ぶことを確認します。そのうえで、Stop を閉じる ] の直後にカンマを1つ置き、その下に次の SessionStart のブロックを足して保存します。.claude/settings.example.jsonc の同じブロックと一字一句同じです。

      "SessionStart": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "powershell.exe",
              "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "${CLAUDE_PROJECT_DIR}/.claude/hooks/sessionstart_verify.ps1"],
              "timeout": 30
            }
          ]
        }
      ]

  保存したら Claude Desktop で Ctrl+N を押して新しいセッションを開き、settings.json に赤い波線が無いことを確かめて、夜間ループの止め金: SessionStart でコミットします。Claude Desktop の入力欄では /hooks は使えないので、登録は settings.json で見ます。
• 5VSCode で .gitlab-ci.yml のいちばん下の nightly_implement: を開き、timeout: 30m と ISSUE_ID: "4" があることを確認します。書き換えません。
• 6VSCode で ci/nightly_implement.sh を開き、claude -p "$PROMPT" \ で始まる行に --max-turns 15 が付いていることを確認します。値は上げないでください。
• 7ブラウザで GitLab の演習プロジェクトを開き、Code > Branches を選びます。main の行に protected の表示が付いていることを確認します。見るだけです。Developer の権限では Settings のメニューは出ません。

影響範囲

手元で効く deny とフックは、Claude Desktop と CLI が同じ設定ファイルを読むので、どちらで動かしても同じように効きます。Day1 に書いた設定をそのまま使えます。Claude Desktop のパーミッションモード(手動 / 編集を受け入れる / プラン / 自動)を 自動 にしても、deny とフックは先に走ります。モードが決めるのは確認ダイアログを出すかどうかだけです。

CI の中では、deny、ジョブの timeout、ブランチ保護に加えて、bash 版の PreToolUse と PostToolUse が効きます。nightly_implement のイメージは Linux(node:22-bookworm-slim)で powershell が入っていないので、ci/nightly_implement.sh が --settings ci/settings.ci.json で bash 版のフックを登録しています。Stop は CI では登録していません。runner には DB が無く、テストが必ず赤になって継続を無駄に使うためです。

git switch ex/h2-yamada
git switch -c ex/h3-yamada

夜間に動かすための時刻の設定を作ります。当日は同時実行を避けるため手動ボタンから流しますが、schedule 自体は各自が作ってください。持ち帰るのはこの設定です。

手順

• 1GitLab で演習プロジェクトを開き、Build > Pipeline schedules を選びます。
• 2New schedule(1本も無いときは Create a new pipeline schedule)を押します。
• 3Description に nightly issue-4 と入力します。
• 4Interval Pattern で Custom を選び、0 2 * * * と入力します。毎日 2:00 の意味です。
• 5Cron timezone を Tokyo に、Target branch を main にします。
• 6Variables に ISSUE_ID = 4 を1行足します。
• 7Activated のチェックを外し、Create pipeline schedule を押します。

影響範囲

schedule を有効にすると、その時刻に全員分が同時に走ります。runner の並列数と API の予算を一晩で使い切ります。時刻で動かすのは、自社のリポジトリに写してからです。

講師が main のパイプラインで nightly_implement を1本だけ流します。受講者は手動ボタンを押さず、全員が同じジョブのログを読みます。全員分を同時に走らせると、後のジョブが待ちに入って演習の時間内に終わらないためです。

手順

• 1講師が Zoom のチャットにパイプライン番号(# の付いた数字)を貼ります。GitLab の Build > Pipelines を開き、その番号の行を探します。ブランチが main の行です。
• 2その行の Stages のいちばん右の丸(implement)を押し、nightly_implement を選んでジョブの画面へ移ります。
• 3黒い領域のログを見ます。1〜2分の準備のあと Issue #4 の実装を開始します。ブランチ: nightly/issue-4 が出れば、スクリプトが動き始めています。
• 4そのまま待ちます。数分から十数分のあいだログは動きません。画面上部の経過時間が進んでいれば動いています。
• 5終わったらログの末尾を読み、下の表のどの終わり方かを確かめて Step 4 へ進みます。

1回目で MR まで届くことは多くありません。止まっているほうが普通です。

影響範囲

このジョブには allow_failure: true が付いています。止まってもパイプライン全体は赤になりません。failed は赤ではなくオレンジの警告アイコンで出て、横に Allowed to fail が付きます。どちらの色で終わっても Step 4 へ進みます。

解説と補足

講師が押している操作　Build > Pipelines の右上の New pipeline を押し、Run for branch name or tag に main を選び、Variables は空のまま起動します。lint と test の段が終わると、いちばん右の implement の段に nightly_implement が再生ボタンの形で出るので、講師がこれを押します。main のパイプラインの再生ボタンは、受講者の画面に出ても押さないでください。

講師の行が見分けられないとき　同じ時刻の行が複数あるときは、講師が Zoom のチャットに貼ったパイプライン番号で特定してください。ジョブ名に受講者名は出ません。

エージェントの出力がログに流れない理由　--output-format json で ci_logs/claude-issue-4.json に書いているためです。ジョブログに出るのは、スクリプトが出す行と最後の要約だけです。

pending のまま動かないとき　他のパイプラインのジョブがまだ runner を使っています。異常ではありません。ジョブ画面の上部に This job is stuck が出ている場合だけ、runner 側の問題なので講師へお知らせください。

30分で打ち切られたとき　ログの末尾に ERROR: Job failed: execution took longer than 30m0s seconds と出ます。--max-turns 15 より先に timeout が効いた形で、1ターンが長いときに起こります。この場合も ci_logs/ は残ります。

環境変数の不足で止まったとき　直すのは講師側の CI/CD の変数です。受講者は Step 4 の記録を「環境変数の不足で止まった」として書き、講師が変数を登録したあとの再実行を待ちます。

止まった場所を1つ特定して記録します。複数同時に起きていることもありますが、最初に効いた1つだけを選んでください。手を入れる層を1回に1つに絞るためです。

手順

• 1ジョブ画面の右の Job artifacts の Browse を押し、ci_logs を開きます。
• 2claude-issue-4.json を開き、is_error と num_turns を見ます。total_cost_usd は Step 7 で使うので控えます。
• 3同じ claude-issue-4.json の permission_denials を見ます。権限で拒否された場合は、ツール名とコマンドがここに入ります。claude-issue-4.err は CLI 自体のエラーの置き場所で、拒否はここには出ません。
• 4下の表から、自分の止まり方に一番近い行を1つ選びます。
• 5VSCode で配布の 計測表_Day1_Day2.md を開き、「Day2 夜間ループ」の節の上4つの欄(止まった箇所・止まった理由・どの層の設定で直すか・直した内容)を埋めます。下3つは Step 5 のあとに埋めます。

影響範囲

ここで選んだ層が、Step 5 で直す1か所になります。2つ以上選ぶと、再実行でどちらが効いたか分からなくなります。

| 項目 | 記入欄 |
|---|---|
| 止まった箇所 | Issue を読めずに終わった |
| 止まった理由 | permission_denials に curl の拒否。curl は ci/settings.ci.json の deny に入っている |
| どの層の設定で直すか | スクリプト(ci/nightly_implement.sh の PROMPT) |
| 直した内容(ファイル名とキー) | PROMPT に「Issue の本文は _issues/issue-4.md にあります」を1行追加 |
| 再実行の結果 | (Step 5 のあとに書く) |
| ジョブの所要時間(分) | (Step 5 のあとに書く。ジョブ画面の Duration) |
| 使ったターン数 | 3(上限 15 に未到達)。cost_usd 0.04 |

Step 4 で選んだ層を1つだけ直して、もう一度流します。2回目は main ではなく、自分のブランチ ex/h3-<ユーザー名> の上で起動します。共有の main は変えません。

手順

• 1VSCode で直す層のファイルを開き、1か所だけ変更します。
• 2ソース管理ペインで、そのファイルだけをステージし、何を直したかが分かるメッセージでコミットします。
• 3ソース管理ペインの ブランチの発行(2回目以降は 変更の同期)を押して、自分のブランチを GitLab へ送ります。
• 4GitLab の Build > Pipelines で、ブランチが ex/h3-<ユーザー名> の行を開きます。手順3 の push で動いたパイプラインです。
• 5lint と test の段が終わると、いちばん右の implement の段に nightly_implement が再生ボタンの形で出ます。ご自身でこれを押します。Developer の権限でも、保護されていない自分のブランチの手動ジョブは押せます。main や他の方のブランチの行は押しません。
• 6nightly_implement を押してジョブの画面へ移り、2回目のログを開きます。
• 71回目に止まった箇所を通過していることを確かめます。別の箇所で止まった場合は、それも計測表に1行足します。

影響範囲

自分のブランチから流すと、そのブランチに入っている .gitlab-ci.yml、ci/nightly_implement.sh、.claude/settings.json で走ります。自分の修正が効いたかどうかを、共有の main を変えずに確かめられます。

git add ci/nightly_implement.sh
git commit -m "夜間ジョブ: Issue 本文を _issues/issue-4.md から読ませる"
git push -u origin HEAD

自動で立った MR を人が読んで、マージしてよいかを判断します。この演習で人が手を動かすのは、ここだけです。講師の1回目で MR まで届かなかった場合は、自分の2回目の MR で行います。

手順

• 1ジョブログの末尾に出た MR の URL を開きます。Code > Merge requests の一覧から探しても同じです。
• 2MR の Pipelines タブで、lint-phpdev、lint-phpver、test、test-phpunit の4つが緑であることを確認します。
• 3Overview タブに戻り、ai_review が置いたコメントを読みます。
• 4Changes タブで差分を Issue #4 の受入条件と突き合わせます。見るのは3点です。app 配下で '作成中' が出てくるファイルが app/libraries/util.php の1つだけになっているか(受入条件1)、app/views/estimate_list.php と app/views/estimate_detail.php の両方から array(1, 2, 3, 4, 9) が消えているか(受入条件2)、tests/run_tests.php にテストが3件増えているか(受入条件4)。app/views/stock_list.php にも同じ並びがありますが、在庫状態のプルダウンなので範囲外です。
• 5同じ Changes タブで、差分が app/ と tests/ の外に出ていないことを確かめます。出ている場合は、下の折りたたみの手当てを行います。
• 6MR の説明に、変更方針3行と影響範囲の調査結果が入っていることを確認します。入っていない場合は、計測表に「人が残る作業」として書き足します。
• 7判断の根拠3つを計測表の「Day2 夜間ループ」の行の末尾に書き、講師へ「マージ可」と伝えます。Merge のボタンは押しません。

影響範囲

ai_gate が赤でもマージボタンは押せる状態のままです。演習のプロジェクトには Pipelines must succeed を設定していないので、パイプラインの色にかかわらず Merge は押せます。main の .gitlab-ci.yml には allow_failure: true も残っていて、ハンズオン2で外した版は各自のブランチにしかありません。赤いままの MR を「押せるが押さない」と判断できるかどうかも、この Step で見ています。

git restore --source=origin/main -- <パス>

研修の後、社内で最初に説明する相手に見せるのはこの1枚です。

手順

• 1VSCode で 計測表_Day1_Day2.md の「Day2 夜間ループ」の節を開き、Step 4 で空けておいた下の3つの欄(再実行の結果・所要時間・ターン数)を2回目のログで埋めます。所要時間はジョブ画面の Duration の分数です。
• 2下の1つ目の表を埋めます。「今夜から回せる」に入れてよいのは、今日の実行で実際に通った工程だけです。
• 32つ目の表の担当と目安を埋めます。項目は決まっています。埋めるのは、自社で誰がそれを持つかと、その判断に何分かけるかです。
• 4計測表の末尾の「最後に1枚書く欄」の3行に、1行目は1つ目の表の「今夜から回せる」に入れた工程名、2行目は2つ目の表の担当と目安、3行目は Step 4 で「直す層」に挙がったものを効いた順に書きます。
• 5VSCode で 持ち帰り台帳.md を開き、この演習の行を1行足します。「足したもの」の列に schedule の設定値を書きます。

影響範囲

schedule はファイルでは持ち出せません。持ち帰り台帳.md に書いた設定値が唯一の控えになります。

| ハンズオン3 | nightly_implement ジョブ + ci/nightly_implement.sh + pipeline schedule(ISSUE_ID=4, 0 2 * * *, main) | .gitlab-ci.yml と ci/(当日確定) | 同じ(当日確定) | 山田 | 置き場所まで決めた |

runner から外部の API へ出られない場合は、Step 3 と Step 5 の CI 実走を講師環境で行います。受講者は同じ手順を Claude Desktop で回します。止め金の効き方は同じで、違うのは push と MR 作成を人が行うところだけです。

手順

• 1VSCode の左下のブランチ名から 新しいブランチの作成 で nightly/issue-4-<ユーザー名> を作ります。CI から流すぶんと同じ名前にすると、push で衝突します。
• 2Claude Desktop で dl-training-app を開き、パーミッションモードを 自動 にします。承認待ちで止まらなくなります。CI の --permission-mode dontAsk とは向きが逆です。dontAsk は許可の一覧に無い操作を聞かずに拒否し、自動 は別のモデルが安全と見た操作を聞かずに通します。どちらのモードでも deny とフックは先に効きます。
• 3入力欄に次の1通をそのまま送ります。/implement-issue 4 と、CI のスクリプトがプロンプトに添えているものと同じ指示を、1通にまとめた形です。2通に分けると、2通目が届く前に skill が手順3 のブランチ作成まで進むことがあります。

  /implement-issue 4 ブランチは既に作ってあります。ブランチの作成と push は人が行うので、skill の手順3と手順7は実行せず、コミットまでで終えてください。

• 4終わったら、Claude Desktop の画面で使ったターン数と、拒否されたツールがあればその行を控えます。CI の ci_logs/ で見ていたものと同じ内容です。
• 5VSCode のソース管理ペインで差分を確認し、ブランチの発行 で GitLab へ送ります。
• 6GitLab の Code > Merge requests で New merge request を押し、送ったブランチから main へ向けて MR を作ります。ここから先は Step 6 と同じです。

影響範囲

手元で回すと、CI では動かなかったフックが動きます。check-phpver が Edit と Write の後に走り、対象の PHP 7.4 で動かない構文を差し戻します。同じ手順でも、手元と CI で通る範囲が変わることをこの差で確かめてください。Step 4 の表で「CI 側」と書いた行の理由がここにあります。

claude -p "/implement-issue 4 ブランチは既に作ってあります。ブランチの作成と push は人が行うので、skill の手順3と手順7は実行せず、コミットまでで終えてください。" `
  --permission-mode dontAsk `
  --allowedTools "Read,Edit,Write,Grep,Glob,Bash(php *),Bash(git add *),Bash(git commit *)" `
  --max-turns 15 `
  --output-format json | Out-File -Encoding utf8 claude-issue-4.json

1回目が止まったまま時間切れになった場合も、止まった箇所の記録と層の選択まで書けていれば到達点に届いています。通すこと自体はこの演習の目的ではありません。

持ち帰るのは5点です。D2 は PowerShell を正、smart3pm は bash を正として運用されていると伺っているので、同じファイルでも置き方が変わります。

• 1ci/nightly_implement.sh の --max-turns を 15 から 5 に下げ、同じ Issue を流します。どの手順で打ち切られたかを num_turns と差分から特定してください。打ち切りは失敗ではなく、Issue の粒度の測り方の1つです。
• 2.gitlab-ci.yml の GATE_LEVEL を P1 から P2 に変えて MR を作り直し、ai_gate が落ちる件数の差を見ます。夜間に回すなら、しきい値をどちらに置くかを台帳に理由つきで書いてください。
• 3PROMPT に書いた「触ってよい範囲」を app/ だけに狭め、同じ Issue を流します。テストが書けずに止まるはずです。範囲を絞りすぎると何が起きるかを、自分の目で見てください。
• 42回の実行の turns と cost_usd を並べます。1本あたりの費用が見えると、夜間に何本回せるかが決まります。人が残る3点の「1件あたりの目安」と合わせて、1晩の上限を出してみてください。

• 1予備の Issue #5 を同じ流れで1本回します。1本目と違う止まり方をしたら、それは Issue の書き方の差です。受入条件が機械で判定できる形になっているかを見比べてください。
• 2Stop hook を CI 側でも効かせます。ci/settings.ci.json は bash 版の PreToolUse と PostToolUse だけを登録していて、Stop は外してあります。runner にテスト用の DB を用意したうえで stop-gate.sh を登録する形です。フックの登録を環境で切り替える書き方を、自社ハーネスの settings.json に持たせるところまでが課題です。環境ごとの設計の勘所は、配布物の 50_環境別のフック設計/環境別のフック設計.md にまとめています。
• 3自社リポジトリで schedule を1晩だけ有効にし、翌朝は MR の説明とテストの結果だけを読みます。
• 4フック自身の受入テストを、bash 版にもそろえます。D2 では hooks/tests/ に回帰テストの仕組みが用意されていると伺っています。同じ形を smart3pm 側にも置くと、二重運用のまま片方だけ検査が抜ける状態を抜けられます。

目的

自分のハーネスを、印象ではなく確かめた結果で語れるようになります。次に足すものを1つに絞り、研修の翌週に着手できる形にします。

準備

判定は3つだけです。「ある」は、効いていることを確かめた項目にだけ付けてください。置いた記憶があるだけのものは「一部」です。ハーネスは、効いていないことが画面に出ません。思い込みで「ある」が付くと、そこだけ確認が止まります。

自分で考える　[2min]　シートの表を開く前に、先頭の予想欄を埋めてください。先に書いてから表を開きます。順番を逆にすると、表を読んだ印象がそのまま予想になり、あとで差が取れません。

• 15層のうち、自分のハーネスでいちばん空いていそうな層を1つ書いてください。層は、文脈・権限・フック・CI・リポジトリ保護の5つです。
• 230項目のうち「ある」が付きそうな数を、数字で書いてください。当てるためではなく、後で差を見るために書きます。

手順

Step 1　30項目を埋める　[9min]

• 1第1層から順に、判定の欄へ「ある」「一部」「無い」のどれかを書いてください。1項目あたり18秒の見当です。迷ったら「一部」に置いて先へ進みます。
• 2「どうやって確かめるか」の欄に書いてある方法で確かめられるものは、その場で確かめてください。設定ファイルの行数を数える、止めたい入力を1つ流す、といった数十秒で済むものだけです。
• 3確かめられなかった項目には、判定の横に印を1つ付けてください。持ち帰って確かめる分です。

Step 2　3行にまとめる　[4min]

• 1シート末尾の表へ、「無い」が一番多かった層を書いてください。層の名前と、その層で「無い」だった項目の番号を並べます。
• 2先頭に書いた予想と結果を見比べ、食い違った項目の番号を書いてください。差が出た場所が、いちばん危ない場所です。守れているつもりだったところだからです。
• 3次の1週間で埋める項目を、1つだけ選んで書いてください。番号と、その項目の「次の一手」の欄にあるファイル名を写します。

達成状態

30項目すべてに判定が入り、末尾の3行が埋まっている状態です。空欄が残っていてよいのは、判定の横に付けた「持ち帰って確かめる」の印だけです。

影響範囲

自社ハーネスへ持ち帰るときの置き場所は、次の表で決めてください。

目的

雛形を読むだけで終わらせず、1層を自社の値に置き換えて動かすところまでを経験します。持ち帰った後は、同じ手順を残りの層へ繰り返すだけになります。

準備

自分で考える　[2min]　ファイルを開く前に、メモへ2つ書き出してください。

• 1プチ演習7 で「無い」が多かった層のうち、どれを選ぶかを決めてください。迷ったら第3層です。書き換えた結果をテストで見られる層なので、20分で1周できます。
• 2書き換えた後、何が止まるようになるかを1行で書いてください。「安全になる」ではなく、「この操作を流すと終了コード2が返る」の形で書きます。この1行が、Step 4 で確かめる対象になります。

手順

Step 1　層とファイルを決める　[2min]

選んだ層に対応するファイルが1つだけあります。この表の右端が、今日触る1ファイルです。

Step 2　直す前に止まり方を控える　[2min]

Windows の方は、雛形の入口 guard.ps1 に入力を1件ずつ流して確かめます。Windows の PowerShell では jq も bash も使えないので、テスト一式を回す guard.test.sh は Mac と Git Bash を使える方向けです。

• 1統合ターミナルで、雛形のフォルダ 60_理想的なハーネスの雛形 にいることを確かめてから、止める側の入力を1件流してください。1行目を Enter で実行してから2行目を打ちます。

  '{"tool_name":"Bash","tool_input":{"command":"rm -fr build"}}' | powershell -NoProfile -ExecutionPolicy Bypass -File template\.claude\hooks\guard.ps1
  $LASTEXITCODE

• 2終了コードが 2 で、その上に [guard] blocked と止めた規則の名前が出ることを確認してください。
• 3通す側の入力も1件流し、終了コードが 0 であることを確認してください。

  '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' | powershell -NoProfile -ExecutionPolicy Bypass -File template\.claude\hooks\guard.ps1
  $LASTEXITCODE

• 42件の結果を控えてください。これが基準線です。書き換えた後にこの2件の結果が変わったら、直したのではなく壊しています。

bash template/.claude/hooks/guard.test.sh

guard.test(sh): 45/45 passed
guard.test(ps): skipped (PowerShell not found on this machine)

Step 3　1ファイルを自社の言葉に直す　[10min]

• 1VSCode で Step 1 の表で決めたファイルを開いてください。
• 2自社の値へ直す箇所を2つから3つに絞ってください。第3層を選んだ方は、write_rules に自社で触られたら困るパスを1件足し、deny_rules に自社で実際に事故った操作を1件足します。全体を書き直す必要はありません。
• 3足した規則には、止まったときに人が読むメッセージを必ず書いてください。止めるだけで代わりの道を示さない規則は、回避されます。
• 4Claude Desktop に手伝わせても構いません。そのときは、ファイルの冒頭の1行と、直したい箇所だけを渡してください。ファイル全体を書き直させると、雛形が持っている判定の作りごと変わります。

Step 4　止めたいものが止まるか確かめる　[4min]

• 1統合ターミナルで、Step 2 の2件をもう一度流し、終了コードが 2 と 0 のまま変わらないことを確認してください。Mac と Git Bash の方は bash template/.claude/hooks/guard.test.sh を流し、件数が Step 2 以上で NG の行が出ていないことを見ます。
• 2「自分で考える」の2番に書いた1行を、実際に流して確かめてください。ここに止めたい操作 を書き換えてから流し、終了コード 2 が返れば効いています。

  '{"tool_name":"Bash","tool_input":{"command":"ここに止めたい操作"}}' | powershell -NoProfile -ExecutionPolicy Bypass -File template\.claude\hooks\guard.ps1
  $LASTEXITCODE

• 3足した規則で止めたくない操作も1件流し、終了コード 0 が返ることを確認してください。通す側を確かめないと、全部止める規則を書いても気づけません。
• 4持ち帰り台帳へ、直した層・触ったファイル・流した入力と終了コードの3つを書いてください。直す前と直した後の両方を書きます。
• 5次に直す層を1つだけ書いてください。日付も入れます。

NG   止める規則 は文書が 12、実装が 13 です

達成状態

基準線の2件の結果が変わらず、自分で書いた1行のとおりに止まる状態です。止めたい操作を流したあとの $LASTEXITCODE はこう出ます。

2

Mac と Git Bash で guard.test.sh にケースを足した方は、末尾が guard.test(sh): 47/47 passed のように、45 に足した件数を加えた数になります。

影響範囲