The CLAUDE.md Pattern: Why Every AI Project Needs a House-Rules File

Every project I run with AI has the same first file. It’s called CLAUDE.md, and it sits at the top of the project folder like a sign on a workshop wall. New session opens, AI reads it, work begins. The file isn’t fancy. It’s the most useful thing in the whole setup.

If you’re using AI for anything that lasts longer than a single conversation, you want a file like this. Here’s the pattern, the why, and how to write one without overthinking it.

What CLAUDE.md is

CLAUDE.md is a plain Markdown file in the root of a project folder. It’s the AI’s briefing for that project. Voice rules. Project context. What tools to use. What not to touch. Where to find the things that matter. Names of the humans involved. Deadlines, constraints, conventions.

The file is automatically loaded by AI tools that support the convention — the original is the one used by Claude Code, but the same shape works as a system prompt or instructions file in basically any agentic tool. The point isn’t the filename. The point is having one document the AI re-reads every time it works in this folder.

Why every project needs one

Without CLAUDE.md, your AI relies on whatever you remembered to type in this session. That works for one-shot tasks. It fails the moment you’re working across hours, days, or sessions, because the AI’s short-term memory has a hard limit and old instructions scroll out of view.

With CLAUDE.md, the rules don’t depend on memory at all. They live on disk. The AI re-reads them at the start of every reply. Drift stops. Consistency stays.

The other thing CLAUDE.md does is force you to write down what you actually want. Most of us carry our project rules in our heads. Pulling them out and putting them on a page is the moment you notice contradictions, gaps, or assumptions you’ve never tested.

What goes in it

Aim for the lowest useful version. You can always add more later.

• What this project is. One paragraph. The thing you’re working on, who it’s for, what success looks like.
• The voice. A few sentences on tone. Examples beat adjectives — show a sentence in your voice, show a sentence not in your voice.
• What the AI should do without asking. Read these files. Draft to this folder. Use this format. Save with this naming convention.
• What the AI should never do without asking. Publish anything. Send anything. Delete anything. Touch these specific files.
• Where to find things. Drafts live here. Research lives there. Past examples are in this folder. The brand assets are at this URL.
• Conventions. File naming. Slug structure. Headline patterns. Anything you do consistently and want the AI to do consistently too.

What stays out

Three things don’t belong in CLAUDE.md.

Secrets. Passwords, API keys, anything sensitive. Those go in a separate file the project ignores (or a password manager). CLAUDE.md is shared with the AI; secrets shouldn’t be.

Long-form writing. If you have a 5,000-word style guide, summarize it in CLAUDE.md and link to the full doc. The file should be readable end-to-end in under a minute. Anything longer competes with your actual project content for the AI’s context window.

Things that change every week. CLAUDE.md is for stable rules. Today’s todo list, the current draft, the next deadline — those go in working files the AI reads on demand, not in the always-loaded briefing.

Stacking them across a portfolio

If you’re running multiple projects, the pattern stacks. One root-level CLAUDE.md for global rules (voice, safety, your overall preferences). One project-level CLAUDE.md inside each project folder for that project’s specifics (which categories, which audience, which deadlines).

When the AI is working in a project folder, it reads both: the global file gives the baseline, the project file overrides where needed. The result is one set of rules you maintain, applied consistently across everything.

This is what makes a vault-of-projects setup possible at all. Each folder is a channel; each channel has its own briefing; the AI behaves differently in each because the file says so. The whole architecture is in Obsidian as a Second Brain: The Claude Code Setup.

The first version takes 20 minutes

Make a file called CLAUDE.md in your project folder. Write the six bullets above, one or two sentences each. Save. That’s your first version.

Iterate from there. Every time the AI does something off-voice or off-pattern, ask yourself: would the right rule in CLAUDE.md have prevented that? If yes, add it. If no, the issue is somewhere else — in the prompt, or in a file the AI didn’t see.

Within a few weeks you’ll have a CLAUDE.md that captures most of how you actually work. The AI starts being useful from the first reply of every session. The drift problem goes away. The “explain it again” problem goes away.

One file. Twenty minutes. The cheapest, highest-leverage move you can make if you’re using AI for real work.

---

Related: Why Your AI Sounds Different at Hour 3 · Giving Your AI Permission to Act Without Permission to Be Reckless · What I Built Into Claude Inside My Slack.