Stale instruction files create documentation debt in coding agents
Original title: When Instruction Files Go Stale: Documentation Debt and Hidden Cost in Coding Agents
Stale docs in coding agents add extra tool calls but task success hides the cost; agents recover without fixing files
Repository instruction files in LLM coding agents like Claude Code can become stale, creating documentation debt that raises costs in every session. The paper studies three real-world examples and finds agents follow stale guidance when relevant even with better info available elsewhere. On the test command, Claude Sonnet 5.5 added two extra tool calls per run. Agents recovered from failures but never repaired the files. Correcting or removing stale instructions eliminated the problems.
- Agents follow stale guidance despite correct alternatives
- Claude Sonnet 5.5 needed two extra tool calls per run
- No agents repaired underlying instruction files
- Correcting instructions eliminated obsolete operations
- AI models
- Claude Sonnet 5.5
From the original article
1 min read at arxiv.orgLLM-based coding agents such as Claude Code are guided by repository instruction files (also called context files or agent configuration files) like AGENTS. md and CLAUDE. md, which are read in every agent session.
By Tural Mehtiyev · arxiv.org
A short excerpt; the article and its images belong to the publisher. Summary, key facts and assessment above are AI-written from the article and can be wrong.