> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> AGENTS.md promises to standardize AI coding assistant configuration, but the real solution is writing better READMEs that serve both humans and AI agents

export const PostMeta = ({data = {}}) => {
  const {author, date, image} = data;
  const authors = Array.isArray(author) ? author : author ? [author] : [];
  const resolveAuthor = slug => {
    const entry = AUTHOR_MAP[slug] || ({});
    const name = entry.name || slug;
    const github = entry.github || null;
    const linkedin = entry.linkedin || null;
    const url = github ? `https://github.com/${github}` : linkedin || null;
    const avatarUrl = github ? `https://github.com/${github}.png?size=64` : null;
    return {
      name,
      url,
      avatarUrl
    };
  };
  const formattedDate = date ? new Date(date).toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  }) : null;
  if (!image && authors.length === 0 && !formattedDate) return null;
  const AUTHOR_MAP = {
    "aaron-collier": {
      "name": "Aaron Collier"
    },
    "aaron-dudenhofer": {
      "name": "Aaron Dudenhofer"
    },
    "aaron-porter": {
      "name": "Aaron Porter"
    },
    "adriaan-odendaal": {
      "name": "Adriaan Odendaal"
    },
    "ajmal": {
      "name": "Ajmal Siddiqui"
    },
    "akalipetis": {
      "name": "Antonis Kalipetis"
    },
    "alexander-varwijk": {
      "name": "Alexander Varwijk"
    },
    "alicia-bevilacqua": {
      "name": "Alicia Bevilacqua"
    },
    "amelie-deguerry": {
      "name": "Amelie Deguerry"
    },
    "anacidre": {
      "name": "Ana Cidre",
      "linkedin": "https://www.linkedin.com/in/ana-cidre"
    },
    "andoni": {
      "name": "Andoni Auzmendi"
    },
    "andrei-taranu": {
      "name": "Andrei (Alex) Taranu",
      "linkedin": "https://www.linkedin.com/in/andrei-alex-taranu/"
    },
    "andrew-baxter": {
      "name": "Andrew Baxter"
    },
    "andrew-melck": {
      "name": "Andrew Melck"
    },
    "antoine-crochet-damais": {
      "name": "Antoine Crochet Damais"
    },
    "augustin-delaporte": {
      "name": "Augustin Delaporte",
      "linkedin": "https://www.linkedin.com/in/augustindelaporte/"
    },
    "branislav-bujisic": {
      "name": "Branislav Bujisic"
    },
    "carl-smith": {
      "name": "Carl Smith"
    },
    "caroline-leroy": {
      "name": "Caroline Leroy"
    },
    "cati-mayer": {
      "name": "Cati Mayer"
    },
    "catplat": {
      "name": "C Trinkwon"
    },
    "ceelolulu": {
      "name": "Celeste van der Watt"
    },
    "chadwcarlson": {
      "name": "Chad Carlson",
      "github": "chadwcarlson",
      "linkedin": "https://www.linkedin.com/in/chadwcarlson"
    },
    "chris-ward": {
      "name": "Chris Ward"
    },
    "chris-yates": {
      "name": "Chris Yates"
    },
    "christian-sieber": {
      "name": "Christian Sieber"
    },
    "christopher-lockheardt": {
      "name": "Christopher Lockheardt"
    },
    "christopher-skene": {
      "name": "Christopher Skene"
    },
    "chuck-morgan": {
      "name": "Chuck Morgan"
    },
    "corey-dockendorf": {
      "name": "Corey Dockendorf"
    },
    "crell": {
      "name": "Crell"
    },
    "damz": {
      "name": "Damz"
    },
    "dan-morrison": {
      "name": "Dan Morrison"
    },
    "davidbonachera": {
      "name": "David Bonachera",
      "github": "davidbonachera",
      "linkedin": "https://www.linkedin.com/in/davidbonachera"
    },
    "dereliahmet1": {
      "name": "Ahmet Faruk Dereli"
    },
    "devicezero": {
      "name": "Jonas Kröger",
      "github": "devicezero",
      "linkedin": "https://www.linkedin.com/in/jonaskroeger/"
    },
    "doug-goldberg": {
      "name": "Doug Goldberg"
    },
    "duncan-naves": {
      "name": "Duncan Naves",
      "github": "duncannaves",
      "linkedin": "https://www.linkedin.com/in/duncan-naves-a94423aa"
    },
    "erika-bustamante": {
      "name": "Erika Bustamante"
    },
    "fabpot": {
      "name": "Fabien Potencier"
    },
    "flovntp": {
      "name": "Florent Huck",
      "github": "flovntp",
      "linkedin": "https://www.linkedin.com/in/florenthuck"
    },
    "fred-plais": {
      "name": "Fred Plais"
    },
    "gauthier-garnier": {
      "name": "Gauthier Garnier"
    },
    "gilzow": {
      "name": "Paul Gilzow"
    },
    "gmoigneu": {
      "name": "Guillaume Moigneu",
      "github": "gmoigneu",
      "linkedin": "https://www.linkedin.com/in/guillaumemoigneu/"
    },
    "gregqualls": {
      "name": "Greg Qualls"
    },
    "guguss": {
      "name": "Augustin Delaporte"
    },
    "haylee-millar": {
      "name": "Haylee Millar"
    },
    "ivana-kotur": {
      "name": "Ivana Kotur"
    },
    "jackrabbithanna": {
      "name": "Mark Hanna"
    },
    "jared-wright": {
      "name": "Jared Wright",
      "github": "jww-sh",
      "linkedin": "https://www.linkedin.com/in/jaredwaynewright"
    },
    "jessica-orozco": {
      "name": "Jessica Orozco"
    },
    "joey-stanford": {
      "name": "Joey Stanford"
    },
    "john-grubb": {
      "name": "John Grubb"
    },
    "jonas-kruger": {
      "name": "Jonas Kruger"
    },
    "kathryn-frazer": {
      "name": "Kathryn Frazer"
    },
    "kemiojo": {
      "name": "Kemi Elizabeth Ojogbede"
    },
    "kieronsambrook-smith": {
      "name": "Kieronsambrook Smith"
    },
    "laurent-arnoud": {
      "name": "Laurent Arnoud"
    },
    "letoya-boyne": {
      "name": "Letoya Boyne"
    },
    "lolautruche": {
      "name": "Jérôme Vieilledent"
    },
    "lyly-lepinay": {
      "name": "Lyly Lepinay"
    },
    "manauwar-alam": {
      "name": "Manauwar Alam"
    },
    "marc-antoine-porri": {
      "name": "Marc Antoine Porri"
    },
    "maria-antinkaapo": {
      "name": "Maria Antinkaapo"
    },
    "maria-de-anton": {
      "name": "Maria De Anton"
    },
    "mark-dorison": {
      "name": "Mark Dorison"
    },
    "markus-hausammann": {
      "name": "Markus Hausammann"
    },
    "mary-thomas": {
      "name": "Mary Thomas"
    },
    "mathias-bolt-lesniak": {
      "name": "Mathias Bolt Lesniak"
    },
    "mathieu-strauch": {
      "name": "Mathieu Strauch"
    },
    "matthias-van-woensel": {
      "name": "Matthias Van Woensel",
      "linkedin": "https://www.linkedin.com/in/matthias-van-woensel-267a069"
    },
    "michael-sharp": {
      "name": "Michael Sharp"
    },
    "mupsi": {
      "name": "Marine Gandy"
    },
    "natalie-harper": {
      "name": "Natalie Harper"
    },
    "ngommenginger": {
      "name": "Nicolas Gommenginger",
      "linkedin": "https://www.linkedin.com/in/nicolas-gommenginger"
    },
    "nicholas-bennison": {
      "name": "Nicholas Bennison"
    },
    "nicholas-vahalik": {
      "name": "Nicholas Vahalik"
    },
    "nick-hardiman": {
      "name": "Nick Hardiman"
    },
    "nickanderegg": {
      "name": "Nickanderegg"
    },
    "nicolas-grekas": {
      "name": "Nicolas Grekas",
      "github": "nicolas-grekas",
      "linkedin": "https://www.linkedin.com/in/nicolasgrekas/"
    },
    "niti-malwade": {
      "name": "Niti Malwade"
    },
    "opensocialteam": {
      "name": "Opensocialteam"
    },
    "ori-pekelman": {
      "name": "Ori Pekelman"
    },
    "otavio-santana": {
      "name": "Otavio Santana"
    },
    "palwandi": {
      "name": "Pawan Alwandi",
      "github": "pawpy",
      "linkedin": "https://www.linkedin.com/in/pawanalwandi"
    },
    "patrick-boest": {
      "name": "Patrick Boest"
    },
    "patrick-dawkins": {
      "name": "Patrick Dawkins",
      "github": "pjcdawkins",
      "linkedin": "https://www.linkedin.com/in/patrickdawkins"
    },
    "patrick-klima": {
      "name": "Patrick Klima"
    },
    "pjcdawkins": {
      "name": "Pjcdawkins"
    },
    "prineet-kaurbhurji": {
      "name": "Prineet Kaurbhurji"
    },
    "quentin-sinig": {
      "name": "Quentin Sinig"
    },
    "ralt": {
      "name": "Florian Margaine",
      "github": "ralt",
      "linkedin": "https://www.linkedin.com/in/florian-margaine-43971136"
    },
    "ramanathanramakrishnamurthy": {
      "name": "Ramanathanramakrishnamurthy"
    },
    "remi-lejeune": {
      "name": "Rémi Lejeune"
    },
    "ribel": {
      "name": "Taras Kruts"
    },
    "robert-douglass": {
      "name": "Robert Douglass"
    },
    "rudy-weber": {
      "name": "Rudy Weber"
    },
    "ryan-hicks": {
      "name": "Ryan Hicks"
    },
    "sabri-helal": {
      "name": "Sabri Helal"
    },
    "savannah-bergeron": {
      "name": "Savannah Bergeron"
    },
    "shannon-vettes": {
      "name": "Shannon Vettes"
    },
    "shawn-ogasawara": {
      "name": "Shawn Ogasawara",
      "linkedin": "https://www.linkedin.com/in/shawn-ogasawara-83a9a0/"
    },
    "shawna-spoor": {
      "name": "Shawna Spoor"
    },
    "shedrack-akintayo": {
      "name": "Shedrack Akintayo"
    },
    "simon-ruggier": {
      "name": "Simon Ruggier"
    },
    "sophie-van-der-kindere": {
      "name": "Sophie Van Der Kindere"
    },
    "stefanos-thampis": {
      "name": "Stefanos Thampis"
    },
    "stephen-weinberg": {
      "name": "Stephen Weinberg"
    },
    "sukhman-virk": {
      "name": "Sukhman Virk"
    },
    "sumaira-nazir": {
      "name": "Sumaira Nazir"
    },
    "sumer": {
      "name": "Sümer Cip"
    },
    "syed-raza": {
      "name": "Syed Raza"
    },
    "tamara-bacchia": {
      "name": "Tamara Bacchia"
    },
    "tara-arnold": {
      "name": "Tara Arnold"
    },
    "theosakamg": {
      "name": "Mickael Gaillard",
      "github": "theosakamg"
    },
    "thomasdiluccio": {
      "name": "Thomas di Luccio"
    },
    "tim-anderson": {
      "name": "Tim Anderson"
    },
    "tom-helmer-hansen": {
      "name": "Tom Helmer Hansen"
    },
    "tylermills": {
      "name": "Tyler Mills"
    },
    "upsun": {
      "name": "Upsun"
    },
    "veronika-tolkachova": {
      "name": "Veronika Tolkachova",
      "linkedin": "https://www.linkedin.com/in/veronika-tolkachova-169167a2"
    },
    "vince-parker": {
      "name": "Vince Parker"
    },
    "vinnie-russo": {
      "name": "Vincenzo Russo"
    },
    "vrobert78": {
      "name": "Vincent Robert",
      "github": "vrobert78",
      "linkedin": "https://www.linkedin.com/in/vincent-robert-498a883"
    },
    "yuriy-babenko": {
      "name": "Yuriy Babenko"
    },
    "yuriy-gerasimov": {
      "name": "Yuriy Gerasimov"
    }
  };
  return <div className="post-meta">
      {(authors.length > 0 || formattedDate) && <div className="post-meta-info">
          {authors.length > 0 && <div className="post-meta-authors">
              {authors.map(slug => {
    const {name, url, avatarUrl} = resolveAuthor(slug);
    const inner = <>
                    {avatarUrl && <img src={avatarUrl} alt={name} className="post-meta-avatar" />}
                    <span className="post-meta-author-name">{name}</span>
                  </>;
    return url ? <a key={slug} href={url} target="_blank" rel="noopener noreferrer" className="post-meta-author">
                    {inner}
                  </a> : <span key={slug} className="post-meta-author">{inner}</span>;
  })}
            </div>}
          {authors.length > 0 && formattedDate && <span className="post-meta-separator" aria-hidden="true">·</span>}
          {formattedDate && <span className="post-meta-date">{formattedDate}</span>}
        </div>}
      {image && <img src={image} alt="" className="post-meta-image" aria-hidden="true" />}
    </div>;
};

