# hints の使い方とステップ対応表

`hints/` は、演習で手が止まったときに開く補助資料です。演習の手順そのものは `exercises/` にあります。手順書の一覧と進む順番は [exercises/README.md](../exercises/README.md) にまとめてあります。まず `exercises/` の手順で進めて、詰まってからこちらに戻ってきてください。

先に全部読んでしまうと、自分で考える部分が答え合わせに変わります。特に A-2（自分で懸念を書き出す）と B-2（不具合を探す）は、先に読むと演習が成立しません。

## ステップ対応表

| ヒント | 対応する演習ステップ | 対応する演習md | 主に助ける場面 |
|---|---|---|---|
| `step01_first_prompt.md` | A-0 素の状態を確認する [5min] | `exercises/exA0_baseline.md` | Claude Code パネルの開き方、`@` でのファイル指定、最初の1指示 |
| `step02_crud_build.md` | A-1 素の状態で CRUD 業務アプリを作る [15min] | `exercises/exA1_vibe_build.md` | 3回に分けた指示の文面、画面が出ないときの直し方 |
| `step03_warning_check.md` | A-2 懸念点を自分で洗い出す [8min] ／ A-3 ハーネスを配置する [5min] | `exercises/exA2_concerns.md` ／ `exercises/exA3_harness_install.md` | 指摘を引き出す聞き方、設定ファイルを置いたのに効かないとき |
| `step04_pipeline.md` | A-4 実行サマリーの出方を確認する [7min] ／ A-5 コマンド一つでパイプラインを回す [20min] ／ A-6 ハーネスの有無を比較する [10min] | `exercises/exA4_exec_summary.md` ／ `exercises/exA5_pipeline.md` ／ `exercises/exA6_compare.md` | `/selfcheck` が動かない、`.work/` の読み方、比較表の作り方 |
| `step05_comment_insert.md` | B-0 課題Bを起動して現状を掴む [8min] ／ B-1 自動化を提案させる [8min] | `exercises/exB0_start_kadaiB.md` ／ `exercises/exB1_setup_recommender.md` | 起動でつまずいたとき、初見の Java コードの読み方 |
| `step06_issue_driven.md` | B-2 Plan モードで壁打ちしてバグを見つける [12min] ／ B-3 Issue を起票する [7min] ／ B-4 修正して、動かして、テストを通す [20min] | `exercises/exB2_plan_hunt.md` ／ `exercises/exB3_issue.md` ／ `exercises/exB4_fix_and_test.md` | 不具合が見つからない、修正で別の場所が壊れた、テストが落ちる |
| `step07_skill_and_threat.md` | B-5 skill-creator で自分の Skill を作る [8min] ／ B-6 脅威モデリングを回す [7min] | `exercises/exB5_skill_creator.md` ／ `exercises/exB6_threat_model.md` | Skill が発火しない、脅威モデルの読み方 |

発展課題（[`exercises/challenges/`](../exercises/challenges/)、ch01 から ch05 の5本）には、対応するヒントを用意していません。自分で考えて試す時間です。

## 各ヒントの中身

どのファイルも同じ5つの見出しで書いてあります。

1. **参考プロンプト** — そのまま貼り付けて動く形で書いています。コピーして構いません。
2. **なぜその形か** — その文面にした理由です。ここを読むと、明日から自分の言葉で書けるようになります。
3. **比較観点** — 何と何を見比べると学びが残るかを書いています。演習中に眺めてください。
4. **よくある勘違い** — 過去に詰まりやすかった思い込みです。作業前に読むと事故が減ります。
5. **次のアクション** — 終わったら何をするかと、うまくいかないときの確認項目です。

## 不具合の手がかりの範囲

課題B（`kadaiB`）には不具合が複数仕込まれています。到達ゴールは **2件を修正し、ブラウザで直ったことを確認し、`./mvnw test` を緑にする** ことです。

`hints/` に手がかりを書いているのは、この **2件までです**（`step06_issue_driven.md` の「手がかり（2件分だけ）」の節）。それ以外の不具合について、再現手順も原因も書いていません。探し方は書いてあります。**画面に見えているもの・データの中身・`CLAUDE.md` の業務ルールの文章、この三点を突き合わせる**やり方です。

3件目以降を探す時間は、発展課題（`exercises/challenges/ch05_third_bug.md`）に置いてあります。15分粘っても見つからないときは、講師に声をかけてください。巡回時に方向だけお伝えします。

## 使うときの前提

- VSCode で開くフォルダは常に `handson` です。`kadaiA` や `kadaiB` を単体で開くと、`CLAUDE.md` も `.claude` も `docs/` も読み込まれません。
- Claude Code は、VSCode 左端のアクティビティバーにある Claude Code アイコンからパネルを開いて使います。ターミナルで `claude` と入力する起動方法もありますが、本研修では画面をそろえるためパネルに統一します。
- 設定ファイル（`CLAUDE.md` / `.claude/` / `docs/`）を追加・変更したときは、パネルをいったん閉じて開き直してください。読み込みは起動時に行われます。
- 本研修では Git と GitHub を使いません。Issue はローカルの Markdown ファイルとして `kadaiB/issues/` に置きます。
- 同じプロンプトを送っても、出力は毎回少しずつ変わります。ヒントの文面どおりの答えが返らなくても、失敗ではありません。
- 演習中に「書いてください」と出てくる書き込み先は、ほぼすべて `handson/memo.md` です。`## A-0` から `## B-6` までの見出しが最初から切ってあります。見出しの文字列と並び順は変えないでください。

## それでも解決しないとき

1. エラーメッセージが出ているなら、全文をコピーして Claude Code パネルに貼り、`このエラーが出ています。原因を調べて直してください。` と送ります。エラー文を要約しないでください。そのまま貼るのがいちばん速く直ります。
2. 何が起きているか説明しにくいときは、`いま何が起きているかを切り分けたいです。確認すべきことを順番に3つ挙げてください。` と聞くと、確認の道筋が返ります。
3. 3分待っても状況が変わらないときは挙手してください。環境側の問題は、手元で粘っても解決しないことがあります。
