exploring-codebases

探索代码库

针对不熟悉的仓库进行探索性代码分析。对本地副本执行结构分析（tree-sitting）和语义分析（featuring）。

工作流

按顺序执行以下五个步骤。不要跳过步骤 0。

0. 设置（每个会话一次）

uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter --python /home/claude/.venv/bin/python
export PYTHON=/home/claude/.venv/bin/python
export TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
export GATHER=/mnt/skills/user/featuring/scripts/gather.py

如果步骤 2 的 --stats 在一个你知道包含代码的仓库中报告 Symbols: 0，说明尚未安装 tree-sitter 核心软件包——请返回此处安装（该引擎自带语法，不使用 tree-sitter-language-pack）。 在这种情况下，Treesit 会以状态码 0 退出且不输出错误，因此零符号是你能得到的唯一信号。这里不会出现 Errors: 行：该行仅在解析失败时出现，而缺少解析器时不会进入解析阶段。完整说明见 tree-sitting 技能的 Setup 部分。

1. 获取仓库（使用 tarball，而非逐个文件获取）

OWNER=...
REPO=...
REF=main                    # branch name, tag, or SHA. For a PR: pull/N/head
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/tarball/$REF" -o /tmp/$REPO.tar.gz
mkdir -p /tmp/$REPO && tar -xzf /tmp/$REPO.tar.gz -C /tmp/$REPO --strip-components=1
ls /tmp/$REPO | head        # sanity check — did extraction land?

一次 HTTP 调用即可获取整个仓库。不要先用 curl 获取 README、用 cat 查看文件，或通过 contents/PATH 获取内容——这些都在 tarball 中。仅私有仓库需要 Authorization 标头；公开仓库无需此标头也能正常使用。

选择 ref 很重要。 如果要探索功能分支、PR 或标签，请相应设置 REF。如果问题涉及尚未合并的分支，默认的 main 会悄无声息地提供过时的代码。

2. 结构扫描

$PYTHON $TREESIT /tmp/$REPO --stats

阅读输出。它会提供文件数、符号数、语言以及各目录的符号密度。这就是用于了解仓库的主要产物——应将其视为此步骤的成果，而非热身。

只有在有具体问题时才深入查看。 如果只是想了解“这个仓库是什么”，就跳过深入查看，进入步骤 3——featuring 会为你呈现有趣的路径。用户询问某个特定子系统，或步骤 3 的输出引出了需要查看源代码的问题时，再深入查看。

需要深入查看时，在一次调用中批量查询。 每次 treesit 调用都要支付完整扫描的开销。在同一命令中添加多个查询会共享扫描，每增加一个查询所需时间约为 0 毫秒。如果你准备对同一路径进行第二次 treesit 调用，就把它合并到第一次调用中。

# GOOD — one scan, three answers
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full \
  'find:*Handler*:function' 'source:main' 'refs:Config'

# BAD — three scans, three answers (3× the cost for the same information)
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full
$PYTHON $TREESIT /tmp/$REPO 'find:*Handler*:function'
$PYTHON $TREESIT /tmp/$REPO 'refs:Config'

3. 功能综合

运行前，先根据交付内容选择模式。

你的交付内容	命令	大小
自己理解代码库——审查、概览或回答问题	--orient	约 115 行
必须引用每个符号的 _FEATURES.md 文档	完整输出	数千行

# Default. Complexity assessment, decomposition ranking, directory tree, entry points.
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --orient

# Only when you are about to WRITE the inventory into a file:
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --source-budget 8000

输出顶部附近会有一个“按符号密度列出的子文件候选区域”列表——这是用于挑选深入查看目标的排序列表。

绝不要将完整输出通过管道传给 head。 如果你准备截断输出，就说明应该选择 --orient 模式，而你已经为不会阅读的数千行付出了代价。有一次审查的完整采集结果达到 5,697 行，却在第 120 行处被截断；其中的每项发现其实都来自 treesit 深入查询和定向阅读。--orient 会返回实际会用到的约 115 行。完整模式的符号清单是用来引用的，不是用来阅读的。

