What Is the Claude.md File and Why Does It Matter for AI Agents?

Your AI Agent’s Permanent Instruction Set

Every time you start a new Claude Code session, you’re starting from scratch. The agent doesn’t remember what you told it last week. It doesn’t know your coding conventions, your project structure, or that you never want it to use semicolons. You have to re-explain everything, every time.

Unless you have a claude.md file.

The claude.md file is a plain markdown document that Claude Code reads automatically at the start of every session. It functions as a persistent system prompt — a set of standing instructions that define how the agent should behave, what it knows about your project, and what rules it must follow. You write it once, and it applies to every interaction going forward.

If you’re using Claude Code and you don’t have a claude.md file, you’re doing more work than you need to. This article explains what the file does, why it’s one of the most important things you can configure, and how to write one that actually improves your results.

What the claude.md File Actually Does

The claude.md file sits at the root of your project directory. When Claude Code launches, it scans for this file and loads its contents into the context window before any conversation begins. That means everything in the file is present before you type a single message.

Think of it as a briefing document. Before a contractor shows up to work, you hand them a document: here’s the project, here’s how we do things, here’s what matters. The claude.md file does the same thing for your AI agent.

This is distinct from a one-off prompt. A prompt is a request. The claude.md file is a standing configuration. It shapes all prompts that follow.

The file can contain:

Project background and architecture overview
Technology stack and conventions
Style and formatting rules
What the agent should and shouldn’t do
File structure notes
Reference to other files or skills

Claude Code also supports a global claude.md file at the user level, which applies across all projects. This is useful for preferences that don’t change — preferred output formats, communication style, general coding standards.

Why It Matters More Than You Might Think

Without a claude.md file, every session is a blank slate. You spend the first few exchanges re-establishing context. You correct the agent when it uses the wrong conventions. You repeat yourself constantly.

With a well-written claude.md, the agent arrives already oriented. It knows the codebase. It knows your rules. It behaves consistently because it has consistent instructions.

This is especially important for two reasons.

Context shapes output quality

The quality of what an AI agent produces is directly proportional to how clearly it understands the task. Prompt engineering focuses on individual requests. The claude.md file is something deeper — it’s the context layer underneath every request.

That distinction matters a lot. Understanding the difference between prompt engineering, context engineering, and intent engineering clarifies why the claude.md file is more powerful than just writing better prompts. You’re not refining a single instruction. You’re building the foundation that all instructions rest on.

Context rot is a real problem

As a session runs longer, earlier instructions start to lose their grip. The agent begins to drift. It starts making decisions that contradict what you told it at the start. This is context rot — and it’s one of the main reasons AI agent output degrades over time.

A claude.md file helps because its contents are re-loaded at the start of every session. When you start fresh, your instructions are fresh too. You don’t accumulate the same compounding drift you get from long, unstructured sessions.

The Anatomy of a Good claude.md File

There’s no mandatory format, but a well-structured claude.md file typically covers four areas.

1. Project context

Start with a short summary of what the project is. Not a marketing pitch — a technical briefing. What does it do? Who uses it? What are the key constraints?

## Project Overview
This is a B2B invoicing tool for small service businesses.
Backend: Node.js with Express. Frontend: React + Tailwind.
Database: PostgreSQL. Auth: JWT with refresh tokens.

Even three or four sentences here saves multiple clarifying exchanges later.

2. Conventions and standards

This is where most of the value lives. Tell the agent how your team writes code. Be specific.

## Code Conventions
- Use TypeScript strict mode throughout
- No semicolons
- Functional components only — no class components
- Named exports only, no default exports
- File names: kebab-case
- Variable names: camelCase
- Database columns: snake_case

The more specific you are here, the less correction you’ll do in sessions. Writing effective instructions for AI agents is about precision, not length — same principle applies here.

3. Behavioral rules

Explicit instructions about what the agent should and shouldn’t do. This is your standing order set. Think of it as the rules file for your AI agent — the lines it must not cross and the defaults it should follow.

