# 提示词：陌生代码库导览

> 刚接手陌生项目时，让智能体按固定顺序读代码，并产出带文件位置的导览文档，帮你在一小时内搞清结构、主流程、测试方式和风险区。

## 适用场景

刚接手一个没人带的老项目，或者要给开源仓库提 PR。你需要的不是「这个项目是做什么的」这种泛泛概述，而是：从哪里进、数据怎么流、怎么跑起来、改哪里最危险。

智能体读代码很快，但如果你只问一句「介绍一下这个项目」，它往往只扫目录和 README 就开始总结，容易说错。下面的提示词强制它按顺序读，并且每个结论都要给出证据位置。

## 模板

```text
我刚接手这个仓库，需要尽快上手。请只读不改：不要修改任何文件，不要安装依赖。

按以下顺序探索，并在每一步引用你读过的具体文件和位置（路径:行号）：

1. 项目定位：阅读 README、包管理文件和配置，说明它是什么、给谁用、技术栈是什么。
2. 运行方式：找出安装、启动、测试、构建的命令，并说明哪些命令是你读到的，哪些只是推测。
3. 入口与主流程：找到程序入口，然后选一条最核心的用户路径（比如一次请求或一次命令执行），
   沿着调用链从头追到尾，画成文字流程图。
4. 数据模型：列出核心数据结构或表，以及它们之间的关系。
5. 目录职责：用一个表格说明每个主要目录的职责，只写你确认过的。
6. 测试与质量：测试框架、测试放在哪里、覆盖了什么、没覆盖什么；有没有 Lint、CI。
7. 风险区：哪些模块耦合最重、最缺测试、最近改动最频繁（可以看 git 历史）；
   第一次改动前我应该先读懂哪几个文件。
8. 术语表：项目里反复出现、但外人看不懂的词。

输出要求：
- 严格区分「已确认」和「推测」，推测要标出来。
- 不要罗列所有文件，只讲对理解整体有帮助的部分。
- 最后给我 3 个适合新人的入门任务，难度从低到高，每个写明需要读哪些文件。
- 如果某一步需要读很多文件，请先交给子智能体去调查，只带回结论。
```

## 怎么用 / 怎么改

- **缩小范围。** 如果你只关心某个子系统，在开头加一句「只关注 `packages/api` 和它依赖的部分」。无边界的探索会读几百个文件，把上下文塞满。
- **先问后查。** 想验证自己的理解时，用提问代替概述，例如「用户登录从哪个文件开始，token 在哪里刷新」。
- **让它写进文件。** 满意以后追加一句「把导览整理成 `docs/ONBOARDING.md`」，下次接手的人能直接用。写文件之前，请你先确认内容没有推测的部分。
- **引用文件更省事。** 在支持 `@` 引用的环境里，直接写 `@src/utils/auth.js` 能把文件内容带进对话，不用等它再去读一遍。
- **打开版本历史。** 对「为什么这里这么奇怪」类问题，指定让它查 `git log` 与 blame，答案往往在提交说明里。

## 常见问题或注意事项

- **它说得头头是道，但文件根本不存在。** 这就是要求「路径:行号」的原因。随机抽三条核对，不对就让它重做，并强调「只写读过的内容」。
- **项目没有 README。** 这很常见。把第 1 步改为「从包管理文件、入口文件和目录名推断项目定位，并标明是推断」。
- **导览太长没人看。** 限定篇幅，比如「全文不超过 80 行」，并要求把次要信息放到附录。
- **提示词里的「只读不改」。** 不同工具对只读模式的支持不一样。Claude Code 可以用计划模式（Plan Mode）：按 Shift+Tab 切换，或者用 `claude --permission-mode plan` 启动，它会读文件和回答问题，但不改动代码。