Optimizing Token Usage Practices

Token Optimization for Coding Agents — Three-Layer Reference

Token spend on agentic coding workflows compounds fast — through context re-sent every turn, tool output bloat, and code architecture that forces agents to read more than they need. The list below consolidates the practices that actually move the needle, from API-level mechanics down to how you structure your codebase.

Core principle

• Treat context as a finite, precious resource — the goal is the smallest set of high-signal tokens that gets the job done, not the most complete one.

Layer 1 — Agent/Platform Mechanics

Set once, at the system level. Applies uniformly across every session; a developer rarely touches these turn-by-turn.

• Keep the request prefix stable (tools → system prompt → static context → variable tail) so prompt caching actually hits.
• Avoid mid-session MCP config churn — server connect/disconnect is the most common silent cache-buster.
• Use 1-hour cache TTL for long-lived main-agent loops; leave short-lived/one-shot subagent calls on the 5-minute default.
• Enable MCP “code mode” once running 3+ servers or heavy tools (search, docs, DB).
• Keep toolsets small, non-overlapping, and clearly scoped.
• Design multi-agent setups with clean, isolated context windows per subagent — but only split when the boundary genuinely reduces total context moved, since decomposition itself carries token overhead.
• Route by model tier (Haiku/Sonnet/Opus) based on task complexity, built into the harness rather than decided per-query.
• At team scale, sit a gateway/router layer (caching, model routing, observability) in front of raw API calls.

Layer 2 — Agent Operation (how you drive a session)

Behavioral. Same underlying agent can cost 3x more or less depending on discipline here — this is on the developer, every session.

• Delegate verbose work (tests, logs, doc reads) to subagents so only a summary lands in the main thread.
• Cap thinking budget (/effort, MAX_THINKING_TOKENS) when deep reasoning isn’t needed.
• Run /compact deliberately at phase boundaries — don’t just wait for auto-compact.
• Use /clear, not just /compact, when switching to an unrelated task.
• Extract large file/log reads to disk; have the agent report a path + one-line summary instead of piping everything into context.
• Use plan mode to catch an over-broad approach before it executes, not after.
• Audit and disable unused MCP servers regularly.
• Batch anything non-interactive.
• Check /usage / /cost periodically rather than assuming.

Layer 3 — Codebase Architecture (the target, not the tool)

Orthogonal to the agent entirely — good engineering with or without AI, but doubly rewarded here since it shrinks what any agent ever needs to load.

• Apply SRP: small, single-purpose classes/functions let an agent read only what’s relevant instead of a whole God Function.
• Keep coupling low (DIP/ISP) — high fan-out drags a wide dependency graph into context for even a small change.
• Avoid Bloaters (Long Method, Large Class) — they blow past file-view truncation limits, invalidate more cache per edit, and dilute attention even when they still technically fit.
• Don’t over-atomize either — fragmenting one behavior across too many tiny files trades a size tax for an indirection tax. Aim for locality of behavior, not minimum size.
• Organize hierarchically by feature/domain so one task touches a small, co-located set of files.

Closing

The three layers compound rather than substitute for each other: platform mechanics set the ceiling on efficiency, operational discipline determines whether you actually reach it session to session, and codebase architecture determines how much work either layer even has to do in the first place. In practice, Layer 3 is the one teams skip because it doesn’t look like an “AI cost” problem — but it’s also the one that keeps paying off silently in every future session, agent, and tool that ever touches the code.

Tool-Specific Implementation Guide

This guide provides detailed implementation strategies for each of the five coding agent tools, showing how to map the three layers to platform-specific mechanics. Each section includes practical, copy-pasteable examples from real-world configurations.

The Coding Agents landscape, in one table

Three details worth flagging because they’re easy to get wrong: Claude Code only gained AGENTS.md support in spring 2026 and still treats CLAUDE.md as the richer format for anything Claude-specific — don’t assume parity. On any machine running both Google’s Gemini CLI and Antigravity CLI, both currently write to the same ~/.gemini/GEMINI.md path, which silently pollutes one tool’s context with the other’s rules unless you separate them deliberately. And Cursor is the only tool here where the scoped rule (glob-matched or agent-decided) is the primary mechanism rather than an optional extra layered on top of one flat file — treating .cursor/rules/ like a second CLAUDE.md and writing one giant always-apply rule defeats the entire point of the format.

Tool-Specific Implementation Guides

This guide provides detailed implementation strategies for each of the five coding agent tools, showing how to map the three layers to platform-specific mechanics. Each section includes practical, copy-pasteable examples from real-world configurations.