Maintain agent documentation by giving each current instruction a clear scope, an owner and a way to verify it. Separate working requirements from historical notes, and review affected guidance when the code changes. The process below is a proposed maintenance practice, not a measured productivity improvement.
The Markdown Layer research overview describes Markdown's use across documentation and agent workflows. This chapter addresses a narrower problem: what to do when several readable files give incompatible advice about the same task.
What does the research establish about documentation sprawl?
Harsha Kokel's Markdown Mayhem, an IBM-affiliated workshop position paper published in May 2026, argues that agent documentation needs clearer authority and governance. It discusses ambiguity and redundant instructions as risks. It does not measure a worldwide rate of documentation growth or prove that a particular maintenance process prevents failures. Author's paper.
There is empirical evidence that configuration artifacts are present in repositories. Galster and colleagues' published study found context files in 2,586 of 2,853 repositories with detected agent configuration. Those repositories came from a filtered set of established GitHub projects, with an artifact snapshot in February 2026. The 90.6% figure describes detected adopters, not all repositories or all developers. Published study.
Neither observation tells a maintainer whether their own instructions conflict. That requires examining the relevant files and the behavior they request. The number of Markdown files alone is a poor target for a cleanup: a large reference library can be coherent, while two short files can contradict each other.
Start with a concrete contradiction
Suppose a fictional repository contains these statements:
| Location | Statement | What a maintainer needs to resolve |
|---|---|---|
| Root agent instructions | Run the quick test suite before submitting changes | Whether quick tests cover this task |
| API package guide | Run the contract suite for public API changes | Whether this adds a scoped requirement |
| Old migration note | Skip contract tests while the test service is unavailable | Whether the temporary exception still applies |
The first two requirements may be compatible. The third needs evidence about its status. Deleting the longer file or telling the agent to prefer the newest timestamp would not resolve the underlying question.
Check the current test service, the package's test configuration and the decision that introduced the exception. If the exception has ended, update the live guidance and mark the migration note as historical. Preserve the reason for the original decision where it helps explain the migration, with a link to the replacement requirement.
An unresolved conflict should stay visible to the reviewer. Do not silently rewrite an uncertain policy into a confident instruction merely to make the files agree.
Inventory the instructions an agent can actually receive
List the entry files, nested instructions and referenced documents used by the team's agent setup. Record their audience and scope. A general search for Markdown is useful for discovery, but it does not tell you which files a particular runtime automatically loads.
Loading behavior can also change after an upgrade. Anthropic's documentation, for example, describes different treatment of project files, imports and scoped rules. Check the documented behavior for the version you use, then inspect the session's loaded context where the tool exposes it. Claude Code memory documentation.
| Record | Why keep it? |
|---|---|
| File path and intended reader | Distinguishes current agent guidance from human reference material |
| Owner or reviewing team | Identifies who can resolve a disputed requirement |
| Applicable package or task | Prevents a local exception from becoming a project-wide rule |
| Source of the requirement | Connects prose to a configuration, decision or tested workflow |
| Last verification and trigger for review | Explains what was checked and what might invalidate it |
A review date should describe an actual check. Changing a date without verifying the content makes the record less useful. If only links were checked, say so; that does not establish that a deployment procedure or test command still works.
Give recurring requirements one maintained home
Choose one authoritative source for each repeated requirement. A test command can live beside the package configuration or in a maintained contributor guide. Agent instructions can point to that source, provided the workflow actually brings the relevant material into context when needed.
Copying the same command into several files creates several places to update. A link reduces that duplication, but introduces a different failure: the reader may never follow it. Decide whether the instruction must be immediately available or can be consulted for a particular task, and verify that behavior in the chosen tool.
Avoid collapsing every document into one large file. Keep detailed migration history where a maintainer can find it, while making its status unambiguous. The knowledge portability chapter discusses the wider problem of preserving meaning when a document moves between tools.
Review documentation with the code change
Attach documentation review to a relevant event. Renaming a command should trigger a search for that command in instructions and examples. Moving a package should trigger a check of scoped paths. Changing an export format should trigger a check of sample output and the instructions used to produce it.
MD2FILE's proposed review cycle. It is a conceptual workflow, not an experimentally validated intervention.
For a command change, a useful review record might look like this:
## Instruction review: API tests
Reason: the contract-test command changed in this revision.
Scope: public API changes in packages/api.
Owner: API maintainers.
Checked: the documented command ran in the supported test environment.
Updated: the package guide and its agent-facing reference.
Historical note: the migration exception is marked superseded.
Open issue: Windows instructions have not been verified.
This is an illustrative record. It makes no claim that these checks have been performed in your project. Adapt the fields to the decision being made and leave unverified cases explicit.
Check behavior as well as the document
A clean document can still describe an ineffective workflow. After changing an instruction, try a task that should exercise it and inspect both the result and the agent's actions. If the instruction asks for a contract test, confirm that the relevant test ran and that its result was handled correctly.
Compare the changed instruction against the previous version when the behavior is important enough to justify the work. Use the same task and repository snapshot, and record agent/model versions. Assess task correctness separately from duration and token use; the agent-instruction evidence review explains why those outcomes can disagree.
Some requirements express policy rather than an efficiency goal. A rule preventing an unauthorized release should not be removed because it slows a benchmark. Define the intended outcome before the trial, and use permissions or other execution controls for boundaries that must be enforced.
Archive instructions without losing their explanation
When guidance expires, remove it from active entry points and preserve useful history with a clear status. An archive record should identify what superseded it and when. If a historical page remains accessible, its opening should make that status understandable without requiring a reader to find another file first.
Keep the editable source when sharing a fixed review copy. A PDF can be useful for a meeting or approval record, but it needs a revision identifier and a link to the maintained source so readers can distinguish that snapshot from current instructions. The document rendering chapter covers the checks needed when publishing such a copy.
Evidence and publisher disclosure
MD2FILE publishes this series and provides Markdown editing and conversion tools. Its commercial interest does not establish a need for more instruction files or a particular publishing format. The maintenance examples above are proposals; we have not measured their effect on agent reliability. The series methodology records research versions, sampling limits and verification scope.
Previous: Markdown for AI agents · Overview: The Markdown Layer · Next: Knowledge portability