How to Set Up CLAUDE.md in 2026: Template and 6 Rules

Materials on vibe coding: tools, case studies, mistakes. Ailoot Guides.

Why do you need CLAUDE.md, and why does Claude forget the project without it?#

You open Claude Code on Tuesday and explain: “I’m working on this project, these are the tools, don’t do this.” It works.

On Thursday, that same chat has already ended, so you repeat everything. On Saturday, again; on Monday, one more time.

That’s what working with an agent without CLAUDE.md looks like: every new window is a blank-slate intern whom you have to tell the same things over and over. I used to spend 5-10 minutes typing out this warm-up for every session. The prompts got long because I had to carry all the context manually. And the result was still generic: the agent didn’t know my audience, my economics, or my principles.

With a living CLAUDE.md, the warm-up disappears. All the rules you used to repeat in every chat are in one file and automatically appear at the start of each session. The prompt becomes short: “do X,” rather than “I’m working on project Y, the tools are Z, don’t do A or B, and by the way, remember C too.”

Then the repeated mistakes go away.

Every agent mistake is a reason to add one line to CLAUDE.md. After a month, you have a living “project constitution,” and Claude stops falling into the same familiar traps.

And there’s a third layer: the agent stops writing in a vacuum. Through CLAUDE.md, I route Claude to folders with context: where to look for information about the audience, pricing, and branding. Without this routing, the agent writes “high-quality solutions” without knowing my economics, so they turn out abstract, formulaic, and “just like everyone else’s.”

What is CLAUDE.md, and in what order does Claude read it?#

Anthropic describes CLAUDE.md this way in its official documentation:

The four places where Claude Code looks for CLAUDE.md, in increasing order of priority:

All four files are loaded into context at the same time. If the rules conflict, Anthropic says directly in its documentation that it is unknown which one will take precedence; Claude may choose one of them arbitrarily. So it’s simpler to keep everything critical in the project CLAUDE.md and avoid creating duplicates.

There’s one technical detail almost nobody writes about, but it explains a lot of strange behavior.

In other words, CLAUDE.md isn’t a “system prompt” in the strict sense. It’s the first user message Claude sees. So its rules are strong suggestions, not laws. If a rule needs enforcement, use a tested hook for its covered event and permissions or environment isolation for the wider access boundary. Automatically running a hook does not make its checks complete. I’ll explain the boundary between hooks and CLAUDE.md below.

How do you write a minimal CLAUDE.md in 5 minutes (ready-to-use template)?#

Below is a template I’ve tested across dozens of my projects. It keeps the file around 80-120 lines, within Anthropic’s recommendation to aim under 200 lines. With this template, the agent gives the most sensible results.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

To have Claude fill in this template for your project automatically, give it this prompt. It will read the context and fill in the square-bracketed fields:

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

Aim to keep the resulting CLAUDE.md under 200 lines. If it is longer, review duplication and move detailed procedures to linked files. Preserve essential planning, reflection, and repo rules, then test them on representative tasks.

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

If you don’t yet have about-me/ and business/ folders, that’s okay. Claude will ask clarifying questions and put together a minimal CLAUDE.md based on what’s available. You can create the folders later, once you know what to put in them.

What 6 rules make CLAUDE.md a living document?#

Rule 1. Keep it under 200 lines

Anthropic says it succinctly in its official documentation:

A long CLAUDE.md works against itself in two ways. First, it burns tokens. An 800-line file of instructions is loaded into every window and uses up several thousand tokens from your budget in every session. On a Pro subscription with a daily limit, that noticeably reduces the number of sessions available. Second, the model starts ignoring the rules.

The documentation recommends aiming under 200 lines to reduce context use and improve adherence. It does not establish a sharp failure boundary at line 201. Review relevance, contradictions, loaded token volume, and actual task results before deciding what to move out.

Rule 2. End every session with a reflection

In CLAUDE.md, write: “At the end of each session, record what you did and learned in retrospectives/YYYY-MM-DD_*.md.” Once you add this line, Claude starts ending every session with a reflection on its own; you don’t have to ask.

Why reflect:

