codebase-explorer— agent skill

Search Query Analysis

Query Optimization Skill

Codanna's semantic search works best with technical terms and specific concepts. Analyze the situation and optimize your codebase explore queries for code search:

Examples:

1. If vague (e.g., "that parsing thing") → Make it specific (e.g., "language parser implementation")
2. If a question (e.g., "how does parsing work?") → Extract keywords (e.g., "parsing implementation process")
3. If conversational (e.g., "the stuff that handles languages") → Use technical terms (e.g., "language handler processor")
4. If too broad (e.g., "errors") → Add context (e.g., "error handling exception management")

OptimizedQuery: _{Claude: I will write my optimized query here, then use it below}_

Execute this command with your optimized query:

Your Workflow <Workflow>

Gather Context <Step_1 GatherContext>

Use the Bash tool to perform semantic code search:

Execute: codanna mcp semantic_search_with_context query:"$OptimizedQuery" limit:5

What Codanna returns:

• Relevance scores (how well each result matches)
• Symbol signatures and documentation
• Relationships (calls, called_by, implements, defines)
• File locations with line ranges

Your Workflow <Step_2 YourWorkflow>

1. Analyze the results with their relevance scores (focus on results with score > 0.6 (if possible))

1. To see actual implementation of interesting results:

• Use the line range from the Location field to read just the relevant code
• Example: If you see "at src/io/exit_code.rs:108-120"
• Use the Read tool with:
• file_path: src/io/exit_code.rs (use the working directory from your environment context <env> to construct the absolute path)
• offset: 108 (start line)
• limit: 13 (calculated as: 120 - 108 + 1)
• Formula: limit = end_line - start_line + 1
• Example: Read(file_path="/full/path/to/src/io/exit_code.rs", offset=108, limit=13)

1. When relationships are shown (called_by, calls, defines, implements):

• If a relationship looks relevant to answering the query, investigate it
• Execute: codanna retrieve describe <relationship_symbol_name|symbol_id:ID>
• Example: If you see "Called by: initialize_registry [symbol_id:123]", run: codanna retrieve describe initialize_registry or describe symbol_id:123
• Note: Following 1-2 key relationships per result is typically sufficient

1. Build a complete picture by following key relationships and reading relevant code sections

1. If needed, repeat <Step_1: GatherContext> with a refined query based on what you learned.

Tips for Efficient Exploration

The results include:

• Relevance scores (how well each result matches the query)
• Symbol documentation and signatures
• Relationships (who calls this, what it calls, what it defines)
• System guidance for follow-up investigation

sed (native on unix only):

• You can also see actual implementation with sed: (works native on Unix based environments):
• Use the line range from the Location field to read just the relevant code
• Example: If you see "Location: src/io/exit_code.rs:108-120"
• Execute: sed -n '108,120p' src/io/exit_code.rs to read lines 108-120
• This shows the actual code implementation, not just the signature. It works like the Read tool.

• Add lang:rust (or python, typescript, etc.) to narrow results by language if you work on multi-language projects
• Follow relationships that appear in multiple results (they're likely important)
• Use the describe command to get full details about interesting relationships

Token awareness:

• Each search uses ~500 tokens
• Each relationship follow uses ~300 tokens
• Each file read uses ~100-500 tokens (depends on size)
• Staying efficient keeps your context window clean for deeper analysis

This command is for exploration:

• Build understanding of the codebase
• Identify patterns and integration points
• Present findings and await user direction
• Don't start implementing or making changes yet

Based on the gathered context, engage with the user to narrow focus and help the user with further request.