ハンズオンガイド Day1

変更の大きさでレビュアーを当て分けられるようになります。3行の修正のために最重量のモデルを待つ状態をなくします。

次の4つがそろってから手順に入ります。

• Claude Desktop で dl-training-app(事前セットアップで取り込んだフォルダ)をプロジェクトとして開いている
• VSCode でも同じフォルダを開き、左のエクスプローラーに app / db / tests / .claude が見えている
• .claude/agents/ に review-light.md と review-full.md の2本がある
• VSCode の左下のブランチ名が ex/p1- で始まっている

手を動かす前に、次の2点をメモに書き出してください。配布した定義には 50行 という数字が入っていますが、その数字が自社に合っているかは別の話です。

• 1軽い側と重い側を分ける境界を、自分の言葉で1行にします。行数で切るのか、触った層(DB・権限・外部連携)で切るのか、両方を使うのか。決めた理由も1行添えます。
• 2自社のレビューで「毎回出るが毎回見送っている指摘」を1つ思い出し、軽い側の「書かないもの」に入れるかどうかを決めます。

• 1[2min]　VSCode で .claude/agents/review-light.md を開き、frontmatter(先頭の --- で囲まれた部分)の model / effort / tools を見ます(sonnet / medium)。そのまま最終行にある境界の1文の前半を、自分で決めた境界に書き換えて保存します。「review-full の対象です」の文言は変えません。手順5の判定に使います。
• 2[1min]　review-full.md を開き、frontmatter が opus / xhigh になっていることを見てから、「観点2 絶対制約」の箇条書きに、自社で絶対に守らせたい制約を1行足して保存します。
• 3[3min]　.claude/settings.json を開き、{ の直後、"permissions" の前に3行を足して保存します。 { "model": "sonnet", "effortLevel": "medium", "maxEffortLevel": "xhigh", "worktree": { "baseRef": "head" }, "permissions": { "deny": [], "ask": [], "allow": [] }, "hooks": {} } worktree の3行は配布時点で入っているので、消さずに残します。保存したら、Claude Desktop のサイドバーで 新しいセッション(Ctrl+N)を開き、プロジェクトフォルダに同じ dl-training-app を選びます。settings.json はセッション開始時に読まれるので、書き換えたあとは必ずこの操作が要ります。新しいセッションの入力欄の右下に出るモデル名と effort の表示が、Sonnet と 中 になっていることを確認してください。
• 4[3min]　小さい差分を1つ作ります。VSCode で app/libraries/util.php を開き、warehouse_name() の中で倉庫コードと名前を対応させている箇所に、既存の行と同じ書き方で倉庫コード 4 を 九州 とする1行を足して保存します。続けて Claude Desktop のターミナルで差分をファイルに落とします。ターミナルは右上の >_ アイコン、または Ctrl+バッククォートで開きます。セッションの作業ディレクトリで開くので、フォルダを移動する必要はありません。サブエージェントは Read と Grep と Glob しか持たないので、差分は自分でファイルにしてから渡します。手順1〜3で書き換えた .claude 配下の3ファイルも未コミットのまま残っているので、差分はパスで util.php だけに絞ります。

  git diff --output=small.diff -- app/libraries/util.php
  git diff --stat -- app/libraries/util.php

  --stat の行に util.php | 1 + と出て、エクスプローラーに small.diff が現れれば取れています。
• 5[3min]　Claude Desktop の入力欄に下の2行を貼って送ります。先頭の @"review-light (agent)" は、入力欄で @ を打つと出る一覧から review-light (agent) を選んでも同じです。 @"review-light (agent)" small.diff をレビューしてください。 指示は「warehouse_name に倉庫コード 4 = 九州 を足す」です。 動いている間に右上の ⋮ メニューの バックグラウンドタスク を開き、review-light の行のモデル名とトークン数を控えます。サブエージェントの effort はこの画面に出ないので、定義に書いた値を表に書きます。

  

• 6[2min]　同じ small.diff を @"review-full (agent)" にも渡し、バックグラウンドタスクのモデル名とトークン数を同じように控えます。
• 7[2min]　次は重い側の担当になるものを渡します。差分は作らず、在庫の引き当てを扱う app/controllers/stock_ctl.php の assign() をそのまま軽い側に渡します。境界は行数だけでなく「DB・権限・外部連携に触る変更」も見ているので、これで差し戻されます。差し戻されたら同じ依頼を重い側に出し直し、両方のモデル名とトークン数を控えます。 @"review-light (agent)" app/controllers/stock_ctl.php の assign() をレビューしてください。 在庫の引き当てをしている箇所です。
• 8[1min]　記録表の4行を埋め、後片付けをします。small.diff はコミットしないので、VSCode のエクスプローラーで削除します。残す変更は2つのコミットに分けます。ソース管理ペインで app/libraries/util.php だけをステージして「倉庫コード 4 を足す」でコミットし、続けて .claude 配下の3ファイルをステージして「レビュアー2本と settings の3行」でコミットします。プチ演習2 はこの2つのコミットの上から始めます。

• small.diff に軽い側を当てると、判定: の1行で終わる
• stock_ctl.php の assign() を軽い側に渡すと review-full の対象です が返る
• バックグラウンドタスクの行に、定義した model のモデル名が出ている
• 記録表の4行が埋まり、トークンの列に数字が入っている
• util.php と .claude 配下の3ファイルが2つのコミットに分かれ、ソース管理ペインの変更一覧が空になっている（stock_ctl.php は触っていない）

記録表です。トークンの列は、バックグラウンドタスクのペインでその行に出た数字を書きます。

| 差分 | レビュアー | モデル(ペイン) | effort(定義) | 指摘件数 | うち重大 | トークン(ペイン) |
|---|---|---|---|---|---|---|
| small.diff | review-light | | | | | |
| small.diff | review-full | | | | | |
| assign() | review-light | | | | | |
| assign() | review-full | | | | | |

• maxEffortLevel は全スコープの上限になるので、既存エージェントの effort が丸められることがあります
• 定義の model は環境変数 CLAUDE_CODE_SUBAGENT_MODEL より優先されます。CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 のときだけ逆になります
• 自社では、既存のレビュー用エージェントの前段に軽い側を置き、数行の修正で最重量のモデルを待たない形にします

AI が一度に広げた変更を、自分の手直しを巻き込まずに戻せるようになります。戻す手間そのものを減らすために、触らせる範囲を先に絞る側も設定で作ります。

この演習で扱うのは、AI に書かせたときにだけ起きる戻し方です。1回の依頼で複数のファイルが同時に書き換わり、そこへ自分の手直しが混ざるところが、人が1人で書いていたときとの違いになります。

• プチ演習1 の変更が、ソース管理ペインで2つのコミットに分かれて確定している(util.php の1行と、.claude 配下の3ファイル)
• ソース管理ペインの変更一覧が空になっている。未確定の変更が残っていると、戻った分と残った分が混ざります
• VSCode の左下のブランチ名が ex/p2- で始まっている。ex/p1- から続けて切ります。main には戻りません
• Claude Desktop で同じフォルダを開いている
• パーミッションモードが 手動 になっている。自動 のままだと確認のダイアログが出ず、手順1と手順8が成立しません。新しいセッションを開くたびに、送る前にモードを見てください

• 1ファイル編集ツールで変えたファイルと、シェルのコマンドで名前を変えたファイル。セッションを巻き戻したあと、それぞれどうなっているかを予想します。
• 2自社のリポジトリで「AI に書き換えさせたくないディレクトリ」を1つ挙げます。手順3でそこを設定に書きます。

• 1[2min]　Claude Desktop の入力欄に次を貼って送り、2つの変更を続けて実行させます。1つ目はファイル編集ツール、2つ目はシェルのコマンドです。確認はどちらも、その1回を許可する側の選択肢を選びます。 index.php の先頭に「// rewind test」という行を1行足してください。 そのあとシェルのコマンドで app/libraries/util.php を util.bak にリネームしてください。 実行後、VSCode で index.php の1行目に // rewind test が入っていること、app/libraries の中が util.bak になっていることを見ます。
• 2[2min]　入力欄に /rewind と打って送ります。メッセージの一覧が開いたら、手順1の依頼文を選びます。確認画面の「復元」を コードのみ にして 巻き戻し を押します。index.php は戻り、util.bak は残ります。セッション単位の巻き戻しが届くのは、AI がファイル編集ツールで書いた範囲だけです。

  

  

• 3[1min]　util.bak を元の名前に戻します。VSCode のエクスプローラーで app/libraries/util.bak を右クリックし、名前の変更 で util.php に戻してください。ソース管理ペインの変更一覧が空になれば片付いています。ここを飛ばすと、午後のハンズオンでテストが全部赤になります。
• 4[2min]　人の確認に回す範囲を先に決めます。.claude/settings.json の "ask": [] を次の内容に置き換えて保存します。db 配下の編集と git push が、どのモードでも確認に回ります。パスの規則は Edit(...) で書きます。Write(...) で書いたパスの規則は受け付けられても参照されません。 "ask": [ "Edit(./db/**)", "Bash(git push *)", "PowerShell(git push *)" ] VSCode で settings.json の ask に3本が並び、赤い波線が出ていないことを確認してから、Ctrl+N で新しいセッションを開いて同じフォルダを選び直します。この手順のあいだだけ、パーミッションモードを 編集を受け入れる に切り替えてください。app/libraries/util.php の末尾にコメントを1行足すよう依頼すると、確認なしで書き換わります。続けて db 配下のファイルの末尾にコメントを1行足すよう依頼すると、こちらだけ確認が出ます。確認では許可しない側を選び、2つとも見たらモードを 手動 に戻し、util.php に足された1行はソース管理ペインで 変更を破棄 します。
• 5[4min]　AI が触った範囲だけを戻します。次を送り、複数のファイルを一度に書き換えさせます。 app/libraries と app/controllers の中から3ファイルを選び、 それぞれの先頭に「// reviewed」というコメント行を1行ずつ足してください。 AI が動いている間に、ご自身で index.php の末尾に // 手直し の1行を足して保存します。終わったらソース管理ペインを開き、AI が書き換えた3ファイルの行だけを選んで 変更を破棄 を実行します。index.php の手直しは一覧に残ります。
• 6[3min]　1つのファイルの中で混ざった場合を分離します。index.php の先頭にコメント行を足すよう AI に依頼し、実行後にソース管理ペインで index.php をクリックして差分エディタを開きます。AI が足した行だけを選択し、右クリックの 選択した範囲を元に戻す を実行してください。末尾の // 手直し は残ります。ファイル単位で破棄すると自分の1行も一緒に消えるので、ここは行単位で切ります。
• 7[2min]　戻せない操作そのものを止めます。.claude/settings.json の "deny": [] を次の内容に置き換えて保存します。deny は ask と allow より先に評価され、allow では deny に例外を作れません。 "deny": [ "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 *)" ] VSCode で settings.json の deny に10本が並び、赤い波線が出ていないことを確認してから、Ctrl+N で新しいセッションを開いて同じフォルダを選び直します。Claude Desktop の入力欄では /permissions は使えないので、登録の確認はいつもこのファイルで行います。

  同じ禁止を Bash(...) と PowerShell(...) の2行で書くのは、Windows で Git for Windows が入っていると、Claude がコマンドを打つときの主なシェルが PowerShell になるためです。このとき Claude は Bash ツールではなく PowerShell ツールを呼び、Bash(...) の規則はその呼び出しに当たりません。Bash(...) だけを書いた設定は、講師の Mac では止まって見えても、皆さんの Windows では素通りします。PowerShell(...) の規則は rm と Remove-Item のような別名も同じコマンドとして照合し、大文字と小文字を区別しません。

• 8[2min]　止まることを確かめます。次の1行をそのまま送ります。 git reset --hard HEAD~1 を実行してください。 返答に、permissions.deny の規則で拒否されて実行できなかった旨が出て、ソース管理ペインのコミットの先頭が動いていなければ合格です。確認のダイアログが出た場合は、規則が読まれていません。許可せずに手順7の確認からやり直してください。あわせて CLAUDE.md の見出し「戻し方」の箇条書きに、自社の運用に合う1行を足します。書いた場所は文脈であって設定ではありません。実際に止めているのは手順7の deny です。最後に後片付けをします。ソース管理ペインで index.php の 変更を破棄 を押して // 手直し の1行を消し、.claude/settings.json と CLAUDE.md の2つをステージして「巻き戻し制約: ask と deny、戻し方の1行」でコミットします。

• コードのみ で巻き戻したあと、index.php は戻り util.bak が残ることを自分の目で見た
• 編集を受け入れる のあいだ、app 配下は確認なしで書き換わり、db 配下だけ確認が出た
• AI が書き換えた3ファイルだけが一覧から消え、index.php の // 手直し が残っている
• index.php の中で、AI が足した行だけが消えて自分の1行が残っている
• 手順8の返答に permissions.deny による拒否の旨が出て、コミットの先頭が動いていない

git reflog

• ask と deny が届くのは Claude Code のツール呼び出しだけです(Claude Desktop と CLI は同じ設定を読むので、どちらでも効きます)。ご自身がターミナルに打つ git checkout -- . は止まりません。人の手元まで含めて止めたいなら、置き場所はリポジトリのブランチ保護と CI になります
• ask を広げると確認が増えて手が止まり、狭めると範囲外まで書き換えられます。まずは戻すのが高くつくディレクトリだけに当てます
• 部分ロールバックが効くのは未確定の変更だけです。コミットした後は revert に切り替わります
• 既存の allow と重なっても deny が勝ちます

設定では塞げない読み取りの経路をフックで止め、そのフックが動くかどうかを AI に聞かずに検査できるようになります。

• プチ演習2 の変更が確定し、ソース管理ペインの変更一覧が空になっている
• VSCode の左下のブランチ名が ex/p3- で始まっている。main には戻りません
• リポジトリ直下にダミーの .env がある。本物の接続情報は置きません
• ソース管理ペインの一覧に .env が出ていない。.gitignore に .env の行は配布時点で入っています

Set-Content .env 'DB_PASS=dummy-secret-123'

• 1自社で「AI に読ませたくないファイル」を3つ挙げ、そのファイル名の形を書きます。固定名か、credentials を含む名前か、拡張子で決まるかで、書く正規表現が変わります。
• 2そのファイルに触る「止めたい形」と「止めてはいけない形」を1つずつ挙げます。手順5でテストケースに変えます。

• 1[2min]　.claude/settings.json の deny の配列の最後 "PowerShell(git clean *)" の末尾にカンマを付け、その下に読み取りの3本を足します。最後の1本にカンマは付けません。VSCode で deny に13本が並び、赤い波線が出ていないことを確認してから、保存して Ctrl+N で新しいセッションを開きます。 "Read(./.env)", "Read(./.env.*)", "Read(./**/credentials*)"
• 2[1min]　.env を読ませてみます。Read ツールが権限で拒否され、中身は返りません。 .env の中身を教えてください。
• 3[2min]　同じセッションで、今度はシェルのコマンドで読ませます。Windows では Claude が PowerShell ツールで Get-Content .env か cat .env を打ちます。確認で許可する側を選ぶと DB_PASS=dummy-secret-123 がそのまま返ります。Read(./.env) の deny は PowerShell ツールの経路を塞ぎません。 cat .env の結果を貼ってください。 演習リポジトリの CLAUDE.md には「.env と認証情報を読みません」の1行があるので、コマンドを打つ前に断られることもあります。その場合は「文脈で断られた」と記録して手順4へ進みます。止めたのは CLAUDE.md の文脈で、設定ではありません。頼み方を変えれば通ることがある状態なので、手順4からのフックで止める理由は変わりません。
• 4[2min]　フックを登録します。本体の .claude/hooks/block-destructive.ps1(Mac は block-destructive.sh)は同梱済みです。VSCode で開き、規則が「patterns が全部一致し、except が1つも一致しないとき止める」の組になっていることだけ見てから、settings.json の "hooks": {} を次の塊に置き換えて保存します。"hooks" のキーを2つにすると JSON が壊れ、ファイルごと無視されます。 "hooks": { "PreToolUse": [ { "matcher": "Bash|PowerShell", "hooks": [ { "type": "command", "command": "powershell.exe", "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.ps1"] } ] } ] } matcher は「どのツールの直前に走らせるか」で、Bash|PowerShell は Bash ツールと PowerShell ツールの両方です。Bash だけにすると、Windows で Claude が PowerShell ツールから打ったコマンドではフックが呼ばれません。command に実行するプログラム、args に引数を分けて書く形なので、フォルダのパスに空白や日本語が入っても引用符の問題が起きません。Mac の方は "command": "bash" と "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh"] の2行に差し替えます。完成形は .claude/settings.example.jsonc にあります。
• 5[2min]　AI を起動せずに1件流します。Claude Desktop の統合ターミナルで次の2行を打ちます。1行目がフックに JSON を渡す部分、2行目が終了コードを表示する部分です。2 が返れば止まっています。

  echo '{"tool_name":"PowerShell","tool_input":{"command":"Get-Content .env"}}' | powershell -NoProfile -ExecutionPolicy Bypass -File .claude\hooks\block-destructive.ps1
  $LASTEXITCODE

  Mac は echo '{"tool_name":"Bash","tool_input":{"command":"cat .env"}}' | bash .claude/hooks/block-destructive.sh と echo $? です。
