2681 Agent Vs Manual Ec01fe01

Decision Framework: Agent vs Manual Read

Part of: Navigator v4.0 Education Layer Type: Decision Framework Use: Quick reference for choosing between agent search and manual file reading

Decision Tree

┌─────────────────────────────────────────┐
│ How many files are potentially          │
│ relevant to your question?              │
└──────────────────┬──────────────────────┘
                   │
         ┌─────────┴──────────┐
         │                    │
       1-2                  3+
         │                    │
         ▼                    ▼
┌──────────────────┐  ┌───────────────────┐
│ Do you know      │  │ Do you know       │
│ exactly which    │  │ exactly which     │
│ files?           │  │ files?            │
└────────┬─────────┘  └────────┬──────────┘
         │                     │
    ┌────┴────┐           ┌────┴────┐
    │         │           │         │
   YES       NO          YES       NO
    │         │           │         │
    ▼         ▼           ▼         ▼
┌────────┐ ┌──────┐ ┌──────────┐ ┌────────┐
│ READ   │ │ USE  │ │ USE      │ │ USE    │
│ MANUAL │ │ AGENT│ │ AGENT    │ │ AGENT  │
│ (3-6k) │ │ (3k) │ │ (4-6k)   │ │ (4-6k) │
└────────┘ └──────┘ └──────────┘ └────────┘

Decision Matrix

File Count Quick Reference

1-2 Files → Manual Read

When:

• You know exactly which files
• Files are small (<5k tokens each)
• Simple question about specific code

Example:

"Read AuthService.ts and show me the login method"

Cost: 3k tokens (one file)
Why manual: Direct, no overhead

3-5 Files → Agent (Usually)

When:

• Exploring related functionality
• Comparing implementations
• Understanding patterns across files

Example:

"Use agent to find how error handling works across the API layer"

Agent reads 4 files (12k if manual)
Returns summary: 4k tokens
Savings: 8k (67%)

6-10 Files → Agent (Always)

When:

• Architecture understanding
• Pattern discovery
• Multi-component interactions

Example:

"Use agent to explain the authentication flow through all components"

Agent reads 8 files (24k if manual)
Returns summary: 5k tokens
Savings: 19k (79%)

10+ Files → Agent (Required)

When:

• Codebase exploration
• Finding all usages
• System-wide patterns

Example:

"Use agent to find all files using the deprecated API"

Agent reads 25 files (75k if manual)
Returns summary: 6k tokens
Savings: 69k (92%)

Scenario-Based Decisions

Scenario 1: Understanding Specific Function

Question: "How does the processPayment() function work?"

Analysis:

• Files involved: 1 (PaymentService.ts)
• Know location: Yes
• Complexity: Simple

Decision: Manual Read

"Read src/services/PaymentService.ts and explain processPayment()"
Cost: 3k tokens

Scenario 2: Finding Implementation Pattern

Question: "How does error handling work in this project?"

Analysis:

• Files involved: Unknown, likely 5-10
• Know location: No
• Complexity: Pattern across codebase

Decision: Use Agent

"Use agent to find how error handling is implemented across the codebase"
Cost: 5k tokens (vs 30k manual)
Savings: 25k (83%)

Scenario 3: Comparing Two Approaches

Question: "What's the difference between AuthV1 and AuthV2?"

Analysis:

• Files involved: 2 implementations (4-6 files total)
• Know location: Yes (two directories)
• Complexity: Comparison needed

Decision: Use Agent

"Use agent to compare auth-v1/ vs auth-v2/ implementations"
Cost: 4k tokens (vs 18k manual)
Savings: 14k (78%)

Scenario 4: Debugging Specific Issue

Question: "Why is this test failing?" (test file open)

Analysis:

• Files involved: 1-2 (test + source)
• Know location: Yes
• Complexity: Focused debugging

Decision: Manual Read

"Read UserService.ts to understand why the test is failing"
Cost: 3k tokens

Scenario 5: Learning Codebase Architecture

Question: "How is this project structured?"

Analysis:

• Files involved: 20+ (entire codebase)
• Know location: No (exploration)
• Complexity: Very complex

Decision: Use Agent

"Use agent to explain the project architecture and main components"
Cost: 6k tokens (vs 80k+ manual)
Savings: 74k (93%)

Question Type Mapping

Specific Questions → Manual Read

Patterns:

• "Show me function X in file Y"
• "Read this specific file"
• "What does this code block do?"
• "Explain this function"

Why manual: Direct answer, no exploration needed

Exploratory Questions → Use Agent

Patterns:

• "How does X work across the system?"
• "Find all places that use Y"
• "Compare implementation A vs B"
• "Explain the architecture"
• "What pattern is used for Z?"

Why agent: Requires reading multiple files, benefits from summary

Token Cost Comparison

Manual Reading Pattern

File 1: 3k
File 2: 4k
File 3: 3k
File 4: 5k
File 5: 4k
────────────
Total: 19k tokens

Efficiency: 60% (used 3 files, read 5)
Waste: 7k tokens

Agent Search Pattern

Agent reads 5 files internally (not in your context)
Agent returns summary: 4k tokens
You load 1 specific file: 3k tokens
────────────
Total: 7k tokens

Efficiency: 100% (used all loaded content)
Savings: 12k tokens (63%)

