Skip to content

method.md

Latest commit

 

History

History
413 lines (280 loc) · 20.7 KB

method.md

File metadata and controls

413 lines (280 loc) · 20.7 KB
title 怎么消化一个 GitHub 项目
description 7 层方法论 + 1500 篇生产实践后的回看
sidebar
order
0

这是这个站点所有项目笔记遵循的方法论。 不是拍脑袋的章节清单，是"如何让一个项目从 README 翻译变成你脑子里的可调用工具"。 7 层方法论是骨架；下面每层都加了"写了 700+ 篇项目笔记后的回看"——哪一层最常被跳过、哪一层改一次就把整篇质量从"译文"拉到"机制"。

顶层结论（先看）

  • 这套方法跑过 726 篇项目 + 785 篇论文 = 1511 篇笔记，跨 19 个一级主题、约 1514 行写作密度
  • 最常被跳过的层是 Layer 4 改一处——但每次跳过都让整篇笔记从"机制"退回"翻译"
  • 真正变成"门面级"反向引用枢纽的笔记（[[react]] 68 / [[pytorch]] 67 / [[kubernetes]] 66 / [[postgresql]] 66），无一例外都做过 L3+L4 双层
  • L0 / L1 / L2 / L7 即使做得平庸也不致命；L3+L4 任一项缺失 = 整篇笔记掉档

失败模式（不及格特征）

不达标的项目笔记长这样：

  • 段落是 README 翻译，没读过任何源码
  • "How" 段是项目自己的话复读一遍
  • Hands-on 只是 npm install + 用一下，没改过任何东西
  • 没和任何竞品对比，看完不知道这个项目和它的"敌人"差在哪
  • 自检问题是 ChatGPT 凑数生成的，自己根本不知道答案

如果一篇笔记达成上面任意一条，这篇笔记不及格，要重做。

回看 726 篇里被退回重做的，约 60% 都卡在"L3 没贴真实代码 / L4 没动手改"——这两层是质量分水岭。

7 层结构（约 75 分钟一篇）

Layer 0 · 身份扫描（5 分钟）

抓硬指标，建立尺度感。命令：

gh repo view <org/repo> --json stargazerCount,forkCount,licenseInfo,pushedAt,defaultBranchRef
gh api repos/<org/repo>/commits --jq '.[0:10] | .[].commit.committer.date'  # 最近 10 commit 时间
gh api repos/<org/repo>/contributors --jq '.[0:5] | .[].login'              # 主贡献者

判断：

  • Star < 5k 且 < 1 年 → 新兴项目，记笔记时标"早期"
  • 维护者就 1-2 人 → 标"个人项目"，要警惕 bus factor
  • 最近 commit > 6 个月前 → 项目可能已死，谨慎推荐

输出到笔记顶部表格：star / version / 最近活跃 / 主语言 / 维护方。

1500 篇后的回看：L0 是最不容易翻车的一层，但最容易撒谎的一项是"读时 commit hash"——726 篇里早期约 30% 没锚 hash，半年后 GitHub 永久链接全部失效。后来强制要求 Frontmatter 含 commit hash + 读时日期，回溯修补了约 200 篇。

Layer 1 · 存在理由（10 分钟）

关键问题：这东西如果不存在，世界会缺少什么？

操作：

  1. 读 README 顶部 5 段
  2. 找作者的 manifesto 文章——通常在 docs/ 顶部、blog 第一篇、或 v1.0 release notes
  3. 找 launch HN 帖（搜 <project name> site:news.ycombinator.com）

输出：3-5 句话，用你自己的话总结 "why this exists"。 拒绝写"它是一个 X 库，提供 Y 功能"——这是 README 翻译。 要写"在它出现之前，做 X 这件事的人都遇到 Y 痛苦；它的核心 insight 是 Z"。

1500 篇后的回看：这一层翻车次数仅次于 L4。早期 200 篇中很多笔记的 Why 段是"它是一个 X 库"——后来引入"必须引用至少 1 处 manifesto / launch HN / 一作 blog"硬约束才稳住。门面级笔记如 [[react]] / [[postgresql]] / [[kubernetes]] 都做了"前世界缺什么"的反向叙事，这是它们成为枢纽的前提。

Layer 2 · 仓库地形（10 分钟）

操作：

git clone --depth 1 https://github.com/<org/repo>
cd <repo>
ls -la                          # 顶层文件
tree -L 2 -I 'node_modules'     # 二级目录树

输出"仓库结构注释表"——每个顶层目录写一句它的角色：

