Performance Optimization
Making agents faster, more accurate, and less expensive through prompt and context tuning
Overview
An agent that produces correct output but takes 15 minutes and costs twelve dollars per session is not a tool anyone will use regularly. Performance optimization for agents means three things: making them faster (fewer iterations to reach a correct result), more accurate (higher first-attempt success rate), and less expensive (fewer tokens consumed per task). These goals reinforce each other -- an agent that finds the right files immediately is faster, more accurate, and cheaper than one that reads half the codebase searching for context. This lesson covers the practical techniques that improve all three dimensions.
The Three Dimensions of Agent Performance
Before optimizing, understand what you are optimizing for. Agent performance has three distinct dimensions, and different techniques target different dimensions.
Three dimensions of agent performance: Speed (fewer iterations, faster feedback loops, smaller context to process), Accuracy (higher first-attempt success rate, fewer rework cycles, better convention adherence), and Cost (fewer tokens per session, right model for the task, avoid redundant file reads). All three connect to an optimized agent at the center.
The good news: most optimizations improve all three simultaneously. A lean CLAUDE.md that gets the agent to the right files immediately is faster (less searching), more accurate (more relevant context), and cheaper (fewer tokens reading irrelevant files).
Optimization 1: Write a Lean CLAUDE.md
The CLAUDE.md is the single largest lever for agent performance. A bloated CLAUDE.md wastes tokens on every session and dilutes the agent's attention. A lean one focuses the agent immediately.
The problem with long CLAUDE.md files:
Every token in the CLAUDE.md is processed on every session. A 2,000-line CLAUDE.md with comprehensive documentation of every module, every convention, and every historical decision consumes context that could be used for actual code. Worse, critical instructions buried on line 1,800 receive less model attention than instructions on line 10.
How to slim it down:
The optimized version gives the agent everything it needs to start working and points it to deeper context only when relevant. Sub-directory CLAUDE.md files are loaded only when the agent navigates to those directories.
Optimization 2: Search-First File Access
One of the most wasteful agent behaviors is sequential file reading -- opening file after file looking for the right code. Each file read consumes tokens whether the content is relevant or not. The search-first approach uses targeted search to find relevant code before reading full files.
Sequential read vs search-first comparison: sequential reading loads file 1 (200 tokens), file 2 (350 tokens), file 3 (180 tokens), and finally file 4 (500 tokens, the relevant one) — consuming 1,230 total tokens. Search-first uses a grep search (50 tokens) to find the relevant code, then reads only file 4 (500 tokens) — consuming just 550 total tokens.
In the sequential approach, the agent consumes 1,230 tokens to find the relevant code. In the search-first approach, it consumes 550 tokens. Across an entire session, this difference compounds dramatically.
How to encourage search-first behavior:
Add explicit guidance in CLAUDE.md about how to find code efficiently.
Optimization 3: Batch Related Changes
Agents work most efficiently when they can make related changes in a single pass. Sending five separate tasks that each touch the same module wastes context on repeatedly reading the same files.
The key insight is that file reads are the largest token cost in most sessions. Any strategy that reduces the number of unique file reads reduces cost proportionally.
Optimization 4: Right-Size the Model
Not every task requires the most capable (and most expensive) model. Model selection based on task complexity is one of the highest-impact cost optimizations.
| Task Type | Recommended Model Tier | Why |
|---|---|---|
| Complex refactoring | Most capable | Requires understanding architecture and making coordinated changes |
| Feature implementation | Most capable | Needs to understand design intent and write new logic |
| Writing tests for existing code | Mid-tier | Pattern is clear: read function, write test. Less reasoning needed |
| Code formatting and linting fixes | Smallest viable | Mechanical transformation with explicit rules |
| Generating boilerplate | Mid-tier | Follows templates with minor adaptation |
| Documentation updates | Mid-tier | Reads code and describes it -- moderate reasoning |
Do not default to the cheapest model "to save money." An underpowered model that fails three times before you switch to a capable one costs more than running the capable model once. Right-sizing means matching the model to the task, not minimizing the model.
Optimization 5: Reduce Feedback Loop Latency
Every time an agent runs tests, waits for a linter, or builds the project, it is waiting. That wait time directly affects session duration and, in interactive sessions, developer patience. Faster feedback loops make agents more effective.
Practical techniques:
- Run only relevant tests -- instead of the full test suite, configure the agent to run tests related to the changed files. Most test runners support file-pattern or tag-based filtering
- Use incremental builds -- if the build system supports it, ensure the agent uses incremental compilation rather than clean builds
- Parallelize checks -- run linting, type checking, and tests in parallel rather than sequentially
- Cache dependencies -- ensure
node_modules, Go module cache, or Python virtual environments are pre-built so the agent does not reinstall dependencies on each session
Optimization 6: Avoid Redundant File Reads
Agents sometimes re-read files they have already read in the same session, especially during long sessions or when switching between tasks. While some re-reading is necessary (the file may have changed), much of it is waste.
Strategies to reduce redundant reads:
- Keep sessions focused -- one task per session means the agent builds context once and uses it throughout
- Structure tasks to minimize cross-cutting reads -- if a task touches three modules, provide the relevant context upfront rather than letting the agent discover it through exploration
- Use task descriptions that reference specific files -- "modify the
handleOrderfunction inapi/handlers/order.go" is more efficient than "find and modify the order creation endpoint"
Measuring Optimization Impact
You cannot optimize what you do not measure. Track these metrics before and after applying optimizations:
- Tokens per session -- total input and output tokens. This directly correlates with cost
- Session duration -- wall-clock time from start to completion. Affected by both token count and feedback loop speed
- First-attempt success rate -- percentage of sessions that produce usable output without retry. The most important accuracy metric
- Files read per session -- a proxy for context efficiency. Fewer files read for the same quality output means better optimization
Before vs after optimization: Before — 2,500 tokens/session average, 8 minutes average duration, 55% first-attempt success, 12 files read average. After applying lean CLAUDE.md, search-first, and task batching — 900 tokens/session, 3 minutes duration, 82% first-attempt success, 4 files read.
These numbers are illustrative, but the proportions are realistic. Teams that apply the techniques in this lesson consistently see 50-70% reductions in token consumption and 20-30 percentage point improvements in first-attempt success rate.
The Optimization Checklist
Apply these in priority order -- each one builds on the previous:
- Lean CLAUDE.md -- under 60 lines in root, details in sub-directory files
- Explicit file pointers -- tell the agent where to find code, do not let it search
- Search-first instructions -- teach the agent to grep before reading
- Batch related tasks -- one session per coherent change, not one session per file
- Right-size models -- match model capability to task complexity
- Fast feedback loops -- targeted tests, incremental builds, parallel checks
- Focused sessions -- one task per session, clear success criteria
Summary
Agent performance optimization targets three dimensions: speed, accuracy, and cost. The highest-impact technique is writing a lean, prioritized CLAUDE.md that directs the agent to the right files immediately. Search-first file access, task batching, model right-sizing, and fast feedback loops each contribute incremental improvements that compound across sessions. Measure tokens per session, first-attempt success rate, and files read per session to quantify your progress. The final lesson in this module -- and this entire academy -- looks forward: where is the agent-ready ecosystem heading, and what patterns are emerging?