• Two weeks later, you can open an old retrospective and remember why you chose that path.
• When you return to the project a month later, you have a ready-made map of recent decisions.
• If you work with a team, a partner can read the retrospective and understand the current state in 2 minutes, without a call.

Rule 3. Commit after every completed task

My CLAUDE.md says: “After every completed task, create a git commit with a meaningful message.” Claude starts breaking the work into atomic commits on its own.

This gives you two things. First, if something breaks, you can roll back one operation, not “everything I did today.” Second, the commit history becomes a work log showing what changed and in what order.

Rule 4. Always consult the business/ folder

For any task involving customers, products, or copy, the agent should first open business/INDEX.md and the relevant file from there. My CLAUDE.md says explicitly: “When working on the UI or copy, first check business/audience/avatar.md and business/assets/brand-guidelines.md.”

Without this rule, Claude writes copy in “the general style of a quality website.” With it, the copy is in your style, for your customer, without your forbidden words.

Rule 5. Add a rule after every agent mistake

This is the main rule that keeps CLAUDE.md alive.

Examples from my own CLAUDE.md that were added after specific mistakes:

• “Never commit someone else’s WIP files with git add . - stage files by name.”
• “Before pushing to main, check git log origin/main..main --oneline - if it isn’t empty, don’t push.”
• “Don’t make up values - get them from .env or the code. Especially URLs, usernames, and tokens.”

Each of these lines is the trace of a specific incident. Once, an agent committed a partner’s unfinished branch. Once, I included someone else’s unpushed commits. Once, an agent made up a URL that doesn’t exist. Each mistake becomes a rule, and the same self-inflicted wound doesn’t happen again.

Rule 6. Put security in .claude/settings.json, not CLAUDE.md

In CLAUDE.md, you can write “don’t touch .env,” but that’s a request; Claude may violate it because CLAUDE.md is loaded as a user message, not a law. For critical security, use .claude/settings.json, where you can strictly block certain commands.

The blocklist I add to every new project:

• rm -rf (recursive deletion of any files).
• Reading .env in full (Read .env).
• export and curl in the same command (a pattern for leaking secrets externally).
• git push --force without explicit approval.

Find other guides at Ailoot.

How is CLAUDE.md structured in an active business (anatomy of a 280-line file)?#

Most CLAUDE.md examples online are technical templates for developers: “Use TypeScript,” “Don’t write tests longer than 50 lines.” For an entrepreneur, this kind of CLAUDE.md is useless - it doesn’t cover the business side.

Below is the structure of my working CLAUDE.md. I’ve removed the specific rules and paths because they reflect my internal operations. But the structure and logic of the sections can be applied to any project: plug in your own circumstances, and you get a working file.

1. Brief project description (15 lines). What we do, who the audience is, what products we offer. Not a marketing-site recap, but a summary for the agent so it understands “where we’re going.”

2. About me (10 lines). A pointer to the about-me/ folder - a digital projection of how I think. Tone, values, principles, forbidden words. When Claude writes text “as me,” it reads this folder first so the voice matches.

3. Repository structure (20 lines). A tree with comments: where the code is, where business context lives, where plans and reflections are. Without this map, Claude searches for files blindly every time.

4. “Where to find things” table (25 lines). Routing from “question → file.” For example, for a real estate agency, it might say “need mortgage terms → business/products/mortgage.md,” or “need the tone of voice for posts → business/assets/voice.md.” Substitute your own files. This table is the heart of CLAUDE.md. Without it, the agent guesses which file contains the answer. With it, it goes straight to the source.

5. Key project principles (40 lines, 10-15 items). This section accumulates slowly and costs the most effort. Every item is the trace of a specific mistake. For an online store, for example, the rules might be “never hardcode prices and delivery times,” “don’t publish a product without an explicit command,” and “check the style against the brand glossary before publishing a product listing.” This section is the “project constitution.”

6. Operational planning (20 lines). A trigger table mapping “user phrase → action.” For example: “When I say ‘plan the week,’ open ops/monthly.md and create the week’s file.” This turns Claude into an operations assistant that understands the context of commands.