• 6[2min]　.claude/hooks/tests/cases.json を開き、配列の最後の要素の閉じ } の後ろにカンマを付けて、自分で考えたケースを1件足します。id は他と重ならない名前にします。保存したらターミナルでランナーを回します。Mac は bash .claude/hooks/tests/run_cases.sh です。 { "id": "ps-ng-my-secret", "hook": "block-destructive", "input": { "tool_name": "PowerShell", "tool_input": { "command": "type .env" } }, "expect_exit": 2, "note": "PowerShell の type でも同じ経路" }

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

  

• 7[1min]　Ctrl+N で新しいセッションを開き、手順3と同じ依頼をもう一度します。今度は止まります。登録の確認は settings.json を VSCode で開いて見ます。Claude Desktop の入力欄では /hooks は使えません。

  

• 8[1min]　ソース管理ペインで .claude/settings.json と .claude/hooks/tests/cases.json の2つをステージし、「秘密情報の遮断: deny 3本、PreToolUse、テスト1件」でコミットします。.env が一覧に出ていないことをもう一度見てから確定してください。午後のハンズオン1 のワークツリーは、このコミットから切られます。

• deny だけの状態で、シェルのコマンドから .env が読めてしまうこと、または CLAUDE.md の文脈だけで断られたことを1度見た
• 自分で足したケースを含めてランナーが 23 cases: 23 passed, 0 failed で終わる
• フックを登録したあと、同じ依頼が止まる

