SMART Workflow Guide

June 12, 2026 · View on GitHub

The SMART workflow is the recommended process for analyzing code using AI assistants with Tree-sitter Analyzer.

What is SMART?

SMART is an acronym for the five-step AI-assisted code analysis workflow:

S - Set: Set the project root directory
M - Map: Map and locate target files
A - Analyze: Analyze code structure
R - Retrieve: Retrieve specific code sections
T - Trace: Trace dependencies and relationships

Why SMART?

Traditional approaches to AI code analysis have limitations:

Problem	SMART Solution
Token limits prevent reading large files	Structured analysis before code extraction
AI struggles with unknown codebases	Systematic file discovery and mapping
Context gets lost in long conversations	Step-by-step workflow with clear checkpoints
Inefficient back-and-forth	Optimized tool usage sequence

Step-by-Step Guide

Quick CLI Workflow Pack

If you want the workflow as a structured, copy-pasteable command pack, ask the CLI before opening a new queue item:

uv run tree-sitter-analyzer agent-skills --format json
uv run tree-sitter-analyzer parser-readiness --format json
uv run tree-sitter-analyzer agent-workflow --format json
uv run tree-sitter-analyzer agent-workflow examples/BigService.java --format json

The pack includes current_phase, phase_order, current_step, and recommended_commands. Without a target file the current phase is set; with a target file it starts at analyze, because the agent already has a queue head and should move straight to health, edit-risk, retrieval, and trace commands instead of remapping the whole project. Targeted packs also include agent_summary.queue_ledger_command, a scoped change-impact command that separates current-queue files from out-of-scope dirty files for handoffs.

Use agent-skills before agent-workflow when the queue item may benefit from a project-local skill. It reports each skill's trigger text, read order, support files, scripts, context needs, side effects, completion-guidance gaps, and a validation summary that separates blocking metadata gaps from caution-level completion gaps and optional handoff polish. MCP callers can use the matching list_agent_skills and get_agent_workflow tools when they need the same flow without leaving the MCP surface. Use parser-readiness or advise_parser_readiness before starting a new language plugin so the queue begins with parser dependency, loader, plugin, fixture, and upstream parser-risk gaps already named.

S - Set Project (First Step)

Purpose: Establish the security boundary and project context.

How to do it:

The project root is configured at server startup. Use either:

Environment variable: TREE_SITTER_PROJECT_ROOT=/path/to/your/project
CLI flag: --project-root /path/to/your/project

Why it matters:

Enables security boundary protection
All subsequent operations are relative to this path
Prevents accidental access to files outside the project

M - Map Target Files

Purpose: Locate and identify files to analyze.

Scenario 1: Unknown file location

Find all Java files containing "BigService" in the project

The AI will use search action=grep to locate relevant files.

Scenario 2: Known file path

I want to analyze the file examples/BigService.java

Scenario 3: Discover project structure

List all Python files in the src directory

Best practices:

Start broad, then narrow down
Use file patterns when you know naming conventions
Combine file and content search for precision

A - Analyze Structure

Purpose: Understand file scale and organization before diving into code.

Example request:

Please analyze the structure of examples/BigService.java, I want to know how big this file is and what main components it contains

The AI will call structure action=analyze and return:

{
  "file_path": "examples/BigService.java",
  "language": "java",
  "metrics": {
    "lines_total": 1419,
    "lines_code": 906,
    "lines_comment": 246,
    "lines_blank": 267,
    "elements": {
      "classes": 1,
      "methods": 66,
      "fields": 9,
      "imports": 8,
      "packages": 1,
      "total": 85
    },
    "complexity": {
      "total": 348,
      "average": 5.27,
      "max": 15
    }
  }
}

Key insights:

Total line count helps estimate analysis scope
Element counts show code organization
Complexity metrics identify potentially problematic areas

R - Retrieve Key Code

Purpose: Extract and examine specific code sections.

Scenario 1: View structure table

Please generate a detailed structure table for examples/BigService.java

Scenario 2: Extract by line range