7. Tools (5 lines). Technologies. Briefly, without fluff.

8. Publishing (15 lines). A step-by-step process for publishing changes to production: which commands to run, in what order, and what to check. I used to explain it every time. Now Claude knows.

9-12. Security (35 lines). Four separate subsections: rules for working with .env, access to the production database, safe commands for demos (screen recordings, streams, screenshots, so tokens aren’t accidentally exposed), and rules for rotating secrets.

13. The plans/ folder (10 lines). The plan standard: filename, phase structure, and what to put in the summary block.

14. The retrospectives/ folder (5 lines). The reflection standard: template, filename, and what it should contain.

15. Live database data (15 lines). A rule for marking “fresh data”: when a file says figures must be current, the agent retrieves them from the source instead of using old ones. This removes the risk of Claude using yesterday’s figures.

16. Language (3 lines). “Always respond in the user’s preferred language. Use hyphens only, not em dashes.”

About 280 lines in total. That exceeds the compactness target but does not make the file invalid. In this example it remained useful; keeping it should depend on measured context use and representative task checks. Tables are not automatically cheaper in tokens than prose.

What does the /init command do, and why isn’t it enough?#

Anthropic describes the command this way in its documentation:

What /init does well:

• Identifies the tools from package.json, Cargo.toml, and pyproject.toml.
• Lists build and test commands.
• Picks up conventions from existing files (.eslintrc, .prettierrc).
• Notices existing Cursor rules (.cursorrules, .cursor/rules/) and Copilot rules and incorporates relevant parts. It picks up AGENTS.md in CLAUDE_CODE_NEW_INIT=1 mode.

What /init won’t do:

• It won’t know who your customer is.
• It won’t include your forbidden words for copy.
• It won’t add rules about agent mistakes (because there haven’t been any yet).
• It won’t create a “where to find things” table for your business structure.

So the right workflow is:

1. Run /init in Claude Code

   You’ll get a starter CLAUDE.md of 30-50 lines with tools and commands. This is the technical foundation.

2. Layer the template from this article on top

   Use the section “A minimal CLAUDE.md in 5 minutes.” Add sections for navigation, routing, and principles.

3. Fill in the square-bracketed fields

   Give Claude the prompt “read my project and fill in the template.” If the business/ and about-me/ folders don’t exist yet, Claude will ask clarifying questions.

4. Run a stress test

   Tell Claude, “Read my CLAUDE.md and find 10 ambiguities that might cause you, as an agent, to misunderstand.” You’ll get a list of fixes.

5. Then, live with the file

   Add a line after every agent mistake. In a month, you’ll have a living CLAUDE.md tailored to your business.

Prompt for step four:

I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.

Your task is to stress-test it. Find 10 reasons we could potentially fail:

where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it

where there are gaps that would force you to make things up

where rules contradict one another

where I overestimate how much can be done in one day

where I underestimate things (this is even worse)

Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.

CLAUDE.md vs AGENTS.md vs MEMORY.md: who reads what in 2026?#

The main question that confuses newcomers is: does Claude Code read AGENTS.md? Before September 2026, the answer was “no”: Anthropic’s documentation advised creating a CLAUDE.md that imports AGENTS.md. Since version 2.1.277 (released September 18, 2026), Claude Code reads AGENTS.md itself, but only if there’s no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working folder or above it.

If the project has a CLAUDE.md, Claude Code reads only that by default and skips AGENTS.md. You can change this in /config, under Project instructions: for example, the claude-md-and-agents-md setting makes it read both files. Another way works in any version: add an import to CLAUDE.md:

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

The @filename syntax imports another file. Claude reads it and loads it into context along with CLAUDE.md. The import doesn’t cause the file to be read twice, even if Claude Code can read AGENTS.md on its own.

When you need AGENTS.md. If you work in parallel with Claude Code and Codex CLI, Cursor, or Copilot, create an AGENTS.md as the single source of truth, put @AGENTS.md in CLAUDE.md, and add any Claude-specific rules on top. If there are no such rules, you don’t need to create CLAUDE.md: since version 2.1.277, Claude Code will read AGENTS.md itself. If you work only in Claude Code, you don’t need AGENTS.md; use just one CLAUDE.md. For all the options step by step, see the guide to using AGENTS.md and CLAUDE.md in one project.

