codebase-search

代码库搜索

何时使用此技能

• 主要任务是在编辑前浏览代码库。
• 用户需要查找定义、调用位置、入口、配置归属、测试、模板、内容引用或可能的影响范围。
• 代码库足够大，随机阅读文件会浪费时间。
• 请求本质上是在问**“这部分在哪里／什么在使用它／我应该先检查什么？”**，即使用户从未提到“搜索”。
• 代码库可能包含应用代码、基础设施／配置、内容／模板，或游戏工具／资源，第一步仍然是探索。

以下情况不要将此技能作为主要工作流：

• 用户已找到相关区域，现在需要根因诊断 → 使用 debugging 或 log-analysis。
• 用户需要保持行为不变的清理或迁移计划 → 使用 code-refactoring。
• 用户需要对具体差异／PR 进行评估 → 使用 code-review。
• 用户需要持久化的全代码库或混合语料结构图 → 使用 graphify。

核心理念

codebase-search 应像数据包路由器，而不是冗长的搜索教程。

1. 将请求归一化为一个主要数据包。
2. 在输出匹配结果前缩小范围。
3. 只阅读最终选出的文件。
4. 返回精简的证据图。
5. 只要搜索不再是瓶颈，就立即转交其他技能。

选择数据包前，请先阅读以下支持文档：

• references/intake-packets-and-route-outs.md
• references/search-modes.md
• references/evidence-map-template.md
• references/handoff-boundaries.md

说明

步骤 1：归一化请求

首先将提示词转换为以下接收格式：

codebase_search_packet:
  primary_packet: exact-text | symbol-indexed | structural | config-content | hosted-search | graph-path
  repo_shape: app | infra | content | game | mixed | unknown
  search_goal: locate | references | ownership | impact | archaeology | unknown
  scope_hint: path | package | file-type | subsystem | repo-wide | unknown
  route_after: stay-here | debugging | log-analysis | code-refactoring | code-review | graphify

为本次运行选择一个主要数据包。如果两个数据包都看似合适，就选成本较低、能最快减少不确定性的那个。

步骤 2：选择数据包

数据包	使用场景	最适用情况	常用工具／形式
exact-text	用户知道某个字符串、环境变量、路由、标志、类名拼写、错误文本或文件片段	字面查找、配置键、路由路径、导入名称	rg、git grep、编辑器搜索
symbol-indexed	用户需要查找定义、引用或调用位置	函数／类／接口归属、API 跟踪、单体代码库导航	LSP／工作区符号、ctags、索引代码库搜索
structural	语法结构比字面文本更重要	查找缺少的清理操作、不安全模式清单、迁移准备	ast-grep、Semgrep、Comby、tree-sitter 风格搜索
config-content	代码库涉及配置、内容、模板、前置元数据、短代码、场景、资源或构建脚本	Terraform／Kubernetes、Markdown／MDX 网站、Hugo／Next 内容、游戏打包／配置	文件发现 + 字面搜索 + 定向脚本
hosted-search	代码库位于远程／以浏览器为主，或需要跨代码库查找	PR 溯源、无法在本地访问的代码库、可分享链接	GitHub／GitLab 托管搜索
graph-path	请求本质上涉及依赖跟踪或持久化结构	调用图、路径跟踪、架构图、图报告	graphify、代码图／代码地图工具

数据包选择规则：

• 用户已经提供具体词条时，优先选择 exact-text。
• 对于“在哪里定义／引用？”这类问题，优先选择 symbol-indexed。
• 只有正则表达式过于宽泛时，才选择 structural。
• 实际目标不是经典源代码时，优先选择 config-content。
• 缺少本地上下文时，优先选择 hosted-search。
• 只有普通搜索不够用时，才选择 graph-path。

对于明确要求使用 Jevgrep 搜索指定范围内源文档的请求，请遵循 jevgrep，遵守其单独的远程内容／成本门槛，并进行有界探索。 exact-text、LSP／索引搜索、结构搜索和现有 zvec 路径仍是默认且权威的方式；这个可选路径不会取代图查询。

第 3 步：阅读所有内容前先缩小范围

读取文件前，至少采用一种缩小范围的方法：

• 按目录或软件包限制范围
• 按文件类型限制范围
• 将自编写文件与生成文件／供应商目录分开
• 从入口点、加载器、配置架构、测试、示例或构建脚本开始
• 对于内容／游戏仓库，先搜索元数据和模板／资源相关内容，再判断答案是否由代码决定

根据仓库类型采用的实用启发：

