Running into this?

If your agent clings to the old

Situations I ran into and solved when my agent kept something I had removed, changed or outgrown. Find yours, hand the decision to your agent.

For a layer to stay, I have my agent write down what forces it from the outside, with file and line: an outside source that delivers the value in that shape, a measured speed difference, or an outside caller that needs it. Another function we wrote ourselves expecting it doesn't count as a reason. A layer whose reason can't be written is deleted together with its inverse, and the callers take the original value directly.
beforebackground mechanisms that say what they protect: 1 of 73 (Oct 20)
after57 of 133 · cached copies stayed only when they gave the same output faster than the path without them (5 of 5)
for every converter and wrapper the removed value passes through, have your agent write its outside reason with file:line; delete the ones without one from that path, and show the output didn't change on the same input
Text for your agent · 24 lines
Situation: you told your agent to remove or simplify something. Instead of removing it, it added another layer on top: a converter, right after it the inverse, a compatibility wrapper, or a function marked "old" and left in place. The code works, but the value changes shape several times before it reaches the place it's used, and every new request brings one more layer.

Why: to avoid breaking existing calls, the agent picks the safest move: it puts an adapter in front of whatever it touches. A rule written as "don't add compatibility layers" often doesn't stop it: anthropics/claude-code#2901 is the same complaint from someone who had written the rule out explicitly. The agent can't remove a layer without asking why it exists; and when asked, the only reason for most layers turns out to be another function in the same project, not something forced from outside. In my setup on Oct 20, 72 of 73 background mechanisms didn't say what they protected.

Do:
(Replace <value> with the name in the code of the thing you had removed. Run the commands at the root of the git repo.)
1. Find the value's path: every function it passes through from where it enters from outside to where it's used. If the value enters from more than one place (an argument, an API response, a file), each entry is its own path.
   git grep -nEi '<value>'
   In those lines, find the definition and the calls of every function the value passes through, by its name: git grep -nw '<function name>'. Write each path on one line: entry (file:line) → layer → layer → use (file:line). The function that reads the value from outside is the entry; a function that prints, stores or computes with it is the use; only the ones in between are layers.
2. Next to each path, write with file:line the shape read at its entry (the unit an API returns, the format of a file being read, a field the user types) and the shape its use gives to the outside (the unit printed on screen, a file written, a published interface someone else calls). If the two differ, one converter stays at that path's boundary and its outside reason is those two lines; if they're the same, a layer on that path can only have a measured speed difference as its outside reason.
3. Save the output before deleting: run the command that produces the project's output using this value (the tests or the program itself).
   <output command> > "$(git rev-parse --git-dir)/before.txt" 2>&1
   Test that the command runs these paths: at every use file:line you wrote in step 1, deliberately multiply the value by 1000 and run step 5's line → diff prints a difference (if it doesn't, pick a command that really prints the value), then undo: git checkout -- <use files>
4. Delete every layer whose outside reason can't be written from that path: callers take the original value directly. Don't write a comment, a "removed" note, or a line in your instructions file for the deleted layer: the history stays in git.
5. Run the same command again and compare the two outputs:
   G=$(git rev-parse --git-dir); <output command> > "$G/after.txt" 2>&1; diff "$G/before.txt" "$G/after.txt" && echo "same output"
6. If step 5 printed "same output", commit once; if it printed a difference, one of the deleted layers had an outside reason: undo with git checkout -- <files you changed>, write its reason in step 2 and run again from step 4.
   git add -A && git commit -m "<value>: removed <names of the deleted layers>, no outside reason"

Check:
- Step 5's line prints "same output".

Don't:
- Don't mark the layer "deprecated" and leave it in place: the agent will call it again.
When I remove something, every line that mentions it (comment · agent instructions · note) goes in the same commit; the commit message carries when and why. When the agent writes a comment carrying a date or a count of the old state, I deny it at write time.
beforeonce the removal note went stale, the agent followed the note in 10 of 10 runs and wrote a converter in 9
aftersame code, note deleted: 0/10
delete every note that mentions what you removed (CLAUDE.md · AGENTS.md · code comments); put why it was removed in the commit message
Text for your agent · 23 lines
Situation: you had your agent remove a feature. It deleted the code but left a note in CLAUDE.md, AGENTS.md or the code: "X was removed · use Y now". Later the code changed again; now the agent treats the new code by that old note: it follows a rule that no longer exists and adds a converter or compatibility layer to bridge the gap.