apps/v4/              ← 文档站点（Next.js）
packages/cli/         ← npx shadcn 命令的实现
packages/registry/    ← registry schema 与 resolver
templates/            ← 用户 init 时复制的脚手架
scripts/              ← 维护者用的发布脚本

然后找心脏目录——最被 import 的 / commit 最频繁的：

git log --format='' --name-only | sort | uniq -c | sort -rn | head -20

这 20 个文件就是项目的"热点"，记下其中 2-3 个最关键的，下一层精读它们。

1500 篇后的回看：L2 的 commit 热点法对工具库几乎万无一失，但对大型应用（如 [[react]] / excalidraw）会跑出"全是 changelog 维护文件"的噪音榜——后来在 v1.1 把大型应用的 L2 改成"按 subsystem 分组热点"，详见后文类型分支。

Layer 3 · 心脏代码精读（20 分钟）

最重要的一步。选 1-2 个核心文件通读。

操作：

  1. 选定文件（来自 Layer 2 的热点）
  2. 完整读完（如果 > 500 行，读最关键的函数）
  3. 在笔记里贴 30-100 行真实代码片段（不是伪代码）
  4. 给每段代码写"这里在做什么 + 为什么这么写"的旁注

输出：3-5 段"机制揭秘"，每段含：

  • 一段 GitHub 永久链接（https://github.com/<org/repo>/blob/<sha>/path#Lxx-Lyy）
  • 真实代码片段
  • 旁注：状态机变化、关键 trade-off、为什么不用更直接的写法

禁止：贴一段代码就放那里不解释——如果读者只能在 GitHub 上读到同样的代码，你的笔记就没价值。

1500 篇后的回看：L3 是"门面 vs 平庸"的真正分水岭。统计 726 篇项目笔记，反向引用 ≥ 50 的 10 篇枢纽（[[react]] / [[pytorch]] / [[kubernetes]] / [[postgresql]] / [[llvm]] 等），无一例外都贴了 ≥ 3 段真实代码片段 + 旁注。反向引用 < 5 的笔记里，约 70% 的 L3 段是"伪代码 / 截图 / 概念图"。结论：贴真实代码不是格式要求，是反向引用形成的物理前提——只有真实代码段才能被其他笔记引用 path:line。

Layer 4 · 改一处（10 分钟）

操作：

  1. 在本地 clone 里改一行核心代码
  2. 跑测试（npm test 或类似）或跑 example
  3. 观察行为变化

例：shadcn 的 button.tsx 把 forwardRef 删掉，看 <Button asChild> 还能不能用。 TanStack Query 把 staleTime 默认值从 0 改成 Infinity，看 devtools 里查询行为。

输出：1 个具体的"我改了 X，发生了 Y"案例。这一步是把抽象的"机制"变成你身体能感知的因果。

1500 篇后的回看：L4 是最常被跳过的一层——726 篇里粗算约 40% 的早期笔记跳过了 L4（环境配置成本、monorepo 没装上、跑测试嫌麻烦）。但凡补回 L4 的，整篇质量肉眼可见提升一个档位。

L4 改一处的实际成效（基于已补回的约 100 个案例）：

  • 3 类高 ROI 改动：(a) 改 default 配置值看行为变化；(b) 删一段错误处理看哪里炸；(c) 加一行 console.log 在热路径看调用频次
  • 改一处的真正价值不是技术深度，是"破除 README 神话"——文档说"零配置"，改一行 default 你会发现根本不是；文档说"可插拔 plugin"，删一行你会发现耦合在哪
  • 平均时间成本：8-15 分钟（远低于预估的 10 分钟里限）；env 装好后 L4 几乎不消耗心智
  • 副作用：写完 L4 的人 3 个月后能复述项目机制的概率，约是没写 L4 的 3 倍（无对照组凭印象，但很显著）

如果你今天只能选一项工具来提升项目笔记质量，选 L4。

Layer 5 · 横向对比（10 分钟）

找 1-2 个直接竞品。要找哲学不同的，不是同一流派的下位替代。

例：

  • shadcn-ui ↔ MUI（哲学差异：代码分发 vs npm install）
  • TanStack Query ↔ SWR（哲学差异：显式 invalidation vs revalidate）
  • Hono ↔ Express（哲学差异：边缘运行时优先 vs Node 优先）
  • Drizzle ↔ Prisma（哲学差异：SQL-first vs schema-first）

输出：对比表（不只是功能差异，还有设计哲学差异），加一句"什么场景选 A，什么场景选 B"。

