Claude Code · Series · Part 3 of 3

Fewer tokens, faster onboarding: making CLAUDE.md pay for itself

By now you have a CLAUDE.md. Two questions remain. Does it really save tokens, or does it just add more? And can it help when you join a new project or start a new feature? The honest answers: yes, if you keep it lean, and yes, and this is where I find it most valuable.

1. Tokens and where they go

Recall from Part 2 that everything Claude sees is text, counted in tokens (short chunks of roughly three-quarters of a word). Your usage allowance, the speed of replies and the size of the context window are all measured in them. A session spends tokens in four places:

2. How to check what you are spending

Saving tokens only works if you can see them. Claude Code has several built-in views, from a quick glance to a detailed breakdown. Everything below comes from the official Manage costs effectively guide.

Where to look

Reading /usage

> /usage

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output,
                       940.0k cache read, 50.0k cache write ($0.55)

• Input and output are the tokens you send and the tokens Claude writes. Output costs more per token (Part 4 has the prices).
• Cache read is repeated content (like CLAUDE.md and earlier conversation) re-read at the cheaper cached rate. Notice it is by far the biggest number: a long session mostly pays to re-read its own history.
• Cache write is new content being stored for reuse.
• It is an estimate. Claude Code works the cost out locally from token counts at list price. For authoritative billing on an API account use the Console. On a Pro or Max subscription your usage is included in the plan, so the dollar figure is not what you are billed; look at the plan usage bars instead.
• It resets on /clear. The next session starts again from $0.
• Newer versions add a “Prompt cache” line showing how many requests hit the cache and whether it is currently warm.

A worked estimate you can do by hand

You can check the order of magnitude yourself with the prices from Part 4. Suppose one request sends 100,000 input tokens and gets 5,000 tokens back from Sonnet 5.5 ($2 per million input, $10 per million output), with nothing cached:

input : 100,000 / 1,000,000 x $2  = $0.20
output:   5,000 / 1,000,000 x $10 = $0.05
total                             = $0.25   (list price, no caching)

Real sessions are cheaper than this per request because most of the input is a cache read, and costlier overall because Claude Code sends the whole conversation with every request and makes many requests per task. This is only an illustration of how the numbers combine, not a prediction of your bill.

What typical spend looks like

The official guide says that across enterprise deployments the average is around $13 per developer per active day and $150 to $250 per developer per month, with 90% of users below $30 per active day. It stresses that costs vary widely with model choice, codebase size, running several instances and automation, and suggests starting with a small pilot group to find your own baseline.

Why usage climbs in a long session

• Long context: Claude Code sends your full conversation with every request, so even a one-line question late in a long session draws on the whole history.
• Cache misses: the first message after a break longer than the cache lifetime reprocesses everything. The lifetime is about an hour on a subscription and five minutes by default on an API key.
• Background and parallel work: scheduled tasks, subagents and agent teammates send their own requests, each with their own context.
• Compaction itself: /compact has to read the conversation it summarises, so compacting a huge context is a large request. When you want a clean start, /clear costs nothing.

The “Habits that save more” section below turns these into actions. For the plan-limit breakdown, behaviour flags (long context, cache misses) appear in /usage when one accounts for 10% or more of your recent usage, with a tip to reduce it. If you hit a limit message such as “You've hit your session limit”, that is a seat-based usage window on a subscription plan, and the message tells you when it resets.

3. How CLAUDE.md saves tokens

Think about what Claude does on a project it has never seen. To answer “how do I run the tests?” it must search, open the build files, read the README, maybe try a wrong command first. Each step reads files (tokens in), reasons (tokens out), and adds to the conversation. A one-line note in CLAUDE.md replaces all of that.

Four separate savings add up:

• No re-explaining. You stop typing the same background into every session, and Claude stops spending a turn confirming it.
• Less blind exploration. A folder map lets Claude open the right file first instead of reading five wrong ones.
• Fewer wrong turns. A recorded gotcha prevents an attempt, a failure and a retry.
• Cheaper to re-read. Claude Code uses prompt caching: content that is repeated at the start of every request, such as your CLAUDE.md, is re-read at a lower cached rate. The cache has a limited lifetime (the docs give about an hour on a subscription and five minutes by default on an API key), so the first message after a long break reprocesses the whole context at full price. See Manage costs effectively.

4. Does Claude get better after 10 days?

This is the question I get asked most, so let me answer it straight. No, Claude does not learn from your usage. The model is fixed. Working with it for ten days does not change it, and on day 10 a new session starts as blank as on day 1, apart from the files you have written down.

Yet day 10 can feel cheaper and faster. The difference is not in Claude, it is in your notes and your habits.

What does and does not get faster

So a task takes less time not because each reply streams faster, but because it needs fewer replies. A large, stale context does the opposite: it makes everything slower, whatever day it is.

Things that do not give you savings

• Resuming an old conversation. Claude Code can reopen a previous session (for example with claude --continue or --resume). That brings the old text back into the window, so it usually costs more tokens, not fewer. On Pro and Max, resuming a big session after a long break offers to continue from a summary, which is cheaper but keeps only what the summary kept. Resuming is useful for continuity, not for saving.
• Plan mode on its own. The plan lives in the conversation and disappears with it. To keep it, save it to a file and link it from CLAUDE.md (section 8).
• Automatic memory. Claude can save notes for a project in a memory folder under ~/.claude/projects/ (Part 2, section 3). It is useful, but it is still saved text being read back in, not the model learning. The start of its MEMORY.md index (up to 200 lines or 25 KB) is loaded every session, so it takes up context like any other file. Review it now and then, and delete notes that are wrong or stale.

A two-minute end-of-day habit

1. Write down what surprised you. A wrong turn, a command that failed, a rule you had to repeat. Add it to CLAUDE.md or the feature note.
2. Delete one stale line. Anything that is no longer true or no longer needed.
3. Save the plan, not the chat. If tomorrow continues today's work, write a handoff note (below) so the next step is in a file.

Do this for ten days and day 10 really is easier, because you taught the next session, not because Claude remembered. The honest way to put it: Claude does not get smarter or faster, it gets less lost.

The handoff note: what “remember this session” should really be

It is tempting to end a day by typing “remember this session”. As Part 2 explained, that alone saves nothing unless Claude writes a file. A reliable version is an explicit handoff note:

Before I close this session, write a handoff note to docs/notes/2026-10-14.md:
- what we finished
- decisions made, and why
- what is still broken or unfinished
- the exact next step
Then add one line to CLAUDE.md pointing to that file.

> Write a handoff note to docs/notes/2026-10-14.md and link it from CLAUDE.md.

● Write(docs/notes/2026-10-14.md)
  + Done: reachability check, fallback notice
  + Decision: fall back only if no text has arrived yet
  + Next: unit tests for the partial-failure case
● Update(CLAUDE.md)
  + Latest handoff: docs/notes/2026-10-14.md

Next morning, start with: “Read docs/notes/2026-10-14.md and continue.” That costs far fewer tokens than resuming the whole old conversation, and you can read and correct the note first.

• Check that it happened. Look for the file write, or run git diff. No file change means nothing was kept.
• Read the note before you trust it. A summary keeps only what Claude chose to include, and subtle details can be lost.
• Keep secrets out. Never put passwords or keys in a note.
• Prune old notes. Keep the latest handoff linked, and archive or delete the rest so CLAUDE.md stays lean.

5. When it costs more than it saves

The file is loaded every time, even for a tiny question. A 3,000-line CLAUDE.md pays that price on “what does this function do?” as well. The balance depends on how long and how relevant it is:

Practical limits that keep you near the sweet spot:

• Aim for short. The official guidance is to keep each CLAUDE.md under about 200 lines, because longer files use more context and Claude follows them less reliably. If you cannot say it briefly, it probably belongs in a linked doc, a skill or a path-scoped rule.
• Leave comments for people. Block-level HTML comments in CLAUDE.md are stripped before it is sent, so maintainer notes cost no tokens.
• Always-needed in the file, sometimes-needed in a link. The release checklist is read once a month, so link it from the file and let Claude open it only when you ask about releases.
• Use skills for long how-tos. A skill shows Claude only a short description until the task matches, so a ten-step procedure costs nothing on unrelated work (Part 2, section 9).
• Deny noisy files. A deny rule for lock files, dependency folders and build output keeps Claude from reading thousands of useless lines. It also keeps secrets out of the context.
• Use sub-folder files. Rules for server/ only load when Claude works in server/.
• Delete the obvious. If the code makes it clear, the line is a tax with no benefit.

A caution on imports from Part 2: @docs/architecture.md loads that whole file every session. If it is long, mention it by name in plain text instead (“deep architecture notes are in docs/architecture.md; read them when changing the engine”) so it is read on demand.

6. Habits that save more

The file is one lever. These habits matter just as much, and most of them come straight from the official Manage costs effectively guide:

> /compact focus on the database migration decisions

● Summarising the conversation…
  Kept: migration plan, the failing test, files changed
  Dropped: exploratory reads, resolved side-questions

✓ Conversation compacted. CLAUDE.md is still loaded.

7. Onboarding onto a new project

Joining a project is the same problem Claude has every morning: lots of unknowns, little context. The file helps both of you. There are two situations.

You are new to the project

If the project already has a CLAUDE.md, reading it is the fastest tour you will get: commands, structure and traps in one page. If it does not, you can use Claude to build the tour, then correct it with a teammate.

Questions that work well in a first session, with or without a file:

Give me a one-page tour of this codebase for a new developer.
What are the main modules and how do they depend on each other?
Trace what happens when a user sends a chat message, file by file.
Which parts look risky or fragile, and why?
What do I need to know before changing the engine code?

Then write what you learned into the file. A new teammate asks Claude the same questions you did; the file answers them before they ask.

You are bringing someone (or Claude) into your project

If you maintain the project, CLAUDE.md doubles as onboarding documentation that is actually kept current, because you use it daily. A new hire reads the same file their assistant does, and both start with the same understanding.

8. Starting a new feature

Features have a different problem from projects: the knowledge is temporary. The decisions you make this week (names, trade-offs, what is out of scope) matter until it ships and then mostly do not. Putting all of that in the permanent root file would bloat it.

Instead, write a short feature note and point to it:

# Feature: automatic offline fallback

## Goal
If the user picked Online but the internet is not reachable,
answer from the on-device model and tell the user why.

## Decisions
- Check VALIDATED network capability, not just "connected".
- If the online call fails before any text arrives, fall back.
- If it fails part-way, keep the text already received.

## Out of scope
- Switching back to online mid-conversation.

## Done when
- Unit tests for the decision logic pass.
- Manual test: airplane mode shows the fallback message.

## Current work
Working on automatic offline fallback.
Read docs/features/offline-fallback.md before changing the engine selection code.

This also helps across sessions. If you stop on Friday and resume on Monday, the new session reads the feature note and picks up where you left off, without you retelling the story.

9. Making it a team habit

1. Commit the root CLAUDE.md so everybody shares the same baseline.
2. Review changes in pull requests like code. A bad line affects every future session.
3. Add a line when something goes wrong. A bug caused by a missing convention becomes a one-line prevention for the next person.
4. Prune on a schedule. Every month or so, delete lines that are no longer true or no longer needed.
5. Keep personal taste personal. Preferences such as tone or language go in ~/.claude/CLAUDE.md, not the shared file.

10. Pitfalls and a checklist

The whole series in one picture