Recently, I kicked off a project for the engineering group I’m part of, and I’d like to share it with everyone subscribed to this newsletter. This is a real-life case.
My goal?
Improve the interaction with the AI Agents when we code with them.
Having AGENTS.md files for AI agents will save you a lot of back-and-forth when interacting with your code assistant while implementing software.
Back-and-forth means time, and saving time means you’ll save tokens, which means you’ll save money.
In today’s email, I’ll explain what AGENTS.md files are (it’s a relatively new thing), how they’re structured, and the best practices for creating effective AGENTS.md files.
🎁 But before we dive in, I have a little gift for you.
If you’re subscribed to this newsletter before ✨October 27th✨, you’ll receive, for free, a perfectly polished prompt that lets your favorite AI agent generate those AGENTS.md files for you. Subscribe now 👇🏻
I’ll send the email with the prompt on October 27th; don’t miss it!
If you know someone who might be interested in the topic of AGENTS.md files and the prompt, forward this email or hit the share button 👇🏻
Alright, let’s get to the good stuff.
💡 What is an AGENTS.md file and what is it for?
In one sentence: It’s the README.md for AI agents.
AGENTS.md is a Markdown file designed for AI coding agents. Its purpose is to provide clear context and precise instructions to help AI tools understand and work effectively with your project’s code.
Unlike a traditional README (which targets developers or users), AGENTS.md contains detailed information about build processes, testing, style, and code conventions, everything that helps AI agents follow your project’s rules correctly.
Tools like GitHub Copilot, Cursor, Windsurf, or Claude Code can rely on this file when generating code or answers, so their output better fits your project’s specific needs.
You just have to create a file named AGENTS.md in the root of your working directory, and the AI Agent will find it.
Now that we know what AGENTS.md files are and why they’re useful, let me show you the structure that’s been working well for me so far.
🏛️ AGENTS.md File Structure
An AGENTS.md file is organized into different Markdown sections. Each section should cover the essentials that the AI agent needs to know. For me, that includes:
Overview
A short description of the project and its general purpose. The role of AI agents in it. General architectural context.
Setup / Build & Test
Exact commands to install dependencies, build, and run tests. For example: npm install, npm test, etc. I also include the frameworks and technologies used in the project.
Code Style / Conventions
Formatting rules, design patterns, and linters. Indicate the language(s) (e.g., strict TypeScript), quote style, line length, etc. (For example: “use single quotes, no semicolons, tabs instead of spaces” 😱). Here, I also explain the engineering patterns I want to use, like Hexagonal Architecture, DDD, etc.
Testing
Details about automated tests: how to run them, which frameworks are used, minimum coverage, etc. Include precise test commands (in code blocks) so the agent can copy them directly.
Workflow (Git/PR)
Branching strategy, commit message conventions, pull request requirements.
For example: “All Pull Requests must follow Conventional Commit and include the Jira ID, e.g. feat(IT-6969): Short and meaningful description of the change.”
Security
Sensitive environment variables, API keys, access limits, and security considerations. Include links to credential documentation.
Give it a try and tell me how it goes 👇🏻
🎯 Best Practices for AGENTS.md Files
Based on my experience, here are 4 key points to keep in mind when creating AGENTS.md files for AI agents:
Brevity & Clarity
Keep it concise (ideally ≲150 lines) so the agent stays on track.
Use Markdown headers and bullet lists to organize information.
Start each section with a clear title and use code blocks for commands.
Avoid redundant or overly detailed text, and include only what your future self (or an agent) will actually need.
Precise Commands
Write commands exactly as they should be executed.
Wrap them in backticks so the agent can copy them directly. For example, instead of writing “install dependencies,” specify
npm installor similar.
Continuous Updates
Treat
AGENTS.mdas part of your codebase. Whenever the build process, tests, or conventions change, update the file in the same pull request.Heads up! Reviewers should also check the quality of this file!
Single Source of Truth
Avoid duplicating information that already exists elsewhere (README, wikis, etc.). Instead, link to those resources. This keeps
AGENTS.mdfocused, consistent, and less prone to inconsistencies.Keep only the critical information for the agents, and link to existing technical or project docs when necessary.
Once your AI agent has access to AGENTS.md, here’s something to remember:
When you ask it to do something, like “Write a function that does X”:
The clearer and more precise the info in your
AGENTS.mdabout your project’s context and conventions…The better aligned the results will be.
So, when you write to your AI agent, keep in mind the instructions you already wrote in the file.
🎁 Don’t forget the gift!
Remember: if you’re subscribed to this newsletter before ✨October 27th✨, you’ll get a perfectly refined prompt that helps your favorite AI agent generate AGENTS.md files automatically, for free. Subscribe now 👇🏻
I’ll send it out on October 27th, don’t miss it!
If you know someone who might be interested in the topic of AGENTS.md and the prompt, forward this email or hit the share button 👇🏻
See you in the next one!