代码库搜索技能指南：精准查找函数、追踪依赖、理解架构与定位错误

codebase-search by supercent-io/skills-template

10,900 周安装量

88 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/supercent-io/skills-template --skill codebase-search

开发代码质量生产力

🇨🇳中文介绍

代码库搜索

何时使用此技能

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

使用说明

步骤 1：明确查找目标

功能实现：

功能 X 在哪里实现？
功能 Y 是如何工作的？
功能 Z 涉及哪些文件？

错误定位：

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

API 使用：

这个 API 是如何使用的？
这个函数在哪里被调用？
使用它的例子有哪些？

配置：

设置在哪里定义？
这个是如何配置的？
有哪些配置选项？

步骤 2：选择搜索策略

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

使用时机：你从概念上理解你要找什么
示例：
- "我们如何处理用户认证？"
- "电子邮件验证在哪里实现？"
- "我们如何连接到数据库？"

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

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 3：搜索工作流程

1. 先宽泛，后聚焦：

步骤 1：语义搜索 "认证是如何工作的？"
结果：指向 auth/ 目录

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

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

2. 使用目录定位：

# 开始时不指定目标（到处搜索）
查询："用户登录在哪里实现？"
目标：[]

# 使用特定目录进行细化
查询："登录验证在哪里？"
目标：["backend/auth/"]

3. 组合搜索：

# 查找功能实现位置
语义："用户注册流程"

# 查找所有涉及的文件
Grep："def register_user"

# 查找测试文件
Glob："**/*register*test*.py"

# 理解实现
阅读：registration.py, test_registration.py

步骤 4：常见搜索模式

查找函数定义：

# 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

查找类定义：

# 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

查找类/函数用法：

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

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

查找导入/引用：

# 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

# 配置文件
glob "**/*config*.{json,yaml,yml,toml,ini}"

# 环境变量
grep -n "process\\.env\\." --type js
grep -n "os\\.environ" --type py

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

查找 TODO/FIXME：

grep -n "TODO|FIXME|HACK|XXX" -i

查找错误处理：

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

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

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

步骤 5：高级技巧

追踪数据流：

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

2. 搜索变量使用情况
   Grep："user\\." 并附带上下文行

3. 跟踪转换过程
   阅读：修改用户的文件

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. 计划变更
   记录：影响和所需的更新

步骤 6：搜索优化

使用适当的上下文：

# 查看周围上下文
grep -n "pattern" -C 5  # 前后各 5 行
grep -n "pattern" -B 3  # 前 3 行
grep -n "pattern" -A 3  # 后 3 行

区分大小写：

# 不区分大小写
grep -n "pattern" -i

# 区分大小写（默认）
grep -n "Pattern"

文件类型过滤：

# 特定类型
grep -n "pattern" --type py

# 多种类型
grep -n "pattern" --type py,js,ts

# 排除类型
grep -n "pattern" --glob "!*.test.js"

正则表达式模式：

# 任意字符：.
grep -n "function.*Name"

# 行首：^
grep -n "^class"

# 行尾：$
grep -n "TODO$"

# 可选：?
grep -n "function_name_?()"

# 一个或多个：+
grep -n "[A-Z_]+"

# 零个或多个：*
grep -n "import.*"

# 备选项：|
grep -n "TODO|FIXME"

# 分组：()
grep -n "(get|set)_user"

# 转义特殊字符：\
grep -n "function\(\)"

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

场景 1：理解一个错误

1. 查找错误消息
   Grep："确切的错误消息"

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

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

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

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

场景 2：学习新代码库

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

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

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

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

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

场景 3：重构准备

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

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

3. 查找依赖项
   语义："X 依赖什么？"

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

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

场景 4：添加功能

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

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

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

4. 查找要模仿的测试
   Glob：类似功能的测试文件

5. 检查文档
   Grep："TODO.*new feature" -i

# 谁更改了这行？
git blame filename

# 文件历史
git log -p filename

# 查找函数何时添加
git log -S "function_name" --source --all

# 查找提及 X 的提交
git log --grep="feature name"

使用 "转到定义" 进行快速导航
使用 "查找引用" 查看用法
使用 "在文件中查找" 进行广泛搜索
使用符号搜索查找类/函数

检查内联注释
查找文档字符串
阅读 README 文件
检查架构文档

未找到结果：

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

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

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

示例 1：基本用法

示例 2：高级用法

2026 年 1 月 24 日

🇺🇸English

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

Instructions

Step 1: Understand what you're looking for

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?

Step 2: Choose search strategy

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

Step 3: Search workflow

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 :

# 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 :

# Find where feature is implemented
Semantic: "user registration flow"

# Find all files involved
Grep: "def register_user"

# Find test files
Glob: "**/*register*test*.py"

# Understand the implementation
Read: registration.py, test_registration.py

Step 4: Common search patterns

Find function definition :

# 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 :

# 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 :

# 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 :

# 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 :

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

# Environment variables
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 :

grep -n "TODO|FIXME|HACK|XXX" -i

Find error handling :

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

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

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

Step 5: Advanced techniques

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

Step 6: Search optimization

Use appropriate context :

# 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 :

# Case insensitive
grep -n "pattern" -i

# Case sensitive (default)
grep -n "Pattern"

File type filtering :

# 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 :

# 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\(\)"

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

Common search scenarios

Scenario 1: Understanding a 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

Scenario 2: Learning a new codebase

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/

Scenario 3: Refactoring preparation

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

Scenario 4: Adding a feature

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

Tools integration

Git integration :

# 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
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

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

References

Examples

Example 1: Basic usage

Example 2: Advanced usage

Weekly Installs

10.9K

Repository

supercent-io/sk…template

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex10.8K

gemini-cli10.8K

opencode10.8K

github-copilot10.7K

cursor10.7K

amp10.7K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

107,800 周安装