AGENT.md: Why your README matters more than AI configuration files

The AGENT.md specification emerged in July 2025 as an attempt to solve a real problem: developers maintaining separate configuration files for each AI coding tool (.cursorrules, .windsurfrules, CLAUDE.md, and more). Created by Sourcegraph’s Amp team, AGENT.md promises “one file, any agent”. A vendor-neutral standard to unify AI assistant configuration. But a surprising truth has emerged: the proliferation of AI configuration files has inadvertently revealed that most projects have terrible documentation, and fixing your README is more important than adopting any new standard.

The problem AGENT.md tries to solve

As AI coding assistants proliferate, developers find themselves maintaining duplicate configuration files. GitHub Copilot wants .github/copilot-instructions.md, Claude needs CLAUDE.md, Cursor uses .cursorrules, each containing largely the same information. AGENT.md proposes consolidating these into a single Markdown file that all tools can understand.

The specification defines a hierarchical system where files can exist at multiple levels (user, project, subdirectory), with more specific files overriding general ones. It includes an @-mention system for referencing external documentation and promises backward compatibility through symbolic linking.

Technically, it’s well-designed. But it’s solving the wrong problem.

The real issue: your README was always inadequate

Here’s what early AGENT.md adopters discovered: the content of a good AGENT.md file looks exactly like the documentation that should have been in the README all along. After explaining project context to AI agents 100 times, developers finally wrote the comprehensive documentation they’d been avoiding for years.

AI agents need the same context a human developer needs:

• Project architecture and structure
• Build and test commands
• Coding conventions and patterns
• Key design decisions
• Development workflow

AI agents already read your README. They don’t need this information duplicated in AGENT.md. What they need is for your README to actually be good.

What really belongs in AGENT.md

If you write a comprehensive README, AGENT.md should be tiny - perhaps 20-30 lines containing only AI-specific operational details:

• CI/CD tools available in the agent’s runtime environment
• Environment variables and secrets the agent can access
• Modified test commands for non-interactive execution
• Warnings about operations requiring human intervention
• Agent-specific API endpoints or service configurations
• MCP (Model Context Protocol) server configurations the agent can connect to and use
• Resource limits or permissions specific to MCP-connected services

For example, if your AI agent has access to MCP servers for PostgreSQL or GitHub integration, document those connection details in AGENT.md, not how your database schema works (that’s README content). The distinction is clear: MCP configuration is about what tools the AI can use, while your README explains what your project does and how it’s built.

If information would help a human developer, it belongs in the README, not AGENT.md. Duplicating your README content in AGENT.md wastes context window tokens and creates maintenance burden.

Potential security issues

Security researchers have identified “Rules File Backdoor” attacks where malicious actors inject hidden instructions into AGENT.md files using Unicode characters and evasion techniques. Since AGENT.md content gets injected directly into system prompts, it creates an attack vector that works across different AI assistants. So be careful what you include in there. Don’t copy paste rules without getting a good understanding at what you are doing.

The more comprehensive your AGENT.md file, the larger your attack surface. Another reason to keep it minimal.

Why the standards war doesn’t matter

AGENT.md now competes with OpenAI’s AGENTS.md format, fragmenting the market it aimed to unify. But this misses the point entirely. Good AI coding tools should let you configure which context file to read. If your tool demands a specific filename with no configuration option, that’s vendor lock-in, not standardization.

Tools that can’t handle basic configuration like “read context from this file” are acting anti-competitively. Demand flexibility from your vendors instead of waiting for a universal standard that may never come.

The practical approach for development teams

1. Fix your README first. If you’re repeatedly explaining the same context to AI agents, your README is inadequate. A good README should enable any developer - human or AI - to understand and contribute to your project.

2. Keep AGENT.md minimal. Include only truly AI-specific operational context. This typically means environment details, runtime configurations, and automation-specific commands.

3. Treat both files as code. Subject them to code review, security scanning, and version control. But prioritize README quality over configuration standardization.

What this means for Upsun users

For teams deploying on Upsun, the Git-driven infrastructure approach already encourages good documentation practices. Your .upsun/config.yaml file define infrastructure as code, making it natural to document these choices in your README.

Focus on documenting:

• How your preview environments work
• Your multi-app architecture decisions
• Resource allocation strategies
• Environment-specific configurations

Let your AI agents learn from this documentation rather than maintaining separate configuration files. If you need AGENT.md, use it only for platform-specific details like environment variables available during deployment or CLI commands specific to your Upsun setup.

The bottom line

AGENT.md’s greatest contribution isn’t standardizing AI configuration, it’s forcing developers to finally write decent documentation. The irony is striking: AI agents have done more to improve README quality in one year than decades of best practice guidelines.

Your README should be your single source of truth for both humans and AI agents. Write it well, and you’ll need minimal AI-specific configuration regardless of which standard wins. The projects that succeed with AI assistance aren’t those with the best AGENT.md files - they’re those with the best documentation, period.

The path forward is clear: invest in documentation quality first, treat configuration standards as secondary. Make your README genuinely useful. Use AGENT.md or alternatives sparingly, only for operational details unique to automated agents. This approach delivers immediate value while sidestepping the standards war entirely.

After all, the same context an AI agent needs to understand your project is what a human developer needs. Get that right, and everything else becomes trivial.

Ready to improve your development workflow? Start with better documentation and let Upsun’s preview environments help you test changes with confidence. Create your free account at upsun.com and see how good documentation combined with powerful deployment tools accelerates development.