Notes: Stop Explaining Yourself Every Session

Ideas to keep

1. 01CLAUDE.md sits in your project, and Claude reads it at the start of every session before you type a word.
2. 02Claude Code ignores the file sometimes, and it does that quietly. You find out when the work comes back wrong.
3. 03The alternative to a rule that holds most of the time is you, remembering to say it every morning on every project.
4. 04The file fills up. Workarounds get added for problems that later get fixed, and nobody checks which ones.
5. 05Twice a year, empty the file out and put back only what the model genuinely still gets wrong.

Ideas to keep

1. 01Your project has a folder called .claude. The file goes in there and is called CLAUDE.md.
2. 02Write the name in capitals. A lowercase name may seem to work on a Mac, but on another machine or on Linux the file is never found.
3. 03The question that decides every line is: if I delete this line, will Claude Code get something wrong?
4. 04Claude Code reads the file when the session opens, not in the middle of one. A line you add mid-session waits for the next session.
5. 05The file goes to GitHub when you push. Keep anything private out of it, or use CLAUDE.local.md for a version just for you.
6. 06One run before and one run after is a demonstration, not proof.

Follow along

1. Make a request without a rules file in the project, so you have something to compare against.
2. Ask Claude to create a CLAUDE.md file and paste the 2 rules in as the content. Let Claude write the file rather than typing it yourself.
3. Check the path before you allow anything. It should be .claude slash CLAUDE.md.
4. Run the same request again in a fresh session. Do not remind Claude of anything.
5. Type slash context to see your file on the list and what it costs. In the demo, 2 rules cost 52 tokens.
6. If you want a private version for yourself on one project, name the file CLAUDE.local.md.

Ideas to keep

1. 01CLAUDE.md comes in 2 kinds. The project one applies only there. The user-level one lives in the .claude folder inside your user folder and loads into every project you open.
2. 02Claude Code also reads a CLAUDE.md in a folder above your project, and a company can add one for the whole team. None of them switches the others off.
3. 03A CLAUDE.md inside a subfolder does not load at the start of the session. It reaches Claude when the work goes into that folder, and the memory list will not show it.
4. 04When 2 rules contradict each other, neither wins automatically. Write the answer into the file yourself.
5. 05The sorting question: would a stranger who inherited this folder need this rule to do the job properly? If yes, it is a project rule. If it is only true because of how you like to work, it follows you.
6. 06A CLAUDE.md can pull in another file. Write an at sign followed by the path.

Follow along

1. Click the context ring, expand the context window, then expand memory files. That lists every memory file this session holds. In the terminal, type slash memory instead.
2. Read each rule and ask the stranger question.
3. Cut the personal rule out of the project file and paste it into your user-level file.
4. If your user-level file is not on the list, start a new session. The current session loaded before the file existed.
5. When the file grows, split it. Put each topic in its own file and pull them in with an at sign and the path.

Ideas to keep

1. 01Claude keeps a memory of its own, apart from your CLAUDE.md. It decides which corrections and practical facts are worth keeping.
2. 02The notes are plain markdown, stored outside your project folder, so they do not go to GitHub.
3. 03At the start of every session Claude Code reads the first 200 lines of that memory, or 25 kilobytes, whichever comes first.
4. 04Claude saves its own reading of what you said, and that reading can be wrong. A wrong note loads every session and looks like a true one.
5. 05Your CLAUDE.md is what you decided. Auto memory is what Claude concluded.

Follow along

1. Type slash context and expand it. Expand the memory files row and look for MEMORY.md under the CLAUDE.md files.
2. Click MEMORY.md to read it. It is an index, and the blue lines are links to the notes.
3. In the terminal, type slash memory and pick the line that says Open auto memory folder.
4. Every so often, read the notes and delete anything wrong.
5. If you tidy it by hand, keep it to one line per entry.
6. If you would rather Claude did not do this on a project, one setting turns it off.

Ideas to keep

