Episode 8: Skill 2 — Smart Explore (Intelligent Code Navigation)

This episode's scenario: The blog project now has 20+ files. You want Claude to understand the src/api/ directory structure. Reading all 20 files via read_file would be 4,000 lines = ~60,000 tokens. There's a smarter way.

---

8.1 The Three MCP Tools

Tool 1: smart_search — Semantic Code Search

AST-based (Abstract Syntax Tree) search that understands code structure.

smart_search(
  query: "comment",
  path: "src/api",
  file_pattern: "*.ts"
)

Returns function names, class names, and their locations — not raw text lines.

Tool 2: smart_outline — File Skeleton X-Ray

Returns only the structural skeleton: exported function signatures, class definitions, interfaces — no implementation bodies.

smart_outline(filepath: "src/api/comments.ts")

Returns (~350 tokens):

export async function createComment(postId: string, body: CreateCommentInput): Promise<Comment>
export async function deleteComment(commentId: string, userId: string): Promise<void>
export async function getCommentsByPost(postId: string, page: number): Promise<PaginatedComments>
export async function updateComment(commentId: string, body: UpdateCommentInput): Promise<Comment>

interface CreateCommentInput { content: string; authorId: string }
interface PaginatedComments { items: Comment[]; total: number; page: number }

vs read_file: Full file = ~8,000 tokens. smart_outline = ~350 tokens. 95% savings.

Tool 3: smart_unfold — Precision Expand

After seeing the outline, Claude can expand just one function in full.

smart_unfold(
  filepath: "src/api/comments.ts",
  entity_name: "createComment",
  line_start: 15
)

Returns ~200 tokens — just that function's complete implementation.

---

8.2 Why AST Instead of grep?

Smart Explore uses Tree-sitter parsers to understand code syntax structure.

Dimension	grep	Smart Explore (AST)
Understands code structure	❌ No	✅ Knows functions, classes, interfaces
Returns	All matching lines (noisy)	Only code entities (precise)
Token cost	High	Low
Cross-file navigation	Search each file separately	One search covers entire directory

---

8.3 Token Comparison

For a 500-line src/api/comments.ts:

Method	Tokens	Information Gained
read_file	~8,000	All 500 lines
smart_outline	~350	4 function signatures + 3 type definitions
smart_unfold (1 function)	~200	One complete function implementation
outline + unfold 1 function	~550	Global structure + 1 function detail

Savings: 93% (550 vs 8,000)

For the entire src/api/ directory (20 files):

Method	Tokens
read_file all	20 × 8,000 = 160,000
smart_outline all	20 × 350 = 7,000
Savings	95.6%

---

Hands-On Exercise

1. Ensure the blog project has multiple API files
2. Ask Claude to understand the project:
   • "Walk me through all the files under src/api/ and what they do"
3. Watch Claude use outline first, then unfold only the functions it needs

---

Coming Up Next

Memory Search handles history, Smart Explore handles code. But when project history gets too long (500+ Observations), even search isn't precise enough. Next: Knowledge Agent — pack scattered memories into a queryable knowledge vault.

➡️ Episode 9: Skill 3 — Knowledge Agent