Code Deep Dive

Code Deep-Dive

为 vibe coding 项目编写中文深度 markdown 长文，让用户在碎片时间用手机补齐全栈代码知识。

核心场景

• 用户是谁：vibe coder——用自然语言指挥 AI 写代码，但对自己项目的底层机制缺乏系统理解。
• 何时触发：用户指定一个主题，想深入理解它，把"AI 替他写出来的代码"变成"他自己懂的知识"。
• 学习场景：不在电脑前。通勤、午休、睡前，用手机阅读。
• 输出形态：单篇 markdown 文件，中文，约 1.5 小时学习时长，完全自包含，配丰富外部链接。

不可妥协的五条原则

这五条是本文档的基础，写作时的所有细节规范都从它们推导。先理解"为什么"，再执行具体规则。

1. 自包含——学习时不在电脑前

用户学习时看不到代码，也搜不了资料。因此：

• 文章中每个被讲解的代码片段都必须完整内嵌，标注来源文件路径。禁止只写"见 src/foo.py 第 42 行"而不贴代码。
• 所有需要的前置概念都在文中解释，默认读者零基础。禁止"你应该知道 X"这种甩锅式写法。
• 文中引用的每个外部链接都要有一句话说明：讲了什么、适合什么阶段。用户在手机/平板上随时可以点开——说明文字帮他们判断"这个链接值不值得现在点开"。

2. 深度优先——把代码讲透

一篇文章的价值在于把主题讲透，而不是复述项目的现状。代码是文章的主体：项目代码是教学载体和入口，核心与周边的代码逻辑都要讲透——不追求逐行抠细节，但核心机制和它周边的配套机制（被调用的依赖、相邻模块、生态中的同类机制）必须讲到位。正文还要覆盖：

• 核心概念的全貌（不限于项目用到的部分）
• 底层原理：机制如何实现、为何这样设计、有什么权衡
• 历史脉络：为什么会出现、解决了什么问题、后来如何演化

项目里没体现但主题相关的部分，一样要讲。这才能支撑起 1.5 小时的学习时长。

3. 代码讲解——讲清"它实际是什么"，而不是"它应该是什么"

本文的核心动作是讲解代码。姿态不带评价：

• 讲清实际行为：这段代码做什么、怎么工作、数据怎么流、和谁交互。把代码的"实际样子"如实讲清楚——这正是读者拿去定位问题、规划重构的依据。
• 不做价值评判：既不唱赞歌（"我们深思熟虑地选择了这个方案"），也不批判（"这段代码有缺陷，应该改"）。代码讲透了，哪里不对劲、哪里要动，读者自己看得出来——你的任务是让"看得出来"成为可能。
• 不虚构动机：代码为什么长这样，只讲客观可考的因果（依赖关系、语言特性、历史沿革、遗留设计）。编造"当初为什么这么选"的叙事是不诚实的——大多数代码不是精心设计出来的。
• 不美化也不丑化：代码行为诡异就如实描述"它的行为是……"，不加评论；代码写得规整也如实说，不吹捧。评判权在读者手里。

4. 手机友好——碎片时间可读，但不牺牲深度

手机友好指排版和阅读节奏，不是内容降级。深度和体量照旧，只为手机优化呈现方式：

• 段落短：每段不超过 4-5 行，长内容拆成多段，不用长段把深度堆成墙。
• 多用列表、表格、引用块、加粗——手机上一扫就能抓住重点。
• 标题层级清晰，用户随时中断、随时续读。
• 每个章节标注预计阅读时长（markdown 版写作时在章首写 > 约 X 分钟；HTML 版由转换脚本按字数/代码量自动估算，写作时不要手动写时长）。
• 代码块单行不宜过长；每个代码块不超过 50 行，更长的按逻辑拆段、段间插入解读，方便手机纵向阅读。

5. 面向 vibe coder 的讲解视角

