The reason why Claude Code and OpenAI’s Codex have become so powerful is that you can tailor them to execute your work. You can give them skills, rules, preferences, and context, and they’ll carry that knowledge into the next task.
The more you teach them, the more they have to remember.
But eventually, the coding agents may get lost in the web of instructions and start working against your productivity.
Kushal Chakrabarti, an advisor at South Park Commons and an engineering leader with over two decades of experience, went down this rabbit hole. He wrote a paper examining why files such as CLAUDE.md keep growing and how this can lead to what he calls “catastrophic remembering.”
In an analysis of more than 1,800 repositories, he found that these files could grow substantially over time, with instruction counts increasing by 226% on average.
And this is precisely the problem, and the central thesis of Chakrabarti’s paper: when instructions pile up, agents have more context to work with and more rules to follow, even when they’ve lost their significance or forgotten.
The Curse of Redundant Instructions
Chakrabarti tells AIM that his wild-goose chase began “entirely by accident.”
“I was using a few coding agents, and I’d set out for it a couple of things for it to do. But it just wasn't following the instructions,” he says.
Chakrabarti doesn’t fault the coding agents. While the agent may be the one struggling to follow the instructions, it is humans who accumulate them without keeping track.
As he dug through his own CLAUDE.md, Chakrabarti found that it contained roughly 50 instructions. Many of them had become redundant, and Chakrabarti couldn’t even remember why he had added them in the first place.
He then realised that perhaps the problem wasn’t that Claude could not manage the instructions, but that the context behind those instructions had been lost. “Catastrophic remembering,” as he calls it.
In a study of 1,867 public GitHub repositories, Chakrabarti’s team examined how developers maintain instruction files such as CLAUDE.md, AGENTS.md, and copilot-instructions.md, which tell AI coding agents how to work within a codebase, including coding conventions, things to avoid and formatting rules.
Rather than simply measuring how much these files grew, the researchers tracked each directive over time, including which were added, which survived, and which were eventually deleted.
They found that maintainers added new directives far more often than they removed old ones. More importantly, the older a directive became, the less likely it was to be deleted.
The researchers link this to a problem: once the reason for a rule is forgotten, removing it feels risky. Nobody knows whether that rule is quietly preventing some past failure from recurring, so it stays.
To test this, they created a simulated software project where an AI maintainer, an LLM, had to maintain an instruction file as new project requirements were introduced over a series of steps. At each step, the agent received feedback on whether it had failed to satisfy a requirement, but was not told which instruction had caused the problem or exactly how to fix it.
The AI maintainer therefore had to infer what new instruction to add, while deciding whether any existing instructions could safely be removed.
The researchers then compared that ideal version with the file the AI maintainer produced. The latter grew increasingly bloated as new requirements were added, adding 571.9% more content than the minimum necessary at the highest difficulty level.
Further, the researchers wanted to see whether an AI coding agent actually got worse at following the instructions that matter when its context is padded with unnecessary information. They took real prompts containing a handful of genuine requirements and mixed in irrelevant directives pulled from other tasks. After adding 16 unrelated directives, the agent’s success rate on the requirements that actually mattered fell from 65.6% to 41.5%.
Adding Context and Comments to Instructions
Finally, the team tested a fix. Instead of silently carrying forward old directives, the maintainer attached a short comment to each one explaining why it was added, what problem it addressed, and what happened when it was tried.
Across 552 simulated maintenance histories, files maintained this way stayed much closer to the minimum necessary size while achieving the same level of requirement satisfaction.
Overall, preserving the rationale cut unnecessary instruction bloat by about 99% and improved instruction-following by roughly 23–25% on more realistic prompts.
Chakrabarti says the finding also has implications for companies building coding-agent harnesses. “People who are working on harnesses can provide support for comments in prompts. I think that is going to be a game changer for their users.”
For developers, however, the solution is rooted in a longstanding software-engineering practice: documenting not just what a piece of code does, but why a particular decision was made.
How Developers Manage the Instruction Bloat
AIM spoke to multiple developers about how they deal with the problem.
Jesai Tarun, Co-founder and CEO of Sentiet OS, a YC-backed on-device private intelligence platform, says keeping codebase documentation and an automatically loaded codebase overview up to date was a recurring problem.
Sentiet addressed this in two ways. First, it added an instruction to its system prompt asking Claude to update the documentation after major code changes. Tarun says this alone could make the files too large, so the company also runs overnight documentation optimisation and rewriting tasks.
“Second, we run overnight codebase documenation optimization/re-writing runs, where we have subagents explore the entire codebase to verify docs are up to date,” he says. “We also have a smart model rewrite any documentation or md that's gotten too huge.”
Similarly, Dheemanth Reddy, Co-founder and CEO of AI firm Maya Research, says he has moved from Claude to Codex and uses a central system to keep context consistent across his agents.
Reddy maintains a private “central operator file” containing his preferences, operating principles, communication style, and approval boundaries. He then creates project-specific skills for recurring tasks such as model training, evaluations, and communications, keeping detailed instructions separate from the central file.
“These contain the detailed rules and workflows relevant to each type of task without bloating the central file,” he says.
He also asks Codex to synchronise context across his active tasks and chats by identifying repeated questions, corrections, and areas where he needs to spend attention.
“Instead of manually updating the instructions every day, I let the system identify patterns in my feedback and suggest improvements to its rules, skills, or workflows,” adds Reddy.
“It gives me a numbered list of proposed improvements,” he adds, with each suggestion explaining what would change and requiring his approval before it becomes a permanent rule.
On the other hand, Manthan Gupta, an AI research engineer, takes a more automated approach. He uses Cursor’s continual learning hook, which is triggered after every 10 interactions in the IDE. The hook keeps the AGENTS.md file updated while also learning from the guidance he provides during chats.
However, developers can be tempted to delegate too much of the coding process to AI agents, potentially at the expense of some software development fundamentals.
The Right Direction
Chakrabarti, however, argues that agentic coding tools should be viewed as amplifiers rather than replacements for those fundamentals.
“Whatever direction you were pointed in, they’re gonna make you go faster that way,” he says. “If you’re pointed in the wrong direction, it’s gonna speed you up 10x in the wrong direction.”
Developers therefore need to retain a strong understanding of software engineering fundamentals—such as adding comments—even as coding moves to higher levels of abstraction.
“More than ever, it’s important to remember what the fundamentals are—learn the fundamentals and know how to follow the fundamentals,” Chakrabarti summarises.
Your reaction
Discussion
What's your take on this story?
No comments yet — be the first to share your view.