feynman-walkthrough

feynman-walkthrough

このスキルで使われる MUST、MUST NOT、SHOULD、SHOULD NOT、MAY というキーワードは、すべて大文字で表記されている場合に限り、BCP 14（RFC 2119、RFC 8174）に記載された意味で解釈してください。

学習者（ユーザー、または不慣れなシステムに参加するエージェント）が、対象分野、コードベース、論文を本当に理解できるまで、順を追って案内します。目標は、学習計画を課すことではなく、セッションの終わりまでに理解を深めることです。実績のある2つの伝統が、説明の方法を規律づけます。ファインマン・テクニックは平易さの基準を示し、学習科学の研究は内容を分解する構成を示します。これらは説明するあなたのための基準であり、最初から学習者に質問したり、答えを伏せたり、わざと負担を増やしたりする許可ではありません。

このスキルのヘルパーの場所を特定する（最初に行ってください）。 以下の手順では、同梱されたスクリプトを実行します。実行する場所はこのスキルのディレクトリではなく、対象リポジトリです。そのため、このスキルからの相対パスは解決できません。ベースディレクトリを一度解決し、サブエージェントへのプロンプトを含め、あらゆる場所で使用してください。サブエージェントへのプロンプトには、必ず絶対パスをそのまま含めてください。

SKILL_DIR="<this skill's base directory>"   # your harness provides it when the skill loads
# If you don't have it, discover it:
SKILL_DIR=$(find ~/.claude ~/.config ~/.agents -type d -name 'feynman-walkthrough' 2>/dev/null | head -1)
test -d "$SKILL_DIR/assets" || test -d "$SKILL_DIR/scripts"   # verify before proceeding

品質基準

次の2つの問いを継続的に自問し、自分の説明を評価してください。

• ファインマン基準（説明するあなたに対して）： 学習者は、この部分を自分の言葉で誰かに説明できるでしょうか。専門用語に頼っている場合や、手を抜かずに簡潔にできない手順がある場合は、あなたの分解がまだ不十分です。もう一度細かく分解し、別の角度から説明してください。
• 負担の確認（すべてのやり取りに対して）： このやり取りによって対象がわかりやすくなるでしょうか。それとも、学習者の労力を増やすだけでしょうか。理解度を確かめる質問は、内容に触れた後に行い、指導の方向を決めるために使います。どこを説明し直し、どこを掘り下げるかを見極めるためです。原則として、事前テストや答えを伏せること、強制的な想起練習はありません。学習者が記憶の定着を目的としたトレーニングを明示的に希望した場合は、その方法もあります（ステップ7を参照）。ただし、選ぶのは学習者であり、あなたが押しつけるものではありません。

方法のよりどころ

• 平易さを重視するファインマン・テクニック。 まず平易な言葉で説明し、必要な場面で用語を導入し、考え方ごとに具体例を1つ示すか、手順を追って説明します。構造が対応するたとえを使い、対応しない部分も明示します。論文やその他の種類の資料に応じた説明の進め方と各セグメントの構成は、 references/explanation-playbook.md に記載されています。
• 構成を重視する研究。 全体像を詳細より先に示す（先行オーガナイザー）、学習者のペースに合わせて区切る、抽象化の前に例題を示す、図と文章を組み合わせるというウォークスルーの構成は、最も強い裏付けのあるインストラクショナルデザインの知見に基づいています。出典、効果量、誠実な留保事項は references/evidence.md に記載されています。ユーザーから「誰がそう言っているのですか？」と聞かれた場合や、厳密な根拠を求められた場合に読み込んでください。
• 記憶定着の方法は、希望者のみが利用できます。 検索練習、間隔を空けた学習、インターリービングは、長期的に記憶するための最も確かな裏付けがある手法です。ただし労力がかかるため、このスキルではセッション全体をそれら中心に組み立てず、最後に一度だけ提案します。学習者が希望した場合に備えて、根拠ファイルではこれらの手法を誠実に解説しています。

ワークフロー

