Back to Details

codebase-study-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Study Guide

代码库学习指南

Generate a study guide that builds durable understanding of a codebase using evidence-based learning techniques. The guide helps readers grasp not just what the code does, but why it exists and how its parts relate.
生成一份采用循证学习技巧的代码库学习指南，帮助读者不仅理解代码的功能，更能理解其存在的意义以及各部分之间的关联。

Guiding Pedagogy

教学指导原则

These principles shape every section of the guide. See references/pedagogy.md for the full research basis.
  • Purpose before structure. Start with the problem being solved, not the file tree. Readers who understand the "why" form stronger schemas for the "how" (Ausubel's meaningful learning).
  • Threshold concepts first. Identify the 2-3 ideas that, once grasped, make everything else click. Front-load these (Meyer & Land).
  • Progressive disclosure. Layer complexity: overview -> systems -> interfaces -> internals. Never introduce more than one unfamiliar subsystem at a time (Cognitive Load Theory).
  • Active over passive. Include prediction prompts, elaborative interrogation questions, and exploration tasks — not just descriptions. Active techniques outperform passive reading by d = 0.5-0.7 (Dunlosky et al.).
  • Dual coding. Pair every textual explanation with a visual (diagram, map, flow). Dual-channel encoding roughly doubles recall (Paivio).
  • Name the patterns. Explicitly identify architectural patterns and link to resources. Pattern recognition is the mechanism of expert code comprehension (Brooks, Soloway).
这些原则贯穿指南的每一个章节。完整研究依据请查看 references/pedagogy.md。
  • 先讲用途，再讲结构：从要解决的问题入手，而非文件目录。理解“为什么”的读者能更好地构建“怎么做”的知识框架（奥苏贝尔意义学习理论）。
  • 先掌握核心概念：找出2-3个关键概念，一旦理解这些概念，其他内容就会豁然开朗。优先讲解这些概念（迈尔与兰德核心概念理论）。
  • 渐进式揭秘：分层呈现复杂度：概览 -> 系统 -> 接口 -> 内部实现。每次只介绍一个陌生子系统（认知负荷理论）。
  • 主动学习优于被动阅读：包含预测提示、详述提问和探索任务，而非仅进行描述。主动学习技巧的效果比被动阅读高出d = 0.5-0.7（邓洛斯基等人研究）。
  • 双重编码：每一段文字说明都搭配可视化内容（图表、映射图、流程图）。双通道编码能大致将回忆效率提升一倍（佩维奥双重编码理论）。
  • 明确设计模式：清晰识别架构模式并链接至相关资源。模式识别是专家理解代码的核心机制（布鲁克斯、索洛韦研究）。

Workflow

工作流程

Step 1: Scope the Guide

步骤1：确定指南范围

Use AskUserQuestion to understand the audience and focus:
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"
Then clarify depth:
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"
使用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"

Step 2: Explore the Codebase

步骤2：探索代码库

Conduct systematic exploration using the Explore agent or direct tools. Investigate in this order:
  1. Entry points — Where does execution begin? (
    main
    , route handlers, CLI entry, event listeners)
  2. Configuration — What shapes behavior? (env vars, config files, feature flags)
  3. Domain model — What are the core entities and their relationships?
  4. Primary flows — Trace 2-3 representative operations end-to-end
  5. System boundaries — Where does this code interact with external systems?
  6. Test structure — What do tests reveal about intended behavior and edge cases?
  7. Existing docs — README, CLAUDE.md, architecture docs, ADRs, inline comments
Also look for:
  • Naming conventions and code organization patterns
  • Error handling philosophy
  • Key dependencies and what role they play
使用Explore代理或直接工具进行系统性探索，按以下顺序展开：
  1. 入口点 — 执行从哪里开始？（
    main
    函数、路由处理器、CLI入口、事件监听器）
  2. 配置 — 哪些因素影响行为？（环境变量、配置文件、功能开关）
  3. 领域模型 — 核心实体及其关系是什么？
  4. 主要流程 — 追踪2-3个代表性操作的端到端流程
  5. 系统边界 — 代码在何处与外部系统交互？
  6. 测试结构 — 测试能揭示哪些预期行为和边缘情况？
  7. 现有文档 — README、CLAUDE.md、架构文档、ADR、内联注释
同时还要关注：
  • 命名规范和代码组织模式
  • 错误处理理念
  • 关键依赖及其作用

Step 3: Identify Threshold Concepts

步骤3：识别核心概念

From the exploration, identify 2-3 codebase-specific threshold concepts — ideas that are:
  • Transformative: Understanding them changes how you see the whole system
  • Integrative: They connect previously unrelated parts
  • Non-obvious: A newcomer wouldn't discover them from casual reading
Examples: "Everything is an event," "ownership determines lifecycle," "the config is the source of truth," "reads and writes are separate models."
从探索结果中，识别2-3个代码库特有的核心概念，这些概念需满足：
  • 变革性：理解它们会改变你对整个系统的看法
  • 整合性：它们能连接之前看似无关的部分
  • 非显性：新手无法通过随意阅读发现它们
示例：“一切皆事件”“所有权决定生命周期”“配置是唯一可信源”“读写采用分离模型”。

Step 4: Build the Concept Map

步骤4：构建概念映射图

Before writing, create a mental model of the system as a concept map:
  • Nodes: The 5-8 primary systems/modules
  • Edges: How they communicate (function calls, events, shared state, HTTP, queues)
  • Direction: Which way data/control flows
This becomes the "System Map" section of the guide and informs the sequencing of everything else.
开始写作前，先创建系统的概念映射心智模型：
  • 节点：5-8个主要系统/模块
  • 边：它们的通信方式（函数调用、事件、共享状态、HTTP、队列）
  • 方向：数据/控制流的方向
这将成为指南中的“系统映射图”部分，并为后续内容的编排提供依据。

Step 5: Write the Guide

步骤5：撰写指南

Follow the template structure in references/guide-template.md. Key principles while writing:
For each system/module section:
  • Open with purpose ("why does this exist?") before mechanics ("how does it work?")
  • Include an elaborative interrogation prompt — a "why" question that forces the reader to think about design tradeoffs
  • Name any architectural pattern being used and link to a canonical resource
  • Show a representative code snippet as a worked example — annotated with reasoning, not just syntax
  • End with an exploration task the reader can do independently
For the Mermaid diagrams:
  • Use 
    graph TD
    for system architecture and data flow
  • Use 
    sequenceDiagram
    for request flows and interactions
  • Use 
    classDiagram
    for domain models with relationships
  • Keep diagrams focused — one concept per diagram, not everything at once
For the exploration tasks:
  • Follow the PRIMM progression: Predict -> Run -> Investigate -> Modify
  • Start with prediction ("before looking at the code, what do you think happens when...?")
  • Include specific file paths and function names to examine
  • Graduate from guided exploration to independent investigation
遵循 references/guide-template.md 中的模板结构。写作时需遵循以下核心原则：
每个系统/模块章节：
  • 先介绍用途（“为什么存在？”），再讲解机制（“如何工作？”）
  • 包含一个详述提问提示——一个“为什么”问题，促使读者思考设计权衡
  • 明确所使用的架构模式并链接至权威资源
  • 展示代表性代码片段作为实例演示——标注设计思路，而非仅语法
  • 结尾提供读者可独立完成的探索任务
Mermaid图表要求：
  • 使用
    graph TD
    展示系统架构和数据流
  • 使用
    sequenceDiagram
    展示请求流程和交互
  • 使用
    classDiagram
    展示带关系的领域模型
  • 保持图表聚焦——每个图表只展示一个概念，而非所有内容
探索任务要求：
  • 遵循PRIMM流程：预测 -> 运行 -> 调查 -> 修改
  • 从预测开始（“查看代码前，你认为当……时会发生什么？”）
  • 包含具体的文件路径和要检查的函数名
  • 从引导式探索逐步过渡到独立调查

Step 6: Review and Deliver

步骤6：审核与交付

Before delivering the guide:
  1. Check the "forest for the trees" — Does a reader who finishes the guide understand why this thing exists and what problem it solves for its users? If the purpose section doesn't answer this compellingly, revise it.
  2. Check progressive disclosure — Could a reader stop after Section 2 and still have useful understanding? After Section 3? Each section should be independently valuable.
  3. Check active elements — Does every major section include at least one question or task? Remove any section that's purely passive description without an active learning prompt.
  4. Check pattern links — Is every named pattern linked to a learning resource?
Write the guide as a single Markdown file placed at a sensible location (
.claude/docs/study-guide.md
or as specified by the user). The guide should be self-contained — a reader with access to the codebase and the guide should need nothing else.
交付指南前：
  1. 检查全局视角 — 完成指南的读者是否能理解这个项目存在的意义以及它为用户解决了什么问题？如果用途部分未能有力回答这些问题，请进行修订。
  2. 检查渐进式揭秘 — 读者在完成第2节后是否仍能获得有用的理解？完成第3节后呢？每个章节都应具备独立价值。
  3. 检查主动学习元素 — 每个主要章节是否至少包含一个问题或任务？移除所有纯被动描述、无主动学习提示的章节。
  4. 检查模式链接 — 每个明确命名的模式是否都链接至学习资源？
将指南编写为单个Markdown文件，放置在合理位置（如
.claude/docs/study-guide.md
或用户指定的位置）。指南应具备自包含性——拥有代码库访问权限和该指南的读者无需其他资源即可完成学习。