tutorkit

tutorkit

複数のセッションを通してトピックを教え、定着した内容を記憶します。tutorkit は、トピックごとにフォルダーを分けた学習リポジトリをひとつ維持し、ユーザーがすでに知っていることの少し先を狙って各レッスンを組み立て、印刷できる HTML 成果物としてレッスンを書き込み、後日実施する想起のきっかけを予定します。ユーザーのことを覚え、学習に合わせて調整するのが家庭教師です。その記憶を持続させることが、設計のすべてです。

4 つの姿勢であり、4 種類の見せ方ではありません。回答して何も書き込まない explain、教え、トラックを開く唯一のモードである lesson、複数のトピックにまたがって想起をテストする drill、理解度を測り、教えることを拒む exam です。

status は 5 つ目のモードですが、5 つ目の姿勢ではありません。何も教えず、何も尋ねず、採点もしません。2 つのルーターファイルを読み取り、すべてのトラックの状況を表示し、次に行うことを決めます。4 つの姿勢のうち、どれを実行するか決めるために使ってください。

tutorkit ではないもの

• コードを書くツールではありません。 ユーザーのプロジェクトに機能を実装することはありません。コードを読み取って例を作り、そこで終わります。
• 意思決定レポートではありません。 「どのキューライブラリを使うべきか」は、どちらも一次資料を読むとしても、調査の質問です。
• プロジェクトのドキュメントではありません。 ユーザーのリポジトリについて何も文書化しません。
• 間隔反復エンジンではありません。 固定された 5 段階の間隔ラダーを使い、SM-2 や FSRS の調整、Anki へのエクスポート、保持率のモデル化はありません。スケジュールは復習を実施するためのものであり、最適化を目指すものではありません。
• 汎用ツールとして設計されてはいません。 どのトピックにも対応しますが、リポジトリに基づく学習、実行可能な演習、ソースコードの引用が特に明確なソフトウェアエンジニアリング向けに調整されています。
• 学習リポジトリを自動でコミットすることはありません。

モードの選択

これはスキルにおける最初の判断であり、トリガーが意図的に重なっています。 「X の仕組みを説明して」は explain、「X を教えて」は lesson ですが、言い回しから得られる手掛かりは弱いものです。表現ではなく意図をもとに判断してください。回答を求める質問なら explain、最終的にその事柄を理解することを求める依頼なら lesson です。「期限が来たものは？」「クイズを出して」「テストして」は drill です。「準備はできている？」「実際のところ、どのくらい知っている？」「試験して」は exam です。「今の状況は？」「何を学んでいる？」「学習状況」「進捗を見せて」は status です。

トピックを指定しない依頼は、ほぼ必ず status です。 これが全体で最も明確な区別です。他の 4 つのモードにはスラッグが必要ですが、status はスラッグを受け付けません。「準備はできている？」はトピックを指定して理解度を測るため exam です。「今の状況は？」はトピックを指定せず、すべてのトラックを報告するため status です。

依頼が本当に曖昧な場合は、手間の少ないほうを選んでください。explain を実行し、最後にトラックを提案します。lesson と推測すると、ユーザーが求めていないミッションの聞き取りが発生します。explain と推測した場合は、文がひとつ増えるだけです。

学習リポジトリ

すべての状態は、ユーザーの作業リポジトリの外にある1つのリポジトリに保存されます。既定では ~/learning ですが、$TUTORKIT_HOME が別の場所を指定している場合はそちらを使います。作業リポジトリの外に置くことで、スキルは作業リポジトリを例の参照元として読み取りながら、そこにメモを書き込まずに済みます。

~/learning/                          ← one git repo; $TUTORKIT_HOME overrides
  INDEX.md                           ← the router
  REVIEW.md                          ← cross-topic due queue, one row per topic
  NOTES.md                           ← how the user likes to be taught, global
  assets/lesson.css                  ← copied from the skill on first run, never overwritten
  topics/<slug>/
    MISSION.md                       ← append-only; why they are learning it, plus the grounding consent
    PROGRESS.md                      ← placement result, what stuck, what is shaky, where they are
    CUES.md                          ← retrieval cues, key points, due dates, interval step, last seen
    SOURCES.md                       ← vetted primary sources, so the agent stops re-searching
    lessons/0001-<dash-case>.html
    reference/<name>.html            ← printable cheat sheets and the glossary
    exercises/                       ← runnable practice, code topics only

初回使用時にリポジトリを作成し、その中で git init を実行します。進捗履歴は本当に役立ちますし、リポジトリはユーザー自身のものです。自動でコミットしてはいけません。 セッションの最後にコミットを提案し、断られたらそれを受け入れます。

