explain-it は何をしますか？
調査したコードを、このコードベースに関する事前知識がまったくない賢い読者でも理解できる小さな静的なHTMLサイトに変換します。ルートページでメンタルモデルを構築し、トピックごとに1ページ、そしてそれらを接続するサイドバーを提供します。
目標とする基準：「単純すぎず難しすぎない平易な言葉」。見下すことなく、リポジトリの知識を決して前提としません。
ワークフロー
1. 説明する前に調査する
読んでいないコードを説明してはいけません。すべてのトピックについて、実際のソース（変更行、それを囲む関数、そして少なくとも1つの呼び出し元）を読み、「このコードはいつ実行されるのか？」という問いに真実のストーリーで答えられるようにします。もし主張が他の誰か（レビューコメントやIssue）からのものであれば、まずコードと照らし合わせて検証し、それが成り立たない場合はその旨を明記します。
2. サイトを計画する
- 1つのルートページ（
index.html）：プライマー。約2分でシステムのメンタルモデルを構築し、すべてのトピックページへのリンクを提供します。 - トピックごとに1ページ（
01-<slug>.html,02-<slug>.html, …）：各ページは1つの変更、バグ、決定、またはサブシステムを説明します。3～7ページが最適で、トピックを統合して9ページを超えないようにします。 - すべてのページに共有サイドバー：すべてのページを読み順にリストし、現在のページを強調表示します。ページは相対的な
<a href>でリンクされたプレーンファイルです。サイトはディスクから直接（file://）開いても動作する必要があるため、ルーター、ビルドステップ、外部JSは使用しません。
フォルダの場所が明らかでない場合にのみユーザーに確認します。それ以外の場合は、作業の隣に適切な名前のフォルダ（例：docs/explainers/<topic>/）を作成し、その場所を伝えます。
3. 各ページを書く
方法論についてはreferences/writing-guide.mdに従ってください。最初のページを書く前に必ず読んでください。絶対条件は以下の通りです：
- 最初にプライマー。 ルートページでは、トピックページが必要とするすべてのドメイン概念を、それぞれ具体的な比喩（例：「リリースはコピーです。実行中のジョブは1つのコピーをピン留めします」）を用いて紹介します。比喩は一度導入したら、その後はすべての場所で同じものをそのまま再利用します。1つの概念に対して複数の比喩を積み重ねてはいけません。
- すべてのトピックをランタイムに基づかせる。 各トピックページは「このコードはいつ実行されるのか？」というストーリーで始まります：2～4アクターの流れ（ユーザーがXを行う → システムが関数Yを実行する → その中の小さなジョブ）。平易な言葉のストーリーと並べて、実際の関数名をコードフォントで表示します（代わりに表示するのではなく）。
- 変更点をdiffとして表示する。 古いコードと新しいコードを赤/緑のdiffブロックで表示し、ヘッダーにファイルパスを記述します。本質的な部分に絞り、1～3つのインラインコメントでなぜを指摘します — 何を説明するのではありません。
- 「なぜ」を定量化する。 「遅い」は禁止です。「リクエストあたり数百KB、時間の～99％を無駄に消費」が基準です。リスクについても同様に、具体的な入力/状態と間違った結果を明記します。
- バグと判断を分ける。 何かが欠陥ではなく、防御可能なプロダクト選択である場合は、間違いとしてではなく、トレードオフを伴う判断として提示します。
- ルートページをスコアボードで締めくくる： 各アイテム（完了 / 提案中 / 保留）とそのコードベース内の場所を表形式で示します。
4. HTMLをビルドする
すべてのページの開始点としてreferences/site-template.htmlをコピーします。このテンプレートには、デザイントークン、サイドバー、およびすべてのコンポーネント（ストーリーブロック、コールアウト、diffブロック、ステータステーブル、ピル）の動作例が1つずつ含まれています。その後：
- 各ページを完全に自己完結型に保ちます（すべてのCSSはページ内にインラインで記述）。サイドバーは各ページに複製し、現在のアイテムに
class="on"をマークします。 - トークンとコンポーネントルールについては
references/design-system.mdに従ってください。パレット、スペーシング、タイプスケールは指定されたままにし、マルチページサイトが1つのシステムのように見えるようにします。テンプレートにはライト/ダーク切り替えと折りたたみ可能なサイドバーが含まれています。これらを削除せずにすべてのページに保持します。 - すでにテンプレートにあるGoogle Fontsリンク（フォントスタックはオフラインでも適切にフォールバックします）とテンプレートのテーマ切り替えスニペット以外のJSを除き、外部依存関係は使用しません。
5. 引き渡す前に検証する
ルートページと少なくとも1つのトピックページを開くかレンダリングし（または再読し）、以下を確認します：すべてのサイドバーリンクが解決できること、散文で言及されているすべてのコード識別子がコードベースにその正確なスペルで存在すること、すべてのdiffが実際のファイルと概念的にコンパイルできること、スコアボードのステータスが最新であること。その後、ユーザーにフォルダパスを伝え、環境が許せばルートページを開きます。
よくある落とし穴
- コードではなく会話の記憶から説明する — 説明はすべての古い主張を引き継ぎます。ソースを再読してください。
- 比喩のずれ：あるページで「コピー」と呼び、次のページで「凍結コピー」と呼ぶ。用語は1つ、すべての場所で統一します。
- 60行そのまま貼り付けるdiffブロック。本質に絞り、周囲に2～4行のコンテキスト行を残します。
- diffを行ごとに説明する散文。diffは何を示し、散文はなぜそれが重要かといつ実行されるかのみを説明します。
- インデックスページにしかないサイドバー。すべてのページが完全なサイドバーを持ちます。
- 幼児語（「コンピュータは特別な箱の中に物事を覚えています」）。読者は賢いのです — ただ、このコードベースを知らないだけです。