Why Rule Files Are Broken
If you’ve worked with coding agents, you already know the pain: every agent ships with its own rules file format. Cursor has one, Claude Code has another, and yet another format shows up in every new IDE. The result? Your repo turns into a junk drawer of rule files that don’t translate across agents.
The rise of MCP (Model Context Protocol) only added more mess. Developers are left juggling multiple formats and remembering which tool expects what. As one developer on Twitter put it: “This is madness. What are we doing?”
The good news: there’s now a movement to unify all of this under one simple standard — Agents.md.
⸻
What is Agents.md?
Agents.md is an open, markdown-based format for guiding coding agents, now adopted by multiple companies and already appearing in over 20,000 open-source projects (based on GitHub searches).
Think of it like this:
• README.md → designed for humans.
• Agents.md → designed for coding agents.
Instead of explaining the project to contributors, it explains the project to AI. Things like:
• How to set up the environment.
• Which tests to run.
• Code style & formatting rules.
• Security considerations.
• Deployment steps.
• Any “gotchas” you’d tell a new teammate.
This way, every agent (Cursor, OpenAI’s Code models, Factory, Jules from Google, Rodeo, etc.) can parse the same file rather than requiring proprietary configs.
⸻
Example Structure
A typical agents.md at your repo root might look like this:
# Project Overview
This is a Python web app using FastAPI and PostgreSQL.
# Setup
- Create a virtual environment: `python -m venv .venv`
- Activate and install dependencies: `pip install -r requirements.txt`
# Build & Test
- Run tests: `pytest tests/`
- Start app: `uvicorn app.main:app --reload`
# Code Style
- Follow PEP8.
- Use Black for formatting: `black .`
# Security Considerations
- Never commit `.env` files.
- Sanitize all user input.
Monorepos / Nested Projects
For large repos, you can add agents.md files in subdirectories. Agents will always use the closest file to the code being edited — similar to how .gitignore or eslint configs work.
⸻
How to Migrate
Migration is intentionally simple:
• If you already have cursor.rules, claude.md, cloud.md, etc., just rename them to agents.md.
• Place them in the repo root, or inside subfolders if context needs to be scoped.
• Agents that support the standard will automatically pick it up.
Over time, this should replace the fractured mess of competing config formats.
⸻
Who’s On Board (and Who’s Missing)
So far, the companies/projects embracing Agents.md include:
• OpenAI (Code)
• AMP Code
• Google’s Jules
• Cursor
• Factory AI
• Rodeo (open-source project)
Notably missing: Anthropic’s Claude Code (still using claude.md) and Gemini CLI (currently gemini.md). Adoption from them would make this truly universal.
⸻
Why It Matters
Standardization matters because:
• You don’t have to relearn formats per-agent.
• Open-source projects can be agent-ready out of the box.
• Agents can execute tests & fixes automatically based on your file.
• Devs can focus on writing code, not wrangling instructions.
It’s the same reason we all use robots.txt, README.md, and package.json — predictable, simple, and shared across tools.
⸻
Final Thoughts
Standards only succeed if developers adopt them. MCP showed us it’s possible. Agents.md could be the same for coding agents — a single, shared language for instructing AI collaborators.
If you’re building with agents today, add an agents.md file to your repo. It’ll make life easier not just for you, but for every developer (and every coding agent) that touches your project.
👉 More info: agents.md
Top comments (0)