name: source-reading description: 带 AI 精读大型开源仓库，产出每句话都能回溯到源码具体行的书稿、课程或技术文档。核心是零幻觉：每一处引用逐字节核实、行号实读、静默删行由脚本抓出。覆盖锁版本锚点、写逐章大纲、八段结构写章节、编成带封面封底的 HTML 书、机器校验、并行子 Agent 生产六件事。当用户要读懂一个陌生的大型仓库、精读某个开源项目源码、把源码整理成一本书、整理成课程或系列文章、做源码解读、写架构分析、或者要派多个 Agent 并行写技术内容时使用。触发词：精读源码、读源码、源码解读、源码分析、拆解这个项目、这个仓库怎么读、把源码写成课、把源码写成书、写源码精读、架构分析、code walkthrough、带我读代码。

源码精读

把陌生的大型仓库读成可交付的内容。唯一不可妥协的要求：每一个技术论断都可回溯到源码的具体行。

AI 读码时幻觉几乎必然发生：根据文件名推测实现、根据常见模式补全细节、把注释当成代码行为陈述。掺进去一次，整份产出的可信度就是零，因为读者无法分辨哪句是真的。下面所有规则都是为了守住这一条。

第一步：先定规模，别过度应用

问清产出形态再动手。四阶段全流程很重，小任务不需要。

不确定就问：产出是给自己看还是给别人看，要不要交互演示，篇数大概多少。

零幻觉铁律

动笔前必须做到，每条都是作废级：

1. 每一处引用、每一个行号、每一个类型名与函数名，动笔前用读文件工具实读核实。 禁止凭印象、禁止根据文件名推测、禁止照抄大纲里的候选行号
2. 代码块与源文件逐字节一致。 保留原始缩进、属性宏、注释、空行。禁止转译、禁止美化、禁止写「示意代码」
3. 中间跳过内容必须显式写省略标记（含 ... 的整行注释）。静默删行会被校验器抓成 FABRICATION
4. 找不到某个机制的实现，写明 未找到对应实现，检索关键词为 X、Y、Z。不许编一个看起来合理的
5. 由推断得出的结论显式标注为推断
6. 引用注释时说明这是注释，不要当成代码行为陈述
7. 数字（行数、文件数、变体个数）必须统计过，统一用 splitlines() 口径
8. 引用符号链接时引真实文件，并注明链接关系

引用格式，三部分必填，路径相对仓库根：

```153:160:core/src/session/turn.rs
pub(crate) async fn run_turn(
    sess: Arc<Session>,
    ...
) -> CodexResult<Option<String>> {
```

四阶段工作流

每一层的输入是上一层的输出，不要跳级。跳级的后果很具体：没有版本锚点，写到第十章时第一章的行号全部失效，且无法判断是当初写错还是后来改了。

- [ ] 阶段一 语料准备：锁版本、备对比语料、建检索脚本
- [ ] 阶段二 大纲：立一个真问题 + 逐章源码锚点
- [ ] 阶段三 章节书稿：八段结构，每处论断带行号
- [ ] 阶段四 成书：编成带封面封底的 HTML 书
- [ ] 贯穿 机器校验（批量生产之前就要建好）

阶段一：语料准备

git -C <repo> tag course-anchor-$(date +%Y%m%d)
git -C <repo> rev-parse --short HEAD

把 tag 与 commit 写进所有下游文档的文件头。然后做三件事：

1. 备至少一个同类项目做对照。 只读一个仓库读不出设计决策，会把作者的选择当成唯一解。对比语料也要锁版本
2. 建 ripgrep 检索脚本，不要建向量库。 查阅场景是关键词匹配，rg 毫秒级、零依赖
3. 找「为什么」的一手材料，按优先级：仓库根的评审红线文件（AGENTS.md、CONTRIBUTING.md、.cursor/rules/）→ 模块级 README → 模块头注释 → 测试文件 → 官方博客。指向外链的空壳文档要识别出来跳过

评审红线文件优先级最高：每条禁令背后通常都是一次真实事故，这是「为什么不那样做」的唯一一手来源。

阶段二：大纲

用 templates/00-outline-template.md。三件事按顺序：

1. 先立一个真问题，把整门内容收束到一句话。这句话决定哪些内容进、哪些不进。缺了它，大纲会退化成源码目录的中文翻译
2. 写清读者带走什么，具体到能直接用。「学会 Agent 架构」不算，「一份该不该做沙箱、做到哪一层的决策树」才算
3. 逐章写锚点：核心问题、源码入口（文件加候选行号）、要分析的设计决策、对比对象、演示方向