## Behavioral Rules
- Always write tests before implementing a feature
- Never modify the database schema directly — use migration files
- Don't install new packages without asking first
- Always check for existing utility functions before writing new ones
- When uncertain, ask — don't guess

Anthropic’s own Claude documentation recommends keeping rules concrete and actionable. Vague instructions like “be careful with the database” don’t help. “Never run DROP statements without explicit confirmation” does.

4. File and directory structure

Brief orientation to the codebase layout. The agent doesn’t need a full map, but knowing where things live saves it from hunting.

## Structure
- /src/api — Express route handlers
- /src/services — Business logic
- /src/db — Database queries and migrations
- /src/components — React components
- /src/lib — Shared utilities

What to Leave Out

The claude.md file has a real cost: tokens. Everything in it loads into the context window at session start. A bloated file eats into the space available for actual work.

AI token management is a real concern in longer sessions. If your claude.md file is 5,000 words, you’re burning significant context before you’ve done anything.

A few things that don’t belong in the file:

Full code examples — Link to reference files instead
Exhaustive documentation — Summarize, don’t copy-paste
Things that change frequently — Use session-level context for that
Redundant explanations — If a rule is self-evident, skip it

The goal is a file that’s dense with useful signal and free of filler. The bitter lesson of building with LLMs applies here: more isn’t always better. Simpler, cleaner instructions often outperform verbose ones.

claude.md vs Other Configuration Files

Claude Code uses several markdown files that can be confused with each other. Here’s how they differ.

claude.md vs skill.md

A skill.md file is associated with a specific Claude Code skill — a discrete, reusable task the agent can perform. The skill.md file contains instructions for that specific skill.

The claude.md file is global. It applies to everything. The skills architecture in Claude Code separates global context from task-specific instructions deliberately. Your claude.md handles the standing rules; each skill handles its own process.

Think of it this way: claude.md is the employee handbook. Each skill.md is the procedure manual for a specific job.

Project-level vs global claude.md

Claude Code supports both:

Project-level (./claude.md) — applies to the current project only
Global (~/.claude/claude.md or similar) — applies across all projects

Most developers maintain a global file with preferences that never change (output style, communication tone, general best practices) and a project-level file with codebase-specific context.

How the Memory Architecture Uses claude.md

Claude Code’s memory operates across multiple layers. The claude.md file sits in what developers sometimes call the “external memory” or “persistent memory” layer — the stuff that exists between sessions and isn’t derived from conversation.

Understanding Claude Code’s three-layer memory architecture helps clarify why the claude.md file is so central. The agent has:

In-context memory — what’s present in the current session window
External memory — files it can read, including claude.md
Auto-memory — what the agent writes back to its own files based on what it learns

The claude.md file is the primary vehicle for layer two. When Claude Code’s auto-memory feature adds new information, it typically writes back to the claude.md file — updating the agent’s persistent knowledge base with things it learned during the session.

This creates an interesting loop: the agent reads the file, does work, learns something, updates the file, and the next session starts with better information than the last. That’s the compounding knowledge loop in practice.

Writing a claude.md That Actually Improves Output

A few practical principles that separate useful files from generic ones.

Be specific about the things you care most about

The agent will apply general judgment to everything not covered explicitly. Use the file to address the things where generic judgment isn’t good enough — your specific conventions, your edge cases, your non-obvious constraints.

If you’ve ever corrected the agent for the same mistake twice, that correction belongs in the claude.md file.

Structure it for scanning, not reading

The agent doesn’t read the file linearly like a human does. It processes all of it, but clear headings and short sections make the structure easier to reason about. Use H2 headers for major categories. Keep rule lists concise.

Update it regularly

Your first claude.md file won’t be your best one. As you work with the agent, you’ll notice patterns: things it gets wrong repeatedly, things you have to clarify too often. Add those to the file. The file should evolve with the project.