4. 根据组合输出进行推理

综合步骤 2 和 3 的结果：能力、功能分组、架构、入口点和异常情况。必要时生成 _FEATURES.md。这是 LLM 负责的步骤；此前的所有步骤都是机械操作。

何时使用此技能，而非其他技能

情况	使用
“我刚克隆了这个项目，它是什么？”	exploring-codebases（此技能）
“重试逻辑在哪里？”	searching-codebases
“查找所有匹配 class.*Error 的文件”	searching-codebases
“列出 auth.py 中的符号”	直接使用 tree-sitting
“哪些文件主要涉及 CSRF / sessions / queryset filtering？”	bm25
“按与多词概念的相关性为这些文档排序”	bm25
“记录这个代码库的功能”	直接使用 featuring
“教我这个代码库”（人类正在学习）	orienting-codebases
“帮我获取这个仓库”——只获取，不分析	accessing-github-repos, cloning-project

探索是发散型技能——你还不知道要找什么。搜索是收敛型技能——你知道自己想要什么。

orienting-codebases 使用相同的 tree-sitting + featuring 流程，是目录中最接近此技能的技能。两者的区别在于受众：此技能帮助 Claude 建立理解，以便继续开展工作；另一项技能则通过引导式练习和 HTML 产物帮助用户理解代码库。如果没有人在学习，应该使用此技能。

在此工作流中配合使用 bm25

步骤 2–3 大致呈现出仓库的结构后，如果你想要按相关性排序的内容搜索，而不仅是 grep 和精确符号查找，bm25 就是合适的补充。它会根据词汇与多词查询的相关性为文件排序，适用于“搜索 X 时，这个代码库实际上是关于什么的？”这类问题——尤其是当你还不知道要传给 tree-sitting 的符号名称时。

BM25=/mnt/skills/user/bm25/scripts/bm25.py

# Pass multiple queries — index builds once, all queries reuse it
python3 $BM25 /tmp/$REPO 'auth flow' 'session backend' 'middleware pipeline' \
  --exclude 'tests/*' --exclude '*/tests/*' --top-k 5

以下两种配合方式尤其有效：

1. bm25 → tree-sitting。 使用 bm25 查找与某个概念相关性最高的文件，然后用 tree-sitting source:Symbol:path/to/file.py 阅读实际实现。
2. 使用 --exclude 'tests/*' 配合 bm25。 测试目录往往会主导关键词查询结果，因为测试名称会重复提及领域术语。预先排除这些目录，就能直接找到实现文件。

bm25 与语料库无关——如果你的探索涉及文档、转录文本或 PDF，它也适用于 project 知识库或 uploads/。

委派给子 Agent

仅当仓库规模较大（超过 1000 个文件或包含多个不同子系统）并且当前环境提供子 Agent 工具（Claude Code 和 CCotw 中的 Agent/Task）时才使用。Claude.ai 聊天和单独运行的技能都不提供此工具：直接内联执行步骤 2–4，并跳过本节。工具不可用时，绝不要通过其他方式模拟并行分派。

无论如何，步骤 2–3 都应内联执行。只有步骤 4 的判断工作需要分派，每个子系统分配一个 Agent；子 Agent 不会继承任何内容——既不会继承对话，也不会继承此文件，更不会知道扫描产物已在磁盘上。编写第一个 Agent 提示词前，请先阅读 references/subagent-delegation.md；该文件说明每个提示词必须包含的四项内容，以及缺少这些内容时会发生什么。

备注

• 大型仓库（超过 100 个文件）：在步骤 2 中使用 --skip tests,vendored,docs,... 聚焦扫描范围。
• Monorepo：将每个包/服务视为独立的探索对象。为每个子系统生成 _FEATURES.md 文件，并从根索引链接到这些文件。
• 深入检查的启发式方法（如果步骤 2 值得深入检查）：符号与文件比例较高的目录（逻辑密集）、入口名称（main、cli、app、server、routes）、导入较多的文件（集成点）。