[block-destructive] env-file: touches a .env file. Keep secrets out of the session: wrap the single command with run-with-secrets.ps1 (op run) or read them from CI/CD variables.
command: Get-Content .env
2

target=PHP 7.4 / cases=23 / materials=v2 2026-09-17

PASS  bash-ok-run-tests  (exit 0)
PASS  bash-ok-op-run  (exit 0)
PASS  ps-ok-git-status  (exit 0)
PASS  bash-ng-reset-hard  (exit 2)
PASS  ps-ng-get-content-env  (exit 2)
PASS  ps-ng-my-secret  (exit 2)

23 cases: 23 passed, 0 failed

• PreToolUse は deny と同じく、どのパーミッションモードでも走ります。except を広げると業務が止まり、狭めるとすり抜けます
• matcher が Bash だけだと、Windows の PowerShell ツールには効きません
• フックは手元で動く仕組みなので、設定を外した人には効きません。消されたら困るものは、リポジトリのブランチ保護と受け入れ時の検査で持ちます

同じフックを別の環境に写すと、黙って効かなくなることがあります。次の4つは、どれも「止まらずに通る」方向に倒れます。フックの単体テストを書く理由がここにあります。

環境は「AI ツールが動く場所」「コードが置いてある場所」「ランタイムの版」の3軸で見ます。WSL と Windows をまたぐ構成は、フックが1回動くたびにパスの変換が入るので遅くなります。判定と実行を分け、止める対象を設定ファイルに出しておくと、環境が増えても入口を1本足すだけで済みます。組み合わせ別の設計は、配布物の 50_環境別のフック設計/環境別のフック設計.md にまとめてあります。

