Semantic Code Exploration

This skill guides efficient code exploration using Serena MCP for semantic navigation.

Prerequisite Check

Before proceeding, verify Serena is available by checking for mcpserena* tools.

If Serena is NOT configured: Tell the user: "This exploration would benefit from Serena MCP for semantic code navigation, but it's not configured. See .claude/skills/read-codebase/setup.md for installation instructions. Proceeding with standard tools (Grep/Read/Glob)."

Then use standard tools as fallback.

Tool Priority (when Serena is available)

1. getsymbolsoverview - First step for any file
2. find_symbol - Locate specific classes/methods
3. findreferencingsymbols - Find all usages
4. searchforpattern - When symbol name is unknown
5. read_memory - Check project knowledge (architecture, patterns)

Quick Reference

Understanding a File

1. getsymbolsoverview(relative_path="path/to/file.php") → see structure
2. findsymbol(namepath_pattern="ClassName", depth=1) → see methods
3. Only use include_body=true for specific methods you need

Finding Where Code Is Used

1. find_symbol to locate the symbol
2. findreferencingsymbols to find all call sites

Exploring Unknown Code

1. Check memories: listmemories → readmemory("architecture")
2. Use searchforpattern with keywords
3. Follow up with symbolic tools

Anti-Patterns

• Reading entire files when you only need one method
• Using Grep/Read when Serena tools would be more precise
• Skipping symbol overview and going straight to file read
• Not checking project memories for existing documentation

When to Use Standard Tools Instead

• Simple text search across many files → Grep
• Config files, markdown, non-code → Read
• Known file needing full content → Read
• Serena not configured → Fallback to Grep/Read/Glob

Additional Resources

• Detailed workflows: [workflows.md](workflows.md)
• Setup instructions: [setup.md](setup.md)