1500 篇后的回看：L5 容易写成"两边都好，看场景"——这是没思考的特征。强制要求"标出对方做不到 / 不愿做的事"才能逼出真对比。门面级 [[postgresql]] 笔记的 L5 段直接写"MySQL 不愿做的事：MVCC/索引并发"，[[react]] 笔记 L5 写"Vue 不愿做的事：把 reactivity 显式化"——这些尖锐对比是反向引用源头之一。

Layer 6 · 与当前工作的连接（5 分钟）

写明 3 件事：

  1. 今天就能用的部分：你正在做的项目里，哪个文件能立刻替换成这个工具
  2. 下个月能用的部分：需要一些重构准备的迁移路径
  3. 不要用的部分：这个项目里有些设计不适合你的场景，明确标出来

输出：迁移路径（含优先级），以及"不要的"清单。

1500 篇后的回看：L6 是"个人化"的分界——同一个项目，不同人写的 L6 完全不一样才正常。如果你的 L6 三段写得和 GPT 通用建议一样，说明项目和你当前工作没真连接，可能根本不该写这篇笔记。

Layer 7 · 自检 + 延伸阅读（5 分钟）

自检问题：3-5 个你目前答不上来的具体问题。 不是"这个库的设计哲学是什么"——这是空话。 要像："useQuery 在组件 unmount 后，AbortController 是在哪里被 abort 的？追到具体行号。"

延伸阅读：精读完心脏文件后，下一步该读哪 2-3 个文件，按什么顺序，回答什么问题。

1500 篇后的回看：L7 自检题是"未来回访"的钩子。每月跑一次"补 L7 答案"扫描，命中约 5-10 篇——这是项目笔记保持新鲜度的低成本机制。早期没强制要求"追到行号"，导致 70% 的自检题是空话；强制后这一层变成笔记最有复利的部分。

笔记输出结构（按层映射）

---
title: <项目名> — <一句话定位>
description: ...
sidebar:
  label: <项目名>
  order: <序号>
---

| 项目 | 信息 |
|------|------|
| Layer 0 数据填这里 |

## 一句话定位
（Layer 1 输出）

## Why（为什么推荐你看）
（Layer 1 输出，3-5 句作者意图 + 你的转译）

## 仓库地形
（Layer 2 输出：目录注释表 + 心脏文件标识）

## 核心机制
（Layer 3 输出：3-5 段代码精读，每段含 GitHub 永久链接 + 代码 + 旁注）

## Hands-on（含改一处实验）
（Layer 4 输出：30 分钟跑通命令 + 1 个具体修改实验）

## 横向对比
（Layer 5 输出：对比表 + 选型建议）

## 与你当前工作的连接
（Layer 6 输出：今天/下月/不要 三段）

## 自检问题 + 延伸阅读
（Layer 7 输出）

哪一层最常被跳过（基于 726 篇项目笔记的回看）

按"早期被跳过的频率"从高到低：

层 被跳概率 跳过的代价 补救成本
L4 改一处 ~40% 整篇退回"译文"档；机制理解半年内忘 中（需重新装环境）
L5 横向对比 ~25% 选型建议变空话；不知道项目"敌人"是谁 低（找一篇竞品笔记对照即可）
L1 Why ~20% Why 段变 README 翻译 低（找 manifesto / launch HN）
L7 自检 ~15% 三个月后无法回访；笔记变一次性消费品 低（写 3 个具体问题即可）
L3 核心机制 ~10% 整篇直接判不及格 高（必须重读源码）
L0 / L2 / L6 < 5% 影响小 低

结论：质量门禁应集中火力在 L3+L4。其他层平庸不致命，但 L3+L4 任一缺失就是整篇判废。

L4 改一处：从抽象到肌肉记忆的桥

L4 是这套方法最被低估的一层。1500+ 篇后的具体观察：

  • 改一处不是"做实验"，是"破除幻觉"：READMEs 经常隐藏耦合点，改一行就暴露
  • 3 类最高 ROI 的改动：
    • (a) 改 default 值（[[pytorch]] DataLoader 的 num_workers / [[react]] StrictMode）
    • (b) 删一段错误处理 / 边界检查（看哪里炸）
    • (c) 在热路径加一行 console.log / fmt.Println（看真实调用频次）
  • 改一处比读 100 行源码更能形成长期记忆——因果链亲手建立比"被告知"强一个数量级
  • 不要选"安全"改动：把 const 改 let 这种没冲击的不算 L4
  • 改完一定写"我改了 X，发生了 Y"——光改不写等于没做

如果整套方法只能保留 1 层，保留 L4。

时间分配的取舍

完整 7 层做完约 75 分钟，对应一篇 400-700 行 markdown。

