codebase-study-guide

代码库学习指南

使用基于证据的学习技巧，生成一份能够帮助读者深入理解代码库的学习指南。指南不仅帮助读者了解代码的功能，还帮助他们理解代码为何存在，以及各个部分之间的关系。

指导原则

这些原则贯穿指南的每个部分。完整的研究依据请参阅 references/pedagogy.md。

• 先讲目的，再讲结构。 从要解决的问题入手，而不是从文件树入手。理解“为什么”的读者，能更好地构建关于“如何做”的认知框架（Ausubel 的有意义学习理论）。
• 优先讲解门槛概念。 找出 2-3 个一旦掌握就能让其他内容豁然开朗的概念，并将其放在前面（Meyer & Land）。
• 循序渐进地揭示信息。 逐步增加复杂度：概览 -> 系统 -> 接口 -> 内部机制。每次最多引入一个陌生的子系统（认知负荷理论）。
• 主动学习优于被动学习。 加入预测提示、深入探究问题和探索任务，而不只是描述。主动学习技巧的效果优于被动阅读，效应量 d = 0.5-0.7（Dunlosky 等人）。
• 双重编码。 每段文字说明都配上视觉内容（图示、地图、流程图）。双通道编码能使记忆效果大致翻倍（Paivio）。
• 为模式命名。 明确指出架构模式并链接到相关资源。模式识别是专家理解代码的关键机制（Brooks、Soloway）。

工作流

第 1 步：确定指南范围

使用 AskUserQuestion 了解受众和关注重点：

question: "Who is the primary audience for this study guide?"
header: "Audience"
options:
  - label: "New team member"
    description: "Developer joining this team, needs full onboarding"
  - label: "Experienced dev, new codebase"
    description: "Senior engineer who knows the stack but not this project"
  - label: "Cross-team collaborator"
    description: "Someone who needs to interface with this system, not own it"
  - label: "Future me"
    description: "Personal reference for a codebase I'm exploring now"

然后进一步确认深度：

question: "What depth should the guide cover?"
header: "Depth"
options:
  - label: "Full guide (Recommended)"
    description: "Purpose, architecture, systems, patterns, interfaces, and exploration tasks"
  - label: "Architecture overview"
    description: "Purpose and high-level systems only, no deep dives"
  - label: "Specific subsystem"
    description: "Deep dive into one area of the codebase"

第 2 步：探索代码库

使用 Explore Agent 或直接使用工具进行系统化探索。按以下顺序进行调查：

1. 入口点 — 执行从哪里开始？（main、路由处理程序、CLI 入口、事件监听器）
2. 配置 — 哪些因素会影响行为？（环境变量、配置文件、功能标志）
3. 领域模型 — 核心实体有哪些？它们之间有什么关系？
4. 主要流程 — 端到端追踪 2-3 个典型操作
5. 系统边界 — 代码会在哪些地方与外部系统交互？
6. 测试结构 — 测试揭示了哪些预期行为和边界情况？
7. 现有文档 — README、CLAUDE.md、架构文档、ADR、内联注释

还要留意：

• 命名约定和代码组织模式
• 错误处理理念
• 关键依赖项及其作用

第 3 步：识别门槛概念

根据探索结果，找出 2-3 个代码库特有的门槛概念，也就是具备以下特点的概念：

• 具有变革性：理解这些概念会改变你对整个系统的看法
• 具有整合性：它们能将此前看似无关的部分联系起来
• 不明显：新手无法通过粗略阅读发现它们

示例：“一切皆事件”、“所有权决定生命周期”、“配置是唯一可信来源”、“读取和写入使用不同模型”。

第 4 步：构建概念图

开始撰写前，先在脑中构建系统的概念图：

• 节点：5-8 个主要系统或模块
• 边：它们如何通信（函数调用、事件、共享状态、HTTP、队列）
• 方向：数据或控制流的方向

这将成为指南中的“系统地图”部分，并为其他内容的编排提供依据。

第 5 步：编写指南

遵循 references/guide-template.md 中的模板结构。编写时请牢记以下原则：

对于每个系统／模块章节：

• 先说明目的（“为什么存在？”），再介绍机制（“如何运作？”）
• 加入一个深入追问提示词——一个能促使读者思考设计权衡的“为什么”问题
• 指出所使用的架构模式，并链接到权威资料
• 展示一个有代表性的代码片段作为完整示例，并附上设计理由，而不只是语法说明
• 以一项读者可独立完成的探索任务收尾

对于 Mermaid 图表：

• 系统架构和数据流使用 graph TD
• 请求流程和交互使用 sequenceDiagram
• 带有关系的领域模型使用 classDiagram
• 图表应简明聚焦——每张图只呈现一个概念，不要一次性展示所有内容

对于探索任务：

• 遵循 PRIMM 流程：预测（Predict）→ 运行（Run）→ 调查（Investigate）→ 修改（Modify）
• 从预测开始（“在查看代码之前，你认为当……时会发生什么？”）
• 指明需要检查的具体文件路径和函数名称
• 从引导式探索逐步过渡到独立调查

第 6 步：审核并交付

交付指南前：

1. 检查“森林而非树木”——读者读完指南后，是否理解这个东西为何存在以及它为用户解决了什么问题？如果目的章节没有清楚有力地回答这些问题，请进行修改。
2. 检查渐进式展开——读者读完第 2 节后，是否已经掌握有用的知识？读完第 3 节后呢？每一节都应独立发挥价值。
3. 检查主动学习元素——每个主要章节是否至少包含一个问题或任务？删除那些只有被动描述、没有主动学习提示的章节。
4. 检查模式链接——是否为每个提及的模式都添加了指向学习资料的链接？

将指南写成一个独立的 Markdown 文件，并放在合适的位置（.claude/docs/study-guide.md，或按用户指定的位置）。指南应自包含——读者只需访问代码库和指南，不需要其他资料。