understand

name	understand
description	実装完了後にユーザーの理解を確認する対話スキル。Claudeが何をやったのか・なぜそうしたのかを、ユーザー自身の言葉で説明させることで理解を定着させる。Spring Boot（Java）との対比で技術概念を翻訳する機能も持つ。/impl の完了報告後に自動発動する。
when_to_use	/impl の Phase 2 完了報告の直後に自動発動する。手動で「/understand」と呼んだ場合も発動する。

起動時の分岐（最初に必ず判定する）

このスキルには複数の入り口がある。起動時にどれかを判定してから進む。

1. impl 完了直後の自動発動（/impl の Phase 2-4 から呼ばれた場合） → Phase M（モード選択）を経由せず、直接「Phase H: 宿題への書き出し（＋Issue 自動起票）」へ進む。 実装に充てたい時間を理解チェックの対話に取られないよう、自動発動時は常に宿題化する（モードを聞かない）。
2. 新規の理解チェック（引数なしの手動 /understand） → 「Phase M: モード選択」へ進む（机で今すぐ解きたい日のため、従来どおりモードを聞く）。
3. 宿題の再開（手動 /understand で、未回答の宿題 Issue が存在する場合） → オープン中の understand-homework ラベル付き Issue があるか確認する。 あれば「Phase R: 宿題の再開」へ進むか新規チェックを始めるかをユーザーに尋ねる。
4. GitHub コメント上の一問一答（GitHub Actions 経由で @claude メンションに応答する実行） → 「Phase G: GitHub コメント上の一問一答」へ進む。 CLI 上の /understand ではなく、.github/workflows/claude.yml から起動された Claude が Issue/PR のコメントスレッドで出題・回答・判定を行う入口。

自動発動か手動かの判定

• 自動発動（入口1）: /impl スキルの Phase 2-4 から続けて呼ばれた場合。impl の完了報告直後に このスキルへ入った文脈であれば自動発動とみなし、Phase M を飛ばして Phase H（宿題用 Issue 起票）へ直行する。
• 手動（入口2〜3）: ユーザーが自分で /understand と打って起動した場合。Phase M でモード選択を聞く。
• 厳密なフラグ機構は設けず、上記のスキル手順書ベースの運用で区別する （impl 側 Phase 2-4 にも「自動発動時は宿題用 Issue が起票される」前提を明記してある）。

過去に溜まった宿題の消化は、手動 /understand（入口3 = Phase R）で行う。

未回答の宿題があるかは gh issue list --label understand-homework --state open で調べる。 宿題は GitHub Issue を唯一の正（ソース・オブ・トゥルース）とし、ローカルの Markdown ファイルには一切残さない。

2方式の関係（CLI / GitHub コメント）: 判定基準（核心の有無・ヒント3段階・正誤）は いずれの入口でも Phase 1 を単一の正 とする。Phase R も Phase G も Phase 1 を参照し、基準を重複定義しない。 宿題の状態（出題済み・回答済み）は Issue 本文とコメントスレッドだけで管理し、ローカルファイルは作らない。

---

Phase M: モード選択（手動 /understand 時のみ聞く）

理解チェックを始める前に、今回の問いを「いま解く」か「宿題にする」かをユーザーに尋ねる。 机にいる日はその場で、外出予定の日は宿題、と日によって使い分けられるようにするため、毎回聞く（デフォルト固定にしない）。

このフェーズを通るのは手動 /understand（入口2）のときだけ。/impl 完了直後の自動発動（入口1）は Phase M を経由せず Phase H へ直行する（モード選択を聞かない）。

---
## 理解チェックのモード選択

今回の実装について理解チェックを行います。どちらで進めますか？

1. いま解く（その場で対話形式。従来どおり）
2. 宿題にする（問いを GitHub Issue に起票し、後で GitHub アプリ等から取り組む）
---

• 「いま解く」を選んだ場合 → 「Phase 0: Spring Boot 翻訳」→「Phase 1: 実装理解チェック」を従来どおり実行する。
• 「宿題にする」を選んだ場合 → 「Phase H: 宿題用 Issue の起票」を実行し、/impl をブロックせず終了する。

