literate-guide

Literate 指南

创建一份指南，以文学作品的方式讲述代码库或功能的故事，体现 Knuth 对程序阅读方式的设想。输出应是一篇连贯的叙事文章，将代码片段与散文交织起来，并按照人类理解事物的逻辑排序，而不是按照文件布局或执行顺序排列。

背后的理念

Knuth 的核心观察很简单：程序被阅读的次数远多于被编写的次数，但我们组织程序时考虑的是编译器的便利，而不是读者的需求。文学化编程颠倒了这一做法——作者根据人们首先需要理解的内容来决定呈现顺序，并将代码放在叙事中恰好需要它的地方。

对于现有代码库，这意味着：

• 不要按照文件树来写。 沿着概念脉络展开。从理解的起点开始，而不是从 main() 所在处开始。
• 每个章节引入一个想法，展示体现它的代码，并解释设计背后的理由。章节使用章节符号编号：§1、§2、§3……（这是 § 字符，U+00A7，不是字母“S”。）章节之间使用相同的符号进行交叉引用。
• 叙述承担主要工作。 代码片段是窥见实现的窗口，而不是主要内容。即使读者跳过代码块，也应能跟上叙述。
• 设计决策是内容的核心。 “我们选择 X 而不是 Y，因为……”是文学化指南的核心。考虑过的替代方案、接受的权衡、塑造设计的约束——正是这些内容让文档在代码变更很久之后仍有价值。

工作流

第 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 中的模板。主要原则：

叙述方式与语气：

• 使用亲切、直接的第一人称复数语气（“我们”“我们的”）。这份指南是作者与读者之间的对话，而不是规范文档。
• 具体明确。“处理边缘情况”这种说法没有意义。“捕获用户在第一个请求完成前重复提交表单的情况”才有用。
• 体现作者的视角。Knuth 并未假装客观——他解释了自己在想什么，以及为什么。我们也应如此。“我选择 X 而不是 Y，因为……”或“团队决定……”，并给出实际原因。

代码摘录：

• 只展示与当前论点相关的代码。大幅精简。如果一个函数有 40 行，但有意思的部分只有 8 行，就只展示这 8 行，并说明其余代码的作用。
• 始终在代码块上方标注文件路径和行号范围，方便读者查找。
• 为代码添加说明。不要只展示代码就继续往下讲——指出重要细节。“注意，retries 是作为参数传入的，而不是从配置中读取。这样测试结果就是确定的（§12）。”
• 当某一章节中的代码与另一章节讲解的概念相关时，使用交叉引用（§N）。

章节结构：

• 开篇用正文解释想法及其动机
• 展示相关代码
• 解释设计背后的考量——曾考虑的替代方案、约束和权衡
• 以连接到下一章节的过渡语收尾。每个章节的结尾都应承接下文，这样指南读起来才像连贯的叙事，而不是一系列互不相关的条目。例如：“有了这种规范化处理，我们现在可以确信 reducer（§7）收到的是干净的输入。”或者：“这就引出了一个问题：系统如何处理……的情况？这正是 §9 要讨论的内容。”

交叉引用：

• 所有交叉引用都使用 § 符号：“正如我们在 §3 中看到的”“这与 §12 中的重试逻辑相关”“传输层（§8）隐藏了这种复杂性”。§ 符号至关重要——它是一个视觉提示，告诉读者“这里指的是本文档的另一个章节”。
• 交叉引用让文档成为一张网，而不是线性序列。请多加使用——优秀的文学化指南每个章节至少有 2–3 个交叉引用，在强化前文观点的同时预示后续内容。

图表：

• 在有助于理解的地方加入 Mermaid 图表——通常在开头附近放一张系统级概览图，在复杂流程中加入时序图
• 图表用于补充正文，不能取代正文

步骤 5：审阅草稿

交付前，请假设自己从未接触过这个代码库，通读指南：

1. 内容是否连贯？ 你能否从 §1 一路读到结尾，而不感到迷失？如果某个部分显得突兀，就需要添加更好的过渡，或者调整顺序。
2. 每段代码摘录是否都有价值？ 如果删除某个代码块也不会影响理解，就删掉它。每段摘录都应阐明周围文字提出的某个具体观点。
3. 设计决策是否明确？ 指南回答“为什么”的次数至少应与回答“怎么做”的次数一样多。如果你发现自己只是在描述机制，却没有说明动机，请停下来补充理由。
4. 交叉引用是否正确？ 每个 §N 引用都应指向正确的章节。在文学编程指南中，错误的交叉引用就像失效的超链接，会破坏知识之间的关联。
5. Knuth 会认可吗？ 这虽是半开玩笑，但很有参考价值：Knuth 的文学编程作品读起来像是深思熟虑的作者在讲解自己的手艺。如果指南读起来像自动生成的文档，就继续修改，直到它听起来像一个人在与另一个人分享自己在意的事情。

步骤 6：交付

将指南写成单个 Markdown 文件。建议位置：

• .claude/docs/literate-guide.md，用于完整代码库
• .claude/docs/literate-guide-{feature}.md，用于特定功能的指南

告诉用户你写了什么以及文件所在位置。提及章节数量和涵盖的主要主题，让用户了解指南内容。