Why: the agent reads instruction files before the code and ranks them higher. A note is true the day it's written and turns into a lie when the code changes; the agent puts the lie ahead of the code. I measured it (Claude Sonnet, the same small project, the same request, 10 runs per arm):
- code uses Y, with or without a CLAUDE.md note saying "X support was removed, everything is Y": mentions X 0/10
- code later moved back to X: with the note still there, mentions Y 10/10, writes a line converting X to Y 9/10; without it, 0/10
While the note is fresh it's harmless; once the code changes again, the agent prefers it over the code. In a 320-run study by Georgia Tech and UC Boulder (Claude Code and Codex CLI), agents followed an old CLAUDE.md or AGENTS.md line that contradicted the code in 90.1% of choices.

Do:
1. Find the tracked notes, from the project root. Instruction files:
   git grep -nEi 'kald(ı|i)r(ı|i)l|kald(ı|i)rd|sil(in|d)|(ç|Ç|c)(ı|i)kar(ı|i)l|art(ı|i)k|eskiden|removed|deleted|dropped|deprecated|no longer|used to|replaced by' -- ':(glob)**/CLAUDE*.md' ':(glob)**/AGENTS.md' ':(glob).claude/**'
   Code comments:
   git grep -nEi '((^|[[:space:]])(//|#|--|;|/\*|<!--)|^[[:space:]]*\*).*(kald(ı|i)r(ı|i)l|kald(ı|i)rd|sil(in|d)|(ç|Ç|c)(ı|i)kar(ı|i)l|art(ı|i)k|eskiden|removed|deleted|dropped|deprecated|no longer|used to|replaced by)'
2. Search the code for what each line mentions; lines step 1 found don't count. If the code stands by the line's rule (the note says "X was removed, everything is Y" and there is no X in the code), write the rule in the present tense: "Everything is Y." If it doesn't, or the line only tells history, delete it.
3. Add this line to the tracked CLAUDE.md (or AGENTS.md) so the agent stops leaving notes when it removes things:
   When something is taken out, every line that mentions it (comment · this file · test · docs) goes in the same commit; the reason lives in the commit message.
4. Commit only the files you changed in steps 2 and 3, together, with the reason in the message: git commit -m "delete removal notes: a stale note wins over the code" -- <those files>

Check:
- Rerun both step 1 commands → no line is left that tells what was removed or how things used to be.

Don't:
- Don't add "this no longer applies" next to the note instead of deleting it: the second note carries the first one's staleness.
- Don't delete all comments at once: a comment carrying a rule or reason the code can't say stays; only the ones telling history go.
When I change a decision I don't add the new one somewhere in the file: I delete the old line, or narrow it to the one place it still holds ("only the old importer reads the old one"). The old version stays in git history.
beforeold line kept in another section: Opus wrote the code to the old decision in 6–7 of 12 runs
afterold line narrowed to its condition or deleted: 0–2/12
delete every line of the old decision in your rules file, or narrow it to the place it still holds; don't add the new one next to it
Text for your agent · 14 lines
Situation: you changed a decision (a unit, a library, a format) and wrote the new one into your rules file (CLAUDE.md, AGENTS.md), but the agent still writes code to the old one or mixes the two. Comments like "CLAUDE.md conflicts" or "the rules contradict" show up in its code.

Why: the agent treats both lines in the file as rules; it can't tell which one is newer and picks one. I measured it with six decision changes, in a folder without git and with tools off: with the old line in one section and the new line in another, Opus wrote the code to the old decision in 6–7 of 12 runs across three measurements, Sonnet in 7 of 12, Haiku in 8 of 18. With the old line narrowed to the place it still holds, or deleted: Opus and Sonnet at most 2 of 12, Haiku 0/18.

Do:
1. Search the project root for the old decision's word and its abbreviation (replace OLD with them, separated by |: word|abbreviation):
   grep -rniIE --exclude-dir=.git --exclude-dir=node_modules 'OLD' .
2. In your rules file (CLAUDE.md, AGENTS.md), delete every line that states the old decision; if the search turned up a code line (not a comment) that still uses the old decision, don't delete that rule line, narrow it to the code's file, for example: "<old> only in <file>; <new> everywhere else".

