An AGENTS.md file is the bedrock of an AI agent's knowledge base. It's where you define the agent's persona, capabilities, and constraints. The problem isn't writing it; it's keeping it accurate. As soon as code changes, the AGENTS.md file starts to lie, and the agent, trusting it implicitly, follows outdated instructions. This decay, often called 'rot,' erodes agent reliability. The solution isn't a one-time write, but a continuous discipline of maintenance. This article outlines a step-by-step process to ensure your AGENTS.md remains a source of truth, not a vector for errors.
The Six Steps to an Unrottable AGENTS.md
The core principle is simple: tie every statement in your AGENTS.md to a verifiable fact in your repository. This means linking documentation to actual code, ensuring it runs, and making documentation changes concurrently with code changes. This discipline prevents drift and maintains agent trust.
Step 1: Start from Truth, Not Template
Before writing any documentation, list what is factually true about your project. This involves examining the repository's current state. What are the actual commands to build? What are the definitive output artifacts? What are the core dependencies and their versions? Don't start with a generic template; start with the concrete realities of your codebase. This foundational step ensures that your documentation is grounded in reality from the outset.
Step 2: Fact-Check Every Line
Once you have your factual list, begin drafting your AGENTS.md. For every claim made in the document – every command, every file path, every configuration setting – you must have a corresponding, verifiable fact in the repository. If you state a command, you must be able to run it and get the expected output. If you describe a file structure, that structure must exist. This is not about prose; it's about executable truth. If a line cannot be tied directly to a fact, it's a candidate for removal or requires immediate correction.
Consider this analogy: maintaining an AGENTS.md is like tending a garden. You don't just plant seeds and walk away. You must weed, water, and prune. If you let weeds (inaccurate statements) grow, they choke out the valuable plants (accurate information), and the entire garden becomes unusable. Each statement in your AGENTS.md is a plant that needs constant tending.
Step 3: Verify Execution
Beyond just existing, the facts must *work*. This means actively running every command, executing every script, and testing every configuration described. The AGENTS.md should function as an automated test suite for itself. If a command fails, the documentation is immediately suspect. This step is critical. It transforms the document from a static description into a dynamic, executable specification. Any discrepancy found here requires an immediate update to either the code or the documentation, or both.
Step 4: Co-locate Changes with Code
The most common failure point is the temporal disconnect between code changes and documentation updates. To combat this, documentation changes must be part of the same Pull Request (PR) as the code they describe. If you refactor a command, update the AGENTS.md in the same PR. If you add a new feature, document its usage in the same PR. This ensures that the documentation is always in sync with the code it represents. This practice prevents the 'stale' state from ever occurring. Your agent won't be fed outdated information because the outdated information will never be merged.
Step 5: Continuous Verification
This discipline isn't a one-off task. It requires ongoing commitment. Integrate the verification steps into your team's workflow. This could mean using CI/CD pipelines to automatically check documentation against code, or establishing a mandatory review step for all PRs that includes a check of the associated AGENTS.md updates. Regularly audit the entire AGENTS.md file to ensure continued accuracy and relevance, especially after significant project refactors or version upgrades.
Step 6: Embrace Agent Feedback
Your AI agent can be your best ally in maintaining the AGENTS.md. If an agent consistently fails to execute a documented step, or reports unexpected outcomes, treat this as a critical bug report. Investigate why the agent is deviating from the documentation. Is the documentation wrong, or is the agent misinterpreting it? Use these failures as signals to tighten your documentation and improve your agent's reasoning. This creates a feedback loop where the agent helps to keep its own knowledge base accurate.
A Worked Example: Building a CI Step
Let's walk through an example. Suppose you want to add a new CI step that lint's your Python code using Flake8.
Initial Code Change (in a PR):
# Add a new script or modify an existing one
# e.g., in .github/workflows/ci.yml
- name: Lint Python code
run: flake8 .
AGENTS.md Update (in the SAME PR):
Now, you must update your AGENTS.md to reflect this change. Instead of just stating 'Lint the code,' be specific:
## Python Code Linting
To ensure code quality, the Python codebase is linted using Flake8. This step runs automatically as part of the CI pipeline.
Command:
flake8 .
Expected Output:
No output if all files adhere to the style guide. Any violations will be listed with file path, line number, and error code.
Prerequisites:
Flake8 must be installed. It is listed as a development dependency in pyproject.toml and installed via pip install -e .[dev].
Verification:
1. Run flake8 . locally to confirm it works and to see typical output. Ensure Flake8 is installed in your dev environment.
2. Ensure the CI workflow correctly installs dependencies (including Flake8) before running the lint command.
3. Submit the PR. The CI pipeline should execute the lint step. If it fails, the PR will fail, and the failure message will guide you to the problem (either in the code or the documentation).
By following this process, you ensure that the AGENTS.md accurately describes a functional, integrated part of your project. The agent will see a clear, executable instruction tied directly to the code's execution path. This is how you stop the rot and build an agent that truly trusts its knowledge base.