已核实的行号标 ✓。✓ 的含义是曾经核实过，不是现在还对。 写作时即使看到 ✓ 也要重读，因为真正要引用的可能是相邻的行。

演示方向要在大纲阶段就逐章分配，句式统一。不提前分配，多个写作 Agent 会做出雷同的演示。

阶段三：章节书稿

填 templates/01-chapter-spec-template.md 里的占位符，填完的那一份就是唯一写作标准。八段顺序固定：

两段最容易被敷衍，也最能拉开深度：边界条件不许答「取决于配置」，必须落到源码里某个 if 的某一行；横向对比不许写成功能清单对照，要说清另一侧为什么可以没有、或用什么别的东西补上了。

阶段四：成书

把章节 markdown 编成一本带封面、目录、正文、封底的 HTML 书：

pip install markdown
cp book/book.config.example.json book.config.json    # 填书名、作者、被读仓库与版本锚点
python3 book/build_book.py

封面放阶段二立的那句话与版本锚点，封底放逐章引用数、图数、字数。读者判断一份源码解读值不值得信，看的就是这两样敢不敢摊开。

带省略的引用块，省略之后的行号构建器不排，只从两头数，中间留空。跳过了多少行只有源文件知道，编一个看起来合理的行号比不给更糟。

用法与输入格式见 book/README.md。校对用 python3 book/shot_book.py dist。

产出形态是课程站交互课页时走 templates/02-page-spec-template.md，与成书并行不冲突。课页上默认零代码，能在一页上贴的代码量远小于理解所需；演示必须有分步动画、每步一句人话字幕、逻辑轨迹面板。写「做个动画演示这个流程」等于没写。

文风

能写成正则的进禁忌，不能的进表达偏好。 无法自动检查的硬性规则等于没有规则。

禁忌交付前必须清零，跑：

python3 templates/style_scan.py path/to/chapters/

扫描器剥掉代码块、行内代码和「」直接引用后再判，避免源码字符被误报。只扫面向读者的正文，大纲和规范这类内部工作文档不在约束范围内。

不要用同义替换绕过正则，比如把「而不是」换成「而非」。禁的是靠否定制造对比这件事，不是那三个字。

完整清单在 templates/01-chapter-spec-template.md 第 4 节。

机器校验

投入产出比最高的一件事，必须在批量生产之前建好。 人工复核十万字的行号不现实。

至少校验三件：

1. 代码块与源文件逐字节比对。以内容为准、行号为辅：按省略标记切成连续段，每段要在源文件里找到完全连续的匹配。拼不上判 FABRICATION，行号错了自动校正
2. 文风禁忌扫描
3. 引用密度下限。防一种隐蔽作弊：删掉报错的引用让校验变绿

第三条来自真实事故：某章初稿 56 处引用带若干报错，交付时只剩 22 处、全部通过。校验器只报「现有引用是否正确」，不报「该有的引用是否还在」，这个缺口必须补。

另外单独写一个脚本查「被引用文件是否存在」「行号是否越界」，逐字节比对验证不了路径写对没有。

校验器会误报，误报会让人开始忽略它的输出，那等于没有校验。每修一个误报都记下判据。

并行生产

规范里每一处含糊都会变成 N 份不同的理解。派活时必须给全四样：

1. 填好的写作规范（一个文件，不要口头补充）
2. 那一章的大纲条目
3. 全部语料的绝对路径。先确认路径真实存在再说，凭印象说「某个语料不在本地」会让子 Agent 绕开它
4. 校验命令，以及「必须全绿才算交付」

子 Agent 的四种典型偏差，规范里要提前堵：删引用让校验变绿、滥用省略标记凑字数、把检查糊弄过去、误报上游文档写错（实际命中率约两成）。

要求上报文档错误时带证据，格式固定：被质疑的原话 → 源码文件与行号 → 那几行的原文 → 为什么对不上。

并行中陆续收到的上游文档问题不要边收边改，开一个 PENDING_FIXES.md 累积，全部回来后统一核实统一修。

参考资料

• 方法论完整版，含每条规则的来由：METHODOLOGY.md
• 29 条踩坑清单，全部来自真实事故，卡住时来查：PITFALLS.md
• 大纲模板：templates/00-outline-template.md
• 章节写作规范模板：templates/01-chapter-spec-template.md
• 课页规范模板：templates/02-page-spec-template.md
• 成书构建器用法与输入格式：book/README.md
• 文风扫描器：templates/style_scan.py
• 真实成品，同一章从大纲到课页的纵向切片：example/README.md

