codebase-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Search

代码库搜索

When to use this skill

何时使用此技能

Finding specific functions or classes
Tracing function calls and dependencies
Understanding code structure and architecture
Finding usage examples
Identifying code patterns
Locating bugs or issues
Code archaeology (understanding legacy code)
Impact analysis before changes

查找特定函数或类
追踪函数调用和依赖关系
理解代码结构与架构
查找使用示例
识别代码模式
定位bug或问题
代码考古（理解遗留代码）
变更前的影响分析

Instructions

操作指南

Step 1: Understand what you're looking for

步骤1：明确搜索目标

Feature implementation:

Where is feature X implemented?
How does feature Y work?
What files are involved in feature Z?

Bug location:

Where is this error coming from?
What code handles this case?
Where is this data being modified?

API usage:

How is this API used?
Where is this function called?
What are examples of using this?

Configuration:

Where are settings defined?
How is this configured?
What are the config options?

功能实现类：

功能X在哪里实现？
功能Y的工作原理是什么？
功能Z涉及哪些文件？

Bug定位类：

这个错误来自哪里？
哪些代码处理这种情况？
这些数据在哪里被修改？

API使用类：

这个API如何使用？
这个函数在哪里被调用？
有哪些使用示例？

配置类：

设置在哪里定义？
如何进行配置？
有哪些配置选项？

Step 2: Choose search strategy

步骤2：选择搜索策略

Semantic search (for conceptual questions):

Use when: You understand what you're looking for conceptually
Examples:
- "How do we handle user authentication?"
- "Where is email validation implemented?"
- "How do we connect to the database?"

Benefits:
- Finds relevant code by meaning
- Works with unfamiliar codebases
- Good for exploratory searches

Grep (for exact text/patterns):

Use when: You know exact text or patterns
Examples:
- Function names: "def authenticate"
- Class names: "class UserManager"
- Error messages: "Invalid credentials"
- Specific strings: "API_KEY"

Benefits:
- Fast and precise
- Works with regex patterns
- Good for known terms

Glob (for file discovery):

Use when: You need to find files by pattern
Examples:
- "**/*.test.js" (all test files)
- "**/config*.yaml" (config files)
- "src/**/*Controller.py" (controllers)

Benefits:
- Quickly find files by type
- Discover file structure
- Locate related files

语义搜索（针对概念性问题）：

适用场景：你对搜索目标有概念性的理解
示例：
- "我们如何处理用户认证？"
- "邮箱验证在哪里实现？"
- "我们如何连接数据库？"

优势：
- 根据含义查找相关代码
- 适用于不熟悉的代码库
- 适合探索性搜索

Grep（针对精确文本/模式）：

适用场景：你知道精确的文本或模式
示例：
- 函数名："def authenticate"
- 类名："class UserManager"
- 错误信息："Invalid credentials"
- 特定字符串："API_KEY"

优势：
- 快速且精准
- 支持正则表达式模式
- 适合已知术语的搜索

Glob（针对文件发现）：

适用场景：你需要按模式查找文件
示例：
- "**/*.test.js"（所有测试文件）
- "**/config*.yaml"（配置文件）
- "src/**/*Controller.py"（控制器文件）

优势：
- 快速按类型查找文件
- 探索文件结构
- 定位相关文件

Step 3: Search workflow

步骤3：搜索工作流

1. Start broad, then narrow:

Step 1: Semantic search "How does authentication work?"
Result: Points to auth/ directory

Step 2: Grep in auth/ for specific function
Pattern: "def verify_token"
Result: Found in auth/jwt.py

Step 3: Read the file
File: auth/jwt.py
Result: Understand implementation

2. Use directory targeting:

undefined

1. 从宽泛到精准：

步骤1：语义搜索"认证机制的工作原理是什么？"
结果：指向auth/目录

步骤2：在auth/目录中grep特定函数
模式："def verify_token"
结果：在auth/jwt.py中找到

步骤3：阅读文件
文件：auth/jwt.py
结果：理解实现逻辑

2. 使用目录定位：

undefined

Start without target (search everywhere)

初始无目标（全局搜索）

Query: "Where is user login implemented?" Target: []

查询："用户登录在哪里实现？" 目标目录：[]

Refine with specific directory

缩小到特定目录

Query: "Where is login validated?" Target: ["backend/auth/"]


**3. Combine searches**:

查询："登录验证在哪里进行？" 目标目录：["backend/auth/"]


**3. 组合搜索**：

Find where feature is implemented

查找功能实现位置

Semantic: "user registration flow"

语义搜索："用户注册流程"

Find all files involved

查找所有涉及的文件

Grep: "def register_user"

Grep："def register_user"

