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

• Ripgrep User Guide

• Regular Expressions Tutorial

• Git Blame Guide

Examples

Example 1: Basic usage

Example 2: Advanced usage