TL;DR
CLAUDE.md, AGENTS.md, and other instruction files for AI agents keep growing — their size increases by an average of 226% over the file's lifecycle and almost never shrinks on its own. Researchers found a fix: attach a comment to every instruction explaining why it was added, what problem it solved, and whether it actually worked. This doesn't change what the executor (the AI agent) sees, but it helps the next person figure out whether that instruction can safely be deleted.
The problem is human memory, not laziness. When you add an instruction to a prompt ("always answer in three sentences"), the reason behind it lives in your head only until the next meeting or task switch. A couple of months later, nobody remembers why that line is there — and deleting it feels risky: what if it's the one thing preventing a bug from resurfacing next week? It's easier to bolt on a new line than to untangle an old one. Hence the paradox: even if the task itself never changes, the file keeps growing purely because people forget the reasons, not because new requirements keep appearing.
The method is simple: next to each instruction, write a hidden comment — what wasn't working, what hypothesis was tested, and how it played out in practice. The comment is never sent to the executor (the model doing the task) — only the next human (or agent) editing the file sees it. In experiments, this eliminated 99.3% of unnecessary instructions and boosted compliance accuracy by up to 23%.
Want this for your own case? Apply this study to your task: AI adapts its method to what you are working on and writes the prompt.
Method Blueprint
STEP 1: An instruction gets added to the file → goes into the general list (no change to current practice)
STEP 2 (NEW): A hidden comment is written next to the instruction → format: [what wasn't working] + [hypothesis/fix] + [worked/didn't work]
STEP 3: The executor (agent) only sees the instructions, comments are "stripped out" before reaching it → task execution proceeds as usual
STEP 4: When it's time to clean up the file → a human/agent reads the comments → figures out which instructions are outdated or redundant → deletes them with confidence
Everything happens in a single file — comments are simply appended next to instructions with every edit; no separate requests needed.
Applied Example
Task: You maintain a CLAUDE.md for a project — an instruction file for Claude Code, which edits code in your repo. Over six months the file has grown to 60 lines: "don't use library X," "always write tests," "reply in comments using American English" — and you no longer remember why half of these lines are even there.
Prompt for adding a new instruction (append to CLAUDE.md):
Always use async/await instead of .then() in JS code.
# 2024-11-03: agent generated code with a .then() chain,
# reviewer asked to rewrite it as async/await —
# adding this rule so it doesn't happen again;
# the bug hasn't recurred for 3 consecutive iterations since
Prompt for cleaning up the file (monthly or quarterly):
Here's a CLAUDE.md file with a comment attached to each instruction.
Read the comments and tell me:
1. Which instructions address a problem that's no longer relevant (e.g., an old library version)?
2. Which instructions, by their own comments, never actually "worked" — i.e., were added but the problem never recurred to confirm they were needed?
3. Which ones can be merged, because their comments describe the same underlying reason?
[paste CLAUDE.md with comments]
Result: The model will analyze the comments and return a list of candidate instructions for removal, with reasoning — instead of you guessing "what if this line is guarding against something important." The file gets shorter, and the agent follows the remaining rules more precisely (less "noise" from contradictory or redundant directives).
Why This Works
Models follow instructions poorly when there are too many of them — this is a well-documented effect: the longer the rule list, the more often the model gets confused or ignores parts of it. So a short, up-to-date instruction file outperforms a bloated one.
But humans (and the agents editing files on their behalf) don't delete instructions without a reason — removing a line "just in case" is risky: if it was guarding against a bug, the bug comes back, and the link between the deletion and the breakage might not be obvious right away. It's cheaper to add a new line than to sort out an old one — additions are cheap, deletions are expensive, because they require reconstructing a lost reason.
The comment solves this cheaply: jot down the reason while it's still fresh in your head (takes seconds), instead of trying to reconstruct it months later (which requires re-checking every related scenario). Models are quite good at summarizing and analyzing text — so if the reason is captured next to the instruction, any LLM can later read the edit history and point out what's safe to remove.
Control levers: - Comment format (what wasn't working / hypothesis / outcome) → simplify it to fit your use case, but keep the "problem → fix → outcome" chain intact, otherwise the comment just becomes noise - Cleanup frequency → cleaning more often means less accumulated debt but more routine work; pick a cadence (monthly, quarterly) - Who writes the comment → if you're adding the rule yourself, write it right away; if it's an agent, ask it to append the comment automatically with every edit to the instruction file
Prompt Template
For adding a new instruction with a comment:
{new instruction}
# {date}: problem — {what wasn't working / what error kept recurring}
# hypothesis — {why this rule should help}
# outcome — {did it work over the last N attempts, or "not yet verified"}
For periodic cleanup of the instruction file:
Here's the instruction file {file name} with a comment attached to each rule.
The comments explain why each rule was added and whether it worked.
Analyze it and point out:
1. Rules whose underlying reason is no longer relevant
2. Rules that, according to their own comments, never confirmed they were actually effective
3. Rules that duplicate each other in the reasoning behind their comments
{paste file with comments}
🚀 Quick start — paste into the chat:
Here's a principle for maintaining an AI agent instruction file (CLAUDE.md/AGENTS.md) —
next to each rule, write a hidden comment: what problem it solves,
what hypothesis is behind it, and whether it actually worked in practice. The executor
never sees the comment — only a human during cleanup.
Help me apply this to my file: {paste your instruction file}.
Add comments to the existing rules based on what I tell you
about the reason behind each one — ask me questions about each rule.
The LLM will ask about the history of each instruction (when it was added, what problem it solved) — because without that context, the comment stays empty and won't help during future cleanup.
Limitations
⚠️ Requires upfront discipline: the method only works if the comment is written at the moment the instruction is added, while the reason is still fresh. If you start commenting retroactively, the effect is weaker, because you'd have to reconstruct the same forgotten reason all over again.
⚠️ The comment needs an outcome, not just backstory: the study found that writing only "what we tried" without "did it work or not" nearly kills the effect. An empty narrative with no resolution is one of the worst options — worse than having no comment at all.
⚠️ Doesn't fix bad instructions from the start: the method helps decide what to delete, but it doesn't improve the quality of new rules — if a rule is poorly worded to begin with, a comment won't fix that.
⚠️ You need a tool or habit to hide comments from the executor: in real use, it's important that the AI agent performing the task doesn't confuse the comment with the instruction itself. If you paste such a file directly into a chat, explicitly ask the model to ignore the comment lines.
How It Was Studied
The team pulled 1,867 GitHub repositories containing files like CLAUDE.md and AGENTS.md and tracked 247,694 individual instructions — not just how the overall file size changed, but how each specific rule line lived and died. It turned out files grow by an average of 226% over their lifetime, and the older an instruction is, the lower the odds it gets removed (rather than simply rewritten along with everything else).
To pin down the cause of this growth, the researchers tested three hypotheses: rules become outdated over time (in which case removal odds would rise with age), fragile rules die young (in which case odds would fall as the file matures), or people simply forget why a rule was added (in which case odds would fall specifically with age, and drop even more sharply when authorship changes hands). The data confirmed the third hypothesis — forgetting the reason, not the task becoming outdated.
Here's the clever part: to test whether the comment trick actually works, you need to know the "ideal" size of an instruction file (how many rules are truly needed) — and in real life, that's unknowable. So the researchers took an existing benchmark, IFEval (where the exact number of required rules is known in advance), and flipped it inside out: they hid the correct rule list, gave the model only a general task description, and made it "rediscover" the rules through trial and error — just like in real life. This let them measure how bloated the instruction file gets with versus without comments — and comments cut the excess rules almost to zero (from +211% bloat down to +1.4%). On real-world data (WildIFEval), the same comments boosted rule-compliance accuracy by 23%.
Original From the Study
Do not truncate or cut off your response; always
complete every sentence and thought you begin.
# r1: response was truncated mid-sentence ("A
body that you often s") suggesting response
generation stopped prematurely; may indicate token
limit, instruction conflict, or assistant aborting
output; this directive ensures responses are
complete
Context: This is what an instruction with a comment looks like in the actual experiment — the comment (after #) describes a specific failure, the hypothesis, and its underlying logic. Comments like this — not just "housekeeping" notes — are what drove the main effect in the study.
Adaptations and Extrapolations
💡 Adaptation for personal prompt templates: If you keep a stash of prompts for recurring tasks (say, a template for business emails, or a resume-screening prompt), apply the same principle — next to every added condition, write one line explaining why that condition exists.
Always list the salary range in job postings if the candidate is from outside a major metro area.
# added 10/15: without a range, candidates outside major metros ignored the posting
# 40% of the time (per recruiter feedback); with a range listed, response rate went up
🔧 Technique: make the comment a required field → prevent "dead weight" from piling up
Instead of tacking on a comment after the fact, build it into the process itself: on every edit to an agent's instruction file, have the LLM ask "why are we adding this rule?" before it writes the rule into the file. That turns a one-off trick into a habit.