source-reading-methodology

一套把陌生的大型仓库读成一门课的方法论。给要做同样事情的人用：选一个开源项目，带着 AI 精读它的源码，最后产出一份别人也能看懂、每句话都能验证的成果。

先看成品：三章样张，在线试读。 这本书是按下面这套方法论产出的，原料在 sample/chapters/，用仓库里的 book/build_book.py 一条命令编出来。翻一下再决定要不要照着走一遍。

用这套方法论跑出来的完整成果，是 小山学堂 上的两门源码精读课：DeepSeek Harness 与 OpenAI Codex，合计 61 节。其中 Codex 那门的章节书稿有 1270 处带行号的源码引用，逐字节校验零编造。

Quick Start：先让 AI 学会它

这套东西不是给你逐字读的，是给 AI 读的。你要做的只有两件：把它挂到 AI 能看见的地方，然后说一句人话。三种挂法，选一种。

一、装成 Agent Skill（推荐）

克隆下来软链进 skills 目录，之后你一提精读源码，AI 自动加载：

git clone https://github.com/itshen/source-reading-methodology.git
ln -sfn "$PWD/source-reading-methodology" ~/.cursor/skills/source-reading    # Cursor
ln -sfn "$PWD/source-reading-methodology" ~/.claude/skills/source-reading    # Claude Code
ln -sfn "$PWD/source-reading-methodology" ~/.agents/skills/source-reading    # 其它遵循 skills 约定的工具

用软链不用复制：git pull 之后 skill 跟着更新，也不会出现两份内容各自漂移。装完直接说：

帮我精读 ~/code/some-repo，我想产出一门课

二、不装 skill，直接指给 AI 读

克隆到工作目录旁边，把这段发给 AI：

先完整读 source-reading-methodology/SKILL.md，然后按它的四阶段工作流和零幻觉铁律精读 <仓库路径>。动笔之前先告诉我你打算走哪几个阶段、产出什么形态。

三、连克隆都省了

给能联网的 AI 这段：

读 https://raw.githubusercontent.com/itshen/source-reading-methodology/main/SKILL.md，按它的规则精读 <仓库 URL>。

怎么判断 AI 真的读进去了

SKILL.md 是唯一入口，一份文件讲完整套流程，需要细节时 AI 会自己去读 templates/ 和 PITFALLS.md。它的反应符合下面五条，说明走对了：

1. 先问清产出形态和规模再动手。读懂一个模块和做一门 32 节的课，该走的阶段数完全不同
2. 动手第一件事是给目标仓库打 tag、记下 commit。不锁版本，后面写的所有行号迟早失效，而且没人分得清是当初写错还是上游改了
3. 每段代码都带 起始行:结束行:文件路径，贴出来的每一行你都能自己跳回去核对
4. 查不到的地方明说「未找到对应实现，检索关键词为 X、Y」，宁可空着，也不填一个看起来合理的
5. 批量写之前先建校验器。人工复核十万字的行号不现实

反过来，如果 AI 上来就甩章节大纲、代码块没有行号、或者一口答应你「三十二章我这就全写完」，它没按这套走，把 SKILL.md 重新发给它。

一句话内核

让每一个技术论断都可回溯到源码的具体行。

可回溯迫使你真的读到那一行，也让读者能自己验证。AI 辅助读码时幻觉几乎必然发生，它会根据文件名推测实现、根据常见模式补全细节、把注释当成代码行为陈述。一旦掺进去，整份成果的可信度就是零，因为读者无法分辨哪句是真的。

这套方法论里所有的规则，都是为了守住这一条。落到版面上是这样：

图是样张第 3 章的一处引用，声明 codex-rs/core/src/session/turn.rs 的 1368 到 1439 行。左侧行号栏是源文件里的真实行号，读者可以直接跳回仓库对照。中间两处省略之后的行只标 ·：省略跳过了多少行只有源文件知道，宁可不显示，也不显示一个编出来的行号。头部的「第 1 / 3 段」点一下会按连续段依次高亮，让人看清哪几行在源文件里真的连在一起。

四个阶段

产出物分层，每一层的输入是上一层的输出。不要跳级。

阶段一  语料准备      锁版本、备对比语料、建检索脚本
   ↓
阶段二  大纲          回答「这门课要解答哪一个问题」+ 逐章源码锚点
   ↓
阶段三  章节书稿      八段结构，每处论断带行号，机器校验
   ↓
