共通の準備

[4min]

研修では Claude Desktop を使います。演習の手順で「Claude Desktop に送る」と書いてあるところは、すべてこの4つの動作の組み合わせです。各演習ではこの節を前提にして、送る文章と見るところだけを書きます。

• 1プロジェクトフォルダを選びます。新しいセッションを始めると、入力欄の上の行で環境、プロジェクトフォルダ、ブランチを選べます。プロジェクトフォルダに演習リポジトリ dl-training-app のフォルダを指定します。
• 2パーミッションモードを 手動 にします。入力欄の下の行の左にあるモード名を押して選びます。新しいセッションを開いたときは、送る前にここを一度見てください。
• 3指示を出します。入力欄に日本語の文章を貼り付けて送ります。ファイル名は文章の中にそのまま書いて構いません。
• 4結果を見ます。書き換えたファイルの名前と差分が返信の中に並びます。実行前に確認が出たら、その1回を許可する側の選択肢を選びます。書かれた中身は VSCode で開いて自分の目で確かめてください。

パーミッションモードは画面の表示で 自動 / 手動 / 編集を受け入れる / プラン の4つです。自動 では確認が出ないため、プチ演習2 と3 の「止まる」ことを見る演習が成立しません。2日間は 手動 のまま進めてください。プチ演習2 の手順4 だけ、確認の出方を見るために一時的に 編集を受け入れる に切り替えます。

研修では Claude Desktop を使います。同じことは CLI でもできるので、すでにターミナルで使っている方はそちらで進めていただいて構いません。設定ファイルは両方が同じものを読むため、.claude/settings.json の権限もフックも CLAUDE.md も、どちらで書いても効きます。演習の達成状態はどちらでも同じです。

腰を据えて使い込む段階に入ると、CLI のほうが自動化に載せやすくなります。差は1つで、対話画面を開かずに1回だけ走らせる形（claude -p）が CLI にしかありません。この形が取れると、出力をそのままファイルに残して CI のジョブや夜間のスケジュール実行に組み込めます。ハンズオン3 の夜間ループが、その実物です。

[3min]

演習で作るブランチは ex/<演習番号>-<ユーザー名> です。演習番号は、プチ演習が p1 から p4、ハンズオンが h2 と h3 です。プチ演習5 は ex/p4- のブランチのまま、プチ演習6 はハンズオン2 の ex/h2- のブランチのまま進めます。プチ演習3なら ex/p3-yamada、ハンズオン2なら ex/h2-yamada になります。切り替えの操作は STEP 3 のソース管理ペインで行います。

ハンズオン1だけは例外です。Claude Desktop の入力欄の上の行で、ブランチ名の右にある ワークツリー にチェックを入れて開始すると、そのセッションだけが隔離した作業ツリーで動きます。名前の入力欄は無く、ブランチ名は worktree- で始まる名前が自動で付きます。入力欄の上に出たブランチ名を控え、以降この資料の worktree-issue-1 は控えた名前に読み替えてください。作業ツリーは .claude/worktrees/ の下に1つできます。

配布した .claude/settings.json には worktree.baseRef = head が入っているので、ワークツリーは開始したときに乗っていたブランチの HEAD から切られます。ハンズオン1 では ex/p3- の最後のコミットが分岐元です。コミットしていない変更は入りません。

[6min]

変更の確認、コミット、同期、ブランチの切り替えは、すべて VSCode の画面でできます。左サイドバーの枝分かれのアイコンがソース管理ペインです。アイコンの右上の数字が、いま変わっているファイルの数です。

• 1ブランチを切り替えます。ウィンドウ左下にいまのブランチ名が出ています。そこをクリックして、一覧から選ぶか 新しいブランチの作成 で新規に作ります。
• 2差分を見ます。変更 の一覧でファイル名をクリックすると、左に変更前、右に変更後が並びます。AI が書いたものは必ずここで読んでください。
• 3ステージに上げます。ファイル名の右の + を押します。変更したファイルだけを選んで押してください。フックが作った作業ファイルまで巻き込まないためです。
• 4メッセージを書いてコミットします。入力欄に日本語の1行を書き、コミット を押します。
• 5同期します。変更の同期 を押すと、手元のコミットが GitLab へ送られ、GitLab 側の更新が手元に入ります。

コミットは1つの変更意図につき1つです。10個の変更を1コミットにまとめると、そのうち1つを取り消したいときに手作業で切り分けることになります。メッセージは「見積一覧の顧客名検索をプレースホルダに置き換える」のように、何をどうしたかを書きます。ファイル名を並べたメッセージは、あとで履歴を読むときに何も足しません。

[8min]

MR の作成、差分の確認、パイプラインの確認、マージの判断はブラウザで行います。main はブランチ保護がかかっており、合流の経路は MR だけです。