---

Phase H: 宿題用 Issue の起票（宿題化）

今回の問いを 宿題用 GitHub Issue として起票し、その場では解かずに終了する。 ローカルの Markdown ファイルは一切作らない（宿題は Issue を唯一の正とする）。 このフェーズに来る入口は2つある:

• 入口1（impl 自動発動）: 必ずここへ直行する。モード選択は聞かない。
• 入口2（手動 /understand で「宿題にする」を選択）: Phase M を経由してここへ来る。

どちらの入口でも手順は同一（Issue 起票のみ）。

手順

1. Phase 0 の翻訳結果を生成する（その場表示はせず、Issue 本文に併記するため内部的に用意する）。 後日 Issue 単体で解くときに文脈を失わないよう、Spring Boot 翻訳も Issue 本文に含める。
2. Phase 1 の質問生成ルール（規模区分と質問数の決定、意図/仕組みの両面）に従って問いを生成する。 その場では出題しない。
3. 宿題用 Issue を起票する（下記「Issue 起票」の手順）。
4. /impl をブロックせず終了する。 宿題化した時点でこのスキルの今回分の役割は完了とみなす（解き終えるまで待たない）。

Issue 起票

生成した問いを gh issue create で GitHub Issue に起票する。外出先からその Issue の コメント欄に @claude 付きで回答すれば、Phase G の基準（= Phase 1）で採点が返る。 机に戻ったときも、手動 /understand（Phase R）が同じ Issue を読んで続きから出題する。

起票の手順

1. 採点指示テンプレート（下記）と Phase 0 翻訳・各問本文を埋め込んだ Issue 本文を組み立てる。 テンプレートは #281（手動起票の実例）と同形にする。
2. gh issue create を実行する:
   • タイトル: 理解チェック宿題: ISSUE-<N>（PR #<番号> / Phase G で採点） （Issue番号が特定できない手動起動時は 理解チェック宿題: <実装日>（Phase G で採点））。
   • 本文: 下記の採点指示テンプレート（問い本文を差し込んだもの）。
   • ラベル: understand-homework を付与する。 このラベルが未作成の場合は先に gh label create understand-homework で作成してから付与する （宿題 Issue を一覧でフィルタできるようにするため）。
3. 起票成功後、Issue 番号と URL をユーザーへの完了出力に記載する（下記「起票後の出力」）。

採点指示テンプレート（Issue 本文の雛形）

問い本文（{問N} の部分）を Phase 1 で生成した問いに、{Spring Boot 翻訳} を Phase 0 の翻訳結果に差し替えて使う。

これは understand 理解チェックの宿題です。外出先からスマホで回答するための Issue。

## @claude への採点指示（毎回適用）

このスレッドで `@claude` 付きの回答が投稿されたら、リポジトリ内の
`.claude/skills/understand/SKILL.md` の **Phase G（GitHub コメント上の一問一答）** の手順に従って採点してください。
判定基準（核心の有無・ヒント3段階・正誤）は **Phase 1 のステップ2〜3（3-A〜3-D）を単一の正** とします。
スレッドの履歴を読み、その問いに対する不正解が何回続いているかを数えてヒント段階を判断してください。

## 回答方法（スマホ）

各問の回答を、このIssueのコメント欄に **先頭に `@claude` を付けて** 投稿してください。
1問ずつ投稿すると、Claude が直前までの文脈を踏まえて1問ずつ採点します。

---

## 対象実装

PR #<番号> / <実装日> / 規模区分: <小/中/大>
（<今回の実装の1行要約>）

## Spring Boot 翻訳

{Spring Boot 翻訳}

## 問1
{問1}

## 問2
{問2}

• 採点指示テンプレートの正はこの Phase H 内に置く（専用テンプレファイルは作らず、判定基準と同じく単一の正を保つ）。
• 問いの数・規模区分は Phase 1 の質問生成ルールに従う（小=1問 / 中=2問 / 大=3問）。
• 第三者が読んで「どの実装の・何を問うているか」が分かるよう、対象（Issue/PR）・実装日・規模区分・問い本文を必ず含める。
• Phase 0 の Spring Boot 翻訳を本文に含めることで、後日 Issue 単体で解くときも文脈を失わない。