如果时间紧（30 分钟轻量版）：跳 Layer 5 + Layer 6 + Layer 7，但绝不跳 Layer 3 和 Layer 4。没读过源码、没动手改的笔记没有价值，是这个站点的硬底线。

这套方法的来源

不是凭空发明，参考了：

  • 抖音 / Linear 工程团队的 "code archaeology" 实践
  • Julia Evans 的 zine 写作法（一页讲清一个概念）
  • "How to read papers" 的 three-pass 读法迁移到代码
  • Karpathy 的"读代码先读 train loop"的项目入门法

状元篇 Checklist v1（项目版高水位）

"状元篇"是这个站点对项目笔记的高水位标准——基于 7 层方法论之上的可量化加固层。 论文版镜像见 /study/papers-method/，按 7 层挂钩，但有项目专属条目。

严格度分级

  • P0 必填：缺则不及格，状元篇必须全部满足
  • P1 推荐：影响"状元"评级，应该满足
  • P2 加分：高阶项，做到额外加分

核心条目（按层）

  • Frontmatter + 信息表 (P0)：title 一句话定位 / description 1 行 trade-off / 信息表 ≥ 8 字段（star、fork、最近活跃、commit hash + 读时日期、主语言、维护方 + 主要贡献者前 3-5、License、类似项目）
  • L1 Why (P0)：3-5 句"前世界缺什么"用自己的话；至少 1 处 manifesto / launch HN / 一作 blog 引用
  • L2 仓库地形 (P0)：顶层目录注释表 + 心脏文件清单 2-3 个 + commit 热点 top 10-20
  • 架构图 / 状态机图 (P1)：≥ 1 张架构图 / 数据流图 / 状态机图（webp，13-15× 压缩）；caption 详细
  • L3 核心机制 (P0)：≥ 3 段代码精读，每段 GitHub 永久链接（commit hash 锚定）+ 30-100 行真实代码 + ≥ 5 个旁注 + ≥ 1 处"怀疑 N"
  • L4 改一处 (P0)：30 分钟跑通命令清单 + 1 个具体改动实验 + 实验输出（截图 / 数字 / 行为变化日志）
  • L5 横向对比 (P0)：≥ 4 维对比表 + ≥ 1 个哲学不同的竞品 + 选型建议段
  • L6 当前工作连接 (P0)："今天/下月/不要"三段，每段 ≥ 4 子弹
  • L7 自检 + 延伸 (P0)：3-5 个追到行号级别的具体怀疑题 + "接下来读哪 N 个文件"表
  • 限制段 (P1)：≥ 3 条独立限制，禁抄项目 README
  • 附录：宣传 vs 现实 (P2)：docs / blog 宣传 vs 代码现实对比，≥ 3 行
  • 结尾元数据 (P1)：升级日期 + 总行数 + 启用工具

量化总指标

维度 底线 备注
行数 500 1500 篇里最长的 xstate 675 行
Figure 数（webp） 1 架构 / 数据流 / 状态机
GitHub 永久链接 3 commit hash 锚定
显式怀疑 3 散布于机制段 + 自检段
path:line 引用 1 至少一处

版本

  • v1 (2026-05-28) — 7 层方法论之上首版 checklist，对齐论文版
  • v1.1 (2026-05-28) — 加项目类型分支（见下），解决 v1 默认"工具库"心智模型、大型应用 / 编译器运行时 / 测试工具套不上的问题
  • 修订规则：未来加新条目升 v2，原 v1 条目不删，只标 deprecated

状元篇 Checklist v1.1：项目类型分支

v1 默认是工具库（small-surface API library，参考 zustand / swr / shadcn-ui）。 大型应用 / 编译器运行时 / 框架 SDK / 测试工具的"心脏物"和"改一处"路径不同——硬套 v1 会逼笔记作者扭曲叙事。 v1.1 引入"项目类型 self-classify"，每类有专属 L2 / L3 / L4 模板。

Step 1：先 self-classify

写笔记前先在草稿顶部标项目类型（5 选 1）：

类型 判定 例子
大型应用 端到端用户产品，仓库含 multiple subsystem，star ≥ 5k 用户量大 excalidraw / continue / plane / cal.com
工具库 小 surface API，单一职责，500-3000 行核心 zustand / swr / tanstack-query / zod / xstate / shadcn-ui
编译器/运行时 输入文本或字节，输出 transformed；含 pipeline 多阶段 vite / esbuild / bun / biome / rolldown / oxc / [[llvm]]
框架/SDK 服务端或客户端框架，提供 abstraction + extension points hono / trpc / drizzle-orm / inngest
测试/验证工具 围绕 test runner / assertion / fixture 模型 playwright / vitest / msw

