grok-repo

grok-repo

先了解用途、结构和机制，再查阅历史以弄清 原因；只有掌握证据后，才评价设计取舍。 根据问题选择一种模式；每项论断都要引用文件路径或提交：

• 范围限定的问题（“X 如何运作？”“Y 从哪里来？”）→ 数据流跟踪。
• 变更问题（“为什么添加了 X？”“这个功能如何演变？”）→ 变更考证。
• 整个代码仓库的问题（“解释这个代码库”“带我了解一下”）→ 完整概览。

数据流跟踪（范围限定模式）

跟踪一个数据项——请求、消息、配置值或文件——从入口到产生效果。跟踪过程就是答案。

• 先用一行写出跳转链，每一跳都要引用： POST /jobs (api/handler.go:41) → validate → Job{} (job.go:12) → enqueue (redis) → worker.Run (worker.go:88) → status written (store.go:130)
• 在每一跳中说明数据的承载者（类型／结构体／模式）、转换过程，以及每次形态变化或重命名（JSON→结构体、字段重命名、枚举映射）。
• 标出跨越的边界：序列化、队列、进程／网络边界、goroutine／线程交接。
• 最后说明略过的旁路、值得进一步跟踪的错误／边缘路径，以及意外之处。
• 如果某一跳的 原因 不寻常，可抽查历史：git log -S '<symbol>'，或对该行执行 blame。

变更考证（历史模式）

重建一个功能或决策，而非整个代码库的完整发展历程：

1. 锚定当前概念——查找现有符号、路径、配置名称、测试和用户术语。先说明它现在的作用，再解释它如何演变至今。
2. 查找引入记录——使用 git log -S '<literal>' 查找内容的出现／消失，使用 git log -G '<regex>' 查找匹配的变更行，并对重命名的文件使用 --follow。也要尝试旧名称。
3. 阅读提交内容，而不只是标题——使用 git show 查看引入该功能的提交及其父提交。提交说明、测试、删除的代码和附近的修复都是证据；仅凭差异无法断定。
4. 追查评审讨论——变更理由往往会在 PR 中留存，比提交说明更完整。找出包含该提交的合并记录中的 PR 编号，再阅读讨论，而不只是说明：

   git log --merges --ancestry-path --oneline <sha>..HEAD | tail -1
   gh pr view <n> --comments        # gh issue view <n> --comments for a linked issue
   

5. 追踪演变过程——检查后续修复、重构、回退，以及对仍保留代码行的 blame。

按 之前 → 压力／证据 → 引入 → 修正／回退 → 当前形式 的顺序展开。 每个阶段都要引用 SHA 和路径；最后总结有证据支持的理由、被否决的替代方案、尚未厘清的背景，以及历史记录的局限。切勿把提交顺序当作因果关系，也不要编造动机。

阅读顺序（完整概览）

自上而下阅读。对于大型代码库，抽查有代表性的组件，并说明抽查了哪些内容。

1. 了解概况——阅读 README、docs/、顶层目录结构、清单（go.mod/package.json/Cargo.toml）、Makefile／CI 配置。找到入口点（main、CLI 命令、服务启动代码、导出的 API）。 如果构建／测试成本不高，就运行一下——通过的测试套件和一次实际调用，可以为后续分析打下基础。
2. 端到端跟踪一个真实流程（请求、命令或构建），然后再归纳。 不经过跟踪就做出的架构判断，通常是错的。
3. 梳理组件和边界——找出模块交汇处：接口、线协议、数据库模式、队列、插件接入点、进程边界。对每处边界都要追问 为何设于此处：是为了可测试性、可替换性、部署边界、团队边界，还是偶然形成。注明哪一侧拥有这些类型。
4. 挖掘 Git 历史以探究理由（见下方命令）。首先确认历史是否浅克隆、经过压缩、导入、生成，或包含大量供应商代码；薄弱的历史记录只能提供线索，而非理由。
5. 最后才评价设计取舍并挑选亮点，并以已收集的证据为依据。

Git 代码考古

scripts/archaeology.sh [repo-dir]         # digest first, then drill into what it surfaces
git show --stat <sha>                     # read the big commits' messages in full
git log --follow --oneline -- <hot-file>  # evolution of a load-bearing file
git log -S '<symbol>' --oneline           # when/why a concept appeared or died

• 按规模和提交说明，而非新近程度，寻找“关键变更”：重写、“重构”、“重新设计”、版本升级提交，以及任何说明了权衡取舍的提交。优秀项目会把设计文档藏在提交说明里——请引用它们。
• 交叉比对频繁改动 × 修复相关改动，选出值得仔细阅读的文件。这只是线索，并不能证明代码脆弱：格式调整、生成代码和长期存在的文件都可能主导计数。
• 回滚可能体现负面理由：在用它解释某个替代方案为何未能保留之前，先确认回滚针对的是当前设计。
• 在分界线两侧分别运行 git shortlog -sn -- <dir>，检验“团队边界”接缝假设：作者集合互不重叠可作为支持，但不能据此定论；出现相同的名字则会削弱这一假设。
• 对令人意外的代码行运行 git blame，再将其称为瑕疵；它通常有对应的修复提交故事。

简报约定

简报是一张帮助读者自行了解代码的地图，而非代码阅读的替代品——每个概念都必须指向讲解它的文件。按以下顺序提供这些部分；全文引用 path:line 或简短 SHA。

0. 问题与用户——它为谁消除了什么痛点，以及项目有意不做什么（非目标通常会写在 README、文档或早期提交中）。
1. 架构——3-7 个主要组件，以及它们的连接方式（流水线、中心辐射式、分层、插件宿主……）。用一段话加一张简洁示意图或列表说明。
2. 设计风格——作者一贯的选择，每项至少用两个例子佐证：依赖策略、错误处理风格、抽象深度、命名、测试理念、并发模型。风格是反复出现的模式；单个例子只是噪声。
3. 组件与接缝——逐一说明每个组件的职责、输入/输出接缝，以及边界为何设在此处。指出泄漏的接缝（导入方向“有误”）。
4. 历史与理由——列出 3-6 个关键提交/阶段，以及它们揭示的设计缘由（例如：“在 X 之后，于 将存储层切换到接口之后”）。
5. 优美代码——若有证据支持，展示 1-3 段新颖、简洁而清晰，或以少胜多的代码。引用一小段，并准确说明其优点：它保护了什么不变量、合并了哪些情况，或让哪个 API 保持严谨。如果抽样的代码中没有特别突出的部分，就如实说明，不要凭空赞美。
6. 探索线索——项目自己的术语（5-10 个术语 → 定义各术语的文件）、2-3 条适合追踪数据流的流程，以及分析未能解答的开放问题——未解释的接缝、可疑代码、未记录的决策。

说明

• 区分观察与推断：“X 通过 Z 调用 Y”是从代码中读到的事实；“可能是为了便于测试”则是猜测——请标明。
• 如果文档与代码不一致，以代码为准；这种不一致本身也是一项发现。
• 控制时间：对于超过约 100k 行的仓库，根据入口点、追踪的一条流程和历史来撰写简报，并列出未阅读的部分。
• 完整简报最后要说明覆盖范围：检查了哪些内容、抽样或跳过了哪些内容、哪些结论依赖推断，以及是否运行了测试或实际调用。