失敗時フォールバック

• gh issue create（または gh label create）が失敗した場合は、起票せずにその旨を報告して終了する。 ローカルファイルは作らない（宿題は Issue を唯一の正とするため）。 「Issue 起票に失敗。後で再度 /understand を実行して起票し直してください」と報告し、/impl はブロックしない。
• 自動発動（入口1）で起票に失敗しても impl を止めない。

起票後の出力

Issue 起票に成功した場合:

---
## 宿題 Issue を起票しました

{N} 問を宿題 Issue #{番号}（{URL}）に起票しました。
外出先からは Issue のコメント欄に `@claude` 付きで回答すれば、その場で採点されます。
机で取り組むときは `/understand` を実行すれば、この Issue を読んで続きから出題します。
---

Issue 起票に失敗した場合:

---
## 宿題 Issue の起票に失敗しました

{N} 問を生成しましたが、Issue の起票に失敗しました（{失敗理由}）。
後で再度 `/understand` を実行すると、起票し直せます。
---

---

Phase R: 宿題の再開（手動 /understand で未回答の宿題がある場合）

オープン中の宿題 Issue の未回答の問いを、机（CLI）で出題・判定する。回答記録は Issue コメントに残し、 全問終えたら Issue をクローズする。ローカルファイルは作らない（宿題は Issue を唯一の正とする）。

手順

1. gh issue list --label understand-homework --state open でオープン中の宿題 Issue を探す。 複数ある場合はどの Issue に取り組むかユーザーに選ばせる。

2. gh issue view <番号> --comments で Issue 本文とコメントスレッドを読み、 「どの問いに・どこまで回答済みか」を把握する（状態は Issue 上だけで管理しているため毎回読み直す）。

3. 未回答の問いを、上から順に「Phase 1 の対話の進め方」（ステップ1〜3、ヒント段階・正誤判定）でそのまま出題する。 ヒント段階は、その問いに対する過去コメントの不正解回数から判断する（Phase G と同じ数え方）。

4. 1問終えるごとに、回答と判定を Issue コメントに追記する（gh issue comment <番号> --body ...）。 記録を Issue に残し、第三者が読んで理解できる状態にするため。

   **問N の回答（机 / Phase R）:** {ユーザーの回答}
   **判定:** {正解 / 解説など。3-A〜3-D に準ずる}
   

5. その Issue の未回答がすべて消えたら、gh issue close <番号> でクローズし、 「## 理解チェック完了」と同等のサマリを出力して終了する。

---

Phase G: GitHub コメント上の一問一答（GitHub Actions 経由の実行）

外出先からスマホの GitHub アプリ等で Issue/PR コメントに回答を書くと、Claude が判定・ヒントを コメントで返す。CLI に戻らずに理解チェックの一問一答を GitHub 上で完結させるための入口。

起動条件

• .github/workflows/claude.yml が issue_comment / pull_request_review_comment イベントで 起動し、@claude メンションを含むコメントが理解チェックの文脈（宿題の問い・回答）である場合。
• write 権限の制御・トリガー条件はワークフロー側で担保される（このスキルでは扱わない）。

運用方針（GitHub Actions 側）

実体は .github/workflows/claude.yml（anthropics/claude-code-action）。確定済みの方針:

• 認証: CLAUDE_CODE_OAUTH_TOKEN（Claude サブスク連携）を使う。ANTHROPIC_API_KEY の従量課金は採らない （1問ごとに Actions が起動するため、サブスク枠でコストを固定する）。Secret はリポジトリに登録済み。
• トリガー範囲: @claude を含む Issue/PR コメント等（claude.yml の if 条件を参照）。理解チェックの宿題は Phase H で起票した専用 Issue のコメント欄でやり取りする。
• 濫用対策: write 権限を持つユーザーのコメントのみ処理される（GitHub App の標準動作）。private リポジトリ前提。
• 長大スレッドへの対処: トークンが嵩む場合は、問いのまとまりごとに Issue を分ける。
• 制約: .github/workflows/ は GitHub Actions 上の Claude 自身は編集できない。ワークフロー変更は CLI から手動で行う。

