Skip to content
台灯与工作台

探索陌生代码库

探索陌生代码库不是一次性的任务：你每接手一个新项目、每进入一个新模块，都要做一遍同样的事——先确认项目能跑，再画架构地图，顺着业务链路深入，最后把结论沉淀下来。这套流程是固定的，所以值得打包成一个 skill：让 Peri 构建一次，以后探索任何项目，一句话就触发整套流程。

构建 explore-codebase skill

Section titled “构建 explore-codebase skill”

把流程描述给 Peri，它会生成 skill 文件：

帮我构建一个探索代码库的 skill，命名 explore-codebase，
保存到 ~/.claude/skills/explore-codebase/（用户级，所有项目都能用）。


流程要求：
1. 先读 README 和 CLAUDE.md，跑构建和测试，报告基线状态
2. 从外到内画架构地图：目录职责、入口文件、模块依赖、数据流
3. 顺着一条业务链路深入，每个环节给出函数名和文件路径
4. 把探索结论沉淀成笔记
5. 每个结论都要带文件路径和行号

Peri 会在 ~/.claude/skills/explore-codebase/SKILL.md 创建一份文档，内容类似这样：

---
name: explore-codebase
description: 探索陌生代码库时使用。用户接手新项目、理解陌生模块、
  或要求画架构地图时触发。
---


# 探索陌生代码库


按以下顺序探索，每个结论都附上证据（文件路径:行号）：


1. **基线**：读 README 和 CLAUDE.md，跑构建和测试，报告项目状态
2. **地图**：从外到内画架构地图——目录职责、入口文件、模块依赖、数据流
3. **链路**：顺着一条业务链路深入（请求/数据/功能），
   每个环节给出函数名和文件路径
4. **沉淀**：把结论整理进 CLAUDE.md 或 NOTES.md


代码库很大时，按模块边界并行派探索子代理，最后汇总成总地图。
结束时总结：已覆盖哪些模块、哪些还没看、建议下一步探索什么。

skill 就是一份 Markdown 文档——name 是它的名字，description 是触发条件（Peri 靠它判断什么时候该用这个 skill），正文是行为规则。构建前如果对流程有自己的想法，先让 Peri 列出流程方案，你确认后它再写入文件。

这套流程在做什么

Section titled “这套流程在做什么”

构建时不用照抄上面的流程，理解每一步的目的后可以按自己的习惯改：

  • 先跑基线：构建和测试都过不了的话，读代码时会反复遇到”这段逻辑可能已经坏了”的干扰，无法判断问题是代码本身的还是自己理解错了
  • 画地图：入口告诉你”世界从哪开始”，目录告诉你”世界分成几块”，数据流告诉你”几块之间怎么连接”。地图阶段理解偏了，后面所有深入探索都会跟着偏
  • 追链路：链路是一个完整的业务动作——一个请求从入口到响应、一条数据从写入到被消费。追链路能强制你理解模块之间的接口（谁在什么时机调用谁），比零散读代码高效得多
  • 沉淀笔记：探索结论不写下来，一周后等于没探索。写进 CLAUDE.md 后，Peri 每次打开项目自动加载，下次直接说”继续做 XXX”就能带着地图工作

使用：一句话触发

Section titled “使用：一句话触发”

skill 构建完成后，探索任何项目只需要一句话：

用 explore-codebase 探索这个项目

Peri 会加载这个 skill，按里面的流程自动执行，不用再复述需求。即使不提 skill 的名字，直接说”帮我看懂这个项目”这类探索任务，Peri 也会根据 description 自动匹配并加载它。

注意：新构建的 skill 在下次启动会话时才会被扫描到。当前会话想立即用，直接描述”按探索流程走”也行，Peri 会照做。

skill 放哪里

Section titled “skill 放哪里”
  • 项目级 .claude/skills/：只对这个项目生效，适合内容里包含该项目特定信息的 skill
  • 用户级 ~/.claude/skills/：所有项目都能用。探索陌生代码库是通用流程，建议放这里——在任意项目里都能直接调用

不满意就改

Section titled “不满意就改”

流程不适合你的习惯？skill 是普通 Markdown 文件，直接让 Peri 改：

explore-codebase skill 的第 2 步改一下：地图阶段先输出目录树，
再逐层说明职责，最后才画数据流

改动即时生效，下次调用就是新流程。

进阶：improve-codebase-architecture

Section titled “进阶：improve-codebase-architecture”

项目已经熟悉、想评估架构质量时，可以用 improve-codebase-architecture（mattpocock/skills 生态）：扫描模块职责、依赖关系和设计模式，把值得深入改进的候选整理成可视化报告，再逐一讨论。它适合已熟悉的项目，不是首次探索的工具。

获取方式：

Terminal window
npx skills add https://github.com/konghayao/peri --skill improve-codebase-architecture

用法：

/improve-codebase-architecture

下一步

Section titled “下一步”