Codebase Domain Map 是一个可移植、可在任意仓库中使用的代码库领域映射技能。其核心目标是在进行任何代码库搜索或探索之前,先通过一个可重新生成的本地快照了解“什么在哪里”,从而避免每次都用 find/grep 重新推导模块地图。
用途:该技能用于大型或不熟悉的仓库中,帮助定位某个功能或领域所在位置、找到某个文件、判断某个应用拥有什么代码。它适用于所有仓库,不仅限于已经存在 .claude/project-snapshot/ 的仓库,也不依赖于项目自身的 CLAUDE.md 或规则是否提到“项目快照”。如果当前仓库缺少快照,正确做法是生成它,而不是跳过该技术。
主要能力:技能维护两个小型文件——.claude/project-snapshot/overview.md 和 .claude/project-snapshot/domains.tsv。overview.md 按项目列出领域和入口点,人类可读;domains.tsv 是扁平的 scope\ttype\tname\tpath 表,便于跨项目按关键词快速 grep。它刻意不提供完整文件列表,因为文件列表容易过时并产生噪声差异,文件级查找可由 glob、rg --files 或 IDE 文件搜索覆盖。该技能将范围缩小到领域/应用/文件夹粒度,不提供行级或符号级结果;在快照指向某个文件夹后,仍需在该文件夹内 grep/read 获取实际内容。
使用方式:通过捆绑脚本生成或刷新快照,脚本适用于 Nx 风格(apps/+libs/)、Go/Rust 风格(cmd/、internal/、crates/)以及扁平仓库,会自动检测存在的容器目录,否则回退到顶层目录。命令为:bash <skill-dir>/scripts/update-project-snapshot.sh(仓库根为 git 顶层或当前目录),或 bash <skill-dir>/scripts/update-project-snapshot.sh /path/to/repo(显式指定根)。在添加新应用/包/领域后应重新运行脚本,因为过时的快照会产生静默假阴性(搜索返回“这里没有”而不是“找错地方了”)。如果团队共享该约定,可提交生成的文件;否则保持本地。
适用场景:在运行 find/grep/Explore 或研究子代理之前,当任务为“找到 X 所在位置”、“哪个应用拥有 Y”、“定位 Z 的文件”时使用。每个调度代理都应使用,而不仅是自己:当把代码库研究委托给子代理时,先自己阅读快照,并将缩小后的领域/路径直接传入子代理的提示中,避免子代理盲目重新推导领域地图。对于单个已知文件路径或小到可以直接读取 ls 输出的仓库,则不需要使用。
限制:快照仅提供文件夹级方向,不提供行级答案;快照需要定期刷新以保持准确;文件列表故意不提供。该技能不涉及功能、收费、价格、平台、效果或使用步骤的额外信息,缺失事实暂未提供。