阶段四  成书          编成一本带封面封底的 HTML 书，可读、可查、可传

跳级的后果很具体：没有阶段一的版本锚点，阶段三写的行号三个月后全部失效；没有阶段二的锚点清单，阶段三的并行写作会互相重复又互相矛盾。

你自己要弄明白时，读什么

上面那三种挂法之后，跑流程是 AI 的事。你要搞清楚原理、或者想把这套改造成自己的，才需要往下读：

1. METHODOLOGY.md（315 行）方法论本体，每条规则都写了来由
2. PITFALLS.md（29 条）全部来自真实事故，不用背，卡住时来查
3. example/ 同一章从大纲到成书的真实成品，拿不准该填到什么程度时对着它看

有两个节点值得你自己盯，AI 容易滑过去：大纲最花时间也最决定成败，它决定哪些内容进、哪些不进；校验器必须在批量生产之前建好，事后补等于没有。

各阶段对应的模板

文风扫描器可以直接用，零依赖：

python3 templates/style_scan.py path/to/chapters/

它把句式禁忌写成正则，扫描前剥掉代码块、行内代码和「」直接引用，避免源码字符被误判。只扫面向读者的正文，大纲和规范这类内部文档不在约束范围内。

阶段一没有模板，它是三件具体的事，在 METHODOLOGY.md 里有操作步骤：给主教材打 tag、备齐至少一个同类项目做对照、包一个 ripgrep 检索脚本。

派并行 Agent 之前

规范里每一处含糊都会变成 N 份不同的理解。派活时必须给全四样东西：填好的写作规范（一个文件，不要口头补充）、那一章的大纲条目、全部语料的绝对路径、校验命令加上「必须全绿才算交付」。

METHODOLOGY.md 的并行生产一节列了子 Agent 的四种典型偏差，规范里要提前堵。

目录

├── SKILL.md               AI 的唯一入口，一份文件讲完整套流程
├── AGENTS.md              克隆或 fork 之后 AI 自动读到的指引，指向 SKILL.md
├── METHODOLOGY.md         方法论本体，给人读，每条规则都写了来由
├── PITFALLS.md            29 条踩坑清单，分五类
├── templates/             三份可复用模板加一个文风扫描器
├── book/                  成书构建器：章节 markdown 编成 HTML 书
├── sample/                样张原料：三章书稿加一份构建配置
├── docs/                  样张构建产物，也是 GitHub Pages 的站点目录
└── example/               同一章从大纲到成书的真实成品，当尺子用

book/ 是阶段四的实现，改一个 JSON 配置就能出书，用法见 book/README.md。

sample/ 加 docs/ 是那个在线样张的两端：前者是三章原料与配置，后者是编出来的书。想自己试构建器，直接拿这份配置跑：

pip install markdown
python3 book/build_book.py --config sample/book.config.json

example/ 是一条纵向切片：同一章在阶段二、三、四各自的成品，包括大纲节选与成书截图。拿到空模板不知道填到什么程度时，对着它看。

这套方法论跑出来的实际结果

一个 Rust 单仓项目，90 多个 crate。口径写在括号里，避免同一个数出现两种算法。

最后两行值得注意。互链候选 64 张最后只挂上 18 条，因为大量卡片拿闭源产品做对照、站内没有对应展开页，硬凑的链接比没有链接更糟。并行生产之所以能跑，靠的是先有逐字节校验器，人工复核十万字的行号不现实。

这类数字不能只写在 README 里，所以每本编出来的书都在封底自带一张逐章数据表和版本锚点，读者照着就能抽查：

上图是三章样张的封底，表里是这三章的实际数据，下面是被精读仓库的 commit 与 tag。这张表是一本书敢不敢让人查的凭证：行号对应哪个版本写清楚了，读者发现对不上，也能分辨是当初写错还是上游后来改了。

成品在 xueai.app，两门课的每一节都能直接看。

交流与关注

这套方法论出自 小山学堂，一个讲 AI 产品与 Agent 工程化的课程站。

• 在线课程：xueai.app
• X：@luoxiaoshan_ai
• GitHub：itshen

如果这份方法论帮到了你，欢迎给仓库点个 Star，也欢迎带着你自己的项目来群里聊聊卡在哪一步。

License

MIT License · Copyright (c) 2026 米羊科技（上海）有限公司 (Miyang Tech (Shanghai) Co., Ltd.)

仓库里的章节书稿、截图与样张页面同样按 MIT 授权。被引用的 openai/codex 源码片段版权归原作者所有，引用用于教学说明。