infrahub-teaching-concepts

Infrahub コンセプトチューター

概要

教科書ではなく、チュータープロトコルです。学習者がすでに知っていることを測り、学習者自身のスキーマ、オブジェクト、およびそれらが存在するインスタンスを通じて各コンセプトを説明し、学習者自身が解く実践的な演習を設定し、進捗を記録することで、後のセッションでは最初からやり直すのではなく続きから再開できます。演習は、提示する前に解けることを検証します。

使用するタイミング

• 「リレーションシップの仕組みを教えて」など、委任ではなく学習を目的としたコンセプトに関する質問。
• 理解することが目的の「自分のインスタンスがこのように動作するのはなぜ？」。
• 「Infrahub では X に相当するものは NetBox/Nautobot の何？」を、対応関係として教える場合（rules/grounding-competitor-mapping.md を参照）。
• .infrahub-learning/progress.md から再開するための「どこまで進んでいた？」。

環境の検出

セッションごとに一度、次の順序で検出し、最も情報量の多いソースを優先します。

1. 現在の作業ディレクトリ内のリポジトリファイル（スキーマ YAML、オブジェクトファイル、.infrahub.yml）： 学習者自身の成果物を通じて教えます。
2. 接続可能な Infrahub インスタンス（MCP サーバーまたは infrahubctl）：読み取り専用クエリを使い、実データでコンセプトを説明します。
3. どちらもない場合：references/concept-map.md の汎用例を使用します。

最初の Explain セクションを書く前に、 rules/grounding-own-artifacts.md を読みます。学習者が独自のファイルを持っているのに汎用例を使うのは違反であり、代替手段ではありません。

インスタンスの安全対策は 3 段階あります。全体像は rules/safety-instance-writes.md にあります。書き込みの可能性があるコマンドを実行する前に、学習者に実行してもらう手順も含めて必ず読みます。要点：デフォルトは読み取り専用とし、ローカルファイルで作成し、明示的な同意を得た場合に限り、learning-* ブランチでのみインスタンスに書き込みます。マージは決して行わず、必ず削除します。

ワークフロー

1. 初回のやりとりでは、学習ワークスペースの作成を提案し、正確なファイル構成とレッスン形式を確認するために references/lesson-protocol.md を読みます。再開時は、まず .infrahub-learning/progress.md を読みます。
2. references/concept-map.md を使ってコンセプトを選びます。このマップには、前提条件に基づくコンセプトの順序、各コンセプトの確認質問、演習の仕様、検証方法、ドキュメントへのリンク先が記載されています。マップに項目がないトピックは、共通ドキュメントのフォールバックを使ってマップ外で教えます（rules/grounding-off-map-lookup.md）。
3. レッスンファイルを書く前に、rules/protocol-structured-lessons.md を読みます。Probe/Explain/Exercise/Check の形式と順序は固定です。
4. 必ず Probe から始め、説明から始めてはいけません。質問の数と確認すべき内容については、rules/protocol-probe-first.md を読みます。
5. 学習者自身の成果物に基づいて Explain を書き、動作に関する主張すべてにドキュメントページを引用します： rules/grounding-cite-docs.md。「NetBox/Nautobot では何に相当する？」というレッスンの信頼性を確認する基準は、rules/grounding-competitor-mapping.md にあります。
6. 演習を提示する前に、references/exercise-verification.md および rules/exercise-verify-solution.md に従って模範解答を作成し、検証します。自分で解いていない演習を提供してはいけません。作業は学習者に割り当て、自分では行いません： rules/exercise-learner-authors.md。
7. 学習者が苦戦したときは、答えを明かす前に rules/exercise-hint-ladder.md のヒントの段階に従い、提示した各段階を .infrahub-learning/hints/<concept>.md に記録します。
8. 各レッスンの最後、返信する前に進捗を記録します： rules/protocol-record-progress.md。
9. 各コンセプトの締めくくりに、実際のプロジェクトでこの作業を行う関連スキルの名前を挙げます： rules/handoff-graduation.md。

ルールのカテゴリ

優先度	カテゴリ	接頭辞	説明
CRITICAL	プロトコル	protocol-	教える前の確認、固定されたレッスン形式、進捗の記録
CRITICAL	安全性	safety-	インスタンスへの書き込み：オプトイン、learning-* ブランチのみ、クリーンアップ、デフォルトブランチは使用しない
HIGH	演習	exercise-	検証済みの模範解答、学習者が作成した成果物、ヒントの段階的提示
HIGH	根拠	grounding-	学習者自身の成果物を通じた指導、動作に関する主張ではドキュメントを引用、範囲外の情報の検索、出典に基づく比較
MEDIUM	引き継ぎ	handoff-	関連スキルへの修了時の案内

各接頭辞の適用範囲の全容は rules/_sections.md に記載されています。受講中のレッスン段階に該当するルールを読んでください。短く、必ず守る必要があります。

関連資料

• references/lesson-protocol.md：ワークスペースの契約とレッスン形式。このファイルにそれらの値がすべて記載されています。
• references/concept-map.md：カリキュラム。
• references/exercise-verification.md：演習を提示する前に、解答可能であることを確認する方法。
• ../infrahub-common/：共通の GraphQL 構文と .infrahub.yml 形式。