explain-repo

解释仓库

这项技能会将代码仓库转化为一份地图集——一组可导航的 HTML 章节，开发者可以打开它们，深入理解代码库并继续开发；此外，还会生成一份提炼后的 SUMMARY.md，用于启动后续的 Agent 会话。

地图集中的所有内容都有依据：每项说法都注明其来源文件、提交或问题，否则就删除。这是这项技能的根本准则——有据可引，无据删去。切勿凭参数化猜测，描述这类代码「通常」会怎样运行。先阅读，再引用。最容易凭空杜撰的两个章节——历史和优缺点——会在第 5 步进行对抗式反驳检查，原因正是如此。

地图集存放在目标仓库中的 .repo-atlas/ 下，并加入 git 忽略列表，不会弄脏工作区；同时会记录生成时对应的截至提交，以便代码发生变化时刷新。

请按顺序执行各步骤。每一步都有完成标准——未达成前不要继续。

地图集工作区

分为两层，分别对应实际项目和项目的地图。

呈现层——开发者打开的内容（HTML），位于 .repo-atlas/ 下。

• index.html：仪表板。开发者打开的唯一页面——左侧菜单列出章节、参考资料和基础文档，另有一行新鲜度信息；当前章节显示在内容区域。整个侧边栏由文件中的 NAV 对象驱动（参见仪表板）。基于 templates/dashboard.html 构建。
• assets/：共享的 style.css 和 md.js（离线 Markdown 渲染器）。设置时从此技能的 assets/ 复制一次，此后每份地图集都不得手动修改。
• brief.html、glossary.html、sources.html：基础文档。基于 templates/doc.html 构建；内容为遵循 BRIEF-FORMAT.md、GLOSSARY-FORMAT.md、SOURCES-FORMAT.md 的 Markdown。
• chapters/*.html：地图集正文。仓库的每个区域对应一个独立的章节，章节目录见 CHAPTERS.md。基于 templates/chapter.html 构建。文件命名为 0001-<dash-case-name>.html，数字依次递增。
• reference/*.html：信息密集、便于速查的参考文档（目录结构图、命令参考、关键文件索引）。基于 templates/reference.html 构建。

状态层——你的工作记忆，开发者不会打开（Markdown），位于 .repo-atlas/ 下。

• findings/*.md：经过验证的仓库事实，以及章节背后尚未解决的问题——你的证据台账。命名为 0001-<slug>.md。使用 FINDING-FORMAT.md。
• SUMMARY.md：提炼后的 Agent 启动文件。遵循 SUMMARY-FORMAT.md。
• .atlas-meta.json：{ asOf, repoRemote, chapters }——用于刷新流程的截至时间戳。
• NOTES.md：用于记录偏好和工作笔记的草稿区。

Markdown 是唯一事实来源

对于基础文档（brief、glossary、sources），Markdown 存放在 HTML 内的 <script type="text/markdown"> 块中（参见 templates/doc.html）。编辑时，只修改该块；读取文档状态时，也只读取该块。由 md.js 负责渲染，无需单独的 .md 文件，也无需重复维护。状态文档（findings/、SUMMARY.md、NOTES.md）保持为纯 .md 文件——开发者不会打开它们，因此不要用 HTML 包装。

步骤 1 — 设置工作区

确定目标仓库（默认使用当前仓库；否则询问路径）。然后从仓库根目录开始：

1. 创建 .repo-atlas/ 并确保将其加入忽略列表——把 .repo-atlas/ 添加到 .gitignore（如果文件不存在则创建）。如果目标不是 Git 仓库，请说明这一点：届时无法获取历史记录和新鲜度信息，并询问是否继续。
2. 将此技能的 assets/ 复制到 .repo-atlas/assets/。
3. 将 templates/dashboard.html 复制到 .repo-atlas/index.html，并根据 templates/doc.html 创建 brief.html、glossary.html、sources.html。
4. 在首次写入文件时，按需创建 chapters/、reference/、findings/。

完成标准：.repo-atlas/ 已存在并已加入 Git 忽略列表，其中包含 assets/ 和一个仪表板，且三份基础文档均已创建（可以为空）。

步骤 2 — 初步勘察并撰写简介

进行一次成本低、覆盖面广的初步勘察——暂时不要深入阅读：

• 布局：目录树（限制深度）、入口点、README、CONTRIBUTING。
• 技术栈：清单和锁定文件、Dockerfile、CI 配置文件（确认其是否存在及文件名）。
• Git：git log --reverse | head、标签、git shortlog -sne（如果不是 Git 仓库则跳过）。
• 远程源：git remote get-url origin——记录其地址，以及仓库是否为公开仓库（Contributing 章节取决于此；如果有 gh 且远程仓库是公开的，则纳入该章节，否则不纳入）。

利用初步勘察完成两件事：

1. 围绕简介进行访谈——开发者为何要研究此仓库，以及他们将要做什么（熟悉项目、修复错误、添加功能、审计、接手）？此外，还要了解他们对技术栈的熟悉程度，以此调整讲解深度。问题控制在几个以内。按照 BRIEF-FORMAT.md 编写 brief.html。简介决定哪些章节需要深入调查。
2. 列出功能模块——值得深入调查的重要子系统。对于大型仓库，按规模和变更频率选取排名靠前的模块进行深入调查，并在 NOTES.md 和简介中记录跳过的内容——绝不静默截断。

**完成标准：**已编写 brief.html，已确认仓库是公开还是私有，并已记录待调查模块列表（以及任何跳过的内容）。

步骤 3 — 调查

现在阅读 CHAPTERS.md——其中包含章节骨架和逐章调查指南（应阅读和引用的内容）。选择简介要求的章节。

分头调查：每章（或每个功能模块）启动一个子 Agent，仅调查其负责的部分，并返回一份结构化的调查结果（FINDING-FORMAT.md）以及一份 Markdown 章节草稿。这样可以避免在主上下文中进行大量阅读。对子 Agent 的指令应包含该章节的调查指南和引用或删去原则：每项声明都必须附带 path:line、提交 SHA 或议题／PR 编号，并标记为已观察（直接阅读所得）或推断（推导所得）。

**完成标准：**每个纳入范围的章节都有一份调查结果，其中每项声明均附有引用并标记为已观察或推断。

第 4 步 — 汇编

将调查结果整理成图谱：

• 根据 templates/chapter.html 编写每个 chapters/NNNN-*.html，并将引文渲染为指向真实源文件的链接——显示为可读文本 src/foo.ts:42，同时也是相对路径 <a href="../../src/foo.ts">（章节和参考文档位于仓库根目录下两级；根目录下的基础文档则使用 ../）。如果远程地址是网页 URL，则将提交链接到 <remote>/commit/<sha>；否则显示纯 SHA。
• 维护 glossary.html（仓库和领域术语，参见 GLOSSARY-FORMAT.md）以及 sources.html（仓库、其文档、技术栈文档，以及对于公开仓库的议题跟踪器和社区，参见 SOURCES-FORMAT.md）。
• 将每个章节和参考文档添加到 index.html 中的 NAV（参见仪表板）。

**完成标准：**所有范围内的章节都能在仪表板中呈现，且源文件链接可正常使用；词汇表和来源列表均已填充。

第 5 步 — 证伪

对最容易出现臆测的两个章节——历史和优缺点——进行对抗性审查。启动一个持怀疑态度的子 Agent，要求它依据实际代码和 git 证伪每项主张；证据不足时，默认判定为“不支持”。将无法找到依据的内容删除或降级为推断。没有引文证据的缺点不得收录。

**完成标准：**历史和优缺点中的每项主张，都有经审查者认可的引文依据，或已被删除。

第 6 步 — 提炼并盖章

1. 按照 SUMMARY-FORMAT.md 编写 SUMMARY.md——这是一份内容精炼、便于解析的文件，供后续 Agent 快速了解项目。它是对调查结果的提炼，而不是新的调查。
2. 编写 .atlas-meta.json，记录截至提交（git rev-parse HEAD）、远程地址和章节列表。在仪表板的新鲜度行中显示截至提交。
3. 提议将 SUMMARY.md 复制到仓库的 CLAUDE.md 中（追加或初始化）——只需提议，绝不自动执行。
4. 如果有可用的 CLI 打开命令，则为开发者打开仪表板（.repo-atlas/index.html）。

完成标准：SUMMARY.md 和 .atlas-meta.json 均已创建；仪表板显示截至提交；并已告知开发者仪表板的位置。

刷新图谱

如果图谱已经存在，再次运行时应进行有针对性的更新，而不是重建。读取 .atlas-meta.json 中的截至提交，运行 git diff <asOf>..HEAD --stat，并将变更路径对应到相关章节。仅在 NAV 中将这些章节标记为过时（仪表板会显示数量），只重新调查这些章节（针对对应部分执行第 3–5 步），然后重新盖章更新 .atlas-meta.json。未受影响的章节保持不变。

仪表板

仪表板是开发者的主界面。其侧边栏和新鲜度行完全由 index.html 中的 NAV 对象驱动——绝不要手动编辑侧边栏标记。创建或刷新任何内容后，都要更新 NAV：

• 新增章节 → 将 { n, href, title, stale: false } 追加到 NAV.chapters，并将 NAV.current 指向该章节。
• 新增参考文档 → 将 { href, title } 追加到 NAV.reference。
• 刷新时章节变为过时 → 将其设置为 stale: true；重新调查后清除此标记。
• 截至提交发生变化 → 更新 NAV.asOf。

图表

默认使用围栏代码块中的 ASCII 方框图——无需依赖、打印效果好，并且与离线 file:// 图谱保持一致。值得绘制的图表包括架构图（模块映射）、CI/CD 图（流水线）和一张端到端流程图。只有开发者提出要求时，才引入 mermaid 这类渲染器。