When Agent Isn't Worth It

Case 1: Single Known File

❌ "Use agent to read AuthService.ts"
✅ "Read AuthService.ts"

Agent overhead: Not worth it for 1 file
Manual is faster: 3k vs 4k (agent has overhead)

Case 2: File Already Loaded

❌ "Use agent to re-analyze this file"
✅ "Based on AuthService.ts above, ..."

Agent cost: 3k to re-read
Manual cost: 0k (already in context)
Savings: Don't use agent

Case 3: Very Small Files

❌ "Use agent to read config.json (20 lines)"
✅ "Read config.json"

Agent overhead: ~2k (setup + summary)
Manual read: 0.5k (tiny file)
Manual wins: 4x more efficient

When Agent Shines

Case 1: Unknown File Locations

"Find all files that implement caching"

Without agent:
├── Guess which files (10 guesses)
├── Read each one (30k tokens)
└── Find 3 relevant files

With agent:
├── Agent searches all files
├── Returns 3 relevant files (4k summary)
└── You load 1 for details (3k)

Savings: 23k tokens (77%)

Case 2: Pattern Discovery

"How do different components handle validation?"

Without agent:
├── Read 15 components (45k)
├── Mentally compare patterns
└── Synthesize understanding

With agent:
├── Agent reads 15 components
├── Identifies 3 validation patterns (5k summary)
└── You understand immediately

Savings: 40k tokens (89%)

Case 3: Codebase Mapping

"Explain the data flow from API to database"

Without agent:
├── Read route files (12k)
├── Read service files (15k)
├── Read model files (10k)
├── Try to connect pieces
└── Total: 37k tokens

With agent:
├── Agent traces flow through all files
├── Returns data flow diagram in text (6k)
└── Clear understanding immediately

Savings: 31k tokens (84%)

Advanced Decision Factors

Factor 1: Context Already Full

Situation: Context at 65%

Decision Shift:

• Manual read (3-6k): Might push over 70% → Use agent (4k summary)
• Agent (4k summary): Safer, prevents context overflow

Rule: When context >60%, prefer agent even for 2-3 files

Factor 2: Iterative Exploration

Situation: Don't know what you're looking for exactly

Example:

"I need to understand how users are authenticated, but I'm not sure of the details"

Approach:
1. Agent: High-level summary (4k)
2. Review summary, identify key areas
3. Manual: Read 1-2 specific files (6k)

Total: 10k tokens
vs Reading all auth files blindly: 30k+ tokens
Savings: 67%

Factor 3: Time Sensitivity

Fast exploration:

• Agent: 30-60 seconds for summary
• Manual: 5-10 minutes reading multiple files

When time matters: Use agent for speed + token efficiency

Common Mistakes

Mistake 1: Agent for Everything

Wrong:

"Use agent to read this one specific file I'm looking at"
Cost: 4k (agent overhead)

Right:

"Read the specific file"
Cost: 3k (direct)

Fix: Use manual for 1-2 known files

Mistake 2: Manual for Everything

Wrong:

Read file 1 (3k)
Read file 2 (4k)
Read file 3 (3k)
... (10 more files)
Total: 40k tokens

Right:

"Use agent to find relevant files"
Agent summary: 5k tokens
Load 1 specific file: 3k
Total: 8k tokens

Fix: Use agent for 3+ files

Mistake 3: Not Leveraging Agent Summaries

Wrong:

Agent returns summary (4k)
Then: "Now read all those files manually" (20k)
Total: 24k

Right:

Agent returns summary (4k)
Decision: Summary is enough, or load 1 file for details (3k)
Total: 7k

Fix: Trust agent summaries, load details only if needed

Quick Reference Card

┌──────────────────────────────────────────┐
│ HOW MANY FILES?                          │
├──────────────────────────────────────────┤
│ 1 file (known)        → Manual Read      │
│ 1 file (unknown)      → Agent Search     │
│ 2 files (simple)      → Manual Read      │
│ 2 files (compare)     → Agent Search     │
│ 3-5 files             → Agent Search     │
│ 6-10 files            → Agent Search     │
│ 10+ files             → Agent Required   │
├──────────────────────────────────────────┤
│ QUESTION TYPE?                           │
├──────────────────────────────────────────┤
│ "Show me X"           → Manual Read      │
│ "How does X work?"    → Agent Search     │
│ "Find all Y"          → Agent Search     │
│ "Compare A vs B"      → Agent Search     │
│ "Explain arch"        → Agent Search     │
├──────────────────────────────────────────┤
│ CONTEXT USAGE?                           │
├──────────────────────────────────────────┤
│ <40%                  → Either works     │
│ 40-60%                → Prefer agent     │
│ >60%                  → Agent required   │
└──────────────────────────────────────────┘

Next Steps

Learn More

• PREPROCESSING-DECISION-TREE.md - Preprocessing vs LLM
• WHEN-TO-COMPACT.md - Context management
• TRY-THIS-AGENT-SEARCH.md - Hands-on practice

Related Guides

• PREPROCESSING-VS-LLM.md - Right tool principle
• TOKEN-OPTIMIZATION.md - Complete strategies

Bottom line: Use agents for 3+ files or exploratory questions. Use manual reads for 1-2 specific known files. When in doubt and context is high, use agent.