• 应用 → 从入口点、路由器／处理程序、配置加载器、测试开始
• 基础设施 → 从模块／叠加层／根配置、变量／架构、部署相关内容开始
• 内容 → 从内容文件夹、前置元数据键、局部模板／包含项／短代码／模板开始
• 游戏 → 从运行时代码、引擎配置、场景／资源／构建脚本、编辑器／可视化图表引用开始

第 4 步：阅读关键文件，而非整个匹配列表

搜索结果返回匹配项后：

1. 选出最可能定义功能或决定归属的文件
2. 选出 1–3 个重要的使用方或引用
3. 设置相关时，选出 1 个配置／测试／示例／构建文件
4. 总结流程，而非粘贴原始终端输出

第 5 步：提供证据图

默认响应格式：

## Search brief
- Goal: [what I was locating]
- Packet: exact-text | symbol-indexed | structural | config-content | hosted-search | graph-path
- Scope: [paths/file types/packages]

## Best entry points
- `path/to/file`: why it matters
- `path/to/other-file`: why it matters

## Key evidence
- `path:line` — what it shows
- `path:line` — how it connects

## Likely flow / ownership
- entry → consumer → config/test/content surface

## Next route-out
- stay in `codebase-search` or route to the next skill

第 6 步：采用与搜索包对应的启发方法

对于 Bug 定位请求

• 从错误字符串、路由、标志或近期变更标记开始
• 找到定义和信号最强的使用方
• 映射出可能的故障路径后，切换到 debugging

对于影响分析

• 先看定义
• 再看主要使用方
• 最后看测试／配置／文档／内容相关部分
• 区分必须更新和可能受影响
• 用户准备调整行为保持型结构时，转到 code-refactoring

对于配置／内容归属

• 先找加载器／架构／模板
• 然后查找运行时使用方或引用的页面／资源
• 说明归属在配置、内容元数据、模板还是代码中

对于结构化搜索

• 用通俗语言说明搜索方式
• 优先使用 AST 感知工具
• 如果不得不使用正则表达式近似搜索，明确说明置信度限制

对于考古式探索请求

• 从入口点、文档、示例、测试或构建脚本开始
• 不要仅凭一次搜索就假装已经了解架构
• 如果用户确实需要持久化的结构映射，则转到 graphify

第 7 步：积极转交给其他工具

如果下一步工作已不再是搜索，则切换工具：

• 根本原因、复现、假设 → debugging
• 原始日志分诊 → log-analysis
• 行为保持型清理／代码改写规划 → code-refactoring
• 差异／PR 评审 → code-review
• 持久化架构图或路径追踪 → graphify

示例

示例 1：变更前探索

提示词：

找出身份验证的实现位置，以及更改前应该检查哪些文件。

理想响应格式：

• 选择 symbol-indexed 或 exact-text
• 找出入口点、配置和测试
• 提供简洁的证据图
• 仅在完成探索步骤后，才转到 code-refactoring 或 debugging

示例 2：配置／内容归属

提示词：

哪些 MDX 页面仍在使用旧版定价 CTA 短代码？共享局部模板定义在哪里？

理想响应格式：

• 选择 config-content
• 搜索内容元数据和短代码／模板相关部分
• 找出源局部模板和受影响页面
• 以探索为先

示例 3：结构化查询

提示词：

找出所有缺少清理逻辑的 React effect。我不想用普通 grep。

理想响应格式：

• 选择 structural
• 优先采用 AST 感知匹配
• 列出置信度最高的命中项
• 如需回退到正则表达式搜索，说明其局限

示例 4：游戏／基础设施考古

提示词：

搜索此代码库，查找匹配区域配置的定义位置，以及哪些场景或服务会使用它。

良好回复的结构：

• 根据代码库的结构选择 config-content 或 symbol-indexed
• 将配置归属与运行时使用方分开说明
• 如果代码和资源／构建相关界面都很重要，需一并指出

最佳实践

1. 选择能够回答问题的最小数据包。
2. 在读取大量匹配结果前先缩小范围。
3. 返回证据图谱，而非终端记录。
4. 如实覆盖配置／内容／游戏相关界面；代码库导航不只是查找源代码。
5. 将搜索与诊断、重构、审查和持久化图谱构建分开。
6. 使用纯文本搜索近似判断结构意图时，标注置信度。
7. 对于单体代码库，按包或子系统对发现结果分组。

参考资料

• references/intake-packets-and-route-outs.md
• references/search-modes.md
• references/evidence-map-template.md
• references/handoff-boundaries.md
• GitHub Code Search 语法文档：https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax
• Sourcegraph 代码搜索文档：https://sourcegraph.com/docs/code_search
• ast-grep 简介：https://ast-grep.github.io/guide/introduction.html
• ripgrep 指南：https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md