codebase-domain-map

代码库领域地图

概览

这是一个位于仓库本地、可重新生成的“内容分布”快照——.claude/project-snapshot/ 下的两个小文件，让你一眼了解领域和文件夹级别的布局，而不必每次都用 find/grep 重新推导模块地图。先阅读它，缩小要查找的范围，然后在这个范围内使用常规搜索工具，找到具体行级答案。

适用于你工作的每个代码库——不只是已经有 .claude/project-snapshot/ 的代码库，也不受任何单个项目自己的 CLAUDE.md/规则中关于“项目快照”的说明影响。 项目自己的规则可能会要求读取该项目已有的同名快照——这项项目本地说明只是这一通用、可移植技术的一个实例，并非全部。这项技能是另一项独立且长期适用的内容：它适用于任何代码库，包括完全没有此类规则的代码库。如果当前代码库中缺少快照，正确做法是生成它（见下方“设置”），绝不能因为没有项目本地规则要求你使用它，就跳过这项技术。

警示信号——切勿跳过

想法	事实
“这个项目有一条关于其他代码库的‘项目快照’规则，所以这个概念不适用于这里”	那条规则和这项技能不是一回事——这项技能是一种可用于任何代码库的可移植技术，无论是否存在相应的项目规则。不要因为项目规则名称相似，就认为它可以代替检查这项技能是否适用
“这里没有 .claude/project-snapshot/，所以我用不了”	缺少就生成，而不是跳过——这正是附带脚本的用途
“这是别人的／不熟悉的代码库，不是我的”	不熟悉的代码库恰恰是这项技术的适用场景——熟悉代码库并非前提
“现在直接 grep 更快”	设置只需运行一个脚本；对于文件数量超过寥寥几个的代码库，跳过设置、盲目 grep 反而更慢，而且这本来就是新 Agent 默认会采用的做法——这正是这项技能要防止的问题

**它能缩小和不能缩小的范围：**仅限领域／应用／文件夹粒度——不提供行级或符号级结果。快照指出某个文件夹后，仍需在其中 grep／阅读，才能找到实际内容。

使用时机

• 在使用 find/grep/Explore/研究子 Agent 之前，只要任务是“查找 X 在哪里”“哪个应用负责 Y”或“定位 Z 的文件”。
• **每个负责分派任务的 Agent 都要使用，不只是你自己：**将代码库研究工作委派给子 Agent 时，先自行阅读快照，再把缩小后的领域／路径直接写进子 Agent 的提示词中（例如：“auth 领域：backend — apps/api/src/app/auth，frontend — apps/web/src/pages/auth”）。如果子 Agent 的提示词只说“查找 X 的代码”，却没有先通过快照缩小范围，就会让子 Agent 盲目地重新推导你本来可以直接获得的领域地图。
• 对于明确已知的单个文件路径，或小到可以直接阅读 ls 输出的代码库，则无需使用。

文件

• .claude/project-snapshot/overview.md — 各项目的领域列表和入口，便于人类阅读。
• .claude/project-snapshot/domains.tsv — 扁平的 scope\ttype\tname\tpath 表；可一次性跨所有项目用 grep 搜索关键词，速度最快。

这里特意不提供完整的文件列表：它很快就会过时，也会产生大量无关差异；文件级查找可通过 glob、rg --files 或 IDE 的文件搜索完成。

设置 / 刷新

通过随附脚本生成或刷新 — 适用于 Nx 风格（apps/+libs/）、Go/Rust 风格（cmd/、internal/、crates/）以及扁平仓库；脚本会自动检测存在的容器目录，否则回退到顶层目录：

bash <skill-dir>/scripts/update-project-snapshot.sh          # repo root = git toplevel (or cwd)
bash <skill-dir>/scripts/update-project-snapshot.sh /path/to/repo   # explicit root

添加新的应用/软件包/领域后，请重新运行脚本 — 缺少新领域的过时快照，比没有快照更糟（会悄无声息地造成误报：搜索结果显示“这里什么都没有”，而不是“找错地方了”）。如果团队共享这一约定，请提交生成的文件；否则将它们保留在本地。

常见错误

错误	修正方法
检查快照前先对整个仓库进行 Grep	先阅读 overview.md / grep domains.tsv — 这只是一个文件，不是一次搜索
调度研究子 Agent，只说“查找 X”，却不限定路径	自己先阅读快照，再将确认的领域/路径传入子 Agent 的提示词
把快照当作逐行搜索	快照只精确到文件夹级别 — 仍需在缩小范围后的文件夹中进行 grep/阅读，才能找到真正答案
添加新应用/领域后从不重新生成	重新运行脚本 — 过时快照会造成误报，而不只是内容过时