1. 01Slash init reads your folder and writes a first draft. If a file already exists, it proposes improvements and the lines you wrote by hand survive.
2. 02Claude can say a file is fine when it only checked that the sections existed. Ask whether it checked that they were accurate.
3. 03Every line lands in one of 3 places: you recognise it, you do not recognise it (a guess), or it is true but could describe any project like yours.
4. 04A team at ETH Zurich found that a context file did not generally improve how often the agent finished the task, and added more than 20 percent to the cost of every run.
5. 05Use the command as a typist and stay the author. Every line should be there because you decided it belonged.

Follow along

1. Open your project and run slash init.
2. Open the CLAUDE.md it wrote and read each line. Ask of each one whether it is true.
3. If a line is long, the top of the bullet is enough.
4. If you do not understand a line, select it and ask Claude Code about it.
5. Click view source and fix wrong lines yourself. Use search if you cannot find the line. Then save.
6. In the demo, Sonnet was chosen because it offers auto mode and the 1 million-token window. Haiku does not offer auto mode, and its window is around 250,000 tokens.

Ideas to keep

1. 01In the demo, Claude Code followed most of the 50 rules and broke 3 of them. None of the 3 announced itself.
2. 02The rules that went were not at the bottom of the file. The belief that top rules win and bottom rules lose was not found when a study moved a rule to the top, middle and bottom.
3. 03The IFScale study tested 20 models with 10 up to 500 instructions. At 500, the best model followed 68 percent of them. A short list gets a rule slightly wrong, and a long one stops mentioning it at all.
4. 04A study of 1,650 Claude Code sessions found that file size, rule position, file structure and a conflicting line in a neighbouring file made no measurable difference. How far into one session you are did. Each further piece of work carried roughly 5.6 percent lower odds that the rule held.
5. 05The documentation names 2 things that break a rule: vague wording, and rules that contradict each other.
6. 06When 2 rules collide, Claude Code goes with whichever looks more specific and quietly drops the other.
7. 07A written rule is a nudge rather than a switch. Emphasis such as IMPORTANT helps, until many lines are shouting at once.

Follow along

1. Write rules that are specific enough to check afterwards, and that do not argue with each other.
2. After a session, ask Claude Code to judge its own work against the file, using the prompt below.
3. Read the table. Look at the rows marked as broken and the ones that did not apply.
4. Read your file together once in a while, so 2 rules written months apart do not collide.
5. Let Claude work. In the demo, scrolling at the same time made it miss the button.

Ideas to keep

1. 01You are not configuring software. You are briefing a smart new person.
2. 02Say what the business is and what you are trying to achieve, then name the 2 or 3 things that will get them into trouble, with the reason.
3. 03A rule with a reason attached survives situations you never thought of. A rule without one only covers the situation you pictured.
4. 04Keep passwords and client details out. The file is sent along with your work every time you open a session.
5. 05Describing your own work clearly is the real skill here, and you already have it.

Follow along

1. Picture someone clever joining on Monday, with you having 10 minutes. Write what you would tell them.
2. Open with 2 sentences on what the project is and who it is for.
3. Then say what it is built with.
4. List the handful of things that matter, each with the reason underneath.
5. When you catch yourself correcting Claude on something the file should already have told it, open the file that evening and update it.

Ideas to keep

1. 01Anthropic calls it context rot. As the amount a model holds grows, it gets worse at recalling accurately what is in there.
2. 02Anthropic calls the limit an attention budget. Every extra thing you load spends some of it, and you cannot top it up.
3. 03Your file arrives whole at the start and stays whole. What weakens is the attention left for it once dozens of unrelated things sit in front of it.
4. 04In the NoLiMa study, 11 of 13 models scored below half of their short-document score at 32,000 tokens.
5. 05The repair is to empty the conversation, not the file. Slash clear removes nothing from the project and reloads CLAUDE.md.
6. 06Several small passes beat one big load on long work. That costs more in total, and it is worth it on work that matters.

