CLAUDE.md: Make Your Repository AI-Ready and Cut Token Waste

The Problem With How Most Developers Use AI

Imagine you hire a contractor to renovate your kitchen. They show up, look around, and ask: “What does this house look like? What style do you prefer? Where do the pipes run? Is there a budget?”

You explain everything. They nod, take notes, and start working.

Two weeks later, the same contractor comes back for a second job. They ask all the same questions again.

That is what happens every time you open a new AI conversation without giving the model structural context. The model has no memory of your project, your conventions, your tech stack, or your preferences. Every session starts from zero. Every session burns tokens reestablishing what you already know.

The cost is real — slower responses, less accurate suggestions, and a cognitive tax on you to keep repeating the same background every single time.

There is a better way.

What CLAUDE.md Actually Does

Claude Code — Anthropic’s CLI for AI-assisted development — automatically reads a file called CLAUDE.md from the root of your repository at the start of every session. No prompt needed. No setup needed. It just loads.

This file is not documentation for humans. It is a briefing document for the model. It tells the agent:

What the project is and who it is for
How the codebase is structured
What commands to use
What conventions to follow
What it should never do

When the model reads this file at the start of a session, it does not need to explore your codebase to answer basic questions. It does not need to ask what your naming convention is. It does not need to guess whether you use Bun or npm. That context already exists.

The result: less exploration, fewer clarifying questions, more focused responses, and significantly lower token consumption per task.

The Two Costs of Missing Context

There are two types of waste when an AI agent lacks project context.

Token waste happens when the model explores files it should already know about, re-reads configuration it has seen before, or generates a response that misses your conventions and has to be corrected. Every correction is additional tokens. Every re-read is additional tokens.

Attention waste happens when you — the developer — have to provide context in natural language at the start of every conversation. “This is an Astro project. We use Bun. Spanish is the default language. We never use emojis.” Writing that every session adds friction, and it still is not as reliable as a structured file.

A well-written CLAUDE.md solves both at once.

Structure of an Effective CLAUDE.md

The file does not need to be long. It needs to be precise. An unfocused CLAUDE.md that includes everything wastes the tokens you were trying to save. Write only what the agent needs to operate correctly.

Here is the structure that works:

1. Project Identity (3-5 lines)

Who made it, what it does, and who uses it. One sentence each.

**Who:** Omar Flores (SazarDev), Full Stack Developer.
**What:** Bilingual portfolio and technical blog. Astro 5, TypeScript, Tailwind, Netlify.
**Readers:** Developers from junior to senior. Write so both can follow.

2. Project Structure (directory tree)

Show the directories that matter, with one-line comments. Skip node_modules, dist, and anything the agent should not touch.

## Project Structure

src/
  content/blog/es/   # Spanish posts (.md)
  content/blog/en/   # English posts (.md)
  layouts/           # BaseLayout, BlogPostLayout
  data/content.json  # All UI text — do not hardcode strings
  config/seo.ts      # Canonical tags and categories

3. Commands

The exact commands to run, nothing more.

## Commands

bun dev        # dev server
bun build      # production build
bun run check  # type checking

4. Hard Rules

The things the agent must never do. Be specific — vague rules get ignored.

## Hard Rules

- No emojis anywhere.
- No auto-commit without explicit instruction.
- No refactoring beyond the task scope.
- Always use bun, not npm or yarn.
- Always add dark: Tailwind variants alongside light mode classes.

5. Pointers to Deeper Context

If the project has specific writing conventions, component patterns, or SEO rules, put them in separate files under .claude/ and reference them here. This keeps CLAUDE.md short while still making detail available on demand.

## More Context

- Writing style and blog structure: .claude/rules.md
- Component and code patterns: .claude/patterns.md
- Full technical context: .claude/context.md

The .claude/ Directory

CLAUDE.md is always loaded. The files inside .claude/ are reference material — the agent reads them when a task requires that specific knowledge.

Think of it as a library. CLAUDE.md is the index. The .claude/ files are the chapters.

.claude/rules.md — writing conventions, voice, style guide, blog post structure, SEO checklist. Loaded when the task involves content creation or editing.

.claude/patterns.md — ready-to-use code snippets, component templates, antipattern comparisons, example frontmatter. Loaded when the task involves generating or reviewing code.

.claude/context.md — tech stack versions, key file paths, i18n architecture, design system tokens, build configuration. Loaded when the task involves architectural decisions or unfamiliar parts of the codebase.

Each file is dense and specific. No filler. No repetition between files. If something belongs in context.md, it is not also in rules.md.

Token Efficiency: The Practical Mechanics

Token consumption in an AI session is roughly:

total tokens = system prompt + loaded context + your message + model response