題材は演習リポジトリの Issue #1 です。見積一覧の顧客名検索で、入力値を SQL 文字列にそのまま連結している箇所を直します。

本体は Step 4 です。実装したセッションに「レビューして」と頼むのと、履歴を切った読み手に読ませるのとでは、出てくる指摘が同じになりません。この差を手元で測ってから、分離の置き方を自社ハーネスへ1本書き戻して終わります。

上から順に、自分で確認できる形にしてあります。講師に聞かずに判定してください。

• MR が1本あり、lint-phpdev / lint-phpver / test / test-phpunit の4つが緑になっている。途中で lint-phpver が赤になった方は、混入した構文と行が MR の説明欄に記録してある(Issue #1 の受入条件3)
• git grep -n "customer_name" -- app/controllers/estimate_ctl.php の結果に、$_GET['customer_name'] を $where へ連結している行が無い
• index() の db_select 呼び出しが第2引数のパラメータ配列を取っている
• tests/phpunit/EstimateSearchTest.php に、顧客名に ' を含む入力のテストが1本以上増えている
• そのテストが変更前のコードでは落ちたことを、CI のログで確認した
• MR の「AI レビュー結果」表の3行が件数と所要時間まで埋まり、4行目の ai_review が件数か「未実施」で埋まっている
• MR の「人が判断した採否」表に全指摘が入り、直さなかったものに理由が書いてある
• ai_gate の結果を見て、今日はそれが止める力を持っていないことを説明できる
• 自社ハーネスに分離の置き方が1本入っている

Step 3 が一番長く、Step 4 がその次です。時間が押したときに削るのは Step 7 で、Step 4 と Step 5 は削りません。

AI を起動する前に、自分で Issue を読んで結論を出します。

• 1ブラウザで GitLab の演習プロジェクトを開き、左のメニューの Plan から Issues を選びます。一覧の #1 が今回の Issue です。
• 2背景、現状、期待する振る舞い、受入条件、対象ファイル、範囲外 の6つの見出しを読みます。このタブは Step 6 と Step 7 でもう一度使うので閉じないでください。
• 3範囲外 の2つを声に出して確認します。date_from と date_to の連結、app/libraries/sql_lib.php の共通処理です。
• 4下の3つの欄を紙に書きます。書けたら伏せておき、Step 2 の終わりに開いて突き合わせます。

git grep -n "customer_name" -- app/controllers/estimate_ctl.php

作業用のチェックアウトを別に作ってから始めます。元のフォルダには手が入らなくなるので、途中で方針を変えたときにフォルダごと捨てられます。

• 1VSCode でこれまでの演習フォルダを開き、左下のブランチ名が ex/p3- で始まっていることを確かめてから、左サイドバーの枝分かれアイコン(ソース管理)を押します。変更が残っていたら、メッセージ欄に「午前の設定を持ち込む」と書いて コミット を押してください。ワークツリーはこのブランチの最後のコミットから切られるので、未コミットの変更は入りません。
• 2Claude Desktop で新しいセッションを開き、入力欄の上の行のプロジェクトフォルダに演習フォルダ(index.php がある場所)を選びます。
• 3同じ行のブランチ名の右にある ワークツリー にチェックを入れ、入力欄に「作業を始めます」と1行送ってセッションを開始します。名前を入れる欄はありません。
• 4入力欄の上に出たブランチ名を、紙に控えます。worktree- で始まる名前が自動で付いています。以降、この資料の worktree-issue-1 は控えた名前に読み替えてください。
• 5VSCode でも同じ作業場所を開きます。ファイル から フォルダーを開く を選び、演習フォルダの .claude/worktrees/ の下にできた1つのフォルダを指定してください。左下の青い帯のブランチ名が、手順4で控えた名前であることを確認します。
• 6午前の設定が入っているかを見ます。VSCode のファイル一覧で .claude > settings.json を開き、deny の13行(プチ演習2 の10本とプチ演習3 の3本)、ask の3行、model、PreToolUse が入っているかを確認してください。deny が空だった場合は、下の折りたたみ「grep-scout が返す見出しと、worktree の注意点」の最後の2段落の手順に切り替えます。

調査を grep-scout に委譲します。影響範囲を調べるだけのサブエージェントで、Read と Grep と Glob しか持っていません。書き換えはできない作りです。

• 7手順3で開始した同じセッションの入力欄に、次の1行をそのまま貼って送信します。Issue の本文は丸ごと貼らないでください。

  @"grep-scout (agent)" 見積一覧の顧客名検索の条件組み立てを直します。影響範囲を調べてください

• 8実行中に右上の ⋮ メニューの バックグラウンドタスク を開いて、モデル名が Haiku になっていることを確認します。.claude/agents/grep-scout.md の frontmatter に書いた model: haiku が効いている場所です。調査には1分から3分かかります。
• 9返ってきた一覧と、Step 1 で紙に書いた仮説を突き合わせ、下の表を埋めます。

## 対象
## 触るファイル
## 呼び出し元と呼び出し先
## データベース
## テストの有無
## 同じ知識が重複している箇所
## 確認できなかったもの

CLI から同じことをする場合

CLI からは、手順2と手順3を1行で済ませられます。CLI では名前を付けて起動できるので、ブランチ名は worktree-issue-1 になります。研修では Claude Desktop で進めます。設定ファイルもフックも共有なので、午前に足した deny や model はどちらで起動しても効きます。

claude --worktree issue-1

テストを先に足し、変更前のコードでそれが落ちることを CI で確認してから実装に入ります。落ちないテストは、通っても何も保証しません。

• 1VSCode で tests/phpunit/EstimateSearchTest.php を開き、既存の5本がこの画面をどう確認しているかを読みます。$_GET に検索条件を入れ、capture_view() で出力を文字列にし、count_list_rows() で件数を数える形です。
• 2顧客名に ' を含む入力で例外が出ず0件になるテストを1本足します。Claude Desktop に頼む場合の文面の例です。入力値と確認する件数の2か所を、自分で決めた内容に替えてください。

  tests/phpunit/EstimateSearchTest.php に、$_GET['customer_name'] に半角の引用符を含む文字列(例: オライオン'商会)を入れて index を表示し、例外が出ず count_list_rows が 0 になることを確認するテスト testAcceptsSingleQuoteInCustomerName を、既存の5本と同じ書き方で1本足してください。app/ 以下のファイルは変更しないでください

• 3VSCode の ソース管理 ペインを開きます。変更 の一覧に tests/phpunit/EstimateSearchTest.php だけが出ていることを確認してください。ファイル名をクリックすると差分が開きます。増えたのがテスト1本だけで、既存の5本が変わっていないことを目で見ます。
• 4ファイル名の右の + を押してステージに上げ、上のメッセージ欄に「顧客名に引用符が入る場合のテストを足す」と書いて コミット を押します。
• 5同じペインの 変更の同期(または ブランチの発行)を押して GitLab へ送ります。初回は「このブランチを公開しますか」と聞かれるので、そのまま進めてください。ユーザー名とパスワードを聞かれたら、事前セットアップで決めた GitLab のものを入れます。
• 6ブラウザで GitLab を開き、左メニューの Build から Pipelines を選びます。検索欄に控えたブランチ名(この資料の worktree-issue-1)を入れて絞り、Stages の丸から test-phpunit を開いて、赤になっていることと落ちた理由が SQL の構文エラーであることを確認します。
• 7実装に入ります。Step 1 で書いた改修方針を、Claude Desktop に渡してください。渡すのは方針と範囲外の2つです。角括弧の中を自分の紙の内容で埋めます。

  app/controllers/estimate_ctl.php の index() で、customer_name を [自分の方針。例: db_select の第2引数にパラメータ配列で渡す形] に直してください。
  参考にする前例は [Step 2 の調査で確認した前例のファイルと関数] です。
  date_from と date_to の連結と、app/libraries/sql_lib.php は今回触りません。
  このプロジェクトの対象は PHP 7.4 です。CLAUDE.md の制約の表に従ってください。
  変更したらファイル名と変更した行を一覧で教えてください。コミットは私がします

• 8ソース管理ペインで app/controllers/estimate_ctl.php をクリックし、差分を自分で読みます。方針と違う場所に手が入っていたら、その場で Claude Desktop に戻させてください。
• 9手順4と同じ要領でステージに上げ、「見積一覧の検索条件をプレースホルダに置き換える」でコミットし、同期を押して送ります。1つの変更意図につき1コミットです。
• 10Pipelines の一覧でいちばん上に増えた行を開き、lint-phpdev、test、test-phpunit の3つと lint-phpver が緑になることを確認します。終わるまで3分から5分かかります。lint-phpver が赤のあいだは、後ろの段の test と test-phpunit が skipped になって動きません。赤になった場合は、Step 6 の記録の表に沿って混入した構文と行を控えてから、実装したセッションに「PHP 7.4 で動く書き方に直して」と頼んで直し、もう一度コミットして同期します。Issue #1 の受入条件3 がこの扱いです。

git log --stat -3
git checkout HEAD~1 -- app/controllers/estimate_ctl.php

.....E                                                            6 / 6 (100%)

There was 1 error:

1) EstimateSearchTest::testAcceptsSingleQuoteInCustomerName
PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "商会"
LINE 6:  WHERE e.del_flg = 0 AND c.customer_name LIKE '%オライオン'商会%'

ERRORS!
Tests: 6, Assertions: 12, Errors: 1.

......                                                            6 / 6 (100%)

OK (6 tests, 13 assertions)

ここがこの演習の本体です。差分は1つ、読ませ方は3つ。読み手から情報を1つずつ外していき、指摘がどう変わるかを自分の数字で見ます。

1から2で履歴が外れ、2から3で役割の定義が外れます。どちらの段で指摘が変わったかで、効いていたのが履歴なのか定義なのかが分かれます。

• 11通り目。実装したセッションでそのまま頼みます。新しい会話にせず、続けてください。

  この変更をレビューしてください。REVIEW.md の基準で、重大な順に最大8件です

• 2差分をファイルに出します。ここはコマンドを使います。サブエージェントは Read と Grep と Glob しか持たず、自分で差分を取れないためです。Claude Desktop の右上の >_ アイコン、または Ctrl+バッククォートで統合ターミナルを開きます。セッションと同じ場所、つまりワークツリーの中で開くので、移動は要りません。yamada はご自身のユーザー名に置き換えます。

  git diff ex/p3-yamada --output=review-input.diff

  比べる相手は main ではなく、ワークツリーを切った元の ex/p3- のブランチです。main と比べると、プチ演習1〜3 で足した設定の変更まで差分に入ります。
• 32通り目。実装の経緯を渡さずに、定義ファイルで役割を固定したサブエージェントへ読ませます。

  @"review-other (agent)" review-input.diff を、同僚が書いたコードとして読んでください。差分に出ていない前提はリポジトリのファイルで裏を取ってください

  結果は「重大度、場所、内容、根拠、直し方」の5列の表と、最後の 判定: 合格 か 判定: 要修正 の1行で返ります。表の行数が指摘件数です。
• 43通り目。Ctrl+N で新しいセッションを開き、プロジェクトフォルダに演習フォルダの .claude/worktrees/ の下の自分のフォルダを選びます。ワークツリーのチェックは入れません。初めて開くフォルダなので、ワークスペースの信頼を聞かれたら ワークスペースを信頼 を押します。押さないとフックと deny が読まれません。役割の定義は渡さず、差分ファイルと基準だけを渡してください。

  review-input.diff と REVIEW.md を読み、重大な順に最大8件で指摘してください。重大度、場所、内容、根拠、直し方の5列の表で返してください

  2通り目と同じ形で返るように、返し方だけを指定しています。役割も観点も与えていないので、2通り目と出方が変わります。
• 53通りの出力を、VSCode で新しいファイルに貼り付けて残します(保存先は演習フォルダの外、たとえばデスクトップに ho1-reviews.md)。Step 6 で MR に貼ります。
• 6review-input.diff を削除します。ソース管理ペインの 変更 にこのファイルが残っていないことまで見てください。
• 7下の表の1行目から3行目を埋めます。開始と終了の時刻を控えて所要時間も入れてください。4行目は Step 6 で CI の結果を受けてから足します。

git diff ex/p3-yamada | claude -p --output-format json --json-schema ((Get-Content .claude\review.schema.json -Raw -Encoding UTF8) -replace '"','\"') "REVIEW.md の基準でレビューし、findings を返す"

{
  "summary": "見積一覧の検索条件の変更を読み、3件見つけました。",
  "findings": [
    {
      "severity": "P1",
      "confidence": 0.9,
      "file": "app/controllers/estimate_ctl.php",
      "line": 22,
      "message": "date_from が文字列のまま SQL に連結されています。db_select の第2引数へ移してください。",
      "category": "sql-injection"
    }
  ]
}

$OutputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

集まった指摘を4つに分けます。分けるのは人です。指摘を全部受け入れると、意図してそうしていた設計が巻き戻ります。

• 13通りで出た指摘を1つの表にまとめます。同じ指摘が複数のレビューから出ている場合は1行にし、どのレビューから出たかを残します。
• 2各行に3軸を付けます。付けられない行は、その場でファイルを開いて確かめてください。
• 33軸から分類を決めます。分類から先に決めると、感覚で仕分けることになります。
• 4date_from と date_to の指摘は範囲外なので将来課題です。GitLab の Plan > Issues から右上の New issue を押し、Title に「見積一覧の見積日の検索条件の組み立て」のように対象が分かる1行を書きます。
• 5Description には Issue #1 と同じ6つの見出しのうち、少なくとも 現状 と 範囲外 の2つを書いて Create issue を押します。作成後のページの見出しの # の後ろの数字が Issue の番号です。
• 6「即修正」に入れたものだけを直します。1件1コミットで、コミットメッセージは「レビュー指摘: 直した内容を1行で」の形にします。ソース管理ペインからコミットまで行い、同期はまだ押しません。送るのは Step 6 の手順1でまとめてです。
• 7直したら、その指摘を出した読ませ方でもう一度レビューし、その指摘が消えたことだけを確認します。新しく出てきた P2 以下は追いません。

MR を GitLab の画面で作ります。MR ができると、push のたびに動く lint と test の4ジョブに加えて、MR 用のパイプラインで AI レビューの2ジョブが動きます。合流前の最終判定をここで受けます。

• 1VSCode のソース管理ペインで 変更の同期 を押し、Step 5 の修正を送ります。即修正が0件で新しいコミットが無い場合は押さずに次へ進んでください。
• 2ブラウザで GitLab の左メニュー Code > Merge requests を開き、右上の New merge request を押します。
• 3Source branch に Step 2 で控えたブランチ(この資料の worktree-issue-1)、Target branch に main を選び、Compare branches and continue を押します。
• 4次の画面で Title を「Issue #1 見積一覧の検索条件をプレースホルダに置き換える」に書き換えます。
• 5Description には、リポジトリの既定のテンプレート(Default.md)の節が最初から入っています。「変更概要」に何をなぜ変えたかを2行と Closes #1、「影響範囲」に Step 2 の突き合わせ結果、「テスト」に Step 3 で見た CI の結果、「AI レビュー結果」に Step 4 の表の4行、「観点別レビュー結果」に Step 4 で review-other が返した指摘、「人が判断した採否」に Step 5 の仕分けを書きます。観点別の3体(security / spec / test-gap)を当てるのは Day2 なので、今日は review-other の分だけで足ります。
• 6Preview タブで表の罫線が崩れていないかを見てから Create merge request を押します。
• 7MR のページ上部の Pipelines タブを開きます。いちばん上の2本が最新で、merge request のラベルが付いた行が MR 用(ai_review と ai_gate)、branch のラベルが付いた行がブランチ用(残りの4つ)です。合わせて6つのジョブの結果を確認してください。
• 8Changes タブを開き、Step 4 で読ませた review-input.diff の変更が含まれているかを見ます。MR の Changes と CI の ai_review は main との差なので、プチ演習1〜3 で足した .claude 配下の設定や util.php の1行も一緒に出ます。Step 4 の3通りより読む量が多いことを踏まえて、4行目の件数を比べてください。

ai_review が動くと、MR の Overview タブの下のほうに「AIレビュー(モデル: ... / 深さ: ... / 差分 ... 行)」で始まるコメントが1本付きます。見出し行の件数を表の4行目に写してください。所要時間はジョブの画面右側の Duration を使います。

ここで一度立ち止まってください。ai_gate は allow_failure: true なので、赤くなってもパイプライン全体は赤になりません。ゲートが赤いのにマージできる状態は、ゲートではありません。列挙しているだけです。この1行を外してゲートを赤にするのが Day2 のハンズオン2です。Merge ボタンまで止めるには、プロジェクトで Pipelines must succeed を有効にしておく必要があります。演習のプロジェクトはこの設定を入れていないので、ボタンは押せますが押しません。

lint-phpver が落ちた方は、直す前に記録してください。記録先は MR の説明欄です。落ちた構文は Day2 の最初のセッションでそのまま教材になります。

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

ゲートで止めた指摘 1 件
  [P1] app/controllers/estimate_ctl.php:22 date_from が文字列のまま SQL に連結されています。

直すか、直さない理由をMRのコメントに書いてから再実行してください。

undefined_functions: PHP 7.4 に無い関数を呼んでいます。php -l は通りますが実行時に落ちます。

実装が終わった後に指示書を作るのは順番が逆ですが、生成したものと自分が書いたものの差を見るのが目的です。

• 1Step 1 で開いたブラウザの Issue #1 を表示し、本文(背景から範囲外まで)を範囲選択してコピーします。
• 2Claude Desktop の入力欄に /shijisho 1 と打ち、Shift+Enter で改行してから、手順1でコピーした Issue 本文を続けて貼り付けて送信します。Enter だけを押すと、本文を貼る前に送られます。途中で grep-scout が再び呼ばれるので、2分から3分かかります。glab や curl で Issue を取りに行く実行確認が出たら、許可しない側を選んでください。本文は貼ってあるので、取りに行く必要はありません。
• 3VSCode で docs/shijisho/issue-1.md を開き、5項目(目的、影響範囲、変更方針、検証、戻し方)で止まっているか確認します。
• 4「目的」と「戻し方」の2つを、自分の言葉に直します。この2つは、Issue の本文を言い換えただけになりやすい箇所です。
• 5ソース管理ペインでステージに上げ、「Issue #1 の作業指示書を足す」でコミットし、同期を押して送ります。worktree を片付けたときに消えないよう、MR に載せておきます。

今日のうちに1本だけ自社ハーネスへ移します。移すのは「実装した本人に採点させない」を仕組みにするものです。2つ用意してありますが、入れるのは片方だけにしてください。

• 12つのファイルを開いて、どちらを自社に置くか決めます。決め手は、レビューを人の手元でやるか MR に置くかです。
• 2選んだ1本を自分のハーネスに写します。下の表の置き場所を見てください。
• 3自社のリポジトリ名、ブランチ名、レビュー基準のファイル名に書き換えます。演習リポジトリの名前がそのまま残っていると、次に使う人が混乱します。
• 4持ち帰り台帳の本日分に、今日足した1本を記入します。

次の3つを、持ち帰り台帳の余白に1行ずつ書いてください。Day2 の冒頭で使います。

上から順に、効き方が大きい順です。全部やる必要はありません。

• 1Step 5 で「将来課題」にした date_from と date_to の Issue を、自分で本文まで書いてください。受入条件 を機械で判定できる形にできるかが、この課題の見どころです。
• 2review-other の model: を opus に書き換えて、同じ差分をもう一度読ませてください。件数と中身がどう変わるかを Step 4 の表に足します。モデルを変える効果は研究では測られていないので、ここは各自の実測になります。
• 3同じ差分を claude -p に渡し、Claude Desktop で出た指摘と比べてください。-p は入力欄からは実行できないので、統合ターミナルを開いて打ちます。結果をファイルに落とせる形になるので、自社で集計に載せるときの材料になります。
• 4Claude Desktop のサイドバーで、このセッションのアーカイブアイコンを押して worktree を片付けてください。押す前に、GitLab 側に worktree-issue-1 ブランチと MR が残っていることを確認します。手元が消えても送ったものは残る、という関係を見ておくと、Day2 で複数の Issue を並行させるときに迷いません。