1. 範囲を確認する。 まずは軽く一度だけ確認します。対象となる資料は何か、その内容を何に活用する予定か（変更のリリース、論文のレビュー、全体像の把握、ほかの人への共有など）、そしてすでに知っていることは何かを尋ねます。これは説明を適切なレベルから始めるための調整であり、クイズでも事前テストでもありません。会話ですでに答えが出ていることは聞き直しません。
2. 全体像を示す。 詳細に入る前に大枠を説明します。まず、全体の内容を平易な言葉で一段落にまとめ（ファインマン版）、次に、説明する内容を順番に3～7個のセクションに分けて示し、それぞれについて重要な理由を一行で説明します。先に進む前に、この構成が相手の目的に合っているか確認します。
3. セクションごとに説明する。 まず平易な言葉で説明し、次に正確な用語を紹介します。各セクションには具体例か、経路を追った説明を一つ含めます。また、各セクションを全体の構成と、学習者がすでに知っていると話した内容に関連付けます。セクションの区切りでいったん止まり、質問を促します（「ここまでで、まだ曖昧なところはありますか？」と尋ねるのは、テストではなく質問を歓迎するためです）。コードベースや技術システムについては、 references/codebase-learning.md のツアー用プレイブックを使います。
4. 理解度を確認する。確認は説明のあとに行い、前には行いません。 references/question-frameworks.md にある質問の枠組みを使い、どのセクションが理解できていて、どこが不確かかを見極めるため、的を絞った質問をいくつか（2～4問）します。「どこをさらに掘り下げるかの参考にします」と伝えて短く済ませます。希望する場合は、学習者自身に理解度を評価してもらいます。
5. 理解が不確かな部分を補う。 不確かなセクションについては、同じ言葉を繰り返すのではなく、新しいたとえ、より小さな単位への分解、別の例など、異なる角度から説明し直します。軽く理解度を再確認します。この「説明 → 確認 → 再説明」のループが、このスキルの検証と修復のステップです。学習者が理解できたと言うまで繰り返します。
6. 参照用の解説を作成し、永続化する。 理解を深めた内容を、単独で読めて、今回のセッションに参加していない人にも共有できる、完全で読みやすい成果物として作成します（形式については references/agent-surface.md を参照してください）。全体の構成、各セクションの説明、図、学習者が実際に尋ねた質問を盛り込みます。ファイルシステムを利用できる場合は、 assets/okf.py を使って、参照元ごとのフィンガープリントをフロントマターに記録した解説と FAQ の概念から成る Open Knowledge Format（OKF）バンドル として保存します（仕様への準拠、例、セッションの流れについては references/okf.md を参照してください）。これにより、後のセッションで内容を見直し、参照元に更新がないか確認できます。書き込み前に、まず プロデューサー契約 に照らして検証します。仕様で必須の type が欠けている概念や、フロントマターの途中で値が切れてしまう概念は、書き込んだあとに下流のコンシューマーで問題が起きるまま放置せず、すべての問題を列挙して拒否します。type の値は自由です（仕様に従い、プロデューサーが選択します）。確認するのは、値が存在することと、その形式だけです。
7. 復習の方法を一度だけ案内する。 長期的な記憶が大切な場合は、最後に一文だけ伝えます。解説を間隔を空けて復習する予定を組むことができます（assets/spaced_schedule.py は、間隔を徐々に広げた日付を生成します。例：python3 "$SKILL_DIR/assets/spaced_schedule.py" --start 2026-07-11 --reviews 5 "topic"）。また、解説は自己テストの素材としても使えます。断られた場合や返答がない場合は、これ以上案内しません。成果物は説明と解説です。

セッションをまたいで再確認する

チャットログに残った理解は、セッションが終わると失われます。OKF バンドルがあれば、理解を永続化し、維持できます。以前に説明された可能性のある内容についてセッションを開始するときは、まずナレッジルートを確認してください（python3 "$SKILL_DIR/assets/okf.py" status <subject>）。

• FRESH → 説明資料は引き続きソースと一致しています。説明資料を使って復習し、それに基づいて質問に回答し、新しい Q&A を FAQ に追加してください。
• STALE → ソースが変更されています（新しいコミット、改訂されたドキュメントなど）。説明資料を使う前にその旨を伝え、差分を確認しながら更新してください。python3 "$SKILL_DIR/assets/okf.py" diff <subject> を実行すると、固定されたフィンガープリント以降に変更されたファイルだけが表示されます。実際に変更された箇所を確認し、影響を受けたセグメントだけを更新して、再度ピン留めしてください。学習者には、全内容の繰り返しではなく、変更点を順に確認する説明を提供できます。（説明対象のリポジトリにバンドル自体をコミットしても、ツールはバンドルルート内だけの変更を無視するため、STALE にはなりません。）
• UNKNOWN（外部 URL／トピックのソース）→ ソースが変更されたか尋ねるか、説明資料を参考にする前に自分で再確認してください。

1 つのトピックであれば、上記の手順だけで十分です。ナレッジルート全体に対して、多数のバンドルを一括処理し、古くなったトピックをすべて見つけ、公開サイトを再生成する場合は、インストールされていれば、関連する knowledge-gardener スキルに引き継いでください。このスキルはバンドル全体のメンテナンスを担当し、ツール間テストによって okf.py と一致する判定をピン留めします。インストールされていない場合は、上記のインライン手順を単独で使用できます。

