What Goes in a .claude/ Directory (and Why It Cuts Your Token Bill)

A .claude/ directory is a folder at your project root that holds context written for Claude Code to read at the start of every session. It contains a compact codebase map, skills (task instructions for your project), memory (architecture, conventions, and decisions), and patterns (reference implementations from your real code). It exists so Claude starts oriented instead of re-learning your repo from scratch every time you open it.

That last part is the whole reason to bother. So before the file tour, it's worth being clear about the problem it solves.

Why the directory exists

Claude doesn't remember your project between sessions. Open a repo it hasn't seen in a week and it re-reads your directory tree, re-opens files, and re-infers your conventions just to get oriented, before it writes a single useful line. When I tracked where my Claude Code tokens actually go, 60 to 70% of the spend on an unchanged codebase went to that orientation, not to features. It's the single biggest reason Claude Code gets expensive.

The .claude/ directory moves that context out of Claude's head and into the repo, where it gets read once and cheaply instead of rebuilt expensively on every cold start.

What goes inside

Here is the shape of a working setup:

Four parts, each doing a distinct job. Take them one at a time.

CODEBASE.md, the map

The single highest-impact file. A roughly 2,000-token map of your whole project: the directory tree with one-line descriptions, your data model, your API routes, key integrations. It's the file that replaces blind discovery with a quick read. Without it, Claude burns 30,000 to 40,000 tokens building that mental model by exploring. With it, Claude reads one file and starts building.

A note on naming: Claude Code also reads a CLAUDE.md at your root automatically. That file is great for short, always-on instructions. The fuller project map is big enough that I keep it as its own CODEBASE.md and point to it, so the always-on file stays lean.

skills/, how tasks are done here

Task instructions written for your specific codebase. Not “how to add an API route” in general, but how to add one in this project, with these imports, following these conventions. A real one looks like this:

Five lines, and Claude stops guessing your patterns, using the wrong imports, or structuring the file differently from everything else in the repo. These are the same Claude Code skills I run every day, just scoped to one project.

memory/, the things Claude keeps forgetting

Three short files, read at the start of every session:

architecture.md: what the system does, how data flows, your key services. Compressed, not comprehensive. Enough for correct decisions without reading everything.

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

decisions.md: why you chose X over Y. The most underrated of the three. Without it, Claude will periodically suggest switching from Prisma to Drizzle, or Resend to SendGrid. One sentence per decision closes those loops permanently.

patterns/, your real code as reference

Reference implementations pulled from your actual production code. Instead of Claude inventing how to do RBAC from its training data, it reads exactly how you've done it: your auth library, your database client, your middleware. New code comes out matching the code that's already there.

How to set one up

Build it in order of impact, and don't try to do it all at once.

Start with CODEBASE.md. Directory tree, one-line descriptions, data model, API routes. Target ~2,000 tokens.

Add one skill.Pick the task you do most often and write the steps as you'd explain them to a strong dev on day one: exact directories, exact imports, exact patterns. Add more once it works; most projects need four to six.

Then the three memory files. Keep them honest and short. Whatever Claude keeps getting wrong is what belongs here.

Commit all of it.The directory is project context, so it lives in git next to the code it describes, and every new session (yours or a teammate's) starts from the same place. For the in-session habits that compound on top of this, here are 12 token-saving techniques that actually work.

What not to put in it

The most common mistake is treating .claude/ like documentation for humans. It isn't. Long prose, onboarding guides, and full API references just bloat the context and get read on every turn, which is the cost you were trying to avoid. Keep it dense and actionable.

Don't paste whole files in either. Point Claude at where the real code lives and let it open what it needs. And skip anything secret: env values and keys never belong in a committed directory. If a file isn't changing what Claude does, it shouldn't be there.

Frequently asked questions