What you will be able to do
- Name the four layers of an established Claude configuration (instructions, knowledge, Skills, memory) and describe how each one goes stale
- Check whether uploaded knowledge files are still current and replace superseded copies instead of leaving old and new versions side by side
- Find which layer caused a drop in output quality with a reproducible test, changing one layer at a time
- Repair instructions that have drifted or contradict each other by rewriting them, not by adding more rules
- Roll back a regressed prompt or Skill version and correct or archive bad memories without losing their history
- Tell the team about a configuration change and set the next review
Key concept
Layer attribution — A configuration that was once good can get worse because one of its layers drifted away from reality: the standing instructions, the knowledge files, a Skill or prompt version, or accumulated memory. To fix it, find which layer is responsible by changing one layer at a time against a fixed test, and leave the layers that still work alone.
1.The four layers that can go stale
A Claude setup that has been in use for months is several separately maintained parts, and each part ages on its own schedule. In a Project you upload documents, text, code or other files to a knowledge base, and you write project instructions that shape every reply, such as a formal tone or a specific role. Claude Code has the same split. CLAUDE.md files hold rules you write yourself. Auto memory holds notes Claude writes itself based on your corrections and preferences. Skills add reusable prompts that run when you type their name or that Claude invokes automatically. Setting these layers up is covered in Project configuration. This lesson is about what happens to them afterwards.
| Layer | Who writes it | Typical way it goes stale |
|---|---|---|
| Instructions (Project instructions, CLAUDE.md) | You or your team | Written for an old policy or process and never revised; rules added over time that contradict earlier ones |
| Knowledge (project knowledge base, reference files) | You or your team | Documents superseded by newer ones, or old and new versions of a document both left in place |
| Skills and prompt versions | You or your team | A new version ships with a broader rule that quietly breaks a case that used to work |
| Memory (auto memory, memory stores) | Claude, from corrections and preferences | Notes about old preferences or past mistakes that are no longer true |
These layers can contradict each other. Suppose a team refreshes its knowledge files to a new pricing policy, but the instructions still state the old one. Every chat now gets two policies: the outdated one from the instructions, which load every time, and the current one from the files. When two instructions contradict each other, Claude may pick one arbitrarily, so drafts end up mixing the two. The layer to blame is the one still holding the outdated text. The model is not inventing the old policy, and memory is not the source either, because the outdated wording sits in the instructions and nobody edited them when the files changed.
Knowledge freshness is its own problem, because knowledge files do not update themselves. A file uploaded to a Project is a copy: a change made to the original on your computer does not reach the Project until you upload the file again and choose Replace when asked about the existing name. A team that edits the master pricing sheet and forgets the re-upload has a Project answering confidently from last quarter's numbers, and nothing in the output flags it. Uploading the new version under a different name makes it worse, since the old and new copies then both sit in the knowledge base. When quality slips after a real-world change, compare the upload date of each knowledge file with the date its source last changed, replace the stale copies in place, and delete files nobody needs any more. Outdated material is worse than none, because Claude has no way to tell which version is current.
Checkpoint 1 of 9· Check yourself
A team's Project has project instructions that state the old 30-day refund policy. Last week the team replaced the knowledge files with the new 14-day policy and changed nothing else. Claude's draft replies now mix the two policies. Which layer is responsible?
Updating the knowledge files does not override instructions that still state the old rule. Both load into every chat, and when two instructions contradict each other Claude may pick either one, so the stale layer is the one nobody edited: the instructions.
“if two instructions contradict each other, Claude may pick one arbitrarily”Source: code.claude.com
Checkpoint 2 of 9· Exam question
A finance team shares a Claude Project that drafts client payment-terms emails. Six months ago the Project instructions were written to say "offer net-30 terms and a 2% early-payment discount." The company has since moved to net-45 with no discount, and the Project knowledge files were updated to match. Drafts now mix the two policies. The team lead must attribute the problem to the right layer. Which layer is most likely responsible?
Correct answer: C — The Project instructions, which were written for the net-30 policy and were not revised when the knowledge files were refreshed
- A. Incorrect. Nothing in the scenario points to remembered conversations as the source of the old terms. The net-30 and 2% discount wording sits in the Project instructions, which are applied to each draft the team generates, so memory is not needed to explain the mix.
- B. Incorrect. The knowledge files were updated to match the net-45, no-discount policy, so excerpts retrieved from them and blended together would still describe the current terms. They cannot be the source of a 2% discount or net-30 wording.
- C. Correct. The instructions are the one layer that was never updated, so they still tell Claude to offer net-30 and a 2% early-payment discount while the knowledge files describe net-45 with no discount. Claude combines the two sources, and editing the instructions to match current policy removes the conflict.
- D. Incorrect. The drafts mix the company's own two specific policies, including a 2% early-payment discount, which matches the text in the Project instructions rather than general training-data conventions. The model follows supplied context, so two configuration layers disagreeing explains the symptom.
2.A diagnostic process that isolates the responsible layer
Diagnosis needs evidence first and edits second. Typical signs of drift are Claude making the same mistake a second time, typing the same correction you typed last session, or a review catching something Claude should already have known. Turn those signs into a test before you change anything:
- Collect a few recent weak outputs and a few older strong ones for the same type of request, and write down exactly how they differ.
- Rerun one identical test request in a fresh chat and confirm that the weak behaviour reproduces. A fresh session carries no earlier conversation, so if the problem still appears, it comes from the standing configuration.
- Change one suspected layer at a time (instructions, knowledge, Skill version, memory) and rerun the same request after each change.
- Keep the change that restores quality, and revert any change that made no difference.
- Tell the team what changed and why, and schedule the next review.
The Managed Agents prompt-versioning example shows step 3 in practice. A routing agent was scored against twenty labelled tickets. A new prompt version was then scored against the same set, with each test session pinned to one exact version so the only thing that differed was the prompt. Breaking the score down by category showed where the damage was.
| Team | v1 score | v2 score |
|---|---|---|
| api-platform | 5/5 | 5/5 |
| auth | 5/5 | 5/5 |
| billing | 4/5 | 2/5 (regressed) |
| dashboard | 5/5 | 5/5 |
The new rule sent anything about API usage to the platform team. On a usage-billed product, billing tickets also talk about API usage, so the broader rule took them over. An overall score would have hidden this, but the per-category comparison showed it immediately. In Claude Code, check what actually loaded before you blame a layer: /context, /memory and /skills show what is in effect, and a Skill can be installed and still never run if its description doesn’t match how you phrase the request.
Checkpoint 3 of 9· Check yourself
You suspect that a new prompt version for a routing agent has made its results worse. How should you set up the test so the result shows whether the prompt caused the drop?
If you pin each session to one exact version, the prompt is the only thing that differs between the two runs. Breaking the score down by category then shows where the damage is, such as billing falling from 4/5 to 2/5, which an overall score would hide. Changing several layers at once would hide which change mattered.
“pins to an exact version, which is what we want for a controlled comparison.”Source: platform.claude.com
Checkpoint 4 of 9· Exam question
A consultant's Claude Project has produced slightly worse proposals for several weeks, and the consultant wants to restore its performance without breaking the parts that still work. Which sequence should the consultant follow before the team relies on the Project again?
Correct answer: A — Compare weak and strong outputs for similar requests → Rerun one fixed request in a fresh chat → Change one layer, rerunning the same request → Keep the change that helped, revert the rest → Tell the team and schedule a review
- A. Comparing outputs defines the concrete symptom, a fixed request in a fresh chat makes it reproducible, and only then can single-layer changes be tested against it, kept or reverted, and communicated to the team.
- B. Changing a layer before reproducing the problem in a fresh chat means there is no fixed, repeatable test to rerun, so any difference could come from a one-off fluke or a long-chat effect rather than from the change.
- C. Changing a layer before comparing weak and strong outputs means the edit is a guess with no concrete symptom, such as a missing section or wrong figure, to aim at or to judge success against.
- D. Comparing weak and strong outputs only after layers have been changed mixes the original symptom with the effects of the edits, so the consultant can no longer tell which differences were there before and which the changes caused.
3.Repairing instructions that have drifted
Instructions usually degrade by accumulation. Six clear lines become thirty as colleagues add rules over a year. One person writes "keep replies under 100 words", and a later person writes "always include full background and three examples". Each rule made sense when it was added. Together they contradict each other, and since Claude may pick one arbitrarily when two conflict, output length and format vary from chat to chat. Length causes a second problem: longer instruction files take up more context and reduce adherence.
Both contradictory rules are still in the instructions, and Claude cannot tell which was added more recently from text that carries no dates. The fix is to remove the conflict itself. Opening a new chat does not help either, because the instructions load into every chat, and moving the rules into memory only shifts the contradiction to another layer.
First, rewrite the instructions as one deduplicated list. For each contradictory pair, choose one wording and delete the other. Make each rule specific enough to check: "Use 2-space indentation", not "Format code properly". Group related rules under headers, because organised sections are easier for Claude to follow than dense paragraphs. Writing good standing instructions is covered in persistent-instruction design. The point here is that once instructions have drifted, you repair them by subtracting rules. Adding more does not help.
Claude Code has tools for this audit. The prompt-audit subcommand flags instructions written for older models in prompts, Skills and tool descriptions and proposes fixes as a diff. /doctor reports checked-in CLAUDE.md content that Claude could work out from the codebase anyway, which is a common kind of bloat.
Checkpoint 5 of 9· Check yourself
Over a year, colleagues have grown a project's instructions from six lines to thirty. One rule says "keep replies under 100 words" and a later one says "always include full background and three examples". Reply length now varies from chat to chat. Which repair fixes the inconsistency?
When two instructions contradict each other, Claude may pick either one, so the fix is to remove the conflict: keep one wording and delete the other. A tie-break rule leaves both rules in place and makes the file longer. Moving the rules into memory only moves the contradiction to another layer, and a fresh chat still loads the same instructions.
“Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions.”Source: code.claude.com
Checkpoint 6 of 9· Exam question
A marketing agency has a Project whose instructions began as six short lines. Over a year, different colleagues appended new rules: "keep every reply under 100 words," later "always include full background and three examples," and "never use bullet points" followed by "present options as bullets." Claude's replies are now inconsistent in length and format. What should the Project owner do first to restore consistent output?
Correct answer: B — Rewrite the instructions as one deduplicated list, and settle each pair of contradicting rules by keeping one wording and dropping the other
- A. Incorrect. A precedence line leaves every contradictory rule in the text and asks Claude to adjudicate among them. The newest rule is also not necessarily the one the owner wants, such as the long-form request that replaced the short-reply limit. The conflicts have to be resolved in the instructions themselves.
- B. Correct. The inconsistency comes from a year of accumulated, overlapping and opposing rules. Merging them into one deduplicated list and picking a single wording for each conflict gives Claude one coherent standard to follow.
- C. Incorrect. Memory is not a mechanism for enforcing Project rules, and relocating the length and format rules does not resolve the contradictions in them. The conflicting standards would still apply, now split across two places that are harder to audit.
- D. Incorrect. The conflicts live in the Project instructions, which load into every new chat in that Project. A fresh conversation therefore starts from the same contradictory text, and rerunning requests just reproduces the inconsistency.
4.Rolling back Skill versions and correcting memory
Versioned layers are the easiest to repair, because the earlier good state still exists. In Managed Agents, every agents.update creates a new immutable version, and sessions choose which version to use by ID. When the billing regression appeared, version 1 was still stored on the server, so rolling back meant passing version: 1 again. Nothing had to be redeployed. If callers pass the bare agent ID, they get whatever version is newest, so an untested change goes live on their next session. That is why production callers should pin an explicit version.
Memory needs a different kind of care, because Claude writes it, and it can hold user preferences, project conventions, prior mistakes and domain context. A note that was once true becomes a standing instruction nobody asked for. Auto memory loads into every session, up to the first 200 lines or 25KB, so a stale note affects every session until someone removes it. Managed Agents memory stores can be edited directly through the API, which is how you build review workflows, correct bad memories, or seed a store before any session runs. To prune a stale memory without destroying it, rename it to an archive path:
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md",
)Every mutation to a memory creates an immutable version, and those versions are not deleted when the memory itself is deleted. If a correction makes things worse, you can undo it. To roll back, retrieve the version you want and write its content back with an update. Versions are kept for 30 days after they are written, though the recent versions of a live memory are always kept. Export versions you need to keep for longer.
Checkpoint 7 of 9· Fill the gap
This call archives a stale memory so it stops acting as a standing instruction but is not destroyed. Which method completes it?
client.beta.memory_stores.memories. ? (
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md",
)Archiving is a rename: update changes the existing memory's path and keeps its content. Delete removes the memory from the store, and create makes a new memory instead of moving the existing one.
Source: platform.claude.comCheckpoint 8 of 9· Check yourself
Ten days ago, an engineer deleted a Managed Agents memory that they thought was stale. Since then, the agent's reports have lost a formatting convention that the memory held. What is the right way to recover?
Memory versions belong to the store and remain after the memory is deleted, as long as they are still within retention. Ten days is inside the 30-day window, so the earlier content can be retrieved and written back. Agent versions cover the prompt, not memory contents.
“Versions belong to the store (not the individual memory) and are not deleted when the memory itself is deleted”Source: platform.claude.com
5.Communicating changes and scheduling the next review
A fix nobody hears about tends to come undone. A colleague who doesn't know the 100-word rule was deliberately removed may add it back the following month. When you change a shared configuration, tell the team what changed, why, and which test confirmed it. In Claude Code, project CLAUDE.md files reach team members through source control, so the commit history records the change. Managed Agents offers no built-in approval step on agents.update, and any key in the workspace can call it. The review gate therefore sits on the pinned version number: anyone can create a new version, but changing the production pin goes through normal review.
Drift keeps coming back, so schedule the review rather than waiting for complaints. Periodically review your instruction files, nested files and rules to remove outdated or conflicting instructions. Put the next review date where the team will see it. For higher-stakes setups, send a fraction of traffic to a new version and compare it with the current one before promoting it fully.
Checkpoint 9 of 9· Check yourself
Several people in your Managed Agents workspace hold API keys. The team wants prompt changes reviewed before production traffic sees them, the same way code changes are reviewed. Where should that review step sit?
agents.update has no built-in approval step, and any key in the workspace can call it. The pinned version is what controls production traffic, so the review happens when someone changes that pin. A caller using the bare agent ID gets the newest version on its next session, whether or not anyone reviewed it.
“Treat the pinned version number as the gate for changing prompts. Creating versions is exploratory; updating the production pin is what goes through review.”Source: platform.claude.com
Sources
(7)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“you can define project instructions for each project to further tailor Claude's responses”
↩︎ The four layers that can go stale - 2.https://code.claude.com/docs/en/memoryOfficial docs
“Auto memory: notes Claude writes itself based on your corrections and preferences”
↩︎ The four layers that can go stale“if two instructions contradict each other, Claude may pick one arbitrarily”
↩︎ The four layers that can go stale“Claude makes the same mistake a second time”
↩︎ A diagnostic process that isolates the responsible layer“Longer files consume more context and reduce adherence.”
↩︎ Repairing instructions that have drifted“Organized sections are easier for Claude to follow than dense paragraphs.”
↩︎ Repairing instructions that have drifted“Every session (first 200 lines or 25KB)”
↩︎ Rolling back Skill versions and correcting memory“Team members via source control”
↩︎ Communicating changes and scheduling the next review“Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions.”
↩︎ Communicating changes and scheduling the next review“if two instructions contradict each other, Claude may pick one arbitrarily”
↩︎ Exam trap 1“Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions.”
↩︎ Exam trap 3“Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions.”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/claude-projectsOfficial docs
“uploads are copies, so a change you make on your computer afterward doesn’t reach the project until you upload the file again”
↩︎ The four layers that can go stale - 4.
“Each Managed Agents session starts with a fresh context by default.”
↩︎ A diagnostic process that isolates the responsible layer“Memory stores let the agent carry information across sessions: user preferences, project conventions, prior mistakes, and domain context.”
↩︎ Rolling back Skill versions and correcting memory“Use this for building review workflows, correcting bad memories, or seeding stores before any session runs.”
↩︎ Rolling back Skill versions and correcting memory“to roll back, retrieve the version you want and write its content back with client.beta.memory_stores.memories.update()”
↩︎ Rolling back Skill versions and correcting memory“Versions are retained for 30 days after they are written”
↩︎ Rolling back Skill versions and correcting memory“are not deleted when the memory itself is deleted”
↩︎ Exam trap 4“Versions belong to the store (not the individual memory) and are not deleted when the memory itself is deleted”
↩︎ Checkpoint - 5.https://platform.claude.com/cookbook/managed-agents-cma-prompt-versioning-and-rollbackSecondary source
“pins to an exact version, which is what we want for a controlled comparison”
↩︎ A diagnostic process that isolates the responsible layer“Every agents.update produces a new immutable version, and sessions choose which version to use by ID.”
↩︎ Rolling back Skill versions and correcting memory“Billing regressed. Version 1 is still sitting on the server.”
↩︎ Rolling back Skill versions and correcting memory“Any key in the workspace can call it.”
↩︎ Communicating changes and scheduling the next review“Treat the pinned version number as the gate for changing prompts.”
↩︎ Communicating changes and scheduling the next review“route a fraction of traffic to a new version and compare”
↩︎ Communicating changes and scheduling the next review“pins to an exact version, which is what we want for a controlled comparison”
↩︎ Key concept“pins to an exact version, which is what we want for a controlled comparison”
↩︎ Exam trap 2“pins to an exact version, which is what we want for a controlled comparison.”
↩︎ Checkpoint“Treat the pinned version number as the gate for changing prompts. Creating versions is exploratory; updating the production pin is what goes through review.”
↩︎ Checkpoint - 6.https://code.claude.com/docs/en/debug-your-configOfficial docs
“Use /context, /doctor, /hooks, and /mcp to see what actually loaded.”
↩︎ A diagnostic process that isolates the responsible layer“or its description doesn’t match how you phrase the request”
↩︎ A diagnostic process that isolates the responsible layer“checked-in CLAUDE.md content Claude can derive from the codebase, with proposed fixes”
↩︎ Repairing instructions that have drifted - 7.https://code.claude.com/docs/en/skillsOfficial docs
“Flag instructions written for older models in your prompts, skills, and tool descriptions and propose fixes as a diff”
↩︎ Repairing instructions that have drifted