AGENTS.MD: The File That Will Stop Your AI From Messing Up When Coding

The problem we all have (and nobody talks about)

Surely it has happened to you: you are programming, you ask your favorite AI for help and… it spits out code that looks like it was written by someone who doesn’t know your project. Comments everywhere when you don’t want them, weird method naming, obsolete dependencies that haven’t been used since 2019, and a lot of little things that make you think “I have to fix this myself, right?”.

And of course, every time you ask for something new, back to square one: “hey, no comments”, “use camelCase”, “I prefer using this library instead of that other one”. It’s exhausting.

Well friends, this is over. Today I bring you AGENTS.MD, a simple file that is going to revolutionize the way you code with AI.

Why you need AGENTS.MD in your life

Relying on artificial intelligence to program is no longer science fiction, it is a reality. But if we are going to do it, let’s do it right. It’s not enough to ask a chat little things or use your editor with AI and cross your fingers.

To be truly efficient we need to apply the new methodologies that are coming out (and yes, I know that in programming everything changes every two days, but that’s what I’m here for, to bring you what’s important).

In previous posts I have talked about MCPs and how to squeeze the most out of Cursor. But what I bring you today is better than tricks for a specific editor. For me, this is something basic that is going to become the industry standard.

PS: Before continuing, if you see these posts and you are not subscribed… what are you doing with your life? Hit the button, it costs nothing and it makes me very happy 😊

What on earth is AGENTS.MD?

The premise is extremely simple: AGENTS.MD is like a README but for artificial intelligences. Basically, it is a file where you define your project instructions so that the AI knows exactly what to do.

In this file you can specify:

How to start the project
How to run tests
What dependencies to use (and which ones NOT to use)
Your preferred coding style
Naming conventions
Comment policy
Folder structure

It is like a bible for the AI. Once it reads it, you no longer have to repeat the same indications over and over again.

”But this already exists…”

Okay, it’s true. Many editors have their own rules:

Cursor calls it “rules”
Jules (the JetBrains assistant) has “guidelines”
Warp uses warp.md for project rules

The difference is that AGENTS.MD does not marry you to any editor. It is an “international” convention that any agent can read.

Who supports AGENTS.MD?

The list grows every day, but for now it is supported by:

Codex
Cursor
Visual Studio Code
Warp (an AI terminal that I recommend)
Gemini CLI
Devin
And many more…

Probably when you are reading this, the list will be even longer.

The advantage over classic rules

Here is the key: today you may be using Cursor, but tomorrow maybe Gemini CLI is better, or Codex, or whatever comes out next week. With AGENTS.MD you don’t have to change anything, the new editor will automatically detect your rules.

And this is important. You already know that I don’t like to always depend on the same tool because things change very quickly in this world.

How does it work?

Nothing out of this world. It is a free text file where you indicate the requirements you want for your project. There is no specific format, no minimum or maximum. Simply put what you think is useful.

There are more than 20,000 examples on the internet depending on your project, language and technologies, but my advice is that you create it yourself with the things you really need for your specific case.

An example that will leave you open-mouthed

To show you the difference, I did a quick test. I asked the AI to create an API with Python. Without AGENTS.MD it generated this:

# Basic API without structure
from flask import Flask

app = Flask(__name__)

@app.route('/api/data')
def get_data():
    # Unnecessary comments
    return {"data": "example"}

Now, I created an AGENTS.MD specifying:

The structure I want
That all calls have authentication
The specific naming of the methods
No obvious comments

With the same prompt, the difference was brutal. It generated a completely structured API, with JWT authentication, following my conventions and without a single unnecessary comment.

The importance of instructions, friends.

Recommended structure (but not mandatory)

Although there is no mandatory structure, here is an example that you can adapt:

# AGENTS.md

## Project Context
- Language/runtime: Python 3.11 / Node 20
- How to run locally: `npm run dev` or `python main.py`
- How to run tests: `npm test` or `pytest`

## Code Style
- Naming: camelCase for variables, PascalCase for classes
- NO obvious comments, only necessary documentation
- Formatting: Prettier/Black depending on language
- Prefer composition over inheritance
- Use async/await when possible

## Dependencies
- Allowed: fastapi, pydantic, sqlalchemy (latest versions)
- AVOID: Flask (legacy), requests (use httpx)

## Testing & Quality
- Framework: pytest with minimum 80% coverage
- Mandatory unit tests for business logic
- Lint with ruff/eslint before commit

## API & Security
- Auth required by default (JWT)
- Error responses: Standard JSON with appropriate status codes
- Logging: structured logging with context

## Git & CI
- Conventional Commits mandatory
- CI must pass tests and lint before merge
- No direct commits to main

IMPORTANT: Do not put keys or secrets in here, please. It is common sense but it never hurts to remember it.

The future is now

If you are as lazy as I am (which you are, let’s not fool ourselves) and you don’t want to waste time explaining the same thing to the AI every time, this is the solution.

Just like it happened with MCPs, this will probably become an industry standard. Those of us who adapt soon will have an advantage.

Conclusion

AGENTS.MD is not magic, it is simply organization and intelligence. It is taking advantage of technology correctly to avoid doing the same work twice.

Implement it in your projects, adapt it to your needs and, above all, share your experience. If you liked the post, leave it in the comments and tell me what other topics you want me to cover.

And remember: in the programming world, either you adapt or you get left behind. Better to adapt, right?

See you in the next post 👋

What do you think?

Leave your opinion, question or suggestion. Comments are synced with GitHub Discussions .