This is especially relevant if you’re running complex multi-skill workflows — as the workflow grows, the claude.md file needs to reflect what the agent needs to know to coordinate across all the pieces.

Test it like you’d test code

After writing or updating your claude.md, start a fresh session and run a few common tasks. Does the agent behave the way you intended? Are there rules being ignored? Sometimes instructions conflict or contradict each other in ways that aren’t obvious until you see the output.

Where Remy Fits

Remy takes a fundamentally different approach to the problem the claude.md file is trying to solve.

In Claude Code, you’re managing configuration across multiple files to keep an AI agent oriented on your project. The claude.md is essential, but it’s still a workaround for a deeper problem: the agent’s context doesn’t naturally stay in sync with your application as it grows.

Remy starts from a different premise. The source of truth for your application is a spec — an annotated markdown document that both humans and the AI agent can read and reason about. The spec isn’t a configuration file layered on top of code. It is the application. Code is the compiled output.

This means the agent is never operating from a disconnected set of instructions. The spec is the application contract. It defines what the app does, how it behaves, and what the rules are — and the agent compiles the code from that, every time.

Instead of writing a claude.md to orient an agent on your existing codebase, you write a spec that describes your application from the ground up, and the full-stack output — backend, database, auth, frontend — follows from that.

You can try Remy at mindstudio.ai/remy and see what building from a spec looks like in practice.

Frequently Asked Questions

What is the claude.md file in Claude Code?

The claude.md file is a markdown document that Claude Code reads automatically at the start of every session. It acts as a persistent system prompt — a set of standing instructions that tell the agent about your project, your conventions, and how it should behave. Unlike a regular prompt, which applies to one request, the claude.md file applies to every interaction in the session.

Where does the claude.md file live?

Claude Code supports two locations. A project-level claude.md file lives in the root of your project directory and applies only to that project. A global claude.md file lives in your Claude Code user directory (typically ~/.claude/claude.md) and applies across all projects. Most developers use both — global for general preferences, project-level for codebase-specific context.

Does the claude.md file affect token usage?

Yes. Everything in the file loads into the context window at session start. A longer file means fewer tokens available for actual work within the session. This is why it’s worth keeping the file focused. Strip out anything that doesn’t actively improve the agent’s output. See the context window management guide for Claude Code for more on how to work with this constraint.

Can Claude Code update the claude.md file automatically?

Yes, through auto-memory. When Claude Code’s auto-memory feature is active, the agent can write new information back to the claude.md file based on what it learns during a session. This is how the agent builds up a persistent knowledge base over time — each session can leave behind useful context for the next one.

What’s the difference between claude.md and a system prompt?

Functionally, the claude.md file is a system prompt — it’s just delivered through a file rather than through the API’s system parameter. The main differences are that it’s human-readable, stored in version control alongside your project, and editable like any other file. For most Claude Code users, the claude.md is the primary mechanism for setting system-level instructions.

Should I use a global claude.md or a project-level one?

Both, ideally. Your global file should contain preferences that apply everywhere: output format, communication style, general coding principles you always follow. Your project-level file should contain everything specific to that codebase: tech stack, file structure, project-specific conventions, domain context. If a rule only makes sense for one project, it belongs in the project file.

Key Takeaways

The claude.md file is a persistent instruction file that Claude Code loads at the start of every session, functioning as a standing system prompt.
A well-written file reduces repeated corrections, improves output consistency, and keeps the agent oriented on your project without re-establishing context each time.
The file should cover four main areas: project context, code conventions, behavioral rules, and file structure.
Keep it lean — every token the file uses is a token unavailable for actual work.
The file works best when it’s treated as a living document, updated as you learn what the agent needs to know.
Claude Code’s auto-memory feature can update the claude.md automatically, creating a compounding knowledge loop across sessions.

If you’re looking for a different approach to the problem entirely — one where the application spec is the source of truth from the start — try Remy at mindstudio.ai/remy.