Follow along

1. Pick a rule whose result shows in the answer itself, such as how Claude reports back.
2. Make several requests and watch the last thing Claude says each time.
3. Check any new rule this way: edit the file, start a new session, and read the very next answer.
4. When a session has run long and things start to loosen, run slash clear instead of pushing harder.
5. For long jobs, break the work into small passes.

Ideas to keep

1. 01Two things must be true. Claude Code has to be reading the file, and the rule has to be one you could check without arguing with yourself.
2. 02The memory files list shows the files Claude Code opened for itself. It does not show every file Claude ends up reading.
3. 03Pick a rule where following it and ignoring it give 2 answers that do not look alike, such as a table in every reply.
4. 04In the demo, the file's own rules pushed back on the request and named the rule numbers that stood in the way.
5. 05A rule can go stale and still work exactly as written. How much of your file is followed depends on how much of it is still true.

Follow along

1. Click the context ring, expand the context window, and expand the memory files. Check your CLAUDE.md is on the list.
2. If it is missing, check where the file sits: the root folder of the project, or the .claude folder inside it.
3. Check the name is CLAUDE.md in capitals.
4. Check you opened the session in the project you think you are in.
5. If you made the file during this session, run slash compact or slash clear, or start a new session in the same folder.
6. For the personal file, check it sits in your user folder, inside the .claude folder.
7. To check a rule works, change one rule to something visible in the answer, such as rule 50 below, and run a request.

Ideas to keep

1. 01Claude Code reads CLAUDE.md. More than 20 other AI coding tools read AGENTS.md for the same purpose, and the file is already in over 60,000 open-source projects.
2. 02Other tools write to AGENTS.md as well, so it fills up on its own. CLAUDE.md only grows when you add to it.
3. 03The knowledge goes in AGENTS.md. The one line goes in CLAUDE.md. The tools reading AGENTS.md cannot follow a line back the other way.
4. 04The memory files list shows the files Claude Code opens for itself, not the ones those files pull in.
5. 05The Claude Code study found no measured difference in how well rules were followed when the file was split across 2 names.

Follow along

1. Find AGENTS.md in the project root, next to index.html.
2. Ask Claude Code to reference AGENTS.md in CLAUDE.md. Do not say how.
3. Allow the write. It adds one line, an at sign then AGENTS.md.
4. Clear the session so everything loads fresh.
5. Ask Claude Code for your house rules, and check that the rules still come back.

Ideas to keep

1. 01Every CLAUDE.md grows. A line gets added after a bad afternoon, and a year later it is a document.
2. 02Shortening the file does not buy obedience. The real reason to cut is that a long file is harder to keep honest.
3. 03A study across nearly 1,900 projects found the files more than tripled in length, gaining about 5 lines with every round of changes.
4. 04The test is time. Will this still be true tomorrow, next month and a year from now? If yes, it stays. If it changes often, it moves to a second file.
5. 05A sentence pointing at the second file is a note, not an import. Claude opens that file only when the work needs it.
6. 06Hand Claude the test rather than a list of lines, so it can say no with a reason you can check.

Follow along

1. Put Claude Code on auto mode so it can work without stopping to ask.
2. Paste the request below, so Claude moves anything that changes often into notes.md.
3. Look at what moved. In the demo, only the status moved first.
4. Ask for one more pass on the file list and anything that will not still apply in a few months.
5. Read why Claude kept the lines it kept.
6. Run the compactor skill from the resources on any project, about twice a year.

Ideas to keep

1. 01Open the project tomorrow and the first answer will already be right, with no reminders.
2. 02The files are not the part worth being pleased about. You ran a test and watched the difference with your own eyes.
3. 03That check works on projects that do not exist yet.
4. 04A few honest notes in the right place is enough. It is not a system or a framework.
5. 05Your file tells Claude what the project is. It says nothing about how to do the job you do every Tuesday.