ルーティング規則は、設計の根幹を支えるガードです。 セッション開始時に INDEX.md と NOTES.md を読み、スラッグを必ず1つだけ特定してから、topics/<slug>/ のみを読みます。topics/ 全体をグロブで検索してはいけません。この規則がなければ、ユーザーが学ぶほどスキルの性能が低下しますが、それはまさに避けるべき方向です。トピックが30個あっても、ルーティングには約60行で済みますが、全件を開くと数万トークンに達します。

例外は2つのモードだけで、どちらも対象範囲が限られています。drill は依頼内容ではなく REVIEW.md からスラッグを特定し、そのトピックの CUES.md のみを開きます。レッスンは読みません。また、グロブも使いません。交互に練習するには複数のトピックを同時に参照する必要がありますが、トピックごとに複数のファイルを読む必要はありません。

status はさらに厳格な例外です。すべてのトピックについて報告しますが、トピックフォルダーは一切開きません。これは、ダッシュボードに表示するすべての項目や、そこから導出する日付が、すでに INDEX.md と REVIEW.md に記載されているため可能です。トピックフォルダーを開く横断的な表示は、トレードオフではなく設計上の失敗です。 2つのルーターファイルがあるのは、ユーザーのトピック数が増えても読み込み量が一定に保たれるようにするためです。

現在の作業ディレクトリが学習リポジトリそのものである場合は、それを学習リポジトリとして扱い、根拠情報の参照元にはしません。 この2つの役割が重なることはありません。そのため、学習リポジトリ内から lesson を実行した場合は、ユーザー自身のメモについて教えることを提案するのではなく、根拠を尋ねる質問を省略します。

ルーター

INDEX.md にはエイリアスが含まれているため、あいまいな依頼でも何も開かずに振り分けられます。

| Topic | Slug | Also called | Status | Last touched |
|-------|------|-------------|--------|--------------|
| Postgres MVCC | `postgres-mvcc` | transaction isolation, snapshot, vacuum, row locking | active | 2026-08-11 |

ステータスは active または learned です。振り分けの結果は3通りで、いずれもコストは低く抑えられます。

• 依頼がスラッグまたはエイリアスに一致する → そのフォルダーを開きます。
• 何にも一致せず、ユーザーが深く学びたい場合 → フォルダーを作成してトラックを開始します。
• 何にも一致せず、ユーザーが回答を求めている場合 → explain を実行し、何も書き込みません。

REVIEW.md にはトピックごとに1行を記載し、手がかりごとには記載しません。例：postgres-mvcc · due: 2026-08-18, 2026-08-18, 2026-08-21, 2026-09-08 · min step: 3d。due セルには、そのトピック内のすべての手がかりの期限を並べ替えて記載し、手がかりに関するそれ以外の情報は記載しません。期限数は読み込み時に算出します。今日までの日付の数を数えてください。数は保存しないでください。保存した数が正しいのは書き込んだ日だけであり、翌日期限を迎える手がかりが数に反映されなくなるためです。drill は行を読み、期限を迎えたトピックを確認して、それらの CUES.md ファイルだけを開きます。ここに手がかりの文章を保存すると、回答が重複し、手がかりを管理するレッスンと内容が食い違う可能性があります。

min step は、そのトピック内の手がかりが到達した間隔ステップの最小値です。これにより、ルーターだけで答えられる問い「このトラックは完了したか？」が分かるため、記載する価値があります。最小の手がかりが 60d のトピックは、learned の条件のうちスケジュールに関する部分を満たしています。そのため、status は CUES.md を1つも読まずに exam を認定できます。平均ではなく最小値を保存してください。条件はすべての手がかりが 60d に達していることであり、手がかりが1つでも 1d なら満たされないためです。

どちらのファイルもキャッシュであり、キャッシュには修復手段が必要です。 修復は、モードがすでにトピックフォルダーを開いている場合にのみ実行されるため、フォルダーを1つだけ開くという制約に反しません。

• トピックフォルダーを開くすべてのモードは、行に誤りがあるかどうかにかかわらず、そのフォルダーの CUES.md と MISSION.md を基に、両ファイル内の該当トピックの行を書き直します。
• ディスク上にフォルダーがあるのに INDEX.md に行がないスラッグは、その行があるものとして振り分けます。そのスラッグで lesson、drill、または exam を実行すると、フォルダーを開いて行を書き込みます。
• status はトピックフォルダーを開かないため、何も修復しません。 ルーターに記載されていないフォルダーと、フィールドが欠けているか古い形式の行をそれぞれ示し、そのスラッグで lesson を実行するよう案内します。

min step がない REVIEW.md の行、または期限の代わりに保存済みの数が記載された行は、現在の形式になる前に書かれたものです。そのトピックを開く次のモードが、現在の形式で行を書き直します。自己修復がなければ、手作業での編集ミスによって、誤った振り分けが気づかれないまま続いてしまいます。

