What CLAUDE.md is and why it changes everything

Lesson outcome

You will understand what CLAUDE.md is, how it works, and why writing one is the highest-leverage thing you can do with the operator stack.

Why this matters in an agency

Without CLAUDE.md, every Claude Code conversation starts blank. Claude does not know your agency name, your services, your file structure, your naming conventions, or your preferences. So you spend the first five minutes of every session re-explaining context. That wastes time and produces worse output because context communicated in a chat message is weaker than context loaded from a persistent instruction file.

CLAUDE.md fixes this permanently. It is a markdown file that Claude Code reads automatically at the start of every conversation. Whatever you put in it — your business context, operating rules, file locations, naming conventions, verification standards — Claude Code knows before you type your first message. It is like giving a new employee a detailed onboarding document instead of explaining everything verbally every morning.

Inputs, tools, and prerequisites

A clear mental model of your business context, your file structure, and your operating preferences. Claude Code running on the VPS or locally.

Step-by-step walkthrough

How CLAUDE.md works

When Claude Code starts in a directory, it looks for a file called CLAUDE.md in that directory. If it finds one, it reads the entire file and treats it as persistent instructions for every conversation in that directory. Claude Code also checks parent directories — so a CLAUDE.md at the root of your home directory applies everywhere, while one inside a specific project applies only there.

There are two levels:

Global CLAUDE.md (~/.claude/CLAUDE.md) — applies to every Claude Code conversation on the machine. This is where you put your identity, your business overview, and universal rules.

Project CLAUDE.md (in any directory) — applies when Claude Code is started in that directory or its subdirectories. This is where you put project-specific instructions, file structure details, and task-specific rules.

Both are read automatically. Both stack — if you have a global CLAUDE.md and a project CLAUDE.md, Claude Code reads both.

What to put in CLAUDE.md

Good CLAUDE.md content falls into four categories:

Identity and context — Who you are, what the business does, who the clients are. This prevents Claude Code from guessing about your business.

File structure and conventions — Where things live, how they are named, what the vault structure looks like. This prevents Claude Code from creating files in random locations or using inconsistent names.

Operating rules — How you want Claude Code to behave. Tone, verbosity, verification requirements, things to never do. This prevents behavioral drift across conversations.

Tool and credential locations — Where scripts live, how to access BWS, what paths matter. This prevents Claude Code from searching for things that are already documented.

What NOT to put in CLAUDE.md

Do not put temporary task context in CLAUDE.md. "I am currently working on the March report" does not belong there because it expires. CLAUDE.md should contain durable information — things that are true across weeks and months, not across minutes.

Do not put secrets or credentials in CLAUDE.md. That file is plain text. Credentials go in BWS. CLAUDE.md can reference BWS ("use BWS to retrieve VPS credentials") but should never contain the credentials themselves.

Do not make it too long. A CLAUDE.md with 200 lines of instructions is more useful than one with 2,000 lines. Claude Code reads the whole thing, and information density matters. Be concise.

Failure modes and verification checks

The main failure is never writing a CLAUDE.md at all. The second failure is writing one that is too vague ("I run an agency, be helpful") or too long (pages of rules no one reads). The third failure is putting temporary information in it and never cleaning it up.

Verification: start Claude Code in the directory with the CLAUDE.md. Ask: "What do you know about my business before I tell you anything?" If Claude Code can describe your agency, your services, and your file structure accurately, the CLAUDE.md is working.

Implementation checklist

• Understand the two levels: global and project.
• Know the four content categories: identity, file structure, operating rules, tools.
• Know what does NOT belong: temporary context, credentials, excessive length.
• Download the companion template.

Immediate next action

Move to the next lesson and write your actual CLAUDE.md files.

Exercise

Before writing your CLAUDE.md, start Claude Code in your vault directory (without a CLAUDE.md) and ask:

```
What do you know about my business right now?
```

The answer will be "nothing" or it will guess from file names. Write down what Claude Code gets wrong or does not know. That gap — between what Claude Code knows and what it needs to know — is exactly what your CLAUDE.md should fill.