You cannot control the system prompt. You can control the loaded context, and how precisely you write your messages.

Principle 1: Front-load context, not messages.

If the agent reads CLAUDE.md and .claude/context.md at the start, your message can be short: “Add dark mode support to the BlogCard component.” Without that context, the same request requires: “This is an Astro project using Tailwind CSS with a .dark class strategy on <html>. The BlogCard component is at src/components/blog/BlogCard.astro. Dark mode should use dark: Tailwind variants, not media queries. Please add dark mode support.”

Same task. One requires 15 tokens. The other requires 80 tokens — and still risks missing a convention.

Principle 2: Specific files load faster than broad exploration.

An agent that explores your codebase to answer a question reads dozens of files and produces thousands of intermediate tokens. A reference to a specific file path skips all of that. Your .claude/ files should include the exact file paths for key resources.

Principle 3: Rules prevent correction cycles.

Each correction doubles the token cost of a task. If the agent generates code without dark: variants and you correct it, you have now used tokens for the wrong output, the correction, and the new output. One clear rule in CLAUDE.md eliminates that cycle.

Principle 4: Dead context costs as much as live context.

A CLAUDE.md file that includes outdated rules, irrelevant configuration, or verbose explanations loads the same token weight as one that is current and precise. Review it when you change your stack. Delete what is no longer true.

Memory Across Sessions

Claude Code supports a persistent memory file that loads into every session across the entire project. The path is:

~/.claude/projects/[project-path]/memory/MEMORY.md

This file is different from CLAUDE.md. It is meant for things you want the agent to remember across conversations — not project structure (that belongs in CLAUDE.md) but learned preferences, recurring decisions, and quick-reference summaries.

A useful MEMORY.md is short — under 60 lines — and covers:

Project identity and runtime preference (one line each)
Agent behavior reminders (read before acting, explain before code)
The writing voice in three bullet points
SEO rules in two bullet points
The file map for the most-accessed resources

Anything longer than that should be in a .claude/ file, not in memory.

What Agentic Mode Changes

When you use Claude Code in agentic mode — where the model can read files, write files, run commands, and take sequences of actions — the quality of your context files matters even more.

Without context, an agent in agentic mode explores broadly before acting. It reads configuration files to understand the tech stack. It reads multiple components to understand patterns. It reads existing content to understand tone. This exploration is necessary — but it is expensive when the information already exists in a structured form.

With a good CLAUDE.md and .claude/ setup, the agent can move directly to the task. It knows the stack. It knows the conventions. It knows what tools to use. Exploration becomes targeted instead of broad.

This changes the speed profile of agentic tasks significantly. Tasks that previously required 10-15 exploratory tool calls before producing output can be reduced to 2-3 when the agent starts with reliable context.

Common Mistakes

Writing CLAUDE.md as documentation for humans. The file is a briefing, not a README. It should be dense and structured, not narrative and welcoming.

Including everything. A 500-line CLAUDE.md is not more useful than a 60-line one. The agent loads it all — the relevant parts and the irrelevant ones. Length is cost.

Vague rules. “Write clean code” tells the agent nothing. “No any in TypeScript. No inline styles. Always add dark: Tailwind variants.” tells the agent exactly what to do.

Not updating it. A CLAUDE.md that describes your old stack is worse than none. It creates confident wrong answers. Treat it like a living document.

Skipping the .claude/ structure. If your CLAUDE.md tries to include all conventions, all patterns, and all context, it becomes both too long to load efficiently and too short to be accurate. The split between a concise root file and detailed reference files in .claude/ is what makes the system scale.

A Minimal Starting Point

If you want to add this to your own project today, start with just three things:

1. Create CLAUDE.md at the repository root. Write your project identity, structure, commands, and five hard rules. Keep it under 80 lines.

2. Create .claude/rules.md with your code conventions — naming, formatting, component patterns, and anything a senior developer on your team would know that a new one would not.

3. Create a short MEMORY.md in ~/.claude/projects/[your-project-path]/memory/MEMORY.md. Put only the things you want the agent to remember session after session: your runtime preference, the most important rules, the file paths it needs most often.

That is enough to see a meaningful difference in response quality and token efficiency. The more specific you are, the more the system compounds over time.

The Compounding Return

The first time you write CLAUDE.md, you invest an hour. Every session after that, you save five minutes and dozens of tokens. Over weeks, that compounds into a measurably faster development workflow.

More importantly, the agent becomes more predictable. It follows your conventions. It does not surprise you with wrong patterns. It does not need correction cycles. The interaction becomes more like working with a developer who knows your codebase, and less like onboarding a new contractor every day.

The agent cannot read your mind. Give it the briefing it needs, and it will stop asking you to repeat yourself.