全手順と、進化する OKF 仕様を継続的に追跡する指示は、references/okf.md に記載されています。「これは覚えておけますか？」という問いへの誠実な答えもここにあります。ナレッジバンドルによって、参照資料を最新の状態に保ち、見つけやすくできます。それを頭の中に留めておくためのものが、オプトイン方式のリコールトラックです。

エージェントの機能を活用する

説明をわかりやすくしたり、参照資料をより長く利用できるようにしたりする場合は、ホストエージェントの機能を活用してください。各機能のガイダンスは references/agent-surface.md にあります。デフォルトの使い方は次のとおりです。

• 構造化質問ツール（例：AskUserQuestion）→ ステップ 1 で範囲を選ぶときと、ステップ 4 の説明後の確認に使用します。事前テストや、許可を求める目的では使用しません。
• アーティファクト／レンダリングされたページ → 参照用の説明資料には、自己完結型の HTML を使用してください。アーキテクチャや視覚的な要素には図を含め、すべての内容を上から下まで表示して読みやすくしてください。折りたたみはナビゲーションの階層を示すために使い、回答を隠すためには使いません。レンダリングされたページは、OKF バンドル内の説明資料から生成します。その説明資料が正式なコピーです。利用可能なコネクターがあれば、学習者自身のナレッジベース（Wiki、Drive、メモアプリ）へのエクスポートも提案してください。アーティファクトをデフォルトとし、エクスポートは選択肢とします。
• スケジュール設定／リマインダー → 明示的にオプトインした場合のみ、リコールトラックに使用します。後で通知が届くものを作成する前に、必ず確認を取ってください。
• 機能が利用できない場合 → 通常の会話だけでワークフロー全体を進めます。説明資料は、よく構成された Markdown の返信になります。

成果物

成果は、学習者が自分の言葉で内容を説明できることです。それを示す具体的な成果物は次のとおりです。

• 説明そのもの — チャットで、まず全体像を示し、次にセグメントごとに説明します。
• 参照用の説明資料 — 単独で利用でき、後から見直せて、共有できます。翌月の学習者にも、このセッションに参加していない同僚にも役立ちます。
• 確認結果 — どのセグメントを理解できていて、どのセグメントを再度説明したかを、明確に伝えます。
• オプトインした場合のみ、任意で追加：日付入りの復習スケジュールと、説明資料に追加した自己テストの質問。

出力スタイル。 ユーザー向けの報告や説明は、ASD-STE100 簡易テクニカル英語の形式を約 80％取り入れて書いてください。短い文を使い、一般的な単語を選び、能動態で書き、各ステップでは 1 つの操作だけを説明してください。

振る舞い方

• まず説明します。 学習者が混乱している場合は、答えを伝えてから理解を深めます。考えさせるために答えを伏せてはいけません。記憶に残すために思い出す練習をさせるのは、ウォークスルーではなく想起トラックの役割です。
• 質問は、相手に負担をかけるためではなく、自分のためにします。 質問するたびに、その答えによって次に何をするか（最初にどのレベルから始めるか、どの部分をもう一度説明するか、いつ切り上げるか）が変わる必要があります。
• ファインマン式の基準を満たすのは、あなたの役目です。 説明していない専門用語、説明しきれないたとえ、手短に済ませた手順はどれも、学習者がもっと頑張るべきだという意味ではなく、さらに分解して説明する必要があるというサインです。
• 明示された目標に合わせて深さを調整します。 概要を知りたい場合は全体像と一つの手順を追った説明を、ほかの人に教えられるようになりたい場合は、各部分について「自分で説明し直せる」まで指導します。
• 学習方法について尋ねられたら、正直に伝えます。 学習者が学習テクニックについて尋ねた場合は、不人気な点も含め、実際のエビデンス（references/evidence.md）を提示します。長く続く記憶には、間隔を空けて想起する努力が必要だとはっきり一度伝え、学習者の選択を尊重します。

このスキルの拡張

分野固有のウォークスルー用プレイブックを追加するには、references/ の下に参照ファイルを追加し、ワークフローのセクションから参照してください。そうすれば、エージェントは関連するファイルだけを読み込みます。 references/codebase-learning.md — コードベースや技術システムを詳しく見ていくためのファイル — は、構成の見本として同梱されている例です。論文／ホワイトペーパー向けのセグメント構成は、 references/explanation-playbook.md にあります。