| name | project-learning |
| description | 以交互式课堂方式带用户学习一个代码项目,按章节讲解架构、模块、函数调用和数据流,并把关键图、代码地图、理解检查和课堂笔记沉淀到项目文档中 |
| when_to_use | 当用户希望从小白视角学习一个项目、通读代码、理解重要函数/数据流,或要求“交互式学习”“课堂笔记”“写进 lesson/usebook”时 |
| argument-hint | [project_root] [lesson_dir] |
| arguments | ["project_root","lesson_dir"] |
| user-invocable | true |
| allowed-tools | Read Glob Grep Write Edit Bash |
| effort | high |
交互式项目学习
用课堂式节奏带用户学习一个代码项目:先建立心智模型,再逐层读入口、配置、核心模块、数据流、测试和扩展点。每节课只讲一个可消化主题,并把高价值内容沉淀为 lesson 文档。
目标
帮助用户真正掌握项目,而不是只得到一次性摘要。
交付物包括:
- 学习路线图:按章节说明先学什么、后学什么。
- 课堂讲解:图、代码地图、调用链、数据流、关键函数解释。
- 互动检查:每节提出少量问题,确认用户是否理解。
- lesson 文档:把图、关键结论、用户困惑和已确认理解写入文档。
适用场景
- 用户说“从小白角度理解项目”。
- 用户说“带着我读代码”。
- 用户说“交互式学习”。
- 用户说“把你讲的图/文字/总结写进 lesson/usebook”。
- 用户希望理解模块、函数调用、数据流、CLI 入口、配置、测试执行链路。
基本原则
- 先建地图,再读代码:不要一上来逐行解释。先说明系统边界、入口、主链路和目录职责。
- 每节只讲一个主题:一次只学一个模块或一条调用链,避免信息过载。
- 以真实文件为准:讲解必须指向实际代码、配置和文档,不凭记忆编造。
- 从调用链解释函数:解释函数时说清楚它被谁调用、输入是什么、输出给谁、失败如何处理。
- 把抽象概念落到数据流:优先画
输入 -> 处理 -> 输出。
- 互动优先:每节结束前问 1-3 个检查问题;用户回答后纠偏,再进入下一节。
- 课堂笔记只记高价值内容:不做聊天全文转录,只记录图、代码地图、关键结论、易错点和用户已确认的理解。
- 不顺手改业务代码:学习过程默认只读代码和写 lesson;除非用户明确要求,不修改项目实现。
文档位置
默认 lesson 目录按以下顺序选择:
- 用户显式指定的
$lesson_dir。
- 如果存在
docs/usebook/lessons/,使用它。
- 如果存在
docs/lessons/,使用它。
- 否则创建
docs/lessons/。
lesson 文件命名:
lesson-1.md
lesson-2.md
lesson-3.md
...
如果已有 lesson,继续追加或创建下一节;不要覆盖用户已有笔记。
执行流程
第一步:建立学习路线
读取最小必要上下文:
README*
AGENTS.md / CLAUDE.md / 项目协作说明
pyproject.toml / package.json / 主配置文件
- 顶层目录结构
- 主要入口文件
输出 5-10 节学习路线。每节应包含:
- 主题
- 要读的文件
- 要理解的问题
- 预期产出的 lesson 内容
不要在第一步就深入解释所有代码。
第二步:每节课的固定结构
每节课按这个顺序讲:
- 学习目标:本节要解决什么问题。
- 一张图:用 Mermaid 或 ASCII 画出调用链/数据流/模块关系。
- 最小代码地图:列出 3-8 个关键文件/函数及职责。
- 关键路径讲解:顺着真实调用链解释,不跳到无关模块。
- 重要代码点:解释关键函数、参数、返回值、错误处理和副作用。
- 理解检查:问用户 1-3 个问题。
- 课堂笔记沉淀:用户确认后,把图、表和关键结论写入 lesson。
第三步:课堂笔记格式
lesson 文档建议结构:
# Lesson N:主题
> 学习目标:一句话说明本节目标。
## 调用图 / 数据流图
```mermaid
flowchart TD
A["输入"] --> B["核心处理"]
B --> C["输出"]
最小代码地图
| 文件/函数 | 职责 | 本节理解重点 |
|---|
path/to/file.py | ... | ... |
关键理解
易错点
当前理解检查
如果用户指定“把第 2、4、5 点写进 lesson”,只写用户指定内容,避免扩写。
### 第四步:讲解深度控制
默认深度:
- 先解释模块职责和主调用链。
- 再解释关键函数。
- 最后解释关键行。
只有当用户明确要求“逐行解释”时,才做逐行解释。
解释代码时优先回答:
```text
这个函数为什么存在?
谁调用它?
它读什么输入?
它产生什么输出?
它改变了什么状态?
它失败时怎么表现?
它和上一层/下一层怎么连接?
第五步:互动规则
每节结束时优先问检查问题,例如:
- “这一步的输入和输出分别是什么?”
- “为什么这里要先保存 previous/current state?”
- “如果这个配置缺失,后面哪一步会失败?”
- “这段代码属于业务逻辑、框架逻辑,还是适配层?”
用户回答后:
- 回答正确:简短确认,并进入下一节或写 lesson。
- 回答不完整:指出缺口,补一小段解释。
- 用户说“不回答了/懂了”:不要强迫,直接进入下一节。
图的要求
优先使用 Mermaid:
flowchart TD
A["用户命令"] --> B["CLI 入口"]
B --> C["核心模块"]
C --> D["输出产物"]
图要服务理解,不要为了好看画大图。每张图控制在 5-12 个节点。
代码阅读纪律
- 搜索优先用
rg / rg --files。
- 先读入口和调用方,再读被调用函数。
- 不确定某函数是否被调用时,用
rg "function_name" 查证。
- 遇到配置项时,同时找 loader、schema/default、实际使用点。
- 遇到生成产物时,区分源文件和 generated/build output。
- 如果解释涉及当前版本行为,必要时运行最小命令验证。
输出风格
- 讲解要像课堂,不像审计报告。
- 保持短段落。
- 一次不要抛太多文件。
- 明确告诉用户“本节只需要记住什么”。
- 对初学者解释术语,但不要降低技术准确性。
完成标准
一次完整学习任务完成时,应至少有:
- 一份学习路线。
- 多个 lesson 文档。
- 每节包含图或代码地图。
- 用户能说明主调用链、关键模块职责、主要数据流和常见调试入口。