AGENTS.md Is Now the One File Your Repo Actually Needs — And the Research Is More Complicated Than the Marketing
AGENTS.md Is Now the One File Your Repo Actually Needs — And the Research Is More Complicated Than the Marketing
Somewhere in the last three months, AGENTS.md quietly stopped being a niche convention and became the new standard configuration file for AI coding tools.
If you haven't seen it yet: AGENTS.md is a Markdown file at the root of your repo that gives AI coding agents project-specific context — build commands, conventions, test rules, things they can't infer from the codebase alone. Think of it as the README, except it's written for an agent instead of a human.
What changed recently is governance. AGENTS.md is now stewarded by the Agentic AI Foundation, under the Linux Foundation. The format is supported across OpenAI Codex, Cursor, Windsurf, Amp, Factory, Jules (Google), and Kilo. Next.js 16.2 now ships an AGENTS.md in create-next-app by default. When a standard gets picked up by every vendor in a space and then formalized under a neutral foundation, that's usually when it becomes a default you stop thinking about.
Which makes the contrarian research that came out of InfoQ last month more interesting, not less. The short version: AGENTS.md doesn't help as much as the vendors claim. And if you're going to spend time on this, you should understand when it earns its keep and when it's just cargo cult.
What AGENTS.md Actually Is
Format is deliberately simple. It's just Markdown, placed at ./AGENTS.md in your repo root. You can also place additional AGENTS.md files in subdirectories — agents read the nearest one in the directory tree first. For monorepos or projects with multiple services, this "nearest file wins" behavior is where the format quietly gets powerful.
The content is whatever helps the agent work on your project. The canonical structure (not required, but common) covers:
- Build and run commands. How to install deps, run the dev server, build for production, run tests.
- Coding conventions. Naming, file organization, style preferences that aren't enforced by a linter.
- Testing rules. What framework, what commands, what to run before claiming a change works.
- No-touch zones. Files or directories the agent should not modify.
- Environment context. What runtime, what versions, what package manager.
The pitch is: you write this once, and every compatible agent — regardless of vendor — gets enough context to do useful work without you having to re-explain your project every session.
The Research That Complicates the Story
In March, InfoQ covered a reassessment of AGENTS.md effectiveness that should have gotten more attention than it did. The research looked at whether AGENTS.md files actually improved agent performance on real tasks, versus just making agents appear to behave better.
The findings were mixed. AGENTS.md helped a lot in some cases — particularly for unusual build systems, project-specific conventions, and test runners that don't match common defaults. In other cases, the impact was negligible or even slightly negative — the agent would fixate on explicit instructions and miss more natural cues from the codebase itself.
The pattern the research suggests: AGENTS.md is most useful when your project has genuine non-obvious context. It's least useful when your project looks like every other project the agent has seen during training.
For solo operators, this is actually the important insight. If you're running a standard Astro or Next.js or Rails setup with sensible defaults, your AGENTS.md is mostly a waste of tokens. The agent already knows how to build and run an Astro project; repeating it is noise. If you're running something weird — a custom monorepo structure, a nonstandard test harness, a deploy process with specific preconditions — that's where the file pays for itself.
What Actually Belongs In One for a Solo Project
Here's a concrete example for a project like this blog (Astro 5 + Keystatic + Vercel deploy). I'll show the full file, then explain what I kept and what I cut.
# AGENTS.md ## Project Astro 5 blog with Keystatic CMS. Content lives in `src/content/posts/*/index.mdoc`. Deployed to Vercel via the Vercel adapter. ## Commands - Install: `npm install` - Dev: `npm run dev` (runs on http://localhost:4321) - Build: `npm run build` - Preview production build: `npm run preview` ## Content Model Posts are Keystatic collections. Each post is its own directory: `src/content/posts/<slug>/index.mdoc`. Frontmatter schema is in `keystatic.config.ts`. Required fields: title, excerpt, publishedDate, draft, tags. Tags are restricted to: ai, stack, building-in-public, tools, lessons. ## Conventions - Prose uses em-dashes (—), not double hyphens. - Headings use sentence case for H2/H3, title case for H1. - Code blocks get language hints. - No emoji in titles or headings. ## Do Not Touch - `dist/` — build output - `.vercel/` — deploy artifacts - `node_modules/` — obviously ## Testing No unit tests. Validation is "build completes + pages render at localhost:4321".
What I kept: the build commands (Astro dev server port is not obvious), the content model (a Keystatic collection with multi-file structure is the thing an agent would get wrong), the tag restriction (agents love inventing new tags), the em-dash convention (models default to double hyphens and it's annoying).
What I cut from my first draft: a long section about design philosophy, a list of my personal writing preferences, a paragraph about why I chose Astro. None of that affects how an agent does the work. It's just me wanting to explain myself to the computer. Waste of tokens.
The rule I use: if an instruction doesn't change what the agent actually does, it doesn't belong in AGENTS.md.
When It Earns Its Keep
Three scenarios where I've noticed a real difference:
Non-obvious build steps. I have a project that uses a pre-build script to generate types from a remote schema. Without AGENTS.md, the agent would skip that step and then wonder why TypeScript was exploding. With one line in AGENTS.md, problem solved. Payoff: significant.
Monorepo subdirectories. In a monorepo with 4 services, I put an AGENTS.md in each service directory with the commands and conventions specific to that service. The nearest-file-wins behavior means the agent never gets confused about which service it's working in. Payoff: significant, and this is the use case that's underhyped.
Writing-heavy projects. For this blog, the tag restriction and em-dash convention genuinely save me from having to correct the agent every time. Not a huge effect, but consistent. Payoff: modest but real.
When It Doesn't
Three scenarios where I've stopped bothering:
Vanilla starter templates. If you create-next-app and deploy to Vercel, your AGENTS.md is probably going to say "it's a Next.js app, run npm run dev." The agent already knows. Skip it.
Projects with great READMEs. If your README already covers commands and conventions, duplicating them into AGENTS.md is overhead. Modern agents read README.md. If anything, I'd rather the agent read the human-facing README than a parallel agent-facing document that can drift out of sync.
Small throwaway projects. If it's a 200-line script, the codebase is shorter than your AGENTS.md would be. The agent can just read the code.
The Standards Question
One piece of this I'm still working out: does the cross-vendor nature actually matter for a solo operator?
In theory, yes. Write it once, it works with whatever agent you're using this quarter. Cursor today, Claude Code tomorrow, Codex next week. No lock-in.
In practice, I notice I write slightly different AGENTS.md files for different agents anyway. Claude Code responds better to more prose, more explanation of intent. Cursor prefers terse bullet lists. Codex is somewhere in between. The "write once, run anywhere" pitch is partially true — the file is compatible, but the optimal content still varies.
Still, the floor of "this file will at least be read by every major agent" is useful. It means when I try a new tool, I'm starting from context, not zero.
The Honest Take
AGENTS.md is worth writing if your project has real context that doesn't live in the codebase. That's more common than people think — pre-build steps, specific test commands, non-obvious deploy processes, conventions that aren't enforced by tooling.
It's not worth writing as a ritual. A bad AGENTS.md (or an out-of-date one, or one that just duplicates your README) is worse than nothing, because it confuses the agent and creates overhead to maintain.
The vendors will tell you every repo needs one. The research suggests it depends. The solo-operator version of "it depends" is: write one if you notice the agent consistently getting something wrong that a one-paragraph explanation would fix. Don't write one as a matter of hygiene. The best AGENTS.md is the shortest one that still captures the specific things the agent would miss.
And once you have one, treat it like any other config file — version it, update it when conventions change, delete the parts that drift. It's code now, not documentation. Maintain it accordingly.