Find test files

查找测试文件

Glob: "**/registertest*.py"

Glob："**/registertest*.py"

Understand the implementation

理解实现逻辑

Read: registration.py, test_registration.py

undefined

阅读：registration.py, test_registration.py

undefined

Step 4: Common search patterns

步骤4：常见搜索模式

Find function definition:

bash

undefined

查找函数定义：

bash

undefined

Python

grep -n "def function_name" --type py

JavaScript

grep -n "function functionName" --type js grep -n "const functionName = " --type js

TypeScript

grep -n "function functionName" --type ts grep -n "export const functionName" --type ts

Go

grep -n "func functionName" --type go

Java

grep -n "public.*functionName" --type java


**Find class definition**:
```bash

grep -n "public.*functionName" --type java


**查找类定义**：
```bash

Python

grep -n "class ClassName" --type py

JavaScript/TypeScript

grep -n "class ClassName" --type js,ts

Java

grep -n "public class ClassName" --type java

C++

grep -n "class ClassName" --type cpp


**Find class/function usage**:
```bash

grep -n "class ClassName" --type cpp


**查找类/函数的使用**：
```bash

Python

grep -n "ClassName(" --type py grep -n "function_name(" --type py

JavaScript

grep -n "new ClassName" --type js grep -n "functionName(" --type js


**Find imports/requires**:
```bash

grep -n "new ClassName" --type js grep -n "functionName(" --type js


**查找导入/引用**：
```bash

Python

grep -n "from.*import.*ModuleName" --type py grep -n "import.*ModuleName" --type py

JavaScript

grep -n "import.*from.*module-name" --type js grep -n "require.*module-name" --type js

Go

grep -n "import.*package-name" --type go


**Find configuration**:
```bash

grep -n "import.*package-name" --type go


**查找配置**：
```bash

Config files

配置文件

glob "**/config.{json,yaml,yml,toml,ini}"

Environment variables

环境变量

grep -n "process\.env\." --type js grep -n "os\.environ" --type py

grep -n "process.env." --type js grep -n "os.environ" --type py

Constants

常量

grep -n "^[A-Z_]+\s*=" --type py grep -n "const [A-Z_]+" --type js


**Find TODO/FIXME**:
```bash
grep -n "TODO|FIXME|HACK|XXX" -i

Find error handling:

bash

undefined

grep -n "^[A-Z_]+\s*=" --type py grep -n "const [A-Z_]+" --type js


**查找TODO/FIXME**：
```bash
grep -n "TODO|FIXME|HACK|XXX" -i

查找错误处理：

bash

undefined

Python

grep -n "try:|except|raise" --type py

JavaScript

grep -n "try|catch|throw" --type js

Go

grep -n "if err != nil" --type go

undefined

grep -n "if err != nil" --type go

undefined

Step 5: Advanced techniques

步骤5：高级技巧

Trace data flow:

1. Find where data is created
   Semantic: "Where is user object created?"

2. Search for variable usage
   Grep: "user\\." with context lines

3. Follow transformations
   Read: Files that modify user

4. Find where it's consumed
   Grep: "user\\." in relevant files

Find all callsites of a function:

1. Find function definition
   Grep: "def process_payment"
   Result: payments/processor.py:45

2. Find all imports of that module
   Grep: "from payments.processor import"
   Result: Multiple files

3. Find all calls to the function
   Grep: "process_payment\\("
   Result: All callsites

4. Read each callsite for context
   Read: Each file with context

Understand a feature end-to-end:

1. Find API endpoint
   Semantic: "Where is user registration endpoint?"
   Result: routes/auth.py

2. Trace to controller
   Read: routes/auth.py
   Find: Calls to AuthController.register

3. Trace to service
   Read: controllers/auth.py
   Find: Calls to UserService.create_user

4. Trace to database
   Read: services/user.py
   Find: Database operations

5. Find tests
   Glob: "**/*auth*test*.py"
   Read: Test files for examples

Find related files:

1. Start with known file
   Example: models/user.py

2. Find imports of this file
   Grep: "from models.user import"

3. Find files this imports
   Read: models/user.py
   Note: Import statements

4. Build dependency graph
   Map: All related files

Impact analysis:

Before changing function X:

1. Find all callsites
   Grep: "function_name\\("

2. Find all tests
   Grep: "test.*function_name" -i

3. Check related functionality
   Semantic: "What depends on X?"

4. Review each usage
   Read: Each file using function

5. Plan changes
   Document: Impact and required updates

追踪数据流：

1. 查找数据创建的位置
   语义搜索："用户对象在哪里创建？"

2. 搜索变量的使用
   Grep："user\." 并查看上下文行