混合类型（如 playwright 既是测试工具又有 browser driver 内核）：选主导特征，附录段说明跨类。

Step 2：按类型套对应 Layer 模板

通用条目（所有类型共享，不变）：

  • Frontmatter / L0 ≥ 8 字段 / L1 Why
  • L5 横向对比 / L6 三段 / L7 自检
  • 限制段 / 宣传 vs 现实附录 / 结尾元数据

差异条目按类型分支：

分支 A · 大型应用（user-facing product）

  • L2：顶层目录注释表必含"路由 / 数据层 / 业务模块"三类区分；心脏文件 ≥ 3（不是 2-3）；commit 热点按 subsystem 分组
  • 架构图：P0 必填（不是 P1）；≥ 1 张全局 + 1 张关键 subsystem 数据流图
  • L3 ≥ 3 段：每段对应一个 subsystem
  • L4 改一处：不要求跑通完整 build；允许"读+理解" + 1 个具体 subsystem 的小改实验

分支 B · 工具库（v1 默认，结构不变）

  • L2 心脏文件 2-3 个
  • L3 ≥ 3 段独立小节，每段 30-100 行真实代码
  • L4 30 分钟跑通 + 1 个改一处实验

分支 C · 编译器/运行时

  • L2：顶层目录必须画出 pipeline phase 划分（parser → transformer → emitter / lex → parse → typecheck → codegen）；心脏文件 = 每个 phase 1 个代表实现
  • Pipeline 图（P0 必填）：≥ 1 张 pipeline 流图，标 input → phase 1 → ... → output + 每个 phase 关键 trade-off
  • L3 ≥ 3 段：按 phase 切——parser / transformer / emitter
  • L4 改一处：加一个 transform 或改一个 default option，看 output 字节级变化；必须含 before/after diff

分支 D · 框架/SDK

  • L2：心脏文件清单含核心 abstraction 定义文件（如 Hono 的 app.ts / Drizzle 的 schema 引擎）；必须列 extension point（middleware / plugin / hook）所在路径
  • L3 ≥ 3 段：核心 abstraction + middleware/handler 模型 + lifecycle
  • L4 改一处：写 1 个 plugin / middleware / schema extension；跑 example 看 lifecycle 何时触发

分支 E · 测试/验证工具

  • L2：心脏文件 = test runner 主循环 + fixture 注入 + assertion / matcher
  • L3 ≥ 3 段：runner loop / fixture 系统 / matcher 模型
  • L4 改一处：写 1 个 custom matcher / reporter / fixture；跑 1 个 test 看生命周期 hook

Step 3：量化指标按类型差异化

类型 行数底线 Figure 数 ≥ GitHub permalink ≥ 显式怀疑 ≥
大型应用 500 2 5 3
工具库 400 1 3 3
编译器/运行时 500 2 5 4
框架/SDK 500 1 4 3
测试/验证 400 1 3 3

工具库 / 测试工具底线 400（不是 500）：表面小、抽象集中，500 行容易逼出冗余。 编译器底线 figure 2 + 怀疑 4：pipeline 性质决定了视觉表达 + 多 phase 都需要审视。

Step 4：自检流程

写完笔记后按以下顺序自检：

  1. 项目类型 self-classify 标对了吗（看心脏物：product / library / pipeline / abstraction / runner）
  2. 通用条目全过了吗（Frontmatter / L0-1 / L5-7 / 限制 / 附录 / 元数据）
  3. 类型专属条目全过了吗（参照分支 A/B/C/D/E）
  4. 量化指标全过了吗（行数 / figure / 锚定 / 怀疑）

任意一项 P0 缺失 → 不及格，要补。

与论文消化方法的关系

项目方法和论文方法共享 7 层骨架，差异点：

  • L3 心脏代码 ↔ 论文方法的"祖坟段"：项目找 hot file，论文追祖论文（如 [[lambda-calculus]] / [[hindley-milner]] / [[paxos-1998]] / [[attention]] 这种地基级祖宗）
  • L4 改一处 ↔ 论文的"复现一个数字"：手感建立路径不同，但都是"破除翻译，建立因果"
  • L5 横向对比 ↔ 论文的"前传/后传"：项目找哲学不同竞品，论文找方法论分叉

不论项目还是论文，反向引用 ≥ 50 的门面级笔记（如 [[hindley-milner]] 126 / [[attention]] 103 / [[react]] 68 / [[paxos-1998]] 67 / [[pytorch]] 67）共同特征只有一个：L3 + L4 都做扎实，且引出至少 3 条可被其他笔记引用的 path:line / 怀疑点。

这是 1500 篇后唯一不动的判据。