---
id: daily-smart-explore
name: "smart-explore"
url: https://skills.yangsir.net/skill/daily-smart-explore
author: thedotmack
domain: ai-software-architecture-engineering
tags: ["code-structure-exploration", "ast-parsing", "static-code-analysis", "code-navigation", "programmatic-code-analysis"]
install_count: 2700
rating: 4.40 (42 reviews)
github: https://github.com/thedotmack/claude-mem
---

# smart-explore

> 利用抽象语法树（AST）解析技术，对代码进行结构化探索与分析，深入理解代码逻辑与架构，提升开发效率。

**Stats**: 2,700 installs · 4.4/5 (42 reviews)

## Before / After 对比

### 代码结构探索与理解效率对比

## Readme

# smart-explore

# Smart Explore

Structural code exploration using AST parsing. **This skill overrides your default exploration behavior.** While this skill is active, use smart_search/smart_outline/smart_unfold as your primary tools instead of Read, Grep, and Glob.

**Core principle:** Index first, fetch on demand. Give yourself a map of the code before loading implementation details. The question before every file read should be: "do I need to see all of this, or can I get a structural overview first?" The answer is almost always: get the map.

## Your Next Tool Call

This skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of:

```
smart_search(query="<topic>", path="./src")    -- discover files + symbols across a directory
smart_outline(file_path="<file>")              -- structural skeleton of one file
smart_unfold(file_path="<file>", symbol_name="<name>")  -- full source of one symbol

```

Do NOT run Grep, Glob, Read, or find to discover files first. `smart_search` walks directories, parses all code files, and returns ranked symbols in one call. It replaces the Glob → Grep → Read discovery cycle.

## 3-Layer Workflow

### Step 1: Search -- Discover Files and Symbols

```
smart_search(query="shutdown", path="./src", max_results=15)

```

**Returns:** Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2-6k tokens)

```
-- Matching Symbols --
  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
  method WorkerService.shutdown (services/worker-service.ts:846)

-- Folded File Views --
  services/infrastructure/GracefulShutdown.ts (7 symbols)
  services/worker-service.ts (12 symbols)

```

This is your discovery tool. It finds relevant files AND shows their structure. No Glob/find pre-scan needed.

**Parameters:**

- `query` (string, required) -- What to search for (function name, concept, class name)

- `path` (string) -- Root directory to search (defaults to cwd)

- `max_results` (number) -- Max matching symbols, default 20, max 50

- `file_pattern` (string, optional) -- Filter to specific files/paths

### Step 2: Outline -- Get File Structure

```
smart_outline(file_path="services/worker-service.ts")

```

**Returns:** Complete structural skeleton -- all functions, classes, methods, properties, imports (~1-2k tokens per file)

**Skip this step** when Step 1's folded file views already provide enough structure. Most useful for files not covered by the search results.

**Parameters:**

- `file_path` (string, required) -- Path to the file

### Step 3: Unfold -- See Implementation

Review symbols from Steps 1-2. Pick the ones you need. Unfold only those:

```
smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")

```

**Returns:** Full source code of the specified symbol including JSDoc, decorators, and complete implementation (~400-2,100 tokens depending on symbol size). AST node boundaries guarantee completeness regardless of symbol size — unlike Read + agent summarization, which may truncate long methods.

**Parameters:**

- `file_path` (string, required) -- Path to the file (as returned by search/outline)

- `symbol_name` (string, required) -- Name of the function/class/method to expand

## When to Use Standard Tools Instead

Use these only when smart_* tools are the wrong fit:

- **Grep:** Exact string/regex search ("find all TODO comments", "where is `ensureWorkerStarted` defined?")

- **Read:** Small files under ~100 lines, non-code files (JSON, markdown, config)

- **Glob:** File path patterns ("find all test files")

- **Explore agent:** When you need synthesized understanding across 6+ files, architecture narratives, or answers to open-ended questions like "how does this entire system work end-to-end?" Smart-explore is a scalpel — it answers "where is this?" and "show me that." It doesn't synthesize cross-file data flows, design decisions, or edge cases across an entire feature.

For code files over ~100 lines, prefer smart_outline + smart_unfold over Read.

## Workflow Examples

**Discover how a feature works (cross-cutting):**

```
1. smart_search(query="shutdown", path="./src")
   -> 14 symbols across 7 files, full picture in one call
2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
   -> See the core implementation

```

**Navigate a large file:**

```
1. smart_outline(file_path="services/worker-service.ts")
   -> 1,466 tokens: 12 functions, WorkerService class with 24 members
2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
   -> 1,610 tokens: the specific method you need
Total: ~3,076 tokens vs ~12,000 to Read the full file

```

**Write documentation about code (hybrid workflow):**

```
1. smart_search(query="feature name", path="./src")    -- discover all relevant files and symbols
2. smart_outline on key files                           -- understand structure
3. smart_unfold on important functions                  -- get implementation details
4. Read on small config/markdown/plan files             -- get non-code context

```

Use smart_* tools for code exploration, Read for non-code files. Mix freely.

**Exploration then precision:**

```
1. smart_search(query="session", path="./src", max_results=10)
   -> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...
2. Pick the relevant one, unfold it

```

## Token Economics

Approach
Tokens
Use Case

smart_outline
~1,000-2,000
"What's in this file?"

smart_unfold
~400-2,100
"Show me this function"

smart_search
~2,000-6,000
"Find all X across the codebase"

search + unfold
~3,000-8,000
End-to-end: find and read (the primary workflow)

Read (full file)
~12,000+
When you truly need everything

Explore agent
~39,000-59,000
Cross-file synthesis with narrative

**4-8x savings** on file understanding (outline + unfold vs Read). **11-18x savings** on codebase exploration vs Explore agent. The narrower the query, the wider the gap — a 27-line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file.
Weekly Installs193Repository[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)GitHub Stars37.6KFirst SeenFeb 26, 2026Security Audits[Gen Agent Trust HubPass](/thedotmack/claude-mem/smart-explore/security/agent-trust-hub)[SocketPass](/thedotmack/claude-mem/smart-explore/security/socket)[SnykPass](/thedotmack/claude-mem/smart-explore/security/snyk)Installed oncodex189gemini-cli187kimi-cli187amp187github-copilot187opencode187

---
*Source: https://skills.yangsir.net/skill/daily-smart-explore*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-smart-explore/markdown*