Claude Code and Codex: How Three Markdown Files Cut Token Waste

AI coding agents burn through context not because they give bad answers, but because they spend almost all their time hunting for the right place in the code. Even with a million-token window, they re-crawl directories, re-read familiar files and re-check servers as if seeing the project for the first time. In one example from the breakdown, a simple question about payments cost the agent more than 80 thousand tokens and 15-plus tool calls, while the answer itself took about 800 tokens.

Almost the entire budget went to navigation, not reasoning. This isn't a quirk of Claude Code; it's a general limitation of today's coding agents. Cursor, Codex and Gemini CLI work the same way: without a map of the workspace, they open every new session with reconnaissance.

With a single project, that's tolerable. But when a developer has dozens of repositories, VPSes and staging environments, the agent first greps the home directory, finds similar files in neighboring projects, reads them, realizes it took a wrong turn, and starts another round of searching. In a real example, a question about payment methods in one bot turned into a search across several projects, repeated reads of six files and even an SSH check of a server config.

This mode isn't just expensive, it's fragile: the model spends its effort on orientation and easily misses the relevant code. The author examines three popular approaches usually offered as a cure. The first is RAG and vector search.

It's good at finding semantically similar snippets but poor at understanding project structure: it may return chunks mentioning auth, login and token, yet fail to reconstruct the exact dependency chain between middleware, refresh logic and JWT configuration. RAG also needs its own infrastructure, an index and reindexing, and every query adds latency. The second path is static analysis and a dependency graph built with AST and tree-sitter.

That's useful inside a single repository but nearly useless at the portfolio level, where the question isn't only how a function works but where the service lives, which server runs it and what its status is. The third option is keeping a CLAUDE.md in every project.

That helps, but only after the agent has already figured out which project to go to. Instead, the author proposes a hierarchical context that guides the agent top-down. Level zero is a global project map: a short table of names, paths, servers and statuses that is automatically loaded into every session.

Level one is a CLAUDE.md at the root of each project, covering the stack, key files, deploy commands, service name and logs. Between them, you can add an intermediate layer such as Graphify if the codebase is large and you need a precise graph of relationships.

As a third markdown layer, the author suggests storing past sessions and engineering decisions as markdown files with YAML frontmatter, so the agent can recall what was already discussed, which files changed, and what debugging or payment decisions were made a week earlier. The idea is simple: map first, then the project description, then memory of past discussions, and only after that the source code. Measurements show the gain is practical, not cosmetic.

For a question about project architecture, the blind agent needed 12 tool calls versus one with the hierarchy in place. For a question about which projects use a specific library, blind mode made 44 calls, scanned the whole disk and still missed one of the three relevant projects; the hierarchy got there in two targeted queries and gave a complete answer. Deployment shows an even bigger effect: without structure, the agent read configs and went over SSH, while with a properly filled-in CLAUDE.

md it answered straight from context with no additional calls at all. The key takeaway is that better-organized context improves not only speed and token savings but also answer accuracy. Why does this work better than a typical RAG pipeline?

Because markdown files give the agent zero latency, predictability and easy updates. The developer decides what matters about a project instead of hoping a ranker pulls the right chunks from an index. If the deploy changes or a service moves, you fix one line.

Scaling looks sensible too: the project map takes about 2 KB, and fifteen project files at 5 KB each add up to less than 80 KB of structured context instead of hundreds of kilobytes of raw source. Amid all the talk of million-token context windows, this matters: more tokens aren't always better. Irrelevant information dilutes the model's attention, and the lost-in-the-middle effect hasn't gone away.

The main conclusion of the breakdown is that the token problem in coding agents usually calls not for pricier models or a more complex stack, but for context discipline. A global project map, a good CLAUDE.md and saved session memory can be put together in literally ten minutes, and the payoff is immediate: less blind searching, fewer repeats, fewer errors and a shorter path from question to the right file.