name: codebase-exploration description: 对代码库进行深度上下文搜索。擅长发现模式、架构、实现，并回答“X在哪里？”、“哪个文件包含Y？”和“查找实现Z功能的代码”等问题。适用于探索不熟悉的代码库、查找特定实现、理解代码组织、发现跨多个文件的模式或在项目中定位功能。支持三种详尽程度：快速、中等、非常彻底。

代码库探索

目的

专门从事系统化的代码库探索和发现。使用高级搜索技术、模式识别和代码分析，快速理解不熟悉的代码、定位特定实现、映射架构模式，并回答有关代码的位置性问题。

何时使用

首次探索不熟悉的代码库
需要查找特定功能的实现位置
在代码库中寻找某种模式的示例
理解组件如何交互
定位特定API或模式的所有使用情况
映射架构组织
在项目中查找相似代码
诸如“X在哪里？”、“哪个文件有Y？”、“查找实现Z功能的代码”等问题

快速开始

在以下情况下调用此技能：

首次探索不熟悉的代码库
需要查找特定功能的实现位置
在代码库中寻找某种模式的示例
理解组件如何交互
诸如“X在哪里？”、“哪个文件有Y？”、“查找实现Z功能的代码”等问题

在以下情况下不要调用：

调试已知错误（使用debugger-skill）
重构代码（使用refactoring-specialist-skill）
审查代码质量（使用code-reviewer-skill）
从头开始编写新代码（使用适当的开发人员技能）

详尽程度级别

快速（快速、粗略概览）

文件结构概览
高级模式匹配
目录组织
主要入口点
~30秒

中等（平衡深度）

详细文件检查
跨文件模式发现
架构映射
常见模式分析
~2-3分钟

非常彻底（深度挖掘）

详尽的代码分析
复杂模式匹配
依赖关系追踪
边缘情况发现
~5-10分钟

决策框架

搜索策略选择

问题类型	搜索策略
“用户认证在哪里？”	搜索认证关键词 + 登录模式
“数据流如何工作？”	查找模型、服务、控制器模式
“哪个文件处理X API？”	搜索端点 + 路由定义
“查找所有数据库查询”	搜索ORM模式、SQL关键词
“定位错误处理”	查找try-catch、错误类

工具选择

工具	最适合	示例
`grep/rg`	文本模式匹配	`rg "function handleAuth"`
`find/fd`	文件名/路径匹配	`fd -e ts auth`
`ast-grep`	代码结构匹配	`ast-grep --pattern "class $NAME"`
LSP工具	符号和引用查找	`lsp_find_references`
`git log`	历史上下文	`git log --name-only`

按问题类型处理

“X在哪里实现？”

按名称搜索X：rg "X|x"
搜索相关术语：rg "related|terms"
检查明显位置：ls src/X/
查看测试：rg "X" tests/

“Y如何工作？”

找到Y的定义
找到Y的用法
追踪流程
理解依赖关系

“哪些文件使用Z？”

搜索Z的导入
使用LSP查找引用
搜索Z被调用的方法

核心能力

搜索策略

基于模式的搜索

通过命名约定查找
通过代码模式定位
通过架构标记发现
通过文件组织识别

上下文感知搜索

理解代码关系
映射依赖关系
追踪执行流程
查找相关组件

多角度发现

按功能搜索
按结构搜索
按命名搜索
按模式搜索

探索工作流

步骤1：定位

我们在寻找什么？
为什么需要它？
需要什么级别的细节？
哪种详尽程度合适？

步骤2：映射结构

识别顶层组织
查找关键标记（入口点、配置文件）
注意目录命名模式

步骤3：执行搜索

选择合适的工具
使用多种搜索角度
记录发现

步骤4：分析与综合

连接线索
识别模式
优先排序发现

最佳实践

先宽后窄

首先：了解整体情况（tree -L 2, ls -la src/）
其次：识别模式（fd -e ts, rg -c "class|function"）
再次：针对特定区域

使用多种搜索角度

按名称搜索：fd auth
按内容搜索：rg "authentication"
按结构搜索：ast-grep --pattern "class $NAME"
按符号搜索：lsp_workspace_symbols

跟随线索

检查导入以查找依赖关系
使用LSP查找引用
查看文件位置以获取架构线索
检查git历史以获取上下文

边探索边记录

# 认证流程
1. 入口：src/middleware/auth.ts
2. 令牌验证：src/services/jwt.service.ts  
3. 用户查找：src/repositories/user.repository.ts
4. 守卫：src/guards/auth.guard.ts

反模式

不要无上下文搜索：首先理解你在寻找什么
不要忽略文件结构：始终检查目录组织
不要依赖单一搜索方法：使用多种方法
不要忘记测试：搜索测试文件以了解实际使用情况
不要跳过配置文件：尽早检查配置

额外资源

详细技术参考：参见REFERENCE.md
代码示例与模式：参见EXAMPLES.md

代码库探索专家Skill codebase-exploration