175 lines
4.6 KiB
Markdown
175 lines
4.6 KiB
Markdown
---
|
|
name: using-serena-for-exploration
|
|
description: Use when exploring codebases with Serena MCP tools for architectural understanding and pattern discovery - guides efficient symbolic exploration workflow minimizing token usage through targeted symbol reads, overview tools, and progressive narrowing
|
|
---
|
|
|
|
# Using Serena for Exploration
|
|
|
|
Use this skill when exploring codebases with Serena MCP tools for architectural understanding and pattern discovery.
|
|
|
|
## Core Principles
|
|
|
|
- Start broad, narrow progressively
|
|
- Use symbolic tools before reading full files
|
|
- Always provide file:line references
|
|
- Minimize token usage through targeted reads
|
|
|
|
## Workflow
|
|
|
|
### 1. Initial Discovery
|
|
|
|
**Use `list_dir` and `find_file`** to understand project structure:
|
|
|
|
```bash
|
|
# Get repository overview
|
|
list_dir(relative_path=".", recursive=false)
|
|
|
|
# Find specific file types
|
|
find_file(file_mask="*auth*.py", relative_path="src")
|
|
```
|
|
|
|
### 2. Symbol Overview
|
|
|
|
**Use `get_symbols_overview`** before reading full files:
|
|
|
|
```python
|
|
# Get top-level symbols in a file
|
|
get_symbols_overview(relative_path="src/auth/handler.py")
|
|
```
|
|
|
|
Returns classes, functions, imports - understand structure without reading bodies.
|
|
|
|
### 3. Targeted Symbol Reading
|
|
|
|
**Use `find_symbol`** for specific code:
|
|
|
|
```python
|
|
# Read a specific class without body
|
|
find_symbol(
|
|
name_path_pattern="AuthHandler",
|
|
relative_path="src/auth/handler.py",
|
|
include_body=false,
|
|
depth=1 # Include methods list
|
|
)
|
|
|
|
# Read specific method with body
|
|
find_symbol(
|
|
name_path_pattern="AuthHandler/login",
|
|
relative_path="src/auth/handler.py",
|
|
include_body=true
|
|
)
|
|
```
|
|
|
|
**Name path patterns:**
|
|
- Simple name: `"login"` - matches any symbol named "login"
|
|
- Relative path: `"AuthHandler/login"` - matches method in class
|
|
- Absolute path: `"/AuthHandler/login"` - exact match within file
|
|
- With index: `"AuthHandler/login[0]"` - specific overload
|
|
|
|
### 4. Pattern Searching
|
|
|
|
**Use `search_for_pattern`** when you don't know symbol names:
|
|
|
|
```python
|
|
# Find all JWT usage
|
|
search_for_pattern(
|
|
substring_pattern="jwt\\.encode",
|
|
relative_path="src",
|
|
restrict_search_to_code_files=true,
|
|
context_lines_before=2,
|
|
context_lines_after=2,
|
|
output_mode="content"
|
|
)
|
|
```
|
|
|
|
**Pattern matching:**
|
|
- Uses regex with DOTALL flag (. matches newlines)
|
|
- Non-greedy quantifiers preferred: `.*?` not `.*`
|
|
- Escape special chars: `\\{\\}` for literal braces
|
|
|
|
### 5. Relationship Discovery
|
|
|
|
**Use `find_referencing_symbols`** to understand dependencies:
|
|
|
|
```python
|
|
# Who calls this function?
|
|
find_referencing_symbols(
|
|
name_path="authenticate_user",
|
|
relative_path="src/auth/handler.py"
|
|
)
|
|
```
|
|
|
|
Returns code snippets around references with symbolic info.
|
|
|
|
## Reporting Format
|
|
|
|
Always structure findings as:
|
|
|
|
```markdown
|
|
## Codebase Findings
|
|
|
|
### Current Architecture
|
|
- **Authentication:** `src/auth/handler.py:45-120`
|
|
- JWT-based auth with refresh tokens
|
|
- Session storage in Redis
|
|
|
|
### Similar Implementations
|
|
- **User management:** `src/users/controller.py:200-250`
|
|
- Uses similar validation pattern
|
|
- Can reuse `validate_credentials()` helper
|
|
|
|
### Integration Points
|
|
- **Middleware:** `src/middleware/auth.py:30`
|
|
- Hook new auth method here
|
|
- Follows pattern: check → validate → attach user
|
|
```
|
|
|
|
## Anti-Patterns
|
|
|
|
❌ **Don't:** Read entire files before understanding structure
|
|
✅ **Do:** Use `get_symbols_overview` first
|
|
|
|
❌ **Don't:** Use full file reads for symbol searches
|
|
✅ **Do:** Use `find_symbol` with targeted name paths
|
|
|
|
❌ **Don't:** Search without context limits
|
|
✅ **Do:** Use `relative_path` to restrict search scope
|
|
|
|
❌ **Don't:** Return findings without file:line references
|
|
✅ **Do:** Always include exact locations: `file.py:123-145`
|
|
|
|
## Token Efficiency
|
|
|
|
- Overview tools use ~500 tokens vs. ~5000 for full file
|
|
- Targeted symbol reads use ~200 tokens per symbol
|
|
- Pattern search with `head_limit=20` caps results
|
|
- Use `depth=0` if you don't need child symbols
|
|
|
|
## Example Session
|
|
|
|
```python
|
|
# 1. Find auth-related files
|
|
files = find_file(file_mask="*auth*.py", relative_path="src")
|
|
# → Found: src/auth/handler.py, src/auth/middleware.py
|
|
|
|
# 2. Get overview of main handler
|
|
overview = get_symbols_overview(relative_path="src/auth/handler.py")
|
|
# → Classes: AuthHandler
|
|
# → Functions: authenticate_user, validate_token
|
|
|
|
# 3. Read specific method
|
|
method = find_symbol(
|
|
name_path_pattern="AuthHandler/authenticate_user",
|
|
relative_path="src/auth/handler.py",
|
|
include_body=true
|
|
)
|
|
# → Got full implementation of authenticate_user
|
|
|
|
# 4. Find who calls this
|
|
refs = find_referencing_symbols(
|
|
name_path="authenticate_user",
|
|
relative_path="src/auth/handler.py"
|
|
)
|
|
# → Called from: middleware.py:67, api/routes.py:123
|
|
```
|