Where does the CLAUDE.md file go?

In the top of your project folder. Claude Code reads it at the start of every conversation in that folder. A CLAUDE.md in ~/.claude/ applies to every project on your computer.

How long should a CLAUDE.md be?

Under 150 lines, and shorter is better. Every line is read on every task, so put detail in other files and give CLAUDE.md one line saying when to read each one.

What is the difference between CLAUDE.md and a skill?

CLAUDE.md is read in every conversation, so it holds rules for every task. A skill holds the steps for one task you repeat, and loads only when you run that task.

Does Claude always follow CLAUDE.md?

Usually, but not always. For anything that must never happen, like deleting files or pushing code, add a deny rule in .claude/settings.json or a hook, which Claude Code enforces.

How do I keep my CLAUDE.md up to date?

When Claude makes the same mistake twice, add one line about it. Every few weeks, review your recent sessions and remove lines you no longer need.

All guides

Guide

How to write a good CLAUDE.md

What CLAUDE.md is, how Claude uses it, and how to keep yours short and useful.

By Austin Marchese · Updated November 7, 2026

How CLAUDE.md works

CLAUDE.md is a text file of instructions in your project folder. Claude Code reads it at the START of every conversation, so it impacts every conversation you have. Below is an example CLAUDE.md file and an explanation of each line. Then at the end is a prompt to optimize your CLAUDE.md

Keep it under 150 lines. Every line is read on every task and costs tokens on every message, so a long CLAUDE.md is slower, costs more and buries the rules that matter. Put the detail in other files and give CLAUDE.md one line saying when to read each one.

Example CLAUDE.md

About 30 lines, in the same structure as your Company Brain from Part 1. Select a note to see the lines it explains.

# Acme Coaching Company Brain
 
1## About
1- Acme sells 1:1 coaching to agency owners. I run it with two contractors.
1- Right now: launching a group program in March.
 
2## How this folder works
2- raw/ holds originals. Never edit them.
2- wiki/ holds the pages you write. One topic per page, with a last-updated date.
2- wiki/departments/ holds marketing, sales, operations and leadership.
 
3## Before any question or task
3- Check wiki/index.md and read the page that covers it.
3- If I ask about my business and no page covers it, say so instead of guessing.
 
4## Where to look
4- Writing anything in my voice: read wiki/voice.md first.
4- Anything about offers or prices: read wiki/offer.md.
4- Before any change to the website: check wiki/design-system.md.
 
5## Skills
5- Writing the weekly newsletter: run /newsletter.
5- Turning a call into a proposal: run /proposal.
 
6## How I work
6- Interview me before any new build and show me the key decisions.
6- Pick the simplest solution that works.
6- Before any task, say how you will check it worked.
 
7## Mistakes to watch for
7- Use only client results from wiki/results.md. You have made numbers up before.
7- Prices change often. Read wiki/offer.md instead of remembering them.
7- Older mistakes and their fixes: wiki/mistakes.md.

What not to put in CLAUDE.md

Each of these makes CLAUDE.md long. Here is where to put each one instead.

Steps for a task you repeat

A skill. The steps load only when you run that task, not in every conversation.

Actions that must never happen

Permissions in .claude/settings.json, or a hook. Claude usually follows CLAUDE.md, but not always. Claude Code enforces settings.json permissions and hooks, so a blocked action, like deleting files or pushing code, cannot happen.

Long background and detail

A page in wiki/. Listed in wiki/index.md, one topic per page with a last-updated date, so Claude opens it only when a task needs it and you update it in one place.

Your next step

Fix your CLAUDE.md

Claude backs up your CLAUDE.md, then goes through each rule on this page with you and fixes your file one change at a time, with your OK on each.

Copy this prompt

Keep it short over time

Run this every few weeks. It reviews your recent sessions, adds the mistakes Claude keeps making and removes lines you no longer need.

This command comes with BuildPartner.ai. Get BuildPartner.ai →

Questions about CLAUDE.md

Where does the CLAUDE.md file go?: In the top of your project folder. Claude Code reads it at the start of every conversation in that folder. A CLAUDE.md in ~/.claude/ applies to every project on your computer.
How long should a CLAUDE.md be?: Under 150 lines, and shorter is better. Every line is read on every task, so put detail in other files and give CLAUDE.md one line saying when to read each one.
What is the difference between CLAUDE.md and a skill?: CLAUDE.md is read in every conversation, so it holds rules for every task. A skill holds the steps for one task you repeat, and loads only when you run that task.
Does Claude always follow CLAUDE.md?: Usually, but not always. For anything that must never happen, like deleting files or pushing code, add a deny rule in .claude/settings.json or a hook, which Claude Code enforces.
How do I keep my CLAUDE.md up to date?: When Claude makes the same mistake twice, add one line about it. Every few weeks, review your recent sessions and remove lines you no longer need.

From the program

The Executive AI Program

This guide is one of the resources in the program, where members build their AI system step by step.

1.1 · Get set up
1.2 · Company Brain
1.3 · Enhance your setup
1.4 · Your BuildPartner.ai tools
1.5 · Research your market
1.6 · Writing style
1.7 · Automate your system
1.8 · Optimize your token usage
Part 2 · Your AI Team
Part 3 · Go deep

Learn more