源码精读方法论

这是什么？适合谁？

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

一句话内核：让每一个技术论断都可回溯到源码的具体行。 可回溯迫使你真的读到那一行，也让读者能自己验证。AI 辅助读码时幻觉几乎必然发生——根据文件名推测实现、根据常见模式补全细节、把注释当成代码行为陈述。一旦掺进去，整份成果可信度就是零。

实际结果：这套方法论跑出了两门源码精读课（DeepSeek Harness 与 OpenAI Codex，合计 61 节），其中 Codex 那门有 1270 处带行号的源码引用，逐字节校验零编造、零行号漂移。

适合人群：想精读大型开源项目的开发者；要做源码级技术写作/课程的人；需要「每句话可验证」成果的团队。

准备工作

1. 给 Agent 发仓库：把 https://github.com/itshen/source-reading-methodology 发给 Agent，让它先读 SKILL.md 并安装为长期 Skill。
2. 明确目标：准备好要精读的源码仓库、产出形态（读一个模块 vs 做 32 节课）、规模。
3. 成本：MIT 开源；成品在 xueai.app 可看。
4. 心智准备：大纲最花时间也最决定成败；校验器必须在批量生产前建好。

快速上手（3 步）

第一步：安装 Skill

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

第二步：确认 Agent 读进去了

Agent 的反应符合这五条说明走对了：

1. 先问清产出形态和规模再动手
2. 动手第一件事是给目标仓库打 tag、记下 commit
3. 每段代码都带 起始行:结束行:文件路径
4. 查不到的地方明说「未找到对应实现，检索关键词为 X、Y」
5. 批量写之前先建校验器

第三步：开始精读

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

成功判定：产出物每个技术论断都能跳到源码具体行核对；查不到的地方明说而非编造。

初级用法

四个阶段（不要跳级）

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

各阶段模板

高级玩法

文风扫描器（零依赖）

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

把句式禁忌写成正则，扫描前剥掉代码块、行内代码和「」直接引用，避免源码字符误判。

派并行 Agent 之前

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

成书构建

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

每本编出来的书封底自带逐章数据表和版本锚点，读者照着就能抽查。

小技巧

1. 先看样张再决定：三章样张在线试读，翻一下再决定要不要照着走。
2. 锁版本是第一步：不锁 commit，后面写的行号迟早失效，且分不清是写错还是上游改了。
3. 校验器先于批量生产：人工复核十万字的行号不现实。
4. 省略不编行号：省略跳过的行只标 ·，宁可少显示也不显示编出来的行号。
5. PITFALLS.md 卡住再查：29 条踩坑全部来自真实事故，不用背。

常见踩坑

踩坑 1：AI 上来就甩章节大纲

• 现象：Agent 直接给大纲、代码块没行号、一口答应「三十二章这就写完」。
• 原因：没按方法论走，跳过了阶段一和校验器。
• 解决：把 SKILL.md 重新发给它；没行号、没锁版本就是没读进去。

踩坑 2：不锁版本导致行号漂移

• 现象：三个月后所有行号失效。
• 原因：没在阶段一给目标仓库打 tag、记 commit。
• 解决：动手第一件事锁版本；封底写清版本锚点，读者发现对不上能分辨是写错还是上游改了。

踩坑 3：批量写完之后才建校验器

• 现象：十万字行号没法人工复核。
• 原因：校验器在批量生产前建才有意义。
• 解决：阶段三开始前建好机器校验器，「必须全绿才算交付」。

踩坑 4：AI 编造实现

• 现象：根据文件名推测实现、把注释当代码行为。
• 原因：幻觉是 AI 读码的默认行为。
• 解决：查不到的地方明说「未找到对应实现，检索关键词为 X、Y」，宁可空着也不填。

踩坑 5：跳级（大纲没定就写书稿）

• 现象：并行写作互相重复又互相矛盾。
• 原因：跳过了阶段二的逐章源码锚点清单。
• 解决：产出物分层，每层输入是上层输出，不要跳级。

常见问题 FAQ

Q1: 这套方法论适合多大体量的项目？

A: 实践案例是 90 多个 crate 的 Rust 单仓项目，产出 32 章、20.8 万汉字正文、1270 处带行号引用。小到读一个模块、大到做一门课都适用，阶段数随规模调整。

Q2: 怎么判断 AI 真的读进去了？

A: 看五条信号：先问产出形态、动手先锁版本、代码带行号、查不到明说、先建校验器。反过来——甩大纲、没行号、一口答应全写完——就是没按这套走。

Q3: 为什么「每句话可回溯」这么重要？

A: 因为 AI 读码必然产生幻觉，读者无法分辨哪句是真的。可回溯让读者能自己验证，让成果可信度不归零。

Q4: 成果是什么形态？

A: 一本带封面封底、可读可查可传的 HTML 书，或交互课页。封底带逐章数据表和版本锚点。

Q5: 商用可以吗？

A: MIT License，含章节书稿、截图、样张页面。引用的 openai/codex 源码片段版权归原作者，用于教学说明。

进阶学习建议

掌握基础后，建议深入：

1. 自己盯两个节点：大纲最花时间也最决定成败（决定哪些内容进/不进）；校验器必须在批量生产前建好，事后补等于没有。
2. 把方法论改造成自己的：读 METHODOLOGY.md（315 行，每条规则写来由）和 PITFALLS.md（29 条真实事故），结合自己的项目调整模板。
3. 并行生产纪律：研究 METHODOLOGY.md 的并行生产一节，提前堵住子 Agent 的四种典型偏差。

参考链接

• 官方仓库
• 三章样张在线试读
• 在线课程 xueai.app

最后更新：2026-08-27 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成