<PostMeta data={{ author: ["gmoigneu"], date: "2025-08-12T00:00:00+00:00", image: "/images/posts/insights/why-your-readme-matters-more-than-ai-configuration-files/why-your-readme-matters-more-than-ai-configuration-files.webp" }} />

The `AGENTS.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, `AGENTS.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**.

<Note>Read the specification on [ampcode.com](https://agents.md/)</Note>

## The problem AGENTS.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. `AGENTS.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 AGENTS.md adopters discovered: **the content of a good AGENTS.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 `AGENTS.md`. What they need is for your `README` to actually be good.

## What really belongs in AGENTS.md

If you write a comprehensive `README`, `AGENTS.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 `AGENTS.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 `AGENTS.md`**. Duplicating your `README` content in `AGENTS.md` wastes context window tokens and creates maintenance burden.

## Potential security issues

Security researchers have identified ["Rules File Backdoor"](https://www.pillar.security/blog/new-vulnerability-in-github-copilot-and-cursor-how-hackers-can-weaponize-code-agents) attacks where malicious actors inject hidden instructions into `AGENTS.md` files using Unicode characters and evasion techniques. Since `AGENTS.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 `AGENTS.md` file, the larger your attack surface. Another reason to keep it minimal.

## Why the standards war doesn't matter

`AGENTS.md` now competes with [OpenAI's `AGENTS.md` format](https://agentsmd.net/), 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 `AGENTS.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 `AGENTS.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

`AGENTS.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 `AGENTS.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 `AGENTS.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](https://upsun.com) and see how good documentation combined with powerful deployment tools accelerates development.