explainer

explainer

人間の理解がボトルネックになっている。 エージェントは書くのが速いが、読み手は追いつけない。 このスキルは、読み手の頭の中にあるものとの差分だけを、検証済みの主張と図で渡す。

ELI5 との違いは 2 つ。

1. 読み手を「5 歳」「マネージャー」のような型でなく、実在の 1 人のペルソナとして持つ。知っていることは書かない。
2. 書いた主張を道具で検査する。「自分で書いていて自信がなくなる」を、検査の緑に置き換える。

読了が 20 分を超える、演習が要る、概念に順序がある。このどれかなら、章立ての explainer-book を使う。

準備（初回だけ）

スクリプトは、このスキルのディレクトリ（以下 <skill>）の scripts/ にあります。 依存は、資料を置くリポジトリに入れます。Node 24 以上が必要です。

npm i -D @mizchi/vlmkit @mizchi/vlmkit-anim marked playwright

Mermaid の図（figures/*.mmd）を使うときは mermaid、アイコンを使うときは @iconify-json/lucide と @iconify-json/logos も入れます。 形式手法の例を扱うときは、TLC（Java 11+）や Apalache（Java 17+）、z3-solver も入れます。 verify-doc.mjs は $TLA2TOOLS（tla2tools.jar）と $APALACHE（apalache-mc）を、リポジトリの .tools/ から探します。

手順

1. ペルソナ   リポジトリのルートの personas/<id>.md を読む。無ければ、質問する前に仮のファイルを書く
2. 問いを絞る  読み手が「読み終えたら判定できるようになること」を 1〜3 個、疑問文で書く
3. 差分を決める ペルソナの「知っている」に載っていることは書かない。「怪しい」を本文の芯にする
4. 実物を作る   主張ごとに、実行できる例（コード・モデル・コマンド）を先に作って走らせる
5. 書く        references/writing.md の型で。出力は貼る、打ち直さない
6. 図          references/figures.md。事実シート（*.expect.json）を先に、図は後
7. 検証        node <skill>/scripts/verify-doc.mjs <doc-dir> が VERIFIED になるまで
8. 読ませる    first-reader スキルで、ペルソナ本人を読み手にして読ませる。途中で離脱した箇所と、翌日残ったものを見る
9. 渡す        HTML（dist/index.html）と要約。検証できなかったことは「未検証」と明記

1. ペルソナ

references/persona.md のテンプレートで作る。材料は 2 つ。

• 質問：本人に聞けるなら、最大 5 問。「いま何を使っているか」「どこで手が止まったか」「読む時間」「好きな説明の形（コード先か図先か）」「この資料を読んだ後に何を判定したいか」。
• 公開情報：GitHub のリポジトリ、ブログ、登壇資料。主張ごとに URL を付け、事実と推測を分けて書く。

ペルソナのファイルは、答えを待つ前に書く。 新しい読み手なら、質問する前に、リポジトリのルートの personas/<id>.md を作る（資料のディレクトリの中ではない。次の資料でも使い直すため）。 質問して止まる返答でも、このファイルは先に書いておく。 依頼文から分かったことは「事実」に、それ以外はすべて「推測」に書き、質問は「未確認」の欄に並べる。

• 本人に聞けるときは、質問して止まる。答えが来たら、ファイルの推測を事実に書き換えて続ける。
• 答えが得られないとき（非対話の実行、本人に聞けない、急ぎ）は、推測のまま書き進める。

資料の冒頭の「想定読者」に、何を仮定したかと、確かめたい質問を書く。

• 依頼文にない経歴（経験年数、使っているツール、困りごと）を事実の欄に書かない。

新しい読み手に質問して止まるときの返答は、次の型にする。 返答を書く前に、Write で personas/<id>.md を作っておく（ツールを呼ばずに質問だけ返さない）。

<読み手> さんのペルソナを、仮のものとして personas/<id>.md に残しました（依頼文から分かったことだけを事実に、残りは推測）。
資料の中身が変わる点を <N> つ確認させてください。

1. <答えで資料の主軸が変わる質問>
2. …

答えがなければ、次の仮定で書き進めます：<仮定を 1〜2 行>

推測のまま資料を書き進めたときも、返答に同じ 2 つ（仮定と、本人に確かめたい質問）を短く書く。 ファイルにだけ書くと、読み手に届かない。

一番大事な欄は「怪しいところ」。 ツールを使えることと、その結果の意味を判定できることは別。 その差を見つけて、資料の芯にする。

2〜3. 問いと差分

資料のタイトルは、読み手の問いの形にする（例：「Z3 と TLA+ の OK は何を保証したのか」）。

冗長さの判定は 1 つ。 ペルソナの「知っている」欄にある説明は削る。 ツールの紹介、インストール手順、一般論は、ペルソナが既に使っているなら書かない。

4. 実物を先に作る

主張は、走らせた結果から書く。逆にしない。

• コードの振る舞い → 最小の実行例と、その出力
• 「この条件で壊れる」 → 反例を出すモデル（Z3 / TLC など）と、反例を実物で再生するテスト
• 構造 → import グラフや状態グラフを道具から出力し、それを事実シートにする

主張を実行で確かめられない場合は、本文に「未検証」と書く。図には入れない。

5. 書く

references/writing.md に従う。要点は次のとおり。

• 冒頭に「想定読者」と「省いたもの」を書く。読み手が自分向けかを 10 秒で判定できるように。
• 最初に「一枚で」の表を置く。本文はその表の各行の展開。
• 1 段落は 1〜2 文。1 節に例は 1 つ。
• 出力の引用は <!-- output: <check名> -->、コードの抜粋は <!-- source: <path> --> を直前に置く。検証スクリプトが実物と照合する。
• 末尾に理解度チェック（3〜5 問、答えは <details>）。読み手が答えられなければ、その節は伝わっていない。

6. 図

references/figures.md。図を描くのは次の場合だけ。

• 4 つ以上の要素とその関係があるとき
• 時間の順序があるとき
• 包含関係があるとき

図は vlmkit-anim のシーン（JSON）で描く。当てはまる kind が無い概念図は、Mermaid で済むなら Mermaid、足りない構造なら D2、D2 に乗らない自由な図なら SVG / HTML で直接書く。どれも scripts/figure-check.mjs で描画・検査して、出てきたシートと辺のシート（矢印を 1 本ずつ強調したもの）を目で見て直す。D2 と Mermaid は配置を道具が決めるので、不自然なら scripts/figure-variants.mjs で候補を並べて選び直す（references/figures.md の「手で描く図」）。 アイコン（データベース・サーバ・製品のロゴなど）は scripts/icons.mjs で探して図の隣に置き、D2・Mermaid・SVG のどれからでも使う（references/figures.md の「アイコン」）。

vlmkit-anim の図の検査は 3 つ。

• check --expect：事実シートと照合する。事実シートは道具の出力（TLC の状態グラフ、import グラフ）から作る。
• layout：重なりやはみ出しがないか。
• still：SVG を出して、一度は目で見る。

7. 検証

<doc-dir>/checks.json に、本文が引用する出力を再生成するコマンドと、期待する行を書く。

node <skill>/scripts/verify-doc.mjs <doc-dir>          # 検査
node <skill>/scripts/verify-doc.mjs <doc-dir> --write  # 図の SVG を描き直す

verify-doc.mjs が見るもの：

1. checks.json の各コマンドの出力に、期待する行が順に出るか
2. 図：vlmkit-anim check --expect / layout / SVG が最新か
3. 本文：output / source の引用が実物と一致するか。画像が存在するか
4. HTML：vlmkit check integrity（<details> を開いた版で厳格に）と check a11y contrast

落ちた行は「何が・どこで・どう直すか」を 1 行で出す。 直して再実行し、verdict: VERIFIED になるまで繰り返す。 上限は 5 ラウンド。それでも通らない主張は本文から外すか、「未検証」と明記する。

8. 読ませる（first-reader）

verify-doc.mjs が保証するのは、主張が正しいことだけです。 読み手が最後まで読み、翌日も覚えているかは、同梱の first-reader スキルで確かめる。

• 読み手の配役：
• sympathetic 役：personas/<id>.md の本人。「既に知っていること」を priors に、「読み方」を patience budget にする。
• skeptical 役：資料が届く場面（PR のレビュー、Slack のリンク）から配役する。
• intended gist：資料の「一枚で」の表と、ペルソナの問い（手順 2）。
• 判定：
• recall の答えが intended gist と食い違ったら、その節は伝わっていない。
• skim gate を通らない、または前半で両者が離脱したら、構成の問題として扱う。行単位の手直しより先に直す。
• 直すのは書き手（このスキル）：
• first-reader は書き直さない。読み手の証言を受けて、どこをどう直すかは explainer が決める。
• 直したら verify-doc.mjs を再実行し、first-reader は again で同じ読み手に読ませ直す。
• 注意：
• 書き手は下書きを全部読んでいる。読み手は必ず fresh な subagent にする（first-reader の手順どおり）。
• signals.py の信頼シグナルの数え方は英語向けで、日本語の資料ではほぼ 0 になる。日本語では trust ledger を自分の通読で判断する。
• .first-reader/ は資料の隣に作られる。git 管理しない。

9. 渡す

• チャットでは、要約（3〜5 行）と dist/index.html を渡す。検証の結果（VERIFIED か、何が未検証か）も添える。
• PR では、差分の説明を同じ型で書き、図の SVG を添付する。理解度チェックは PR 本文の末尾に置く。

PR の説明に使うとき

問いは「この PR がマージされたら、何が変わるか」「何が壊れうるか」にする。 差分はファイル順ではなく、説明の順に並べる（literate diff）。

実物は次の 2 つ。

• vlmkit-anim pr --base origin/main の変更地図
• 変更前後で振る舞いが変わる最小の例（テストの追加・変更から選ぶ）

やってはいけないこと

• 出力を打ち直す。 貼る。検証スクリプトが照合する。
• 図を記憶から描く。 事実シートを先に作る。図が事実シートと食い違ったら、図が間違っている。
• 読み手の既知を説明する。 ペルソナの「知っている」にあるものは削る。
• 緑を過大に報告する。 「検査が通った」と書くときは、何の検査が、どの範囲で通ったかを書く。

ファイル