literate-guide

リテラシーガイド

Knuth が意図した、プログラムを文学として読む方法にならい、コードベースや機能の物語を伝えるガイドを作成します。出力は、コードの抜粋と文章を織り交ぜた単一の物語形式のエッセイです。ファイル構成や実行順ではなく、人間が理解する論理に沿って展開します。

この考え方の背景

Knuth の中心的な指摘はシンプルです。プログラムは書かれる回数よりもはるかに頻繁に読まれるにもかかわらず、私たちは読者ではなくコンパイラーの都合に合わせてプログラムを構成しています。リテラシー・プログラムはこの考え方を逆転させます。作者が、人間が何を最初に理解する必要があるかに基づいて説明の順序を決め、コードはそれが必要になる箇所に、物語の中へ組み込まれます。

既存のコードベースの場合、これは次のことを意味します。

• ファイルツリーをたどらないでください。 概念の筋道をたどってください。main() がある場所ではなく、理解が始まる場所から始めます。
• 各セクションでは1つの考えを紹介し、それを体現するコードを示し、設計の理由を説明します。セクションにはセクション記号を付けて番号を振ります。§1、§2、§3…（これは § という文字、U+00A7 であり、アルファベットの「S」ではありません）。セクション間の相互参照にも同じ表記を使います。
• 説明文が中心的な役割を担います。 コードの抜粋は実装をのぞく窓であり、主な内容ではありません。読者がコードブロックを読み飛ばしても、説明の流れを追える必要があります。
• 設計上の決定を中心的な内容として扱います。 「Y ではなく X を使うのは……だからです」は、リテラシーガイドの要です。検討した代替案、受け入れたトレードオフ、設計を形作った制約こそ、コードが変更された後もこの文書を価値あるものにします。

ワークフロー

ステップ 1：対象範囲を把握する

ガイドで何を取り上げたいか、ユーザーに尋ねます。

question: "What should this literate guide cover?"
header: "Scope"
options:
  - label: "Entire codebase"
    description: "The full story of this project, end to end"
  - label: "A specific feature or subsystem"
    description: "Deep narrative on one part of the codebase"
  - label: "A recent change or PR"
    description: "The story of a specific set of changes and why they were made"

機能またはサブシステムを選んだ場合は、どれを対象にするか確認してください。コードベースが大規模（50 ファイル以上）な場合は、サブシステムに対象を絞ることを強く勧めてください。優れたリテラシーガイドは深く掘り下げるものであり、対象を広げすぎると内容が薄まります。

対象読者についても尋ねます。

question: "Who will read this?"
header: "Audience"
options:
  - label: "A developer joining the team"
    description: "Assumes general programming knowledge, no project-specific context"
  - label: "A senior engineer reviewing the architecture"
    description: "Assumes deep technical knowledge, wants to understand design rationale"
  - label: "Future me"
    description: "Personal documentation for a system I'll forget the details of"
  - label: "Open source contributors"
    description: "External developers who want to understand the project well enough to contribute"

ステップ 2：深く読み込む

コードベースを徹底的に読みます。ざっと目を通すのではなく、物語を探します。次の順序で調べてください。

1. 問題 — このソフトウェアは、どのような課題を解決するために存在するのでしょうか？ README、ドキュメント、コメント、コミットメッセージ、課題トラッカーを確認します。
2. ドメインモデル — 中核となる抽象概念は何でしょうか？ 現実世界の何を表しているのでしょうか？
3. アーキテクチャ — 各要素はどのように連携しているのでしょうか？ 境界はどこでしょうか？
4. 処理の流れ — 主要な操作を2〜3つ選び、最初から最後まで追跡します。これらが物語の軸になります。
5. 設計上の決定 — 興味深いトレードオフはどこにあるでしょうか？ 次の点に注目してください。
   • 「何を」ではなく「なぜ」を説明するコメント
   • より単純な方法が採用されなかった箇所 — たいてい理由があります
   • 過剰に作り込まれているように見える抽象化 — 多くの場合、苦労して得た教訓が反映されています
   • 設定と機能フラグ — 作者が想定していた変化の軸が明らかになります
6. 歴史 — git log で大規模なリファクタリング、方向転換、書き直しを確認します。これらは物語の展開点になります。

ステップ 3：物語の筋道を見つける

書き始める前に、次の点を明確にします。

• 導入 — 読者に最初に触れてもらうべきアイデアや問題は何でしょうか。これは、コードのエントリーポイントであることはほとんどありません。それは動機、つまり残りのコードが必要となる問題です。
• 展開 — 理解が自然に進んでいく順序はどうなっていますか。通常は、問題 → ドメイン → 中核となる抽象化 → 仕組み → エッジケースへの対処 → システムの他の部分との接続、という流れです。
• 重要な決定 — システムの特性を形作る設計上の選択を 3〜5 個挙げます。これらは、コードの解説を一度止めて「これを選んだ理由」を説明する場面です。
• セクション — § 記号を使って、物語を番号付きのセクションに分けます。§1、§2 などです（「S1」や「Section 1」ではありません。セクション記号 § は、Knuth の TeX の伝統に由来する意図的なスタイル上の選択です）。各セクションには、ファイルではなくアイデアを表す名前を付けます。「§4. コールバックではなくイベントを使う理由」は、「§4. EventEmitter クラス」より適切です。

