Source Reading Methodology

source-reading-methodology

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

[](https://itshen.github.io/source-reading-methodology/) [](https://xueai.app/?from=source-reading-methodology) [](https://x.com/luoxiaoshan_ai) [](LICENSE)

**先看成品：[三章样张，在线试读](https://itshen.github.io/source-reading-methodology/)。** 这本书是按下面这套方法论产出的，原料在 `sample/chapters/`，用仓库里的 `book/build_book.py` 一条命令编出来。翻一下再决定要不要照着走一遍。

用这套方法论跑出来的完整成果，是 [小山学堂](https://xueai.app/?from=source-reading-methodology) 上的两门源码精读课：DeepSeek Harness 与 OpenAI Codex，合计 61 节。其中 Codex 那门的章节书稿有 1270 处带行号的源码引用，逐字节校验零编造。

---

Quick Start：把这个仓库发给 Agent

你不需要判断自己用的是哪一种 Agent，也不需要手动找它的 Skill 目录。把这个仓库的地址发给 Agent，再把下面这段话发给它：

阅读这个仓库：https://github.com/itshen/source-reading-methodology
先完整阅读 SKILL.md，把它安装成你可长期使用的 Skill；安装位置和方式由你根据当前运行环境自行判断。
安装完成后，询问我要精读的源码仓库、产出形态和规模，再按 SKILL.md 执行。

Agent 会自己读取仓库、完成安装，并在开始精读之前问清任务。以后你只需要直接说：

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

怎么判断 AI 真的读进去了

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

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

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

---

一句话内核

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

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

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