What is MEMORY.md? Since a recent update, Claude Code automatically keeps notes about you in ~/.claude/projects/<project-name>/memory/MEMORY.md. These include conversational habits (“the user prefers short answers”), recurring phrases (“forbade emojis in code”), and behavioral observations (“works on macOS, uses zsh”).

This is a separate memory system, not CLAUDE.md. You don’t write it by hand; Claude does, based on your conversations. If MEMORY.md contains something that should become a rule, move it to CLAUDE.md. If it contains something unnecessary or incorrect, you can delete it manually; it’s a text file.

What is a useful CLAUDE.md size, and how should you review a long file?#

In every Claude Code window, several layers are loaded into context: Anthropic’s system prompt (estimated at tens of thousands of tokens), your CLAUDE.md, files imported with @, MEMORY.md, the current chat history, and the contents of files Claude opens. All of this has to fit into the model’s context (200K tokens for Sonnet, 1M for Opus).

The bigger CLAUDE.md gets, the less room there is for current work. A 1,000-line file is about 8,000 tokens, repeated in every session. On a Pro subscription (in my experience, around 10-12 “heavy” prompts a day), that cuts your capacity by a quarter.

Cost is only one concern. Adherence can degrade when instructions are long, irrelevant, or conflicting; there is no universal number of reliably followed instructions. Test a few representative tasks that exercise the critical rules, record failures, and compare behavior after a focused edit.

So here’s the rule of thumb for size:

• 80-120 lines - a convenient starting range for a concise project map, not a guaranteed adherence score.
• 150-200 lines - a useful prompt to review relevance and move detailed procedures to linked files.
• 200-300 lines - inspect token volume, duplication, and task results; the 280-line business example above may still work well.
• 400+ lines - a strong reason for a focused review, not proof that the file is unusable. Keep essential constraints and move detail only after checking that the links and rules still work.

Line count alone cannot establish success or failure. After an edit, repeat the same representative tasks and verify the important rules, rather than assigning an invented compliance percentage.

Anthropic gives a direct test in its documentation:

Apply this to every line. If the answer is “it would still get it right,” remove the line. CLAUDE.md isn’t the place for documentation, decision history, or philosophy. It’s only for the rules the agent needs to avoid messing up.

What 7 mistakes make CLAUDE.md useless?#

Mistake 1. “Be a good engineer”

The most common mistake. People write general wishes in CLAUDE.md: “write clean code,” “use best practices,” “think like a senior engineer.”

These words don’t mean anything. Claude already writes “clean code” in a general sense. These lines take up context without affecting any decision.

Replace “write clean code” with “use 2-space indentation,” “don’t use any in TypeScript,” or “functions must be no longer than 30 lines.” Specific and verifiable.

Mistake 2. Duplicating what Claude already knows

Descriptions of standard language conventions (“in JavaScript, functions are first-class citizens,” “TypeScript has static typing”). Explanations of how npm, git, or docker work.

Claude learned all this during training. Duplicating it in CLAUDE.md adds nothing; it only cuts into your context.

Mistake 3. Long step-by-step instructions inside CLAUDE.md

Long instructions on “how to deploy the project,” “how to write a database migration,” or “how to set up a new component.” Dozens of step-by-step lines.

This isn’t the place for long step-by-step instructions. It’s for one-line rules. Put long instructions in skills/ (a separate Claude Code mechanism loaded on demand) or in docs/. In CLAUDE.md, use a one-line link: “When creating a new migration, open docs/migrations.md.”

Mistake 4. Rules already checked by an automatic code analyzer

“Use semicolons,” “don’t leave unused imports,” “don’t use var.” ESLint, Prettier, and Biome catch all of these - they’re linters (automatic code-checking tools).

A linter is deterministic: it runs, finds an error, and fixes it. A CLAUDE.md rule is probabilistic; the agent may forget. There’s no need to duplicate it - it’s easier to configure the linter.