Verify:
- Rerun step 1's search: in the CLAUDE.md and AGENTS.md lines, the old decision either doesn't appear or appears only in the line you narrowed.

Don't:
- Add the new decision in another section and leave the old line in place.
I don't keep a line on gut feeling: I write a short scene that asks for the move the line is supposed to change, run the same scene a few times with a context-free agent against the file with and without the line, and count the right moves. If the agent makes the same move without the line, the line goes; if the move drops without it, the line stays.
beforerule file loaded on every task: 181,567 bytes
after159,361 bytes · agent's right moves 32/32 → 32/32
before deleting a line from CLAUDE.md, run the same scene three times against a copy with the line and a copy without it; if the copy without it gets the same move, delete it
Text for your agent · 28 lines
Situation: your CLAUDE.md has grown to hundreds of lines. You don't know which lines still change what the agent does and which ones just repeat something the model already does; when a new model comes out, the same question comes back.

Why: CLAUDE.md is read in full at the start of every session; every line takes up context on every request and competes with the other lines for attention. A line that says something the model already does changes no move. Whether a line is needed also depends on the model reading it: you find out by counting with that model, not by guessing. In my setup (Nov 16), 129 quote lines came out of the rule file loaded on every task: 181,567 → 159,361 bytes, and the context-free reader's (Opus) right moves on four distinguishing scenes went 32/32 → 32/32. The same day, 3 of the 27 lines I meant to remove stayed: without them the right move dropped from 3/3 to 1/3.

Do (one line at a time; every claude -p is a model call, 6 calls per line):
1. Pick a single line and find its number (grep -n 'use only pnpm' CLAUDE.md). Don't cut the whole file at once.
2. Write a scene that asks for the move the line should change, force the answer onto one line, and write the start of the right move as a pattern. Example, for the line "use only pnpm to install packages":
   S='Add the lodash dependency to this project. Do not run any command or touch any file. Answer in one line: the command you would run, no explanation.'
   D='^`?pnpm add'
3. From the project root, set up two copies in an empty temp folder: one with the line, one without. N is the single number of the line to remove:
   N=7
   B=$(mktemp -d); mkdir "$B/with" "$B/without"
   cp CLAUDE.md "$B/with/CLAUDE.md"
   sed "${N}d" CLAUDE.md > "$B/without/CLAUDE.md"
   If CLAUDE.md imports other files with @, copy them to the same path in both folders. The diff below must print exactly two lines: "7d6" (for N=7) and under it "< " followed by the line you meant to remove; if it's empty or longer, N is wrong, don't go to step 4:
   diff "$B/with/CLAUDE.md" "$B/without/CLAUDE.md"
4. Run the same scene three times in each copy and count (S, D and B from steps 2 and 3 must be defined in the same shell):
   for d in with without; do for i in 1 2 3; do (cd "$B/$d" && claude -p "$S") > "$B/$d-$i.txt" 2>&1; done; done
   grep -H . "$B"/with-*.txt "$B"/without-*.txt; echo "with $(grep -lE "$D" "$B"/with-*.txt | wc -l | tr -d ' ') / 3 · without $(grep -lE "$D" "$B"/without-*.txt | wc -l | tr -d ' ') / 3"
5. First read the printed answers: if D misses a right answer or counts a wrong one, fix D and rerun only the last line of step 4. Then take the first rule from the top that matches:
   without 3/3 → delete it · with 0/3 or 1/3 → the line doesn't work as text: move it into a hook that denies the wrong command · any other count → keep it.
6. Once you've deleted a line, measure the next one against the file without it: whether a line is needed depends on the rest of the file (in my setup, with "Run `pnpm test` for tests." still in the file, the agent wrote pnpm add 3/3 after the pnpm line was deleted).

Check: first see the method tell a known line apart: under a new B=$(mktemp -d), write only "In this project, use only pnpm to install packages." into with/CLAUDE.md, leave without/CLAUDE.md empty, and run step 4 with the S and D from step 2 → with 3/3 · without 0/3 (in my setup on Claude Code 2.1.325); don't move on to real lines until you get it.

Don't:
- Don't cut the whole file at once and measure: you can't tell which line the dropped move came from (in my setup, removing 27 lines at once dropped the move in three scenes).
- Don't delete a line someone explicitly asked for on the count alone: ask that person first.