スタイルシート

assets/lesson.css はこのファイルと同じ場所に含まれています。初回実行時に、このスキルがインストールされているディレクトリを特定し、スタイルシートを <repo>/assets/lesson.css にコピーしてください。作業ディレクトリはスキルのディレクトリではなくユーザーのプロジェクトなので、相対パスではスタイルシートが見つからないためです。コピーは一度だけ行い、その後は上書きしないでください。 以降のスキル更新では、新しいリポジトリに新しいデフォルトが適用され、既存のレッスンの表示は書かれた当時のまま保たれます。インストール先のパスを直接参照すると、スキルの場所が移動した時点で、すべてのレッスンが壊れてしまいます。

モード

各モードの本文は、modes/ 内のファイル1つずつに記載されています。モードの選択に従って振り分け、該当するファイルを1つ読み、その指示に従ってください。この行より上のすべての内容と、以下の共通セクションは、すべてのモードに適用されるため、モードのファイルでは繰り返しません。

• モード status → modes/status.md を読み、その指示に従います。
• モード explain → modes/explain.md を読み、その指示に従います。
• モード lesson → modes/lesson.md を読み、その指示に従います。
• モード drill → modes/drill.md を読み、その指示に従います。
• モード exam → modes/exam.md を読み、その指示に従います。

間隔スケジュール

間隔：1d → 3d → 7d → 21d → 60d。ヒントはトピックごとに CUES.md に記録します。

| id | cue | key points | due | step | misses | last seen |
|----|-----|------------|-----|------|--------|-----------|
| 3 | Why does a long-running read never block a write in MVCC? | readers see a snapshot; writers make a new row version; visibility is decided per transaction | 2026-08-21 | 3d | 1 | 2026-08-18 |

• got it は間隔を1段階進めます。
• partial は同じ間隔で繰り返します。
• missed は 1d にリセットし、ヒントをその場で再度教えます。

遅れによる減衰はありません。 上限によって保留されたヒントは、ユーザーではなくスキル側の負債です。上限によって、期限から30日過ぎたヒントが保留されることもあります。スケジュールのルールは2つより1つのほうが理解しやすく、partial の評価があれば、減衰ルールが対処するはずの事態の大部分をすでに吸収できます。

自由記述の回答を評価する

ヒントに保存された2～3個の重要ポイントを基準に、3段階で評価します。

• got it。 表現は問わず、重要ポイントを押さえています。
• partial。 重要ポイントの一部を押さえているか、要点は合っているものの細部が間違っています。
• missed。 重要ポイントが含まれていないか、回答がそれらと矛盾しています。

正誤の二択では、半分正解の回答（ほとんどの回答がこれに当たります）を誤って判定せざるを得ません。3段階目の評価を設けることで、曖昧さをどちらかに誤って寄せずに吸収できます。

不正解のときだけでなく、すべての評価で判定の修正を提案してください。 間隔の段階全体がこの判定に基づくため、ユーザーが判定を訂正できる必要があります。特に、重要ポイントでは想定されていない言葉で正解した場合に必要です。

レッスンの成果物

topics/<slug>/lessons/NNNN-<dash-case>.html に置く、単独で完結したHTMLファイルです。../../../assets/lesson.css にリンクします。Tufte の制約として、1カラム、広めの余白、脚注ではなく傍注を採用し、およそ700語を上限とします。作業記憶には限りがあり、長いレッスンは最後まで終わらないレッスンです。

各レッスンには、次の項目を順番に含めます。

1. ミッションとの関連を示す1行。そのレッスンの執筆時に参照した、日付入りの MISSION.md エントリーを明記します。
2. ユーザーの予測と、どこが間違っていたか。
3. 仕組み。
4. 具体例を1つ。
5. フィードバックループを含む練習問題。
6. スケジュールに登録されたヒント。
7. 次に読むべき一次資料。
8. 関連するレッスンとリファレンスシートへのリンク。
9. まだ不明な点があればエージェントに質問できることを思い出させる締めくくりの一文。

ミッションのエントリーを明記することで、ミッションが変更されても古いレッスンをそのまま残せます。更新前のミッションに基づいて書かれたレッスンは、間違いではなく、古いものとして読めます。

新しく作る前に、既存のものを再利用してください。 まず assets/ を読み、すでにあるコンポーネントを使って作成します。スタイルシートがあるからこそ、ばらばらのファイルの寄せ集めが1つのコースとしてまとまります。また、ユーザー自身のトピックで得られたコンポーネントも、その隣に蓄積されます。別のレッスンでも重複するものを、インラインで再度書いてはいけません。

