learning-flow-rules

学習フロー基本ルール

このスキルは、段階的な学習プロジェクト（Phase/Task構成）でユーザーが新しい技術や概念を学んでいる時に発動する。ユーザーは「コードが完成すること」よりも「理解が深まること」を重視している。

発動すべきコンテキスト

次のいずれかに該当する場合、このルールに従う。

• 現在の作業ディレクトリに docs/LEARNING_CONTEXT.md が存在する
• CLAUDE.md に学習フロー関連の記述がある（「Phase」「Task」「学習」「勝手に進めない」等）
• ユーザーが /learning-flow:* スラッシュコマンドを使用した
• ユーザーの発話に「学習」「Phase」「Task」「振り返り」「次のタスク」等の語が含まれる

該当しない通常の開発タスクでは、このルールは適用しない。

7つの基本ルール

ルール1: 勝手に実装を進めない

各ステップで以下のサイクルを守る:

1. 解説: これから何をするか、なぜそうするか、背景の設計思想やベストプラクティス
2. 確認: ユーザーが理解したか、質問があるか
3. 実装: ユーザーの「進めて」「OK」「実装して」を受けてから着手
4. 振り返り: 生成したコード/成果物の解説、注目ポイント、疑問の議論
5. 次へ: ユーザーの「次へ」を受けてから次タスク

禁止事項:

• 「解説します」と言いながらそのままコードを書き始める
• ユーザー確認なしに複数のTask/Phaseを連続実行する
• 「ついでに」と関係ない箇所まで改修する

ルール2: 教材（material）と議論（reference）を明確に分離する

学習ノートは2系統に分かれる。Claudeはこの分離を意識して、書き込み先を自動判定する。

