What you will be able to do
- Recognise the signals that a durable instruction is missing and should be written down rather than repeated in chat
- Choose the instruction file whose scope matches who the change should reach
- Predict when an edit to a CLAUDE.md file takes effect during and after a session
- Prune stale and aspirational rules on a regular review cycle
1.Signals that an instruction is missing
In Claude Code, durable instructions live in CLAUDE.md files. These are plain markdown files that you write, and Claude loads them at the start of every session. Claude also keeps a separate auto memory: notes it writes itself from your corrections and preferences. The two differ in who writes them. CLAUDE.md holds the rules and instructions you decide on. Auto memory holds what Claude has picked up on its own.
The Claude Code memory documentation lists the signals that something belongs in CLAUDE.md. Claude makes the same mistake a second time. A code review catches something Claude should have known about the codebase. You type the same correction into chat that you typed last session. A new teammate would need the same context to be productive. What these signals share is repetition. A correction typed into chat fixes one conversation. The same correction written into the instruction file fixes every conversation after it. The support guide puts the rule of thumb simply: if Claude gets something wrong twice, a rule is missing, so add one line.
A pricing analyst notices Claude quoting a discount tier that was retired at the last price review. What should the analyst do first?
Correct answer: B — Check the project's uploaded documents to see whether the retired price list is still in the knowledge base.
- A. A fresh chat still reads the same project knowledge, so the retired figures come back.
- B. Correct. Confirming whether a superseded source is still loaded is the cheapest way to explain the wrong answer.
- C. Public search is not a reliable source for internal pricing and leaves the stale file in place.
- D. This hides the symptom behind a disclaimer instead of removing the outdated source.
2.Put the change where it reaches the right people
Choosing where to make an update is a maintenance decision in its own right. Each CLAUDE.md location reaches a different audience. Put a team convention in a personal file and your teammates never see it. Put a personal preference in the shared file and everyone gets it.
| Scope | Location | Shared with |
|---|---|---|
| Managed policy | System location, managed by IT/DevOps | All users in organization |
| User instructions | ~/.claude/CLAUDE.md | Just you (all projects) |
| Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | Team members via source control |
| Local instructions | ./CLAUDE.local.md | Just you (current project) |
The project file reaches the team "via source control", and that phrase matters. Editing the file on your own machine is not enough to share the change. The guide's advice is to commit it to git so the whole team benefits. Claude Code settings behave the same way. A shared project settings file reaches a teammate's clone only after it is committed. Until then it is just a file on your disk.
3.Editing mid-session, and when the change takes effect
You don't have to wait until the end of a session to record a rule. You can open /memory to edit the file directly, or ask Claude to "remember" a rule, and Claude appends it to the right CLAUDE.md. Timing is the part people get wrong. CLAUDE.md is read at session start, and it is not re-read from disk on each turn. An edit made mid-session is picked up the next time you run /compact or open the file via /memory. Otherwise it takes effect in your next session.
Changes also have a small cost effect. Claude Code applies prompt caching to CLAUDE.md, and the cache is content-addressed. Any edit therefore invalidates the cache, and the next request pays the full input price again. That is no reason to avoid updates. It is one more reason to make them deliberately rather than constantly.
No. The file is not re-read from disk on each turn. The new rule will be picked up after /compact, after opening it via /memory, or in the next session. If the developer wants their teammates to get it too, they also need to commit the file.
Sources2
4.Pruning: stale rules are worse than none
The guide describes CLAUDE.md as a living onboarding document rather than a specification. It names specific moments to revisit the file:
| When | What to do |
|---|---|
| After /init | Review once to clean up the generated draft |
| When Claude gets something wrong twice | Add one line to address the missing rule |
| When conventions change | Update for the new framework, test runner, or set of lint rules |
| Quarterly skim | Delete anything stale |
The quarterly skim comes with a strong claim: outdated instructions are worse than none. A missing rule leaves Claude to work things out from the code. A stale rule actively points Claude in the wrong direction, and every session applies it faithfully. The same review should remove aspirational rules the team does not actually follow, and anything already obvious from the file tree. Every line in the file is loaded every session, so a line that no longer earns its place should go.
A team uploads the new travel policy to a project but leaves the previous year's version in the knowledge base as well. What is the greatest risk?
Correct answer: C — Both versions are available, so Claude may cite the superseded rules without anyone noticing the conflict.
- A. Nothing removes or archives an uploaded file on its own; that is the maintainer's job.
- B. Retrieval relates to the size of project knowledge and still allows documents to be quoted.
- C. Correct. Two live versions of the same policy make wrong answers look exactly as authoritative as right ones.
- D. There is no restriction preventing two documents on the same topic.
Sources2
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Editing CLAUDE.md in the middle of a session changes Claude's behaviour on the very next turn.Why is that wrong?
The file is read at session start and not re-read on each turn. A mid-session edit applies after /compact, after opening it via /memory, or in the next session.
Covered in Editing mid-session, and when the change takes effect
2.Leaving an old rule in the instruction file does no harm. At worst Claude ignores it.Why is that wrong?
The guide says the opposite. Stale content should be deleted on a regular skim, because outdated instructions are worse than having none.
Covered in Pruning: stale rules are worse than none
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/memoryOfficial docs
“You type the same correction or clarification into chat that you typed last session”
↩︎ Signals that an instruction is missing“Auto memory: notes Claude writes itself based on your corrections and preferences”
↩︎ Signals that an instruction is missing - 2.https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-promptsOfficial docs
“When Claude gets something wrong twice — that is the signal a rule is missing.”
↩︎ Signals that an instruction is missing“Most teams only need the project-root file. Commit it to git so the whole team benefits.”
↩︎ Put the change where it reaches the right people“the change is picked up the next time you run /compact or open it via /memory”
↩︎ Editing mid-session, and when the change takes effect“open /memory to edit the file directly, or just ask Claude to "remember" a rule”
↩︎ Editing mid-session, and when the change takes effect“The cache is content-addressed, so any change to CLAUDE.md invalidates it and the next request pays full price again.”
↩︎ Editing mid-session, and when the change takes effect“Treat it like a living onboarding doc, not a spec.”
↩︎ Pruning: stale rules are worse than none“Aspirational rules the team does not actually follow.”
↩︎ Pruning: stale rules are worse than none“it is not re-read from disk on each turn.”
↩︎ Exam trap 1“Quarterly skim — delete anything stale, since outdated instructions are worse than none.”
↩︎ Exam trap 2 - 3.https://code.claude.com/docs/en/settingsOfficial docs
“It reaches your teammate’s clone and the cloud session only if you commit the file to version control”
↩︎ Put the change where it reaches the right people