---
title: "探索陌生代码库"
description: "让 Peri 把探索流程打包成 skill——构建一次，以后探索任何项目都只需一句话"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# 探索陌生代码库

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

## 构建 explore-codebase skill

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

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

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

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

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

# 探索陌生代码库

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

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

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

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

## 这套流程在做什么

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

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

## 使用：一句话触发

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

```text
用 explore-codebase 探索这个项目
```

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

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

## skill 放哪里

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

## 不满意就改

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

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

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

## 进阶：improve-codebase-architecture

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

获取方式：

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

用法：

```text
/improve-codebase-architecture
```

## 下一步

- skill 机制本身 → [Skills](/peri-cool/docs/features/skills/)
- 探索完开始干活 → [定位并修复 Bug](/peri-cool/docs/features/fix-bugs/) ｜ [实现新功能](/peri-cool/docs/features/implement-feature/) ｜ [安全重构](/peri-cool/docs/features/refactor-code/)

Source: https://konghayao.github.io/peri-cool/docs/features/explore-codebase/index.mdx