繰り返し参照するものがリファレンスシートなので、説明の物語ではなく、要点を凝縮して記載します。表、判断ルール、図などにし、内容を物語形式で書き直してはいけません。reference/<name>.html に作成します。用語集を一度作成したら、その後のすべてのレッスンでそれに従います。

クイズの選択肢は、単語数と文字数を同じにします。そうすれば、書式から答えが漏れることはありません。

レッスンを開く処理は、できる範囲で試みますが、決して処理を妨げてはいけません。 プラットフォームの起動コマンド（macOSでは open、Linuxでは xdg-open、Windowsでは start）を試します。いずれも成功しなければ、ファイルパスを表示して先に進みます。レッスンの書き込みに成功した場合、ブラウザーが起動しなかったことを理由に失敗を報告してはいけません。

引用のルール

自明でない主張にはすべて一次資料を添えます。仕様書、RFC、ソースコード、公式ドキュメント、変更履歴などです。ブログ記事を読むより、ソースを読むことを優先してください。 出典が見つからない場合は、断定するのではなく、「Xだと考えますが、出典を確認できませんでした」と記載します。

読んだ資料は SOURCES.md に記録します。タイトル、URL、読んだ日付、その資料で確定できることを一行で記載します。これにより、後のセッションで同じことを再検索せずに済みます。検索する前に SOURCES.md を確認してください。

引き継ぎ

このセクションは手順を示す文体で書きます。1文につき指示は1つとし、能動態、現在形、比喩なしで記述します。

変更内容。 作成したレッスン、設定した合図、記録した評価、曖昧だと判断した点を示します。変更しなかった内容も示します。辞退したトラック、出典を確認できなかった合図、記録を拒否したステータスを示します。

保存先。 トピックフォルダーのパスとレッスンのパスを示します。この実行でリポジトリを作成した場合は、リポジトリのパスも示します。

次のステップ。 状態に応じて、次に行うことを1つ選びます。

• 合図が今すぐ必要な場合 → drill を実行します。
• トラックの途中で、必要な合図がない場合 → 次の lesson を実行します。
• すべての合図がステップ 60d にあり、トラックが完了したように見える場合 → exam を実行します。
• トラックが learned として終了した直後の場合 → 次のステップはないと伝えます。tutorkit は基本的に終端です。後続の手順を作り出してはいけません。

その後、学習リポジトリへのコミットを提案します。許可を得ずに実行してはいけません。

status の実行は、出力全体が引き継ぎになるため、締め方が異なります。 ダッシュボードに次に行うことがすでに示されているため、同じ内容を重ねて出力してはいけません。変更がなかったことを伝え、修正が必要な各行を示します。コミットを提案してはいけません。

explain の実行は、何も書き込まないため、短く締めます。 変更がなかったことを伝えます。ユーザーがトラックの提案を受け入れた場合は、そのトピックの lesson を次に行うこととして示します。断った場合は、次のステップはないと伝えます。コミットを提案してはいけません。

関連するルートが2つありますが、どちらも範囲は限られています。関連スキルがインストールされている場合に限り、そのスキルの名前を挙げます。それ以外の場合は、行う内容をそのまま説明します。質問が知識の不足ではなくツールの選択に関するものだと分かった場合は、リサーチスキルに誘導します。誠実に答えるには実際に作って確かめるしかない場合は、プロトタイプ作成スキルに誘導します。

注意事項

• コンテキストガードは、ここにある他のすべてのルールより優先されます。 1つのトピックを教えるために30個のトピックフォルダーを開くスキルは、ユーザーが学ぶほど遅くなります。スラッグを1つ解決し、フォルダーを1つだけ開きます。status は30個すべてについて報告し、どのフォルダーも開きません。これは例外ではなく、ガードが機能している状態です。
• status は報告を行いますが、評価は行いません。 必要な合図の数を表示するのは、事実を読み取る行為です。ユーザーがトピックを理解しているかを判断するのは exam であり、何かを伝える前にユーザーから回答を得る必要があります。min step 列から習熟度を推測するダッシュボードは、報告すると称するシグナルそのものを捏造することになります。
• 毎回、説明する前に予測させます。 簡単なトピックでは省略したくなりますが、予測こそが診断です。予測なしで教えるのは、何も分からないまま教えることです。
• 出典のない主張を事実として断言してはいけません。 自信たっぷりの誤った説明は、レッスンがないよりも悪いものです。ユーザーがその説明を土台にしてしまうためです。
• 書き込み可能なファイルシステムがない場合（ブラウザー上で動作するエージェントなど）は、そのことを明確に伝えます。ユーザーが保存できるよう、レッスンをコードブロックで出力し、状態を保存できないため間隔を維持できないことを記します。書き込めない合図を設定したふりをしてはいけません。status と explain はどちらも書き込みを行わないため、引き続き実行できます。