進め方

1. スレッド全体を文脈として読む。Issue/PR の本文と全コメント履歴を読み、 「どの問いに・どこまで回答済みか」を把握する（GitHub は会話状態を保持しないため、 毎回スレッドを読み直して文脈を復元する）。
2. 未出題の問いがあれば、1問ずつ出題する。問いの出どころは Issue 本文（Phase H で起票した問い）と スレッド内で既に提示済みの問い。一度に複数問を投げず、Phase 1 と同じく重要な問いから順に1問ずつ進める。
3. ユーザーのコメント回答を判定する。判定基準（核心の有無・ヒント3段階・正誤）は Phase 1 のステップ2〜3（3-A〜3-D）と完全に同一とする。Phase G 独自の基準は設けない。
   • 直前までのスレッドで、その問いに対する不正解が何回続いているかを数え、 ヒント段階（1回目は観点のみ → 2回目は具体ヒント → 3回目は正解提示）を判断する。
4. 判定結果をコメントで返す。Phase 1 のステップ3の出力フォーマットに準じる。 正解なら次の問いを同じコメント内で続けて出題してよい。
5. 全問終了したら完了コメントを返す。「Phase 1 全問終了時」のサマリ（正解数/全問数）に準じる。 GitHub Actions 上の Claude はリポジトリへ push しない前提のため Issue のクローズは行わず、 完了コメントに「全問終了した」旨を明記する。机に戻った CLI 側（Phase R）でクローズする。

Phase R / Phase H との関係

• Phase H で起票した宿題 Issue は、外出先ではそのまま Phase G として解ける。Phase G は宿題の 「出題・判定」を GitHub 上で行うもので、問いの生成ルール（Phase 1 の質問生成ルール）も 判定基準（Phase 1 のステップ2〜3）も Phase 1 を共有する。
• 机に戻ったあとは、手動 /understand の Phase R が同じ Issue を読んで未回答の続きから出題し、 全問終えたら Issue をクローズする。宿題の状態は一貫して Issue 上だけで管理する。

---

Phase 0: Spring Boot 翻訳（理解チェックの前に必ず実行）

「いま解く」を選んだ場合に実行する。「宿題にする」を選んだ場合は Phase H の手順で内部的に生成し、宿題 Issue 本文に併記する。

今回の実装で使われた Next.js / React の技術概念を、Spring Boot（Java）の対応概念に翻訳して説明する。 ユーザーは Spring Boot / Java の開発経験があり、Next.js / React は学習中である。

対応表

Next.js / React	Spring Boot / Java
Server Actions	@Controller の @PostMapping / @GetMapping メソッド
Server Components (RSC)	Thymeleaf テンプレート + Controller（サーバーサイドレンダリング）
Client Components ("use client")	REST API を呼ぶフロントエンド JS（Thymeleaf + fetch/axios）
App Router (app/ ディレクトリ)	@RequestMapping によるルーティング定義
layout.tsx	共通テンプレートレイアウト / Spring Security の FilterChain
middleware.ts	Spring Security の Filter / HandlerInterceptor
page.tsx	Controller メソッド + 対応する Thymeleaf テンプレート
loading.tsx	※ Spring MVC に直接対応なし（フロントエンド固有のローディング表示）
error.tsx	@ControllerAdvice + @ExceptionHandler
Prisma ORM	Spring Data JPA / Hibernate
Prisma schema (schema.prisma)	@Entity アノテーション付き Java クラス
Prisma の findMany, create 等	JPA Repository の findAll(), save() 等
Zod バリデーション	Jakarta Bean Validation (@Valid, @NotNull, @Size 等)
React Hook Form	Spring MVC のフォームバインディング (@ModelAttribute)
Supabase Auth	Spring Security + JWT / OAuth2
API Route (route.ts)	@RestController のエンドポイント
useEffect	※ フロントエンド固有。Spring に対応なし
useState	※ フロントエンド固有。Spring に対応なし
Tailwind CSS	※ CSS フレームワーク。Java 側に対応なし
revalidatePath / revalidateTag	Spring Cache の @CacheEvict
redirect()	return "redirect:/path"
cookies() / headers()	HttpServletRequest から取得
環境変数 (process.env)	application.properties / @Value

