Best Tools to Keep AGENTS.md Files Up to Date

An AGENTS.md file is a promise to your coding agents that the repository works a certain way. It was true the day someone wrote it. Then a test command got renamed, a service moved, and a review thread settled an architecture question that never made it into the file. The agent does not know any of that. It reads the file at session start and treats every line as fact, with more confidence than the code in front of it.

That is the maintenance problem this comparison is about. Not how to write a good instruction file, which is well covered, but what keeps one true after the code moves. The same question applies to CLAUDE.md and Cursor rules, and it gets harder when a team runs all three, because each agent loads its file with different precedence rules and nothing warns you when they disagree.

Eight approaches are compared below. Some of them maintain instruction files. Several maintain something adjacent and get sold as if they did the same job. The table and the sections say which is which.

Why instruction files rot, and what "up to date" means

A 2026 study by ETH Zurich and LogicStar, Evaluating AGENTS.md, compared coding agents with generated, developer-written, and absent context files.

In the tested settings, context files increased inference cost by more than 20% on average without a statistically significant improvement in task success. Repository overviews offered little benefit.

For maintenance, keep instructions concise and specific, then test their effect on your own tasks.

So "up to date" does not mean "regenerated recently" or "longer." It means the small set of repo-specific facts in the file still match the repository, in every format your agents read.

What to look for in a maintenance approach

• Update trigger. What causes the file to change? A coding session, a merged pull request, a CI job, or a person remembering. Write-once generators produce a snapshot that starts aging immediately.
• Cross-format drift. Check which files each client loads and how it handles nested instructions. Claude Code supports importing AGENTS.md from CLAUDE.md.
• Source breadth. Decisions can live in repository docs, pull request threads, chat, or tickets. Check whether the tool can read the sources your team actually uses.

Memory APIs and generated wikis appear below because buyers encounter them in the same searches. They are judged on what they actually do, not penalized for not doing this job.

How the eight compare

Dosu, for a file that changes because the code did

Dosu captures engineering context from coding sessions and connected Sources. With Monitor enabled, it checks relevant pull requests against published Documents and proposes edits when it detects drift. Applying those edits follows the configured review workflow.

Dosu supports generating AGENTS.md, README.md, architecture.md, and deps.md. Connected discussions can supply the reasoning behind those files, while coding agents retrieve wider context over MCP and the CLI. For documentation stored in git, accepted updates can produce a documentation PR. Shared knowledge can reduce repeated investigation, but savings depend on the task and the relevance of the retrieved context. Dosu is SOC 2 Type II compliant.

Where is the line? Dosu does not maintain CLAUDE.md or .cursor/rules. If your team runs Claude Code, the fix is the one Anthropic's own documentation recommends: a CLAUDE.md whose first line is @AGENTS.md, so both tools read the same maintained file. Path-scoped Cursor rules stay hand-written. And Dosu is infrastructure for teams using coding agents, not a memory API for building them.

Falconer, for a knowledge base that updates when PRs merge

Falconer is the closest thing in this list to "documentation that updates itself on merge," and it deserves credit for that. It connects GitHub, Slack, Linear, Notion, Google Docs, and Confluence into a searchable knowledge base with an agent named Falcon on top. When a pull request merges, Falcon identifies which documents are affected and proposes updates for the owner to accept or reject. Coding agents reach the knowledge base through a hosted MCP server with tools to search, read, create, edit, overwrite, and archive documents.

Falconer documents a hosted knowledge base and MCP access. Confirm whether your workflow also needs updates to committed instruction files. Its Starter plan includes MCP, while Pro adds automatic document updates.

Unblocked, for live context beside hand-maintained files

Unblocked calls itself a context engine, and it is the clearest example of the supplement-not-replace pattern. It indexes more than 25 sources, including GitHub, GitLab, Jira, Linear, Slack, Teams, Confluence, Notion, Datadog, and Sentry, and serves reconciled, cited answers to Claude Code, Cursor, Codex, and Copilot through a single read-only MCP server. Its own guidance says to keep anything that changes weekly out of instruction files entirely and let the context engine answer what is true now.

Unblocked supplies context during a session. Teams should confirm how they will maintain the instruction files loaded at startup. Code Review starts at $19 per user per month and Platform, which includes MCP access, at $29 per user per month, both billed annually.

Open source sync mirrors, for one canonical file

