why agents.md keeps growing

so i’ve been watching my AGENTS.md get longer.

i use a few agent harnesses. i don’t keep a claude-only file. AGENTS.md is the one i actually edit. CLAUDE.md and the rest just symlink to it.

not in a dramatic way. just one more line. then another. “don’t do this.” “always do that.” after a few weeks you open the file and it feels heavy. and the weird part is you can’t delete anything. because you don’t remember why it’s there. and deleting it feels like it might break the agent.

that’s the whole problem. the file grows because deletion feels unsafe, not because every rule is still doing work.

leftover rules confuse the agent

someone measured this. kushal chakrabarti. the paper is why does claude.md keep growing? (alphaxiv). extra lines do not sit there quietly. they make the agent worse on the rules that still matter.

people try to fix it by wiping the file. that looks clean for a week. then it comes back worse.

the fix is a comment

we already do this in code. we write comments.

the rule tells the agent what to do. a # comment tells you why. the harness strips the comments before the model runs. the agent never sees the essay. you do. six months later you can decide if the line still earns its place.

dummy comments don’t work. “added to address a recurring issue” is just noise. write what failed and when it’s safe to delete.

don’t let the agent auto-delete from those comments. they can be wrong. a human still has to look.

write the why

if you can’t fill this in, don’t add the rule.

do the thing.
# YYYY-MM-DD: what failed.
# hypothesis: the guess.
# outcome: what happened.
# keep unless: when it's safe to delete.

here’s what that looks like when an agent runs npm in a bun repo.

don’t nuke the file. don’t add a rule you can’t comment.

and this isn’t only AGENTS.md. bookmarks. team wikis. house rules. that note that says “we always do it this way” with no date on it. same disease.

¹1: i already wrote about this instinct in capture the why. that post is the feeling. this paper is the measurement, plus a template you can actually paste.

paper: kushal chakrabarti, why does claude.md keep growing? catastrophic remembering in agentic coding, 11 aug 2026. arxiv:2608.11095 · alphaxiv