• 具体，不抽象：讲具体代码、具体例子、具体场景，不堆概念和抽象描述。能用一段代码说明的，不用三句抽象话。全文的默认语言是"实在"。
• 先讲"为什么在意"：这个知识对用户有什么用——更好指挥 AI、能审查 AI 的产出、能排查问题、能重构旧代码。这是动机，也是留存。
• 从现象到原理：先用用户熟悉的产品行为做钩子（"你点那个按钮时……"），再往下拆。
• 类比要准：类比是为了建立直觉，但必须准确，讲完类比要回到精确的定义。
• 术语给中文：首次出现的英文术语给中文译名 + 简短解释，括号保留英文原名（如"中间件（middleware）"），因为用户和 AI 沟通时要用到英文术语。

工作流程

Phase 1：确认主题与学习目标

用户指定主题后，先用一两句话向用户确认（或自行明确）本篇的定位：

• 主题是什么、为什么选它（它在你项目里承担什么角色）
• 学习目标：学完能做什么（3-5 条具体能力）
• 前置知识假设：读者已经知道什么、从哪开始补

确认后输出一份本篇规划给用户：主题、学习目标、章节大纲（每章一句话 + 预计时长）。得到用户确认后再开写。一篇 1.5 小时的长文方向错了代价很高，值得花 30 秒确认。

注意：规划要简短（几行即可），不要写成文档。用户确认只是防止方向跑偏。

Phase 2：项目调研

• 先读项目根目录的 AGENTS.md（如有）和 README，了解项目定位。
• 找出与主题相关的代码文件，完整阅读。
• 提取将要在文章中讲解的代码片段，记录文件路径与行号。
• 理解真实代码的调用链：这段代码被谁调用、它调用谁、数据怎么流。
• 带着理解的眼光读代码：不仅要懂"它在干什么"，也要看懂它的异常之处和不寻常之处——这些在讲解时要如实讲清（讲行为，不评价）。

只有先真正读懂代码，才能写出有深度的解读。这一阶段不做透，文章必然浮于表面。

Phase 3：网络调研与资料收集

写作前必须做一轮 Web 搜索，收集主题相关的权威资料：

• 官方文档优先（框架/语言的官方 docs、API 参考）
• 经典教程、权威博客、高质量视频、社区讨论（Stack Overflow、Hacker News 等）
• 尽量核实链接真实有效，禁止编造 URL。

收集到的链接按主题组织，稍后写入文章末尾的"学习资料库"，并给每个链接配一句话说明。

Phase 4：撰写

按 references/article-template.md 的结构撰写全文。写作规范见 references/writing-guidelines.md。

撰写时用项目真实代码作为讲解对象（见 references/writing-guidelines.md 的"代码解读规范"）。

Phase 5：自检

对照下面的质量标准逐条自查，不达标就修改。写完自查很重要——长文容易在细节上偷工减料。

质量标准（每篇必须满足）

Phase 6：输出

• 保存到项目 docs/learning/ 目录，文件名 yymmdd-{主题slug}.md（如 260807-react-hooks-原理.md）。目录不存在则创建。
• 文章开头用几行"元信息"：主题、来源项目、学习时长、前置知识、写作日期。
• 可选：format=html——若用户要求 HTML 版，则在撰写 markdown 时按 references/html-format.md 的约定加入测验（:::quiz，支持选择题与问答、含解说）、折叠块（:::details）、图表（:::mermaid）、图标（{{icon:name}}）等互动元素，然后用 scripts/md2html.py 转换为单文件 HTML，md 与 html 并存。预计时长由脚本自动计算，不要手动标注。
• 交付后向用户简述：文章位置、篇章结构、学习建议（每章适合什么碎片场景）。

Reference Files

• references/article-template.md — 文章结构模板：每个章节写什么、量化指标。写文章前必读。
• references/writing-guidelines.md — 写作规范：深度讲解方法、代码解读规范、外部链接规范、手机排版细节。写文章前必读。
• references/html-format.md — HTML 版约定格式与转换脚本用法（仅 format=html 时阅读）。
• scripts/md2html.py — markdown → 单文件 HTML 转换脚本（仅 format=html 时使用）。