Three small projects solve the cross-format problem deterministically. mujinlabs/agentsync mirrors AGENTS.md to CLAUDE.md or the reverse and exits non-zero in CI when a generated copy has been hand-edited. resuaico/agentsync goes wider, writing Cursor .mdc rules, Copilot instructions, Windsurf rules, and GEMINI.md from one source, and adds a linter that catches paths that no longer exist, renamed scripts, contradictory sections, and secrets pasted into a curl example. lohn/sync-claude-md is a pre-commit hook that ensures every AGENTS.md has a sibling CLAUDE.md containing the @AGENTS.md import.

Synchronization keeps generated copies aligned. Some tools also flag stale paths, commands, or conflicting rules. Those checks cover specific errors, while broader architectural meaning still needs review.

Scan-and-regenerate generators, for catching mechanical drift

mikiships/agentmd, Adamchaua/agent-ready, and markoblogo/AGENTS.md_generator scan repository evidence such as package files, CI config, and source layout, generate instruction files from it, and ship a drift command with a CI exit code. Each offers a GitHub Action that fails a pull request when the evidence has moved past what the file says. The last of the three only writes inside explicit marker blocks, so hand-written sections survive regeneration.

Where is the line? A scanner sees a renamed test command. It does not see that the architecture note above it is now misleading, and it cannot know that a decision was made in a PR thread. These catch the mechanical drift and none of the semantic drift.

LLM regeneration in CI, for the semantic gap

sheepbox8646/agents-md-updater is a reusable GitHub Workflow that runs Codex or Claude Code against your repository and rewrites AGENTS.md, CLAUDE.md, or both, on a weekly schedule, on pushes to chosen paths, or after a merge. It opens a pull request by default rather than pushing, handles monorepos with nested files, and needs an API key or OAuth token in repository secrets.

This workflow uses a model to propose changes, so budget for each run and review its output. The cited study did not test this updater. Evaluate whether its changes improve your agents’ work before making regeneration routine.

Memory layers for applications and coding agents

Mem0, Zep, and Cognee preserve context across tasks. Their interfaces and maintenance models differ. Mem0 offers coding-agent plugins and MCP access. Cognee can build memory from code and connects through plugins and MCP.

For an AGENTS.md workflow, verify how the chosen integration detects repository changes, reviews corrections, and updates the committed file. Persistent memory alone does not establish that workflow.

Docs platforms, for a surface agents can read

Mintlify runs a documentation agent on a schedule or on push that opens PRs against your docs, and it serves every page as Markdown plus llms.txt and an MCP server. GitBook's agent flags documentation that no longer matches the product and queues it for review. DeepWiki generates a repository wiki on request.

Compare the workflow each product documents. Mintlify can propose documentation changes through PRs and accepts its own agent instructions. For each platform, verify whether maintenance covers the committed instruction files your coding agents load and how those changes are reviewed.

Which approach fits your team

A small team on one repository with one agent should hand-write a short AGENTS.md, add a sync mirror if a second agent shows up, and put a scanner in CI. That is free and covers the mechanical half of the problem.

A team using several coding agents can share a canonical instruction file and check generated copies in CI. Review client-specific instructions and loading rules as well, since matching text alone does not establish consistent behavior.

If decisions live in Slack or Linear, include those sources in your evaluation. Unblocked and Falconer provide context from connected systems. Dosu combines shared retrieval with proposed documentation updates.

For a codebase that changes daily, evaluate the full workflow on one repository. Publish the relevant documentation, enable Monitor, and inspect the proposed edits and review steps.

FAQ

Does AGENTS.md replace CLAUDE.md and Cursor rules?

No. One option is a shared AGENTS.md, imported by CLAUDE.md, plus client-specific rules where needed. Check each client’s loading behavior before removing existing instructions.

Do LLM-generated instruction files help coding agents?

Results depend on the setting. The cited study found higher costs without a statistically significant task-success improvement. It supports testing concise, task-relevant instructions against a baseline.

Can any tool detect conflicting instructions across all three formats?

Sync checks detect textual divergence, and some linters flag specific contradictions. To evaluate semantic conflicts across formats, test the tool against conflicting instructions from your own repository.

How is a memory layer different from an instruction-file maintenance tool?

A memory layer preserves context for later retrieval, including through coding-agent integrations. An instruction-file maintenance workflow also needs to detect source changes, propose edits to committed files, and review those edits. Check which parts the product and its integrations provide.

Check what your agents are actually loading

Open Claude Code in your repository and run /context to inspect its Memory files. Check the loaded CLAUDE.md and whether it imports or links to AGENTS.md. Then review the loaded instructions for stale commands and decisions.

Connect that repository to Dosu, enable Monitor for the relevant Sources, and review the documentation updates it proposes.