Mistake 5. Secrets in CLAUDE.md

I’ve seen test account passwords, sandbox API tokens, and links to authenticated admin panels. All of it was in a file committed to git and loaded into Anthropic’s model context.

Never. Secrets belong in .env, which is in .gitignore. At most, CLAUDE.md should say: “Don’t read .env in full; use grep for a specific variable.”

Mistake 6. A 500+ line dumping ground that hasn’t been cleaned up in six months

CLAUDE.md has grown, duplicates half of docs/, contradicts itself in several places, and no one remembers what’s in it. The agent starts ignoring most of it. The team complains that “Claude doesn’t follow instructions” and adds more rules, making things worse.

Signs that a CLAUDE.md is neglected: more than 300 lines, repeated rules in different sections, outdated links to files that no longer exist, and “historical” notes such as “in 2024 we decided to do it this way, then changed our minds.”

The fix: every two weeks, ask Claude to review it using Anthropic’s test, “If this line were removed, would the agent make a mistake?” Delete anything where the answer is “no.”

Mistake 7. CLAUDE.md created and forgotten

This is the opposite of the previous mistake. The file was put together once, two months ago, and hasn’t been touched since. In the meantime, the tools have changed, new folders have been added, and new agent mistakes have surfaced. CLAUDE.md knows none of this because nobody has updated it.

A telltale sign: you repeat the same instruction in every session. “Don’t do X,” “don’t touch Y,” “remember Z.” If you’ve repeated it more than twice, the rule belongs in CLAUDE.md, not in your head.

How do you make CLAUDE.md self-learning with an “update at the end of the session” rule?#

My CLAUDE.md has a short section:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

After this section was added to CLAUDE.md, Claude started asking at the end of every session: “Was there anything new worth recording?” If there was, it suggested a draft rule, I clarified it, and a file was created.

After two months of working this way, I have more than two dozen files in about-me/feedback/ - rules learned from specific mistakes. Each file is one page in the Rule → Why → How format. The folder became a “second memory” recording my individual preferences and taboos.

Each mistake isn’t repeated because it becomes a rule, and rules accumulate and reinforce one another. After six months, Claude knows my project better than I remember it after a month-long break.

How do you add legal rules, marketing, and operations to CLAUDE.md?#

For most teams, CLAUDE.md is a purely technical document: tools, build commands, coding conventions. That’s useful, but it’s only a third of the value.

When an entrepreneur maintains CLAUDE.md, it makes sense to add business sections. Three matter most:

Legal rules (for regulated markets)

If you publish copy in a regulated industry (finance, medicine, drug advertising, children’s products), forbidden words have legal weight and belong in CLAUDE.md as explicit rules. Not in someone’s head, not in an editor’s screenshot - in a file the agent sees in every session.

Example for a fintech project without a banking license:

Editorial note: The following shows the format of an internal rule for a specific project. It is not universal permission to use the listed terms: whether a statement is acceptable depends on applicable law and the company’s status.

🚨 CRITICAL - financial wording is prohibited. In customer-facing materials, do not use: “deposit,” “guaranteed return,” or “investment product.” Use: “savings account,” “expected return,” and “variable-rate product.” The reason is the legal requirements applicable to advertising financial services for this project.

This block in CLAUDE.md does something simple: every time you ask Claude to write customer-facing copy, the agent checks it against these prohibitions. Without the rule, forbidden words crop up in every third campaign. With it, you forget they exist.

The same approach works for:

• Medical projects (no claims that something “treats” or “cures”).
• Drug advertising (no “most effective” claims; required warnings).
• Any regulated industry with its own advertising rules.

Marketing style and copy format

If you publish copy regularly (social media, newsletters, websites), it’s worth documenting the format in one paragraph in CLAUDE.md. Here’s an example of what an influencer or agency running a messaging channel might write:

When writing channel posts, consult style/posts.md. Use the channel’s permitted formatting markers and avoid “dangerous” special characters. End with a CTA that has a UTM tag following this convention: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Claude used to write posts in “the general style of a marketing website.” Now it follows your format, uses your UTMs, and doesn’t give away that it’s AI-written.

