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: "**/registertest*.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: "**/authtest*.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