How to Save AI Agent Tokens When Working with Large Codebases: 5 Patterns

The problem: tokens burn away on exploration

AI agents are getting more deeply integrated into the development process — they no longer just generate functions, but explore projects, search for files, analyze architecture, and run tests. On large codebases, this creates an acute problem: a significant share of tokens gets spent before the first line of code is even written. Before making a small change, an agent might need to study the repository's structure, find the right service, read documentation, figure out conventions, and check how tests are organized. On the next task, part of this exploration gets repeated all over again. On a small project this goes unnoticed, but the bigger the repository, the more expensive it is to explore the system.

Attempts to feed the agent all the documentation at once, or to use a cheaper model, deliver either a small effect or simply shift the token spend somewhere else. The right approach is to treat token management as a context management problem — applying the principles of lazy loading, data locality, caching, and separation of concerns to an AI agent's information flow.

Five context optimization patterns

1. Minimize Permanent Context

The knowledge-hoarding trap always looks the same: you create an AGENTS.md or CLAUDE.md and start piling in more and more information. First the architecture and repository structure, then code-writing rules, service conventions, database quirks, testing, CI/CD, and integrations.

The problem: this entire set becomes permanent context. When modifying the billing service, the agent almost certainly doesn't need the rules for developing a mobile app — but if they're in the global context, the model receives them again and again. Global instructions should be a map of the project (where is the information?), not an encyclopedia (what should I tell you about?). A root-level AGENTS.md should point to where detailed instructions for auth, billing, database, and infrastructure live — everything else loads on demand.

2. Progressive Context

Knowledge gets organized in layers: global context → domain/service context → task-specific instructions → reference implementation → relevant source code. For a task like adding a new payment provider, the agent follows this path: AGENTS.md → services/payments/AGENTS.md → skills/add-payment-provider.md → existing provider implementation → relevant source files. For a mobile app, the path is entirely different; for infrastructure, a third path applies. Instead of 20,000 tokens of "everything about the project," you get: global context (500) + service context (700) + task instructions (600) + reference (800) + source files (2500). Most of the project's knowledge exists separately and only enters the context when it becomes relevant.

3. Reduce Exploration

Even with a small permanent context, there remains a major cost driver: exploring the codebase. The agent needs to figure out where the payment handlers are, which service publishes events, which message broker is used, where the consumers live, how notifications are created, where the templates are, and how all of it is tested. A well-organized repository provides entry points: a project map with sections (HTTP handlers: services//handlers/, business logic: services//domain/, and so on), golden examples (for a new message consumer, a link to services/orders/consumers/order-created/ shows the structure, naming, error handling, logging, layer interaction, and testing), and search-before-read (search first via rg, git grep, or LSP tools, then read).

4. Reuse Knowledge

When an agent investigates how an order payment works, it uncovers the chain: HTTP request → order service → billing service → payment provider → payment event → message broker → order consumer. To do this, it reads hundreds of files. Then the session ends, a new task arrives a week later, and a new agent starts the exploration from scratch.

This knowledge duplication needs to be eliminated. If the exploration revealed an important and stable feature of the system, it's worth saving the result in docs/payment-flow.md with a brief description, a list of files, and a link to a reference implementation.

The next AI session will start with a few hundred tokens of structured description instead of re-reading the files. Useful knowledge can be stored in AGENTS.md, service instructions, documentation, task-specific skills, architecture notes, golden examples, or code comments, depending on scope.

The result is a cycle: expensive discovery → structured knowledge → cheap future retrieval.

5. Keep Context Clean

The flip side of the previous approach: if every useful discovery gets saved, documentation keeps growing and context pollution sets in — outdated instructions, irrelevant examples, and forgotten conventions coexist alongside new ones. Context needs to be cleaned up regularly: deleting outdated information, updating examples, and removing duplication. Just as with code, it's better to delete stale documentation than to leave it in place with a comment explaining it's outdated.

All five patterns work together: minimize the permanent context, load knowledge in layers as needed, help the agent explore less through clear entry points, don't repeat expensive exploration twice, and remove outdated information. The result is lower token spend — not through cheaper models, but through managing what information the agent sees and when.