• 1MR を作ります。同期したあとにプロジェクトの画面を開くと、上部に Create merge request の帯が出ます。出ていないときは左メニューの Code > Merge requests から New merge request を押します。
• 2合流先が main、元が自分のブランチになっていることを確かめます。
• 3説明欄には、リポジトリの既定のテンプレート(.gitlab/merge_request_templates/Default.md)が最初から入っています。変更概要 と 影響範囲 を先に埋め、AI レビュー結果 の表は演習の途中で埋めます。
• 4差分は Changes タブで読みます。行の左に出るアイコンから、その行に直接コメントを付けられます。
• 5パイプラインは Pipelines タブで見ます。落ちたジョブの名前をクリックするとログが開きます。
• 6Merge は押しません。演習中は誰の MR もマージせず、開いたまま残してください。MR の一覧が2日間の記録になります。

Pipelines タブには、パイプラインが2本ずつ並びます。1本目は変更を出すたびに走るブランチ用で lint と test の2段4ジョブ、2本目は MR に対して走る MR 用で review と gate の2段2ジョブです。どちらも前の段が落ちると後ろの段は動きません。ブランチ用のいちばん右の implement にある nightly_implement は再生ボタンが付いた手動ジョブで、ハンズオン3まで押しません。

落ちたジョブのログの読み方

落ちた理由は、ログのいちばん下ではなく赤い行の直前にあります。ai_gate が止めたときは、止めた指摘がそのままログに並びます。

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

ゲートで止めた指摘 1 件
  [P1] app/controllers/estimate_ctl.php:48 顧客名がSQL文字列へ連結されており、検索欄から任意のSQLを実行できます。db_select の第2引数にプレースホルダで渡してください。

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

どの指摘で止まったかが分かれば正しく読めています。

[4min]

ai_review は MR にコメントを1本置きます。1件の指摘は severity、confidence、file、line、message、category の6つを持ちます。ノートは列挙するだけで、直すかどうかは決めません。

読む順番を決めておくと速くなります。severity で P0 と P1 だけを先に読み、次に confidence が 0.5 以下のものを「実物を確かめてから判断する」側に寄せ、最後に今回の変更の外を指している指摘を外します。この3手で、6件のノートが2件の判断に減ります。

AIレビュー(モデル: claude-sonnet-5 / 深さ: quick / 差分 42 行)

見積一覧の検索条件とテストの差分を読み、6件を報告します。

P0 0 件 / P1 1 件 / P2 3 件 / P3 2 件

- [P1] app/controllers/estimate_ctl.php:48 (sql-injection / 確信度 0.9)
  顧客名がSQL文字列へ連結されており、検索欄から任意のSQLを実行できます。db_select の第2引数にプレースホルダで渡してください。
- [P2] app/controllers/estimate_ctl.php:61 (spec-mismatch / 確信度 0.6)
  期間の上限が指定日の 00:00 で切れるため、指定日当日の見積が一覧に出ません。

判定は ai_gate ジョブが行います(現在のしきい値 P1)。採否の理由はこのMRのコメントに書いてください。

画面から実行できないものは、Claude Desktop の統合ターミナルから打ちます。右上の >_ アイコン、または Ctrl+バッククォートで開きます。セッションの作業ディレクトリで開き、Claude と同じ環境を共有するので、パスを移動する操作はいりません。2本目のタブが要るときは、ターミナルペーンの + で増やします。演習の手順で「ターミナルで」と書いてあるのは、すべてこのターミナルです。コマンドを打つ場面は2日間で十数か所あり、どれも統合ターミナルにそのまま貼れる形で書いてあります。

2日間で足す機能を1行ずつ記録します。演習中に決めるのは置き場所と担当で、ここが空欄のまま研修が終わると、持ち帰ったファイルは端末の中に残ったままになります。最後の列は「未 / 書いた / 置き場所まで決めた」の3つから選びます。

| 演習 | 足したもの | D2 での置き場所 | smart3pm での置き場所 | 担当 | 状態 |
|---|---|---|---|---|---|
| プチ演習1 | review-light.md / review-full.md | agents/ 配下(当日確定) | agents 相当の場所(当日確定) | 山田 | 置き場所まで決めた |
| プチ演習2 | deny 5本 + CLAUDE.md の戻し方 | settings.json | settings 相当(当日確定) | 山田 | 未 |

指摘の総数、うち P0 と P1、所要時間の3つを演習ごとに取り、採否を決めたら採用・見送りの件数を足します。Day2 の最後に、これが効果測定の初回の実測値になります。数字を取らないと、品質が上がったかどうかを言葉でしか言えません。

| 読ませ方 | 指摘の総数 | うち P0 と P1 | 採用・見送り | 所要時間(分) |
|---|---|---|---|---|
| 1 実装したセッションでそのまま依頼 | 4 | 1 | 1・3 | 2 |
| 2 review-other サブエージェント | 6 | 2 | 2・4 | 3 |
| 3 履歴を切った新しい会話 | 3 | 2 | 1・2 | 6 |
| 4 CI の ai_review | 6 | 1 | 1・5 | 1 |