AGENTS.md is not a changelog

AGENTS.md is loaded at the start of every session. When teams append pull-request narratives and measurements to it, the file only grows, and the actual rules get buried. The brief should stay short; the history belongs somewhere else.

·7 min read

Public developer issues and discussions often talk about how to maintain AGENTS.md. Earlier this month we wrote about stale rules, and why a rules file is not a decision log. Another problem that keeps coming up is the file that only grows.

People were not asking for a longer brief. They were trying to stop an always-loaded instruction file from turning into a diary.

The file that only grows

AGENTS.md is useful because agents load it at the start of a session. That is also why an unbounded file is expensive: every extra paragraph is paid for again tomorrow.

In one public issue, the author described what they had observed in a private production repository. Six AGENTS.md files plus a root file added up to 9,243 lines. The root file alone was 1,792 lines; one area file was 2,659. An agent would load the root plus the area file before starting work, so 2,000 to 4,000 lines of instructions in a single session. In one day of agent work, 218 lines were added, most of them dated measurements that were already recorded in pull request bodies and commit messages. The underlying mechanic was familiar: a check flagged documentation that had not been updated, agents complied by appending an incident narrative, and nothing ever asked for a line to be removed.

A second public issue described a 698-line AGENTS.md that was loaded in full every time an agent started work. Roughly 500 lines were project-specific rules, about 130 lines were generic advice about using AI tools, and about 70 lines repeated material that already lived in other docs. Important rules, such as cache directives and auth checks, were getting lost in the rest. The team wanted the file cut to 350 lines, with the duplicated sections replaced by links.

A third discussion asked, plainly, what value there was in keeping change history inside the instruction file that loads in every session. The file in question was CLAUDE.md. It had grown to 47,000 characters and was being injected into every session and every project agent.

The pattern is the same. The rules file becomes the easiest place to append what just happened. History is valuable. It just does not belong in the brief that is loaded, in full, every time.

A longer brief is not a better brief

This is no longer only a matter of taste. The tools themselves already treat size as a limit.

The official AGENTS.md site describes the file as a README for agents. It is a predictable place for build steps, tests, and conventions, so those instructions do not clutter a human README. Cursor's rules documentation says to keep rules under 500 lines, split large rules into focused files, and reference other files instead of copying their contents. That way the always-loaded text stays short and does not go stale as the code changes. OpenAI's Codex documentation on custom instructions with AGENTS.md is more mechanical. Codex concatenates AGENTS.md files from the project root down to the working directory, and stops adding files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default. Truncated instructions are a documented failure mode. The suggested fixes are to raise the limit or to split large files so critical guidance stays intact. Anthropic's Claude Code documentation also covers reading a repository's AGENTS.md. It recommends targeting under 200 lines per instruction file: longer files consume more context and reduce adherence.1

Even when a file fits in the window, a longer context is not free. On 14 July 2025, Kelly Hong, Anton Troynikov, and Jeff Huber at Chroma published Context Rot: How Increasing Input Tokens Impacts LLM Performance. They evaluated 18 models, including GPT-4.1, Claude 4, Gemini 2.5, and Qwen3, on tasks that were deliberately kept simple while only the input length changed. The tasks were extensions of Needle in a Haystack, a conversational question-answering set (LongMemEval), and a repeated-word copying task. Models did not use context uniformly. Performance grew increasingly unreliable as input length grew, even under those minimal conditions. The authors note that the evaluation is not exhaustive of real-world use, and that agent tasks are typically more complex, so they would expect the effect of length to be even more pronounced in practice.

A 2,000-line always-on brief is not a more complete project memory. It is a larger haystack in which the current rule has to be found again, every session.

Compile the rule, don't append the story

The temptation to append is understandable. Something went wrong, you measured it, you want the next agent to know. The mistake is leaving the story in the place of the rule.

A November 2026 preprint makes the alternative precise. Nima Vahdat and Pashootan Vaezipoor (Georgian AI Lab) posted Decision Context: Persistent Behavioral Learning for AI Agents. Their system, forge_dc, compiles human corrections and self-assessed tool-call failures into imperative rule directives, then injects those rules at the decision points where they apply, instead of retrieving raw history. The test used DC-Bench: 71 scenarios across nine behavioral dimensions, built from real executed agent traces in a deterministic mocked-tool environment. On that benchmark, forge_dc reached 95% compliance, up from 55% with naive retrieval, while injecting roughly ten times fewer tokens per query.

These results come from a mocked-tool benchmark, not from repository AGENTS.md files. They measure compliance with compiled rules rather than end-to-end software quality. They still help explain this kind of growth: dumping yesterday's narrative into the always-loaded file is the naive-retrieval move. The cheaper, more reliable move is to update the current rule, and to keep the story somewhere it can be audited without being injected every time.

A practical split looks like this:

  • Keep AGENTS.md as the current brief. Commands to build, test, lint, and run. Directories not to touch. How to open a PR. Facts you can verify against the repo today.
  • If a change produced a measurement or an incident write-up that already lives in a pull request or a commit, do not also append it to AGENTS.md. The next agent does not need the dated log. It needs the rule and, if there is one, the check that now enforces it.
  • If a section already has a home in docs/, link to it. Cursor's guidance is the same: reference a file rather than pasting it, so the brief stays short and does not rot when the longer document changes.
  • When the file grows, condense or split it. Do not only add. If generic "how to use AI tools" advice is taking a hundred lines, it is probably not earning its place in this repository's brief.
  • Watch the budget the tools actually apply. A root file that is already thousands of lines will hit Codex's 32 KiB default and can crowd out the nested, more specific files that matter for the directory you are in.

Current truth, plus a timeline

History still needs a place. The useful pattern is the same one a decision log needs: a current answer that can be rewritten as a whole, and an append-only trail of how you got there. The trail is where dated measurements, reversals, and incident notes belong. The current answer is what the next session should load.

MindMux itself makes a product in this space. This is what it does today.

MindMux captures background, decisions, and constraints from the conversations you already have with agents, and writes them into a Markdown project brain. Agents read that brain over MCP before they start a task. To connect Claude Code or Codex, install @mindmux/cli and run mmx setup in the project. mmx setup --local gives a local Brain without Cloud login. The open, local counterpart, brain.md, is a brain/ folder in your repo plus a small CLI (@mindmux/brain-md). Every page keeps a compiled_truth, the current answer, and an append-only timeline of how you got there. It is git-native and agent-agnostic: Claude Code, Codex, Cursor, and anything else that can read a file.

AGENTS.md can stay short. The brain holds the decisions, and the timeline holds the history. The next session, on the next tool, starts from the current understanding, not from a 2,000-line diary of last week's pull requests.

This is cross-session, cross-tool decision memory.

If that is the problem you have:

If the first thing you notice is that the brief is still readable, and that yesterday's measurements did not get pasted into it again, it is working.

Footnotes

  1. Anthropic, How Claude remembers your project. ↩

Share to