CLAUDE.md.example

## CLI Usage: Modern Syntax

Codanna supports both MCP tools and CLI commands. The CLI has been updated with Unix-friendly syntax:

### Simple Commands (positional arguments):
```bash
# Text output (DEFAULT - prefer this to save context)
codanna mcp find_symbol main
codanna mcp get_calls process_file
codanna mcp find_callers init

# JSON output (only when structured data needed)
codanna mcp find_symbol main --json
```

### Complex Commands (key:value pairs):
```bash
# Text output (DEFAULT - prefer this)
codanna mcp search_symbols query:parse limit:10
codanna mcp semantic_search_docs query:"error handling"

# JSON output (only for parsing/piping)
codanna mcp search_symbols query:parse --json | jq '.data[].name'
```

### Important: Prefer TEXT Output
- TEXT output is concise and human-readable
- JSON fills context window quickly (3-5x more tokens)
- Only use `--json` when you need to parse results programmatically
- The agent should default to TEXT for exploration and analysis

## INSTRUCTIONS: Using Codanna-Navigator Agent Effectively

### Multi-Hop Pattern for Deep Analysis

When analyzing complex features or implementation requirements in this codebase, you (Claude) MUST use the codanna-navigator agent in a multi-hop fashion for comprehensive understanding. Single-shot prompts often miss critical details that only emerge through iterative exploration.

### Key Principles

1. **Start Broad, Then Deep**: First prompt should map the landscape, follow-ups should drill into specifics
2. **Track Progress**: Always instruct the agent to use TodoWrite for complex analyses
3. **Score and Iterate**: Mentally score each response (0-10) and identify gaps to fill
4. **Context Preservation**: Each follow-up should reference findings from previous hops
5. **Structured Prompts**: Break down complex requests into numbered steps with clear deliverables

### CRITICAL: Context Forward-Passing

Since the codanna-navigator agent starts fresh with each invocation, you MUST pass forward relevant context from previous hops. This dramatically improves the agent's precision and efficiency.

**What to Forward**:
- Specific file paths and line numbers discovered
- Struct/function names that need investigation
- Patterns or conventions identified
- Key findings that narrow the search scope
- Relationships between components

**Example Context Forwarding**:
```
"CONTEXT FROM PREVIOUS ANALYSIS:
- The Symbol struct at src/types/symbol.rs:45 already has Serialize/Deserialize
- Main output logic is in src/main.rs lines 901-1684
- You found 14 commands using direct println! calls
- SearchResult struct at tantivy.rs:321 needs serde derives

Now focus on: [specific targeted request based on above context]"
```

This context forwarding transforms vague searches into surgical strikes, allowing the agent to navigate directly to relevant code instead of searching blindly.

### When to Use Multi-Hop

- **Feature Implementation Planning**: Understanding impact across multiple files/modules
- **Refactoring Analysis**: Identifying all touchpoints and dependencies
- **Architecture Understanding**: Mapping relationships between components
- **Pattern Discovery**: Finding consistent patterns across the codebase

<codanna-agent-workflow-example>
<workflow>
**Use Case**: User asks to implement JSON output support for CLI commands

**My Initial Thoughts**:
"This is a cross-cutting feature that will impact many parts of the codebase. I need to understand:
1. Current output architecture
2. All commands that produce output
3. Existing serialization infrastructure
4. Best insertion points for the feature

The README mentions this is a priority feature but doesn't detail implementation. I'll need comprehensive analysis."

**First Hop - Broad Analysis**:
```
Prompt to agent:
"Analyze the codanna codebase to understand how to implement JSON output support for all CLI commands.

Step 1: Understand Current Output Architecture
- Search for println! and formatting code
- Find main entry point and trace command output
- Identify all CLI commands that produce output

Step 2: Analyze Command Structure
- Find CLI command definitions
- Identify where each command's output is generated
- Check for existing JSON serialization

Step 3: Identify Impact Points
- List all files with output formatting
- Find structs needing JSON serialization
- Identify best insertion points for --json flag

Step 4: Propose Implementation Strategy
Based on findings, provide:
1. Commands needing JSON output
2. Key files to modify
3. Recommended approach

Use TodoWrite to track your progress."
```

**Analyzing First Response** (Mental Score: 9/10):
"Excellent architectural overview. Found:
- Main.rs has all CLI logic (2157 lines)
- Direct println! calls scattered throughout
- Some types have serde, others missing
- 14 commands need JSON support

