code-structure

# Code Structure Exploration Tools

## Recognizing Structure Questions

**These keywords mean use structure tools, NOT grep/search:**
- "all the methods/functions/classes in..."
- "list of function signatures"
- "what functions/exports/API..."
- "package API" or "module exports"
- "method signatures with receivers" (Go)
- "what's available in..."

**These keywords mean use search (Grep tool or ast-grep):**
- "where is X defined"
- "find calls to X"
- "search for pattern Y"

## Before You Choose a Tool

Ask yourself:
1. Am I listing/exploring what exists? → Structure tools
2. Am I finding WHERE something is? → Search tools (Grep or ast-grep)
3. Am I understanding HOW something works? → Read

## When to Get File Outline vs Read

**Get outline/index when:**
- File is large (>500 lines)
- Need to see what's available (functions, classes, exports)
- Exploring unfamiliar code
- Want to decide what to read in detail
- **Saves 90%+ context** vs reading entire file

**Just use Read when:**
- File is small (<500 lines)
- Already know what you're looking for
- Need to understand implementation details
- ast-grep pattern already targets what you need

## Anti-Patterns

**DON'T use grep/rg/Grep tool for:**
- Extracting function/method lists
- Getting API overviews
- Finding all exports/public members
- Getting signatures/interfaces

These are STRUCTURE queries, not SEARCH queries.

## Exploration Strategy

**Tiered approach (try in order):**

1. **ast-grep with known patterns** - Fast, targeted
   - Extract exports, functions, classes with specific patterns
   - See [code structure guide](./reference/code-structure-guide.md) for patterns

2. **Toolchain-specific approaches** - When available
   - **Go:** `go doc -all <package>` for all methods/functions with signatures
     - Example: "list all methods" → `go doc -all ./internal/pkg`
     - Example: "method signatures" → `go doc -all ./internal/pkg`
   - **Python:** Language-specific indexers
   - **ctags/universal-ctags:** Symb