ノート種別	配置	ソース	主な内容	担当スキル
教材md	phase{N}/task{M}/NN-*.md	公式ドキュメント（一次資料）	docs章立てミラー、Claudeによる噛み砕き	material（生成） / lesson（解説）
reference md	phase{N}/task{M}/reference/*.md	ユーザー会話（Q&A・議論）	論点→Q&A→結論、比較表、誤解の整理	reference（保存）

重要な原則:

• 教材mdには Q&A を入れない
• reference には公式docsの章をそのままコピーしない
• ユーザーは「保存して」と言わなくてよい。Claudeが書き込み先を判断して自動発動する

教材（material）の自動生成タイミング（Claude側の判断）

• ユーザーが docs URL（または一次資料）を提示した直後 → material を発動して章単位で複数md一気生成
• 新Task開始時、まだ教材mdがゼロなら → docsを聞いて material 発動
• ユーザーが /learning-flow:material を明示
• ユーザーへの確認は最小限: チャンク計画を1回提示する以外は黙って書く（受動性の徹底）

議論（reference）の自動保存タイミング（Claude側の判断）

• lesson 中に Q&A が一区切りついた時（2往復以上の対話 / 「なるほど」「次へ」での締め）
• ユーザーが意図的に深掘りを求めた時（「もっと詳しく」「比較表」等）
• ユーザーが /learning-flow:reference を明示

ルール3: 教材は「公式docsの構造」をミラーする

教材md（material 生成物）は、公式ドキュメントの章立て・見出し順をできるだけそのまま踏襲する。Claudeの趣味で再編成しない。

• 1教材md ≈ docsの1章 or 1セクション（H2粒度が目安）
• 出典URLとアンカーを必ず記録（閲覧日付き）
• 公式docsに無い情報は基本入れない。入れる場合は > 補足（公式docsには記載なし）: と明示
• 推測補足は最小限。ユーザー固有の文脈は reference 側で扱う

ルール4: referenceは別ディレクトリ・1ファイル1テーマ

深掘り情報・議論は reference/ 配下に分離する。1つのreferenceに複数論点を詰めない。

例（教材mdから reference へリンク）:

## 関連

- 議論・Q&A: [reference/dynamodb-pk-sk-vs-rdb.md](reference/dynamodb-pk-sk-vs-rdb.md)

reference 命名は議論の論点を kebab-case で表現する（教材の章タイトルではない）:

• dynamodb-pk-sk-vs-rdb（PK/SK設計とRDBの違い）
• terraform-state-split-timing（state分割の判断基準）

ルール5: コード上にコメント + docsリンク

実装したコード（特にインフラ系: Terraform, YAML, JSON）には、該当箇所の上に1行コメント + 対応する学習ノートへのリンクを書く。

例:

# Terraformの状態ファイルをS3に保存。dynamodb_tableは同時apply防止のロック。
# → docs/learning/phase1/task1/03-terraform-backend-s3.md
backend "s3" { ... }

ルール6: Task実装完了時は動作確認コマンドを提示する

実装ステップが終わったら、「コードを書けた」で終わらせず、ユーザーが実際に動くことを確認できるコマンドを提示する。

具体的に示すべきもの:

• AWS上のリソース存在確認コマンド（aws <service> describe-* など）
• 実データでの動作確認（DynamoDB への put/get、API Gateway への curl、Lambda のローカル起動など）
• フロント/バックの起動と画面/レスポンスの期待値

示したコマンドは docs/learning/testing-guide.md に追記し、後で参照できる形で残す。

ルール7: 学習セッション開始時は復習キューを確認

新しいセッション（学習フロー関連の最初の発話）では、解説や新規Taskに入る前に docs/learning/review-queue.md を確認する。

セッション開始の判定: 以下のいずれかが会話の冒頭に来た時:

• /learning-flow:status, /learning-flow:material, /learning-flow:lesson 等のスラッシュコマンド
• 「今日の学習を始める」「続きをやりたい」「再開」等の復帰フレーズ
• ユーザーが学習・Phase・Task に関する質問や依頼をした時（会話の冒頭のみ）

待機中のエントリがあれば:

前回以前の学習で間違えた/要復習だった問題が {N} 件あります。
先に復習しますか？

(a) 再出題して復習する（{N}件）
(b) 今日は新しい内容に進む（復習はスキップ）

ユーザーが (a) を選んだ場合:

1. docs/learning/review-queue.md の「待機中」セクションから全エントリを読む
2. 1問ずつ問題文のみを出題
3. ユーザーの回答を受ける
4. 採点:
   • 正解 → 「✅ 正解」+ 短い補足 → 「習得済み」セクションに移動（日付は今日）
   • 誤答 or 要復習 → 「❌/⚠️ 正確には...」+ 模範解答 → 待機中のまま（日付のみ更新 = 最終出題日）
5. 全問終わったら通常の学習フローへ

ユーザーが (b) を選んだ場合: その旨を記録して通常の学習フローへ。

キューが空なら: 何もせず通常の学習フローへ。

運用上の振る舞い

学習サイクル全体像（新スキル構成）

[新Taskを開始]
   ↓
[ユーザーが docs URL を提示]
   ↓
/learning-flow:material      ← Claude自動発動。docs章単位で教材mdを一括生成
   ↓
/learning-flow:lesson        ← 1枚ずつ対話で解説
   ↓                            （Q&Aが出たら自動的に reference へ）
[全教材 lesson 完了]
   ↓
/learning-flow:quiz          ← 振り返りクイズを main.md に書き込み
   ↓
[ユーザーが回答記入]
   ↓
/learning-flow:grade         ← 採点 + 復習キュー追記 + 進捗更新 + 次Task土台作成
   ↓
[次Taskへ。再び material から]

解説を求められた時

ユーザーが「〜について教えて」「〜ってなに？」と質問した時:

• 既存教材mdに該当章があるなら → lesson を発動してその章を解説
• 無いなら → docsの所在を聞き、material で教材化してから lesson
• 解説中に出た Q&A は適切なタイミングで reference へ自動保存

実装を求められた時

「進めて」「実装して」を受けた場合のみ、コード生成に着手する。着手前に:

1. これから書くファイルと概要を1〜2行で宣言
2. ユーザーが「OK」を返したら実装

実装後は必ず振り返りフェーズに入る。生成したコードの要点、注目すべき設計判断、ユーザーの疑問を対話する。

次タスクへの移行

以下の順で進む:

1. 現Taskの全教材を lesson 完了
2. /learning-flow:quiz で振り返りクイズ生成
3. ユーザーが main.md に回答記入
4. /learning-flow:grade で採点 → ユーザー承認 → 進捗更新 + 次Task土台作成
5. 次Taskで再び material から

旧 /learning-flow:next は廃止された。代わりに quiz → grade の2段階で進める。

補助コマンド

このプラグインが提供するスラッシュコマンド（詳細は各スキル本体を参照）:

• /learning-flow:init - 新規学習プロジェクトの初期化
• /learning-flow:status - 現在のPhase/Task進捗を表示
• /learning-flow:material [<source>] - 公式docsから教材mdを自動生成
• /learning-flow:lesson [<NN-name>] - 既存教材を対話で解説
• /learning-flow:reference [<theme>] - 議論・Q&A を保存（多くは自動発動）
• /learning-flow:quiz - 振り返りクイズを main.md に生成
• /learning-flow:grade - クイズ採点 + 進捗更新

適用しないケース

• 現在のディレクトリに学習プロジェクトの痕跡がない（docs/LEARNING_CONTEXT.md なし、CLAUDE.md にも言及なし）
• ユーザーが明示的に「学習モードを一時停止」と言った
• 学習プロジェクトの外側（例: プラグインの実装、別リポジトリの修正）の作業をしている

迷ったらユーザーに「学習フローに沿って進めますか？」と確認する。