Versioning and Reviewing Context Files as Source Code

Two lines added to a context file change how every session in the repository behaves. It usually gets less scrutiny than a typo fix, because it is markdown and markdown feels harmless.

A file that changes how every session behaves

Adding two lines to AGENTS.md changes the behaviour of every agent session in the repository, for everyone, immediately. That is a broader blast radius than most code changes, and it routinely lands with less scrutiny than a typo fix — because it is markdown, and markdown feels harmless.

The correct mental model is that a context file is closer to CI configuration than to documentation. It is not executed, but it is operative: it changes what happens, silently, until someone notices the output got worse.

Route the review to the right people

The minimum is a CODEOWNERS entry so that changes require review from people who understand the consequences.

# The root file affects every session in the repo — small owner set
/AGENTS.md                    @platform-leads

# Package files are owned by whoever owns the package
/packages/api/AGENTS.md       @api-team
/packages/web/AGENTS.md       @web-team
/packages/pipeline/AGENTS.md  @data-team

Deliberately asymmetric. The root file gets a small, senior owner set because it is a shared resource that degrades under uncoordinated additions. Package files get the team that lives with them, because they are the ones who will notice when a rule is wrong.

What to actually look for in review

"LGTM" on a context file diff is close to worthless. Five questions are worth asking every time.

Those five fit in a PR template checkbox and take a reviewer under a minute. The third catches most real defects.

Commit messages that explain themselves

Context file entries decay because nobody remembers why they exist. Six months on, a rule looks arbitrary, someone deletes it during a cleanup, and the problem it prevented comes back.

The fix costs nothing: put the incident in the commit message.

context: cap partner-api retries at 2

Agent raised retries to 5 in #4471, which tripped partner-api's
rate limit (3/min per key) and got our key blocked for an hour
during business hours. The low number is deliberate.

Refs: INC-2026-0412

git log on the file then becomes an institutional memory of every trap the team has hit. That log is worth more than the file itself after a year, and it is free.

Removal needs a forcing function

Files grow monotonically without one. Additions are easy to justify — something went wrong, this prevents it. Removals are hard to justify, because nothing bad is currently happening and removing the rule might be why it starts.

Two mechanisms that work in practice:

Dated entries for temporary rules

## Temporary
- Do not add new endpoints to `/v1/` — the v2 migration lands in Q3.
  REMOVE AFTER: 2026-10-01

Add a CI check that fails when a REMOVE AFTER date passes. That converts a rule everyone has forgotten into a build failure with a name attached, which is the only reliable way these get revisited.

A budget that forces a trade

Cap the root file — forty lines, or a token count — and enforce it in CI. When someone needs to add a rule and the file is at capacity, they have to remove something. That conversation is exactly the one nobody has voluntarily.

#!/bin/bash
LIMIT=40
n=$(grep -vcE '^\s*$' AGENTS.md)
if [ "$n" -gt "$LIMIT" ]; then
  echo "AGENTS.md is $n non-blank lines (limit $LIMIT)."
  echo "Adding a rule? Remove one that no longer earns its place."
  exit 1
fi

Rolling out a change without surprising people

Some context file edits are genuinely breaking. Changing the stated test command, adding a hard prohibition where there was none, or restructuring the file so that rules move position — each changes behaviour people have built expectations around.

The failure is social rather than technical. An engineer who has been running agent sessions all week suddenly gets different behaviour, does not connect it to a markdown diff they never saw, and concludes the tool has regressed. They may spend an hour on it. Multiply by the team.

Two habits prevent it. Announce breaking changes in whatever channel the team actually reads, with one line on what changed and why. And prefer additive changes where you can — adding a rule is usually safe, changing the meaning of an existing one is not.

A changelog inside the file

For a root file in an active repository, a short trailer earns its keep:

<!-- Changelog — newest first, keep to 5 entries
2026-06-09  test command is now ./check.sh (was: three separate commands)
2026-05-28  added flag-before-changing rule for src/auth/
2026-05-14  removed v1 endpoint freeze — migration completed
-->

An HTML comment, so it does not render if the file is ever displayed, and it sits at the bottom where it costs the least positional value. Five entries, oldest dropped. Anyone confused by a behaviour change can check the bottom of the file before filing a bug against a tool.

Treat it as an interface

The most useful reframing: your context file is an interface between your repository and every agent that touches it. Interfaces get versioned, reviewed, documented and deprecated deliberately. They do not get edited casually because the change looked small.

Two habits follow from taking that seriously. Changes go through review like any interface change. And breaking changes — a renamed test command, a new hard prohibition — get announced to the team, because people have mental models built on the old behaviour and will not read the diff.