Your CLAUDE.md Is In The Wrong Folder And Nothing Will Tell You

Six steps to a working Claude Code agent: install, context, memory, skills, agents, autopilot. Every step comes with a prompt written out for you to copy. It is a well-made card, most of it is accurate, and the features it describes are real – skills, subagents, scheduled runs all exist.

But notice what kind of instruction this card is mostly made of. Four of the six steps tell you to write a file to a specific path. ~/CLAUDE.md. ~/.claude/projects/{project}/memory/. ~/.claude/skills/[name]/SKILL.md. ~/.claude/agents/.

A path is a different kind of instruction from a prompt, and it fails differently. Give a model a badly worded prompt and you get a bad answer – visible, annoying, fixable in a minute. Write a file to the wrong folder and you get nothing at all. No error, no warning. The file sits on your disk looking exactly right, Claude never reads it, and you carry on for weeks believing you configured something you did not.

So we did what the card’s own footer asks – “Check Claude’s official docs before you rely on them” – and checked all four paths against Anthropic’s documentation.

Step 2 is wrong.

The card says, twice, that ~/CLAUDE.md is “the onboarding doc Claude reads before every chat”, and its copy-paste prompt ends “Save the final file to ~/CLAUDE.md.” Anthropic’s memory documentation lists the locations in a table, and the user-level one is:

User instructions  →  ~/.claude/CLAUDE.md

Not ~/CLAUDE.md. The file belongs inside the hidden .claude folder. Put it one level up and it is just a markdown file in your home directory.

Four kinds of mistake, and only two of them shout

This is the thing worth taking away even if you never build an agent. Setup instructions fail in several ways, and they are not equally detectable.

Diagram: loud failures and silent ones

Rows three and four are the dangerous ones precisely because the system keeps working. Nothing breaks. You simply never get the benefit you believe you are getting, and because there is no error message there is nothing to search for.

This is the same category of problem we hit with a card of domains where “it loads” was not sufficient evidence. A thing that appears to work is the hardest kind of broken to catch.

The six steps, checked against the docs

Four of six are right. We are listing all of them so you can see the ratio rather than just the misses.

Step 3 builds by hand what already ships in the box

The idea behind step 3 is completely right: “Every correction becomes its own .md file. The same mistake never lands twice.” That is a real and valuable behaviour, and most people never set it up.

They do not need to. Anthropic’s memory documentation describes two systems that both load at the start of every session. CLAUDE.md files, which you write, containing instructions and rules. And auto memory – described as “notes Claude writes itself based on your corrections and preferences”, scoped per repository and shared across worktrees, loaded into every session.

That is step 3, as a feature, maintained by the people who make the tool.

The card’s hand-rolled version writes corrections into ~/.claude/projects/{project}/memory/ with filename prefixes and a hand-maintained index. It will probably work, in the sense that Claude can read files you point it at. But you are now maintaining a convention that nothing enforces, in a folder the documentation does not describe as a memory location, instead of turning on the thing that is designed for it.

The docs also give a useful dividing line the card does not: facts go in CLAUDE.md, procedures go in a skill. If a section of your CLAUDE.md has grown into a multi-step process, that is the signal to move it to SKILL.md – which is exactly what step 4 is for. The two steps are more connected than the card shows.

A 95/100 gate written in markdown does not fail anything

Step 5 is the one that sounds the most rigorous and is the most misunderstood. “Add a 95/100 QA gate that fails any work below the bar.”

Here is the sentence from Anthropic’s documentation that settles it:

“Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.”

A number written into an agent’s markdown file is an instruction the model will usually follow. It is not a gate. Nothing checks the score, nothing computes it, and nothing stops the work moving on if the model decides it is a 96 when it is a 70. There is no scoring function anywhere in this setup – the agent is being asked to grade itself and then honour its own grade.

That is not worthless. Asking for a self-assessment genuinely does raise quality, because it makes the model re-read its own output against a standard. But call it what it is: a review habit, not a gate. If you want an actual gate – something that refuses regardless of what the model concludes – the docs name the mechanism, and it is a hook, not a sentence.

The distinction matters most at exactly the moment you stop watching. We made the same point about an agent setup where the lock-down step was numbered after the exposure step: a guardrail you describe is not a guardrail you have.

Five minutes to check all of it

Everything above is checkable in your own terminal, and should be, because file paths change and our reading is dated. Here is the verification pass.

Check one takes thirty seconds and settles the whole CLAUDE.md question for your machine, whatever a card or a blog post says. Check five is the one almost nobody does, because deliberately producing bad work to see if your own system catches it feels like a waste of an afternoon – right up until the first time it does not catch it.

Four honest caveats

Four of the six steps are right, and the card is well built. Step 1 names three install surfaces where most guides name one. Step 4 is correct on both the path and the reasoning. Step 5 has the agents folder right and the Opus-for-analysis, Sonnet-for-execution split is a sensible pattern. This is a better guide than most, which is exactly why the two silent problems are worth naming.

The footer invited this. “Features, commands and file paths change often. Check Claude’s official docs before you rely on them.” That is the correct instruction, printed on the card, and following it is the only reason we found anything. Credit where it is due – and the same sentence applies to this post.

We read docs; we did not run the full setup. We checked the paths against Anthropic’s published documentation on 10 October 2026 and quoted it directly so you can verify rather than trust us. We did not install a six-agent team or run a scheduled job for a week. If your machine behaves differently, your machine is the authority.

And paths move. Everything here is a statement about documentation as it stands today. The whole point of the post is that these things change silently, which includes changing in ways that make this article wrong. Run check one yourself; it takes thirty seconds and it is true for your machine rather than for ours.

The one-line version

Four of these six steps write a file to a path, and a wrong path is the only instruction on the card that fails without telling you. Step 2 says ~/CLAUDE.md; the docs say ~/.claude/CLAUDE.md. One hidden folder, and the difference between a file that shapes every session and a file nobody reads.

Two more things worth knowing before you follow it. Step 3 hand-builds a memory system that Claude Code already has as a feature. And the “95/100 QA gate” in step 5 is a sentence in a markdown file – the docs are explicit that such instructions are context, not enforced configuration, and they name hooks as the thing that actually blocks.

So: write the file, then prove it loaded. Put a silly word in it, open a fresh session, and see whether the word comes back. Thirty seconds, and it is the only evidence that any of this is switched on.

Learning a lot does not make anyone good. Doing a lot does. But setting a thing up is not doing, either – setting it up and then checking it works is, and the second half takes a fraction of the first.

If you want to be held to that, we run a free challenge at BANI Academy. There is no barrier to entry – you commit a small fee that is refunded when you finish, and the only requirement is that you actually do the work for the length of the challenge.

Run the banana test on your own CLAUDE.md and tell us whether it came back. Comments are under the original post – and if yours was in the wrong folder, you are not the only one.

More on building a channel for a global audience at mmoyoutube.com.