Gap identified: I don't see specific println! patterns or complexity assessment. Need concrete examples to understand refactoring effort."

**Update My TodoWrite**:
- ✅ Understand architecture
- ✅ Identify commands needing JSON
- ⏳ Get specific code patterns
- ⏳ Assess refactoring complexity
- ⏳ Create implementation plan

**Second Hop - Fill the Gap (Leveraging First Hop Context)**:
```
Prompt to agent:
"I need you to analyze the specific println! patterns in codanna CLI to understand exactly how output is currently formatted.

CONTEXT FROM PREVIOUS ANALYSIS:
- Main CLI logic is in src/main.rs (2157 lines)
- Commands are at lines 901-1684 for retrieve commands
- You found these structs already have serde: Symbol, SymbolKind, Range, Visibility
- Missing serde on: SearchResult (tantivy.rs:321-334), TextHighlight (tantivy.rs:337-342), IndexStats (progress.rs:8-26)
- 14 commands need JSON support, particularly retrieve commands

Step 1: Find and Categorize println! Patterns
Focus on src/main.rs lines 901-1684 (retrieve commands section).
Search for all println! and eprintln! calls and categorize by:
- Simple string output
- Formatted output with variables
- Table/structured output
- Error messages
Provide 3-5 examples with line numbers for each.

Step 2: Analyze Complex Output Formatting
Look specifically at how Symbol and SearchResult structs are printed.
Look for places where output is built over multiple println! calls.
Provide specific code snippets.

Step 3: Map Command to Output Pattern
For each retrieve command (lines 901-1684), provide:
- Command name
- Line numbers where output happens
- Exact println! pattern used
- Which data structure is being printed (Symbol, SearchResult, etc.)

Step 4: Provide Refactoring Examples
Show 2-3 concrete before/after refactoring examples, particularly for:
- Symbol display (since it already has serde)
- SearchResult display (needs serde added)

Track progress with TodoWrite."
```

**Analyzing Second Response** (Mental Score: 10/10):
"Perfect! Now I have:
- 50+ formatted outputs (lines 770-776, 909-910, etc.)
- 15+ table outputs (lines 1302-1312, etc.)
- 25+ error messages
- Concrete refactoring examples with before/after code
- Complexity assessment for each command

This fills all gaps. I can now provide a complete implementation plan."

**Final Synthesis**:
Combining both agent reports, I now have:
1. Complete architectural understanding
2. Specific code patterns and line numbers
3. Complexity ratings for prioritization
4. Concrete refactoring examples
5. Clear implementation phases

**Decision**: Ready to provide comprehensive answer. Score: 10/10
</workflow>
</codanna-agent-workflow-example>

### Common Multi-Hop Patterns

#### Pattern 1: Architecture → Details → Examples
```
Hop 1: "Map the architecture of [feature]"
Hop 2: "Drill into specific implementations of [component]"
Hop 3: "Show concrete examples of [pattern]"
```

#### Pattern 2: Current State → Impact → Migration
```
Hop 1: "Analyze current implementation of [system]"
Hop 2: "Identify all dependencies and touchpoints"
Hop 3: "Propose migration strategy with examples"
```

#### Pattern 3: Search → Filter → Deep Dive
```
Hop 1: "Find all occurrences of [pattern]"
Hop 2: "Filter to [specific criteria]"
Hop 3: "Analyze top candidates in detail"
```

### Agent Prompt Best Practices

1. **Always include TodoWrite instruction** for complex tasks
2. **Number your steps** for clarity
3. **Specify deliverables** for each step
4. **Reference file paths** when you know them from README/docs
5. **Ask for line numbers** when you need to modify code
6. **Request examples** when patterns aren't clear
7. **Be specific about output format** you need

### Red Flags Requiring Follow-Up

- Agent says "I found some examples" without specifics → Ask for line numbers
- Agent provides high-level description → Ask for code snippets
- Agent analyzes structure but not patterns → Ask for pattern analysis
- Agent misses complexity assessment → Ask for difficulty ratings
- Agent report feels incomplete (score <8) → Identify gaps and iterate

### Remember

The codanna-navigator agent starts fresh each time without context. Your prompts must be self-contained and comprehensive. The agent is excellent at:
- Semantic search across the codebase
- Finding patterns and relationships
- Analyzing code structure
- Providing line-specific details

Use these strengths by crafting prompts that leverage the agent's code intelligence capabilities.