I Tracked My Claude Code Token Usage Across 6 Projects. Here's What I Found.

Last Tuesday I opened a project I hadn't touched in two weeks. Simple task: add a webhook endpoint for Stripe subscription cancellations. I'd done this exact thing before — different project, same stack, same pattern. Should have taken ten minutes.

I watched Claude spend 8,000 tokens before it wrote a single line of code. Reading my directory structure, opening files it had already seen, re-learning my naming conventions, re-discovering I use Prisma, re-figuring out where my API routes live. At Opus 4 pricing, that's roughly $0.12 — just to remember what it already knew two weeks ago. For one feature. On one project.

I'd been vaguely aware that Claude Code felt expensive. But I'd never measured where the tokens actually went. So I started.

Six projects. Three weeks. Every session logged.

The number that made me take this seriously

Here's what I found when I broke down token usage by session type:

60–70% of Claude Code token spend — on a codebase that hasn't changed — goes to orientation. Reading files. Inferring patterns. Figuring out where things live. Claude doesn't remember previous sessions. Every return is a cold start.

You're not paying for code generation. You're paying for code comprehension, over and over again.

The fix lives in the repo, not the prompt

I tried the obvious things first. Longer prompts. Pasting context manually. Claude's built-in memory.

Better prompts shaved orientation from 10,000 tokens to maybe 6,000. Still 6,000 tokens wasted. Pasting code manually hit context window limits, got stale after refactors, and made me do Claude's job for it. The built-in memory remembered that I prefer TypeScript. It did not remember my database schema.

After a few weeks of this, I realized: the problem isn't my prompting. It's structural. Claude starts every session blind because nothing in the project tells it what it needs to know. The fix has to live in the repo itself.

The .claude/ directory

Add a .claude/ folder to your project root. It contains files written specifically for Claude to read at the start of every session — not documentation for humans, but compressed, actionable context for Claude.

CODEBASE.md

The single highest-impact file. A ~2,000 token map of your entire project: directory tree with one-line descriptions, data model overview, API routes, key integrations.

Without it, Claude burns 30,000–40,000 tokens building this mental model through exploration. With it, Claude reads one file and starts building. The whole point is replacing blind discovery with a map.

.claude/skills/

Task instructions written for your specific codebase. Not “how to add an API route” — how to add one in this project, with these imports, following these conventions.

A real example:

Eight lines. But those eight lines prevent Claude from guessing your patterns, using the wrong imports, or structuring the file differently than everything else in your codebase. Each skill takes ten minutes to write and saves thousands of tokens every time Claude executes it.

.claude/memory/

Three files Claude reads at the start of every session:

architecture.md — What the system does, how data flows, your key services. Compressed, not comprehensive. Enough for Claude to make correct decisions without reading everything.

conventions.md — Naming patterns, file structure, import rules, error handling. The stuff that makes code look like it belongs in your project.

decisions.md— Why you chose X over Y. This one is underrated. Without it, Claude will periodically suggest switching from Prisma to Drizzle, or from Supabase Auth to NextAuth, or from Resend to SendGrid. It's trying to be helpful — but if you've already made these decisions, decisions.md closes those loops permanently.

.claude/patterns/

Reference implementations from your actual production code. Instead of Claude guessing how to implement RBAC from its training data, it reads exactly how you've done it — with your auth library, your database client, your middleware pattern.

The results

Two weeks, both setups running in parallel, similar features across all six projects:

Same work shipped. 4x cost difference. The orientation token count dropped from 8,000–12,000 per session to under 2,000.

One pattern worth noting: newer models seem to make this gap larger, not smaller. They explore more thoroughly, consider more alternatives before committing. Better reasoning — but more tokens spent on orientation. The efficiency problem doesn't self-correct with model updates. If anything, it compounds.

How to build this yourself

It takes 2–3 hours to set up well. It pays back from your second session.

CODEBASE.md first. Start with your directory tree. Add one-line descriptions for every important directory and file. Include your data model (table names and key fields, not full schemas). List your API routes. Target ~2,000 tokens — enough to replace blind exploration, short enough that Claude reads it immediately.

One skill file next.Pick the task you do most often. Write the steps as you'd explain them to a good developer on their first day: exact directories, exact imports, exact patterns. Reference real files. Once you have one working well, add skills for your other common tasks. Most projects need 4–6 to cover 90% of daily work.

Three memory files last. architecture.md under 500 tokens. conventions.md under 400. decisions.md: one sentence per technology choice. These have no word count trick — just be honest about what Claude keeps getting wrong and put the answers here.

Test it.Open a fresh session, reference CODEBASE.md first, run a task you have a skill for, compare token counts. If Claude still explores after reading your skill files, the instructions aren't specific enough. Tighten until it doesn't.