Operational habits

Trigger tables. When you say a specific phrase, the agent knows which files to open and what actions to take. Here’s an example for a team that plans by the week:

“Plan the week” → open ops/monthly.md, create YYYY-WNN.md in the same folder, and move the tasks from ops/backlog.md under the appropriate days. “What’s in the backlog?” → read ops/backlog.md and show it as a list. “Close the week” → fill in the “Week summary” section in the current week’s file.

With tables like these, Claude goes from a “helper that writes code” to an “operator” that knows your business routine. Every Monday, I say “let’s plan the week,” and Claude opens the right files, reads the monthly goals, and suggests how to break things down.

How do you check your CLAUDE.md against a 12-point checklist in 5 minutes?#

1. Size. Is it concise, with roughly 200 lines as a review target rather than a pass/fail ceiling?
2. Name. Is it exactly CLAUDE.md with uppercase letters, not claude.md?
3. Location. Is it at the project root or in ./.claude/CLAUDE.md?
4. Project description. Do the first 5 lines make clear what the project is and who it’s for?
5. Tools. Are the technologies listed explicitly and without fluff?
6. Structure. Is there a repository diagram with explanations?
7. Routing. Is there a “question → file” table showing where to find answers?
8. Principles. Is there a section with rules that begin with “never” and “always”?
9. Specificity. Is every rule verifiable? (“Use 2 spaces,” not “write beautifully.”)
10. Self-updating. Is there a rule to “check what to add at the end of the session”?
11. Reflection. Is there a rule to “record the session summary in retrospectives/”?
12. Security. Are critical prohibitions (.env, rm -rf) also included in .claude/settings.json?

If you have more than five “no” answers, open Claude and give it this prompt:

Read my CLAUDE.md and compare it with the checklist below. For each item, say: yes / no / partly, and what specifically to fix.

Checklist:

Compact enough for the task; review around 200 lines without treating it as a hard ceiling

Project description in the first 5 lines

Tools listed explicitly

Repository structure diagram included

“Question → file” table included

Principles section with rules included

Every rule is specific and verifiable

“Update at the end of the session” rule included

“Reflect at the end of the session” rule included

Critical prohibitions included in .claude/settings.json

No duplicates of the same rule in different sections

No dangling links to files that no longer exist

After the audit, give me a list of specific changes that will make the file living.

What should you use after CLAUDE.md: Plan Mode, Skills, or sub-agents?#

CLAUDE.md is the foundation. Once it works, you can add three Claude Code mechanisms that reinforce one another.

Plan Mode. A mode in which Claude first creates a change plan, waits for your approval, and only then starts working. Activate it with Shift+Tab or the /plan command. It addresses the main pain point of vibe coding: “I asked Claude to fix one thing, and it rewrote half the project.” That won’t happen in Plan Mode - you see the plan before the agent touches any files.

Skills. Separate .md files in the .claude/skills/ folder containing knowledge for a specific type of task. For example, a “how to write a database migration” skill contains a specific procedure, a template, and examples. That knowledge isn’t in CLAUDE.md because it’s too extensive. But when Claude encounters a task like “write a migration,” it loads the relevant skill and follows it.

Sub-agents. When a task needs a lot of context (for example, reviewing a large feature), Claude can start a separate sub-agent in its own clean context. The sub-agent does the work and returns the result without cluttering your main chat context.

All three mechanisms use CLAUDE.md as their entry point: they read it at the start of their work to understand the project context. That’s why these features also work poorly without a living CLAUDE.md. Foundation first, then the layers on top.

Next step. Create a CLAUDE.md file at the project root, copy the template from the beginning of this article, and fill in the square-bracketed fields using the helper prompt. Then live with the file: turn each agent mistake into one new line. After two or three weeks, CLAUDE.md stops being “a document we wrote and forgot” and becomes something Claude actually consults every session.

If you want to build a complete framework around CLAUDE.md - a business/ folder for a second brain, an about-me/ folder for a digital projection of you, basic skills, and a configured Plan Mode - use the steps and examples in this article. Ailoot Guides.

Continue with Ailoot.