ステップ 4：ガイドを書く

references/guide-template.md のテンプレートに従います。主な原則は次のとおりです。

語り口とトーン：

• 温かく率直な一人称複数形の語り口（「私たち」「私たちの」）で書きます。ガイドは仕様書ではなく、著者と読者の対話です。
• 具体的に、明確に書きます。「エッジケースに対応します」では不十分です。「最初のリクエストが完了する前にユーザーがフォームを 2 回送信するケースを検出します」なら役に立ちます。
• 著者の視点を大切にします。Knuth は客観的なふりをせず、自分が何を考え、なぜそう考えたのかを説明しました。同じように書きます。「Y ではなく X を選んだのは……」や「チームが……と決めたのは、実際に……という理由からです」のように、実際の理由を示します。

コードの抜粋：

• 説明する内容に関係するコードだけを示します。思い切って削りましょう。関数が 40 行あっても重要な部分が 8 行なら、残りの処理について注記したうえで、その 8 行だけを示します。
• コードブロックの前には必ずファイルパスと行範囲を記載し、読者が該当箇所を見つけられるようにします。
• コードに注釈を付けます。コードを示して先に進むだけではなく、重要な点を指摘します。「retries は設定から読み込むのではなく、パラメーターとして渡されている点に注目してください。これにより、テストの動作が決定的になります（§12）。」
• あるセクションのコードが別のセクションで説明した概念と関係する場合は、相互参照（§N）を使います。

セクションの構成：

• アイデアとその動機を説明する文章から始めます。
• 関連するコードを示します。
• 設計上の理由を説明します。検討した代替案、制約、トレードオフを取り上げます。
• 次のセクションにつながる流れで締めくくります。各セクションの末尾は、次に続く内容への橋渡しとなるようにします。そうすることで、ガイドは孤立した項目の羅列ではなく、ひと続きの物語として読めます。たとえば、「この正規化により、reducer（§7）にクリーンな入力が渡されると信頼できるようになりました。」や、「ここで疑問が生じます。このシステムは……の場合にどう対応するのでしょうか。その答えを§9で説明します。」のようにします。

相互参照：

• すべての相互参照に § 記号を使います。「§3で見たように」「これは§12のリトライロジックにつながります」「トランスポート層（§8）がこの複雑さを隠します」のようにします。§ 記号は重要です。文書内の別のセクションへの参照だと読者に伝える視覚的な合図になります。
• 相互参照があることで、文書は直線的な並びではなく網目になります。積極的に使いましょう。優れた解説ガイドでは、各セクションに少なくとも 2〜3 個の相互参照を含め、前のセクションに戻って概念を補強したり、後のセクションを先取りして示したりします。

図：

• 理解の助けになる場合は Mermaid 図を含めます。通常は冒頭近くにシステム全体の概要図を 1 つ、複雑なフローにはシーケンス図を使います。
• 図は文章を補足するものであり、文章に取って代わるものではありません。

ステップ 5：草稿を見直す

提出する前に、コードベースを初めて見る人になったつもりでガイドを読みます。

1. ストーリーになっていますか？ §1 から最後まで、迷うことなく話の流れを追えますか？ つながりが不自然に感じられるセクションがあれば、よりよい導入を加えるか、順序を入れ替える必要があります。
2. すべてのコード抜粋に意義がありますか？ 理解を損なわずに削除できるコードブロックがあれば、削除します。それぞれの抜粋は、周囲の文章で述べている具体的なポイントを説明するものであるべきです。
3. 設計上の判断が明示されていますか？ ガイドでは、「どのように」と同じくらい「なぜ」にも答える必要があります。動機を説明せずに仕組みだけを説明していることに気づいたら、立ち止まって理由を加えます。
4. 相互参照は正しいですか？ すべての §N 参照が正しいセクションを指している必要があります。文芸的プログラミングのガイドで相互参照が壊れているのは、ハイパーリンクが壊れているのと同じで、理解のつながりを損ないます。
5. Knuth に認めてもらえそうですか？ これは冗談半分ですが、役に立つ観点です。Knuth の文芸的プログラムは、技術を丁寧に説明する著者が書いたエッセイのように読めます。ガイドが自動生成されたドキュメントのように読めるなら、何かを大切に思う人が、同じものを大切に思う別の人に語りかけているように感じられるまで、書き直します。

ステップ 6：提出する

ガイドを単一の Markdown ファイルとして作成します。保存先の例：

• .claude/docs/literate-guide.md（コードベース全体向け）
• .claude/docs/literate-guide-{feature}.md（特定の機能向け）

作成した内容と保存先をユーザーに伝えます。セクション数と主なテーマにも触れ、どのような内容かがわかるようにします。