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)

在每一跳上，说明其持有者（类型/结构体/schema）、所做的变换，以及每一次形状变化或重命名（JSON→struct、字段改名、枚举重映射）。标注跨越的接缝：序列化、队列、进程/网络边界、goroutine/线程交接。收尾时列出被跳过的旁支流程、值得再追一次的出错与边界路径，以及意外之处。若某一跳的原因奇怪，用 git log -S '<symbol>' 或对行执行 blame 抽查历史。

变更考古

只重建某一个特性或决策，而不是整个仓库的年表：

锚定当前概念——找到现存的符号、路径、配置名、测试和用户词汇；先说明它现在做什么，再解释它如何变成这样。
找到它的引入——用 git log -S '<literal>' 找出现与消失，用 git log -G '<regex>' 匹配变更行，用 --follow 跟踪改名文件；也尝试旧名称。
读提交而不只读标题——用 git show 查看引入提交及其父提交；提交正文、测试、被删除的代码和附近的修复都是证据，仅看 diff 只能推断。
拉取评审线索——变更的理由通常比提交信息存活更久，它存在于 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

追踪整条弧线——检查后续修复、重构、回滚，以及对存活行的 blame。

以「先前形态 → 压力/证据 → 引入 → 修正/反转 → 当前形态」的顺序呈现，每个阶段引用 SHA 与路径；收尾给出有支撑的理由、被否决的替代方案、未解决的上下文和历史局限。绝不把提交顺序当作因果关系，也不臆造动机。

完整简报的阅读顺序

自上而下进行；在大仓库上抽样代表性组件，并说明抽样了哪些部分。

定位——README、docs/、顶层目录结构、清单文件（go.mod/package.json/Cargo.toml）、Makefile/CI 配置；找出入口点（main、CLI 命令、服务启动、导出的 API）。若构建和测试成本低，就实际运行——通过测试套件加一次真实调用能为后续一切提供锚点。
在推广之前，先把一条真实流程（一个请求、一条命令、一次构建）端到端追一遍。没有追踪就做出的架构判断通常是错的。
绘制组件与接缝——模块交界处：接口、线上协议、数据库 schema、队列、插件点、进程边界。对每处接缝问「为什么在这里」：可测试性、可替换性、部署边界、团队边界，还是偶然。注明哪一侧拥有类型。
挖掘 git 历史获取理由（命令如下）。先检查历史是否浅克隆、被压缩、导入、生成或充斥 vendor；弱历史只能提供线索而非理由。
在最后、基于已收集的证据评判品味并挑出亮点。

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

按规模和提交信息而非时间新近度寻找「关键变更」：重写、「refactor」、「redesign」、版本号提升提交，以及任何解释权衡的提交。好的项目会把设计文档藏在提交信息里——引用它们。

把「频繁改动 × 修复涉及」交叉比对来选择精读文件。这是线索而非脆弱性的证明：格式化、生成代码和长寿文件都可能主导计数。

回滚是一种可能的负面理由：在用它解释某替代方案为何没存活前，先确认该回滚针对的是当前设计。

用 git shortlog -sn -- <dir> 检验「团队边界」接缝假设：作者集合不相交支持该假设但不构成证明；同一批名字则削弱该假设。

在把某行称为瑕疵前先对意外行做 blame；它往往有一段修复提交的故事。

简报契约

完整简报按以下顺序产出这些章节，全程引用 path:line 或短 SHA：

问题与用户——它消除了什么痛点、为谁消除，以及项目刻意不做什么（非目标常写在 README/docs 或早期提交中）。
架构——3 到 7 个主要组件及其连接形态（流水线、中心辐射、分层、插件宿主等），一段话加一个紧凑图示或列表。
设计品味——作者一贯的选择，每项由两个或更多例子支撑：依赖策略、错误处理风格、抽象深度、命名、测试哲学、并发模型。品味是重复出现的东西；单例只是噪声。
组件与接缝——按组件说明职责、入站/出站接缝，以及边界为何在此处；标出泄漏的接缝（以「错误」方向跨越的导入）。
历史与理由——3 到 6 个关键提交/时期，以及各自揭示了设计为何如此（例如「存储在 after X 时被换到接口之后」）。
优美代码——若证据支持，展示 1 到 3 段新颖、密集而清晰或简洁有力的代码，引用一小段并精确说明好在哪：它保护的不变量、它收敛的情形，或它保持诚实的 API。若抽样代码中没有突出之处，就如实说明，不要制造赞美。
好奇心钩子——项目自己的词汇（5 到 10 个术语 → 定义各自的文件）、2 到 3 条适合做数据流追踪的流程，以及分析未能解决的开放问题：无法解释的接缝、可疑代码、没有文档的决策。

注意事项

把观察与推断分开：「X 经由 Z 调用 Y」是从代码读出的；「大概是为了可测试性」是猜测——给猜测加标注。若文档与代码不一致，代码是真相，而这种不一致本身就是一项发现。对超过约 10 万行的仓库做时间盒控制：依据入口点 + 一条追踪流程 + 历史交付简报，并列出哪些区域未读。完整简报收尾时给出覆盖面：检查了什么、抽样或跳过了什么、哪些结论依赖推断，以及是否运行了测试或一次真实调用。

限制

资料未说明该技能的安装方式、运行环境、收费情况、支持的平台与具体输出格式（除上述章节结构外）。其命令与流程均基于 git、gh 等命令行工具，资料未提供其他依赖或集成信息。