3. 跟踪数据转换
   阅读：修改user的文件

4. 查找数据的消费位置
   Grep：相关文件中的"user\."

查找函数的所有调用点：

1. 查找函数定义
   Grep："def process_payment"
   结果：payments/processor.py:45

2. 查找该模块的所有导入
   Grep："from payments.processor import"
   结果：多个文件

3. 查找函数的所有调用
   Grep："process_payment\("
   结果：所有调用点

4. 阅读每个调用点的上下文
   阅读：每个包含调用的文件

端到端理解功能：

1. 查找API端点
   语义搜索："用户注册端点在哪里？"
   结果：routes/auth.py

2. 追踪到控制器
   阅读：routes/auth.py
   发现：调用AuthController.register

3. 追踪到服务层
   阅读：controllers/auth.py
   发现：调用UserService.create_user

4. 追踪到数据库
   阅读：services/user.py
   发现：数据库操作

5. 查找测试文件
   Glob："**/*auth*test*.py"
   阅读：测试文件获取示例

查找相关文件：

1. 从已知文件开始
   示例：models/user.py

2. 查找导入该文件的位置
   Grep："from models.user import"

3. 查找该文件导入的内容
   阅读：models/user.py
   记录：导入语句

4. 构建依赖图
   映射：所有相关文件

影响分析：

在修改函数X之前：

1. 查找所有调用点
   Grep："function_name\("

2. 查找所有测试
   Grep："test.*function_name" -i

3. 检查相关功能
   语义搜索："哪些功能依赖X？"

4. 检查每个使用场景
   阅读：每个使用该函数的文件

5. 规划变更
   记录：影响范围和所需更新

Step 6: Search optimization

步骤6：搜索优化

Use appropriate context:

bash

undefined

使用合适的上下文：

bash

undefined

See surrounding context

查看周围上下文

grep -n "pattern" -C 5 # 5 lines before and after grep -n "pattern" -B 3 # 3 lines before grep -n "pattern" -A 3 # 3 lines after


**Case sensitivity**:
```bash

grep -n "pattern" -C 5 # 前后5行 grep -n "pattern" -B 3 # 前3行 grep -n "pattern" -A 3 # 后3行


**大小写敏感性**：
```bash

Case insensitive

不区分大小写

grep -n "pattern" -i

Case sensitive (default)

区分大小写（默认）

grep -n "Pattern"


**File type filtering**:
```bash

grep -n "Pattern"


**文件类型过滤**：
```bash

Specific type

特定类型

grep -n "pattern" --type py

Multiple types

多种类型

grep -n "pattern" --type py,js,ts

Exclude types

排除类型

grep -n "pattern" --glob "!*.test.js"


**Regex patterns**:
```bash

grep -n "pattern" --glob "!*.test.js"


**正则表达式模式**：
```bash

Any character: .

任意字符：.

grep -n "function.*Name"

Start of line: ^

行首：^

grep -n "^class"

End of line: $

行尾：$

grep -n "TODO$"

Optional: ?

可选：?

grep -n "function_name_?()"

One or more: +

一个或多个：+

grep -n "[A-Z_]+"

Zero or more: *

零或多个：*

grep -n "import.*"

Alternatives: |

多选：|

grep -n "TODO|FIXME"

Groups: ()

分组：()

grep -n "(get|set)_user"

Escape special chars: \

转义特殊字符：\

grep -n "function()"

undefined

grep -n "function()"

undefined

Best practices

最佳实践

Start with semantic search: For unfamiliar code or conceptual questions
Use grep for precision: When you know exact terms
Combine multiple searches: Build understanding incrementally
Read surrounding context: Don't just look at matching lines
Check file history: Use
```
git blame
```
for context
Document findings: Note important discoveries
Verify assumptions: Read actual code, don't assume
Use directory targeting: Narrow scope when possible
Follow the data: Trace data flow through the system
Check tests: Tests often show usage examples

从语义搜索开始：针对不熟悉的代码库或概念性问题
使用grep实现精准搜索：当你知道确切术语时
组合多种搜索方式：逐步构建对代码的理解
阅读上下文内容：不要只看匹配的行
检查文件历史：使用
```
git blame
```
获取上下文
记录发现：记录重要的发现
验证假设：阅读实际代码，不要仅凭猜测
使用目录定位：尽可能缩小搜索范围
跟踪数据流：追踪数据在系统中的流转
查看测试文件：测试通常会展示使用示例

Common search scenarios

常见搜索场景

Scenario 1: Understanding a bug

场景1：理解Bug

1. Find error message
   Grep: "exact error message"

2. Find where it's thrown
   Read: File with error

3. Find what triggers it
   Semantic: "What causes X error?"

