Will Ayers
← Back to all postssystems /

Maintain AGENTS.md Without Building a Policy Landfill

A practical method for adding, revising, and deleting agent instructions without turning one file into permanent context debt.

aiagentsdocumentationmaintenance

This is part six of AI Working Agreements. Start with AGENTS.md Is a Communication Protocol for the complete working-agreement structure.

An AGENTS.md file usually grows for a good reason. An agent makes a frustrating mistake, so we add a rule to prevent it from happening again.

Over time, that reaction can create a policy landfill: duplicated warnings, stale commands, contradictory defaults, tool-specific workarounds, and instructions so specific that they only describe one incident.

More context is not the same as better guidance. A working agreement needs maintenance.

Every permanent rule has a cost

An instruction consumes attention in every task inside its scope, not only the task that caused it to be written.

That cost shows up in several ways:

  • important rules compete with low-value details
  • stale commands produce failed execution
  • overlapping instructions create interpretation work
  • exceptions make behavior less predictable
  • long files become harder for people to review
  • project-specific rules leak into unrelated work

The marginal cost of one bullet is small. The accumulated cost of hundreds of unexamined bullets is not.

I treat the file as active system configuration rather than an archive of past annoyance.

Add rules from recurring failure patterns

I use three tests before adding a permanent instruction:

  1. Recurrence — Is the problem likely to happen again?
  2. Clarity — Can the desired behavior be stated in a way another person could apply?
  3. Scope — Will the rule help enough future tasks to justify permanent context?

A one-time typo fails the recurrence test. A vague reaction such as "be smarter about architecture" fails the clarity test. A workaround for one package fails the global scope test but may belong in a nested file.

This filter prevents the working agreement from becoming a transcript of every mistake.

Write the replacement behavior

Rules are easier to follow when they describe what to do, not only what to avoid.

Weak:

1- Do not make huge changes.

Stronger:

1- Prefer the smallest useful change that solves the request.
2- Ask before materially changing scope, architecture, dependencies, or
3  user-facing behavior.

The stronger version defines both the default action and the escalation boundary.

Negative examples still have value when a common interpretation needs to be removed. Pair them with a positive target:

1- Lead with the answer and state each fact once.
2- Do not repeat the conclusion in an opening summary and closing summary.

The combination is more precise than either instruction alone.

Fix the system before adding prose

Some failures should not become language instructions at all.

If an agent repeatedly runs the wrong command because package scripts are unclear, fix the scripts.

If generated files are being edited, add a generated-file header or move output to an obvious directory.

If formatting varies, configure and run a formatter.

If a dangerous operation is possible through an unrestricted tool, change permissions or require an approval gate.

If a convention can be enforced by types, schemas, tests, or lint rules, executable enforcement is usually more reliable than another paragraph.

Use AGENTS.md for judgment, navigation, and workflow boundaries. Use the rest of the engineering system for machine-checkable contracts.

Watch for landfill symptoms

Several patterns indicate that an instruction file needs an audit.

Repeated rules

"Run tests before finishing" appears in communication, coding, testing, and Git sections with slightly different wording.

Consolidate it under validation and reference that expectation elsewhere only when a local exception exists.

Escalating emphasis

The file contains IMPORTANT, then VERY IMPORTANT, then NEVER, all trying to make one rule stronger than the surrounding rules.

Priority should come from structure, scope, and explicit boundaries rather than typography.

Incident-shaped instructions

A rule includes names, paths, and steps from one old task but no longer expresses a general contract.

Move durable operational detail into a runbook. Delete the rest.

Contradictory autonomy

One section says to act without asking. Another says to ask before any edit.

Replace both with a boundary based on scope, reversibility, and consequence.

Tool archaeology

The file mentions formatters, test runners, models, or deployment commands the project no longer uses.

Instructions must change with the system they describe.

Universal project preferences

A global file requires one framework, language, or testing style even in repositories with established alternatives.

State that local conventions win and move specific rules closer to their scope.

Run a deletion-first audit