Please extract lines 93-106 from examples/BigService.java

Scenario 3: Query specific elements

Show me all public methods in examples/BigService.java

Best practices:

Start with structure table to identify targets
Extract small, focused code sections
Use queries with filters for precision

T - Trace Dependencies

Purpose: Understand relationships and call chains.

Scenario 1: Find related methods

Find all methods related to authentication in examples/BigService.java

Scenario 2: Locate entry points

Where is the main method in this file? What does it do?

Scenario 3: Track method calls

Which methods call the authenticateUser method?

Best practices:

Trace from entry points to understand flow
Use content search to find callers
Combine multiple searches for complete picture

Complete Example Session

Here's a complete SMART workflow session:

User:

I want to understand the large file examples/BigService.java:
1. How big is it? What main features does it contain?
2. How is the authentication feature implemented?
3. What public API methods are available?

AI Response (Following SMART):

Step 1 (Set): (Assumed already set or will prompt)

Step 2 (Map): Located file at examples/BigService.java

Step 3 (Analyze):

File has 1419 lines total
Contains 1 class with 66 methods and 9 fields
Average complexity: 5.27

Step 4 (Retrieve):

Authentication is handled by authenticateUser method (lines 141-172)
Uses session-based authentication with configurable timeouts

Step 5 (Trace):

Found 19 public methods available as API
Authentication is called from the main method during initialization

Language-Specific Examples

Web Development (HTML/CSS)

I want to analyze the HTML structure of index.html:
1. What HTML elements are present?
2. What CSS rules are defined?
3. How are elements classified?

AI will:

Extract HTML elements with tag names and attributes
Analyze CSS selectors and properties
Generate classification tables (structure, media, form)

Database Development (SQL)

I want to analyze the database schema in sample_database.sql:
1. What tables, views, and stored procedures are defined?
2. What are the relationships between database objects?
3. Show me the database structure in professional format.

AI will:

Extract all SQL elements (tables, views, procedures, triggers)
Display database-specific terminology
Generate professional documentation

Best Practices

1. Natural Language First

Describe your needs in plain language:

✅ Good: "I want to understand how user authentication works in this project"
❌ Avoid: "Call analyze_code_structure on auth.py with format=full"

2. Start High, Go Deep

Begin with overview, then drill down:

1. "What does this project contain?"
2. "What files handle authentication?"
3. "Show me the login function"
4. "Extract the password validation logic"

3. Combine Steps When Appropriate

For simple cases, you can combine steps:

"Analyze src/auth.py and show me all public methods"

4. Use Checkpoints

For complex analysis, verify understanding:

"Before we continue, let me confirm: this file has 3 main classes - UserService, AuthService, and SessionManager. Is that correct?"

5. Optimize for Large Files

For files > 500 lines:

1. Always analyze structure first
2. Use table compact for overview
3. Extract specific sections, not whole file
4. Query specific elements with filters

Tool Reference

Workflow Step	Primary MCP Tool	CLI Equivalent
Set	`TREE_SITTER_PROJECT_ROOT` env var (server startup)	`--project-root /path`
Map	`project action=files`, `search action=grep`, `project action=parser`	`list-files`, `find-and-grep`, `parser-readiness`
Analyze	`structure action=analyze`, `health action=scale`, `health action=file`	`--structure`, `--metrics-only`, `--file-health`
Retrieve	`structure action=read`, `search action=query`	`--partial-read`, `--query-key`
Trace	`search action=content`, `health action=deps`, `edit action=impact`, `edit action=safe`	`search-content`, `--dependencies`, `--change-impact`, `--safe-to-edit`

Troubleshooting

"File too large to analyze"

Use incremental approach:

Check scale with check_code_scale
Use --structure for overview
Query specific elements instead of full analysis

"Can't find the file"

Use discovery tools:

list_files with broad pattern
find_and_grep with content search
Check file extension and directory

"Results are too verbose"

Apply optimization:

Use suppress_output with output_file
Apply filters to narrow results
Use summary_only or total_only options