- The AI Stack for devs
- Posts
- From README to AGENTS.md: The next big convention
From README to AGENTS.md: The next big convention
The new standard bringing sanity to AI-assisted development
Sanket Gawas
August 29, 2025 • Estimated Reading Time: 6 minutes
Before you jump in, here’s something you’ll love.
I’ve put together a curated list of MCP servers and MCP registries to support your development workflows. When you subscribe to the newsletter, you’ll get instant access to this resource in your welcome email.
Bonus: I’m also working on a collection of free educational resources for building AI agents at every skill level. Coming soon for subscribers. Stay tuned!
This tweet below was doing rounds a couple of weeks back
Bouncing between Claude Code, Cursor, Codex, Copilot and maintaining the context for each agent is a headache. Every tool wants its own special rules file.
This "madness" has finally hit a breaking point. And out of it comes a new standard.
AGENTS.md has emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory.
It’s a simple markdown file, placed at the root of your repo, that gives all the context your AI agents need:
- how to build, test, and deploy
- coding style + naming conventions
- commit message formats
- security guardrails
- performance tips
Instead of scattering this across README.md (for humans) and half a dozen vendor specific configs, AGENTS.md now becomes the single source of truth for coding agents.
The Benefits
-One file for multiple agents
- Consistency across agents
- Less clutter in README.md
- Your repo is instantly usable across Cursor, Aider, Zed, RooCode, OpenAI’s Codex, Google’s Jules and more.
- Faster onboarding where agents spin up with zero configuration
There are already over 25,000 repos on GitHub are already using AGENTS.md as of Aug 2025.
This is all we need now.
This is what it looks like now
Monorepos
AGENTS.md also solves a tricky problem of monorepos.
Put one file at the root, then drop extra AGENTS.md files inside packages or services. Agents read the closest one in the directory tree.
This means your frontend, backend, and infra code can all have tailored instructions without the top-level rules bleeding into everything.
The Claude Problem
There’s one outlier though: Our fan favorite Claude Code.
Anthropic still insists on using CLAUDE.md. That leaves Claude projects a bit stranded outside the new standard.
In the meantime, workarounds exist:
- @AGENTS.md import inside CLAUDE.md
- symbolic links (ln -s AGENTS.md CLAUDE.md)
- session start hooks to auto-load
Until Claude plays ball, devs will keep duct taping.
If you’re not a subscriber, here’s what you missed this month
Subscribe to get access to such posts every week in your email.
👀 Whats shipping (shipped) this week?
Grok Code is now available in Cursor and it's free for one week.
⭐️ Trending open source repos
👓️ Worth reading for Devs
🤠 What you may have missed last month
My Recommendations
Techpresso gives you a daily rundown of what's happening in tech and read by 300,000+ professionals.
The Deep View The go to daily newsletter for 250k+ founders and knowledge workers who want to stay up to date with artificial intelligence.
Looking for more such updates in your inbox? Discover other newsletters that our audience loves to read here