When reviewing the file, I do not begin by asking what is missing. I begin with what can be removed.

For each rule:

1Is it still true?
2Is it in the correct scope?
3Does another rule already cover it?
4Can the system enforce it instead?
5Does it describe behavior clearly?
6Would removing it recreate a likely failure?

The first four questions often shrink the file before any rewriting begins.

After deletion, combine related instructions and normalize language. A section with five variations of "be concise" should become two or three observable behaviors.

Finally, look for actual gaps revealed by recent work. This order prevents every audit from producing a longer file.

Separate defaults, boundaries, and examples

Instructions become easier to reason about when they play clear roles.

A default describes what normally happens:

1- Make clearly scoped, reversible changes without asking.

A boundary describes where the default stops:

1- Ask before changing authentication, billing, migrations, secrets, or deploy configuration.

An example clarifies interpretation:

1- "Could we simplify this?" is a question; answer it before editing files.

Problems arise when examples are mistaken for exhaustive policy or when exceptions are added without a stable default.

Organizing around this pattern makes future maintenance easier. New cases can often be handled by improving the boundary rather than appending another incident-specific prohibition.

Give temporary rules an exit

Some temporary instructions are necessary. A flaky test may need serial execution. A migration may require a short-lived command order. A provider outage may change deployment behavior.

Temporary rules should identify their removal condition:

1- Until issue #482 is resolved, run the database integration suite serially.
2  Remove this instruction when the shared fixture becomes isolated.

Better yet, keep operational incidents in a runbook or issue and place only the minimal routing note in AGENTS.md.

A temporary instruction without an owner or exit condition is a permanent instruction waiting to become false.

Review changes like code

The working agreement affects every agent-generated patch, so changes deserve review.

A useful instruction-file diff should answer:

  • Which recurring problem does this solve?
  • Why is this the correct scope?
  • Does it conflict with an existing rule?
  • Could an executable check solve it better?
  • What behavior should change in the next relevant task?

Version control gives the file a useful history. When an instruction creates unintended friction, the original change explains what it was trying to protect.

Avoid large generated rewrites that replace the team's actual agreement with generic advice. A generated first draft can help inventory a repository, but the final rules need human ownership.

Test instructions through real work

An instruction is only useful if it changes behavior in the intended way.

After adding a rule, observe relevant sessions:

  • Does the agent apply it without being reminded?
  • Does it ask at the intended boundary?
  • Does it over-apply the rule to unrelated tasks?
  • Does the completion report contain better evidence?
  • Did the rule create new permission loops or verbosity?

This is qualitative evaluation, but it is still system feedback.

For repository commands, validation can be direct: run the documented setup from a clean environment. For communication and autonomy rules, review several real tasks rather than staging one ideal prompt.

Schedule lightweight maintenance

The file does not need a governance meeting. It does need an owner and a trigger for review.

Useful triggers include:

  • changing framework or build tooling
  • replacing test or formatting commands
  • adding a new package boundary
  • changing deployment ownership
  • observing the same agent failure several times
  • noticing repeated exceptions to an existing rule

A periodic review can be small: inspect the diff history, remove stale instructions, and verify the commands still work.

The best time to delete a rule is when the system has made it unnecessary.

A maintenance policy

1## Maintaining these instructions
2

3- Add rules for recurring, clearly stated problems rather than one-time mistakes.
4- Keep each rule at the narrowest scope where it remains true.
5- Prefer executable enforcement for machine-checkable behavior.
6- Pair important prohibitions with the desired replacement behavior.
7- Give temporary workarounds an issue, owner, or removal condition.
8- Remove stale, duplicated, or contradictory instructions before adding more.
9- Review changes to AGENTS.md as system behavior changes, not prose cleanup.

Adapt this process to the size of the team and repository. A personal working agreement can evolve quickly. A shared organizational file may need owners and review from several disciplines.

The objective is not the shortest possible AGENTS.md. It is a file where every section earns its place by making repeated work clearer, safer, or easier to verify.

A good working agreement becomes more precise over time. A policy landfill only becomes longer.

Resources