提示词：陌生代码库导览

适用场景

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

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

模板

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

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

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 启动，它会读文件和回答问题，但不改动代码。