出力フォーマット

---
## Spring Boot 翻訳

今回の実装を Spring Boot で例えると:

**変更内容の要約**
{1-2文で今回やったことを要約}

**ファイルごとの対応**
- `{変更したファイル}` → Spring Boot では `{対応するクラス/ファイル}` に相当
  - {具体的な説明}

**使われた技術概念**
- {Next.js の概念}: Spring Boot でいう {対応概念}。{補足説明}

**Spring Boot 開発者として注意すべき違い**
- {考え方が根本的に異なる部分があれば記載。なければ省略}
---

ルール

• 今回の実装で実際に使われた概念だけを翻訳する（対応表を全部出さない）
• 対応がない概念（useState 等）は「Spring Boot に対応なし。フロントエンド固有の仕組みで〜」と正直に伝える
• 翻訳は簡潔に。1概念につき1-2文で説明する
• ユーザーが追加で「これは Spring Boot でいうと何？」と聞いてきたら、対応表を参考に回答する

---

Phase 1: 実装理解チェック

実装完了後、ユーザーが「何が変わったのか」「なぜそうしたのか」を自分の言葉で説明できるか確認する対話を行う。

Phase 1 の質問生成ルール

今回の実装内容を振り返り、以下の両面から質問を作る:

• 意図（なぜ）: なぜこの実装方針を選んだのか、なぜこの設計にしたのか
• 仕組み（どう動くか）: 技術的にどう動作するのか、データの流れはどうなっているか

質問数の決定

変更の規模に応じて質問数を決める:

• 小さい修正（1〜2ファイル、バグ修正、スタイル調整など）: 1問
• 中規模の変更（新しいコンポーネント追加、API追加など）: 2問
• 大きい機能追加（複数ページ、DB変更、認証周りなど）: 3問

各質問は、今回の実装で最も重要なポイントから順に出題する。

対話の進め方

ステップ1: 質問を出す（ヒントなし）

質問をユーザーに投げかける。最初はヒントを一切出さない。

出力フォーマット:

---
## 実装理解チェック（1/N問目）

【質問】
{質問文}

あなたの言葉で説明してください。
---

ステップ2: 回答を判定する

ユーザーの回答を受け取ったら、核心を突いているかどうかを判定する。

• 技術用語の正確さは求めない
• 言い回しが多少違っていてもOK
• 核心部分（なぜそうしたか、どう動くか）を自分の言葉で説明できていれば正解

ステップ3-A: 正解の場合

正解です！

{ユーザーの理解を補強する一言（30文字以内）}

次の質問があればステップ1に戻る。全問正解なら対話を終了する。

ステップ3-B: 不正解の場合（1回目）

ヒントは出さず、どの部分が惜しいかだけ伝える。

惜しいです。{どの観点が足りないか}の部分をもう少し考えてみてください。

ステップ3-C: 不正解の場合（2回目）

具体的なヒントを1つ出す。

ヒント: {実装内容に関連する具体的な手がかり}

ステップ3-D: 不正解の場合（3回目）

正解を伝えて次の質問へ進む。

正解はこうです:

{正解の説明}

次の質問に進みます。

全問終了時

すべての質問が終わったら、以下を出力して対話を終了する。

---
## 理解チェック完了

{正解数}/{全問数} 問正解でした。
---

注意事項

• 質問はコードの細部（変数名、行番号など）を問うものではなく、設計意図や動作の流れを問うこと
• ユーザーが「スキップ」「わからない」と言った場合は正解を教えて次に進む
• 対話中にユーザーが追加の質問をしてきた場合は、それに答えてから理解チェックに戻る