4. Find related code
   Grep: Related function names

5. Check tests
   Glob: "**/*test*.py"
   Look: For related test cases

1. 查找错误信息
   Grep："精确的错误信息"

2. 查找错误抛出的位置
   阅读：包含错误的文件

3. 查找触发错误的原因
   语义搜索："什么会导致X错误？"

4. 查找相关代码
   Grep：相关函数名

5. 检查测试文件
   Glob："**/*test*.py"
   查看：相关测试用例

Scenario 2: Learning a new codebase

场景2：学习新代码库

1. Find entry point
   Semantic: "Where does the application start?"
   Common files: main.py, index.js, app.py

2. Find main routes/endpoints
   Grep: "route|endpoint|@app\\."

3. Find data models
   Semantic: "Where are data models defined?"
   Common: models/, entities/

4. Find configuration
   Glob: "**/*config*"

5. Read README and docs
   Read: README.md, docs/

1. 查找入口文件
   语义搜索："应用程序从哪里启动？"
   常见文件：main.py, index.js, app.py

2. 查找主要路由/端点
   Grep："route|endpoint|@app\."

3. 查找数据模型
   语义搜索："数据模型在哪里定义？"
   常见位置：models/, entities/

4. 查找配置
   Glob："**/*config*"

5. 阅读README和文档
   阅读：README.md, docs/

Scenario 3: Refactoring preparation

场景3：重构准备

1. Find all usages
   Grep: "function_to_change"

2. Find tests
   Grep: "test.*function_to_change"

3. Find dependencies
   Semantic: "What does X depend on?"

4. Check imports
   Grep: "from.*import.*X"

5. Document scope
   List: All affected files

1. 查找所有用法
   Grep："function_to_change"

2. 查找测试文件
   Grep："test.*function_to_change"

3. 查找依赖关系
   语义搜索："X依赖哪些功能？"

4. 检查导入
   Grep："from.*import.*X"

5. 记录范围
   列出：所有受影响的文件

Scenario 4: Adding a feature

场景4：添加新功能

1. Find similar features
   Semantic: "How is similar feature implemented?"

2. Find where to add code
   Semantic: "Where should new feature go?"

3. Check patterns
   Read: Similar implementations

4. Find tests to emulate
   Glob: Test files for similar features

5. Check documentation
   Grep: "TODO.*new feature" -i

1. 查找类似功能
   语义搜索："类似功能是如何实现的？"

2. 查找代码添加位置
   语义搜索："新功能应该放在哪里？"

3. 检查实现模式
   阅读：类似的实现代码

4. 查找可参考的测试
   Glob：类似功能的测试文件

5. 检查文档
   Grep："TODO.*新功能" -i

Tools integration

工具集成

Git integration:

bash

undefined

Git集成：

bash

undefined

Who changed this line?

谁修改了这行代码？

git blame filename

History of a file

文件的历史记录

git log -p filename

Find when function was added

查找函数何时被添加

git log -S "function_name" --source --all

Find commits mentioning X

查找提及X的提交

git log --grep="feature name"


**IDE integration**:
- Use "Go to Definition" for quick navigation
- Use "Find References" for usage
- Use "Find in Files" for broad search
- Use symbol search for classes/functions

**Documentation**:
- Check inline comments
- Look for docstrings
- Read README files
- Check architecture docs

git log --grep="功能名称"


**IDE集成**：
- 使用“跳转到定义”快速导航
- 使用“查找引用”查看用法
- 使用“在文件中查找”进行宽泛搜索
- 使用符号搜索查找类/函数

**文档**：
- 查看内联注释
- 查找文档字符串
- 阅读README文件
- 查看架构文档

Troubleshooting

故障排除

No results found:

Check spelling and case sensitivity
Try semantic search instead of grep
Broaden search scope (remove directory target)
Try different search terms
Check if files are in .gitignore

Too many results:

Add directory targeting
Use more specific patterns
Filter by file type
Use exact phrases (quotes)

Wrong results:

Be more specific in query
Use grep instead of semantic for exact terms
Add context to semantic queries
Check file types

未找到结果：

检查拼写和大小写敏感性
尝试使用语义搜索替代grep
扩大搜索范围（移除目录目标）
尝试不同的搜索术语
检查文件是否在.gitignore中

结果过多：

添加目录定位
使用更具体的模式
按文件类型过滤
使用精确短语（加引号）

结果不符：

让查询更具体
对于精确术语，使用grep而非语义搜索
为语义查询添加更多上下文
检查文件类型

References

参考资料

Examples

示例

Example 1: Basic usage

示例1：基础用法

Example 2: Advanced usage

示例2：高级用法