How I Write My AGENTS.md Files - Best Practices

Agents MD: A Comprehensive Guide to Guiding AI Coding Agents

Key Concepts:

• Agents MD: An open, vendor-agnostic format (Markdown file) for providing instructions and context to AI coding agents.
• Vendor Agnostic: The ability to work with various AI agent tools (Cursor, Claw Code, Windsurf, Client, etc.) without modification.
• Type Hints: Annotations in code that specify the expected data types of variables, function arguments, and return values (e.g., def calculate_sum(a: int, b: int) -> int:).
• Camel Case: A naming convention where words are concatenated without spaces, and each word (except the first) is capitalized (e.g., lucasNumber).
• UV: A fast, modern package manager for Python, alternative to pip.
• Granular Rules: Applying specific Agents MD files to particular directories within a project for tailored instructions.

Introduction to Agents MD

The video introduces Agents MD as an open format designed to guide AI coding agents, regardless of the specific tool being used. Unlike vendor-specific solutions like Cursor Rules, Claude MD, or Gemini MD, Agents MD is universally compatible. The primary goal is to provide consistent instructions and context to agents, improving code quality and adherence to project standards. The presenter aims to both introduce Agents MD to newcomers and demonstrate best practices for experienced users.

Demonstrating the Impact: A Django Application Example

A simple Django application, named "sample project," is used to illustrate the benefits of Agents MD. This application features basic mathematical functions, including calculating the nth Fibonacci number and exporting results to PDF. The presenter highlights that without Agents MD, the AI agent operates without awareness of project-specific coding styles or environment configurations.

A key point is made regarding the importance of type hints. The initial attempt to implement a Lucas number function using Sonnet 4.5, with only the utils.py file provided as context, resulted in code lacking type hints – despite the existing functions potentially benefiting from them. This demonstrates the agent's reliance on the provided context and its inability to infer project preferences.

Implementing Instructions with Agents MD

The core demonstration involves creating an agents.md file in the project's root directory. A simple instruction – "instructions always no matter what use type hints especially in utils py files" – is added. Crucially, this file is not explicitly passed as context to the agent during the subsequent function implementation request. However, because the file is named agents.md, the agent automatically recognizes and incorporates its instructions. The resulting Lucas number function now includes type hints, even though the original code lacked them and the prompt didn't request them.

Quote: "So, you can see already here just by instructing the model in agents to use type hinting, it used type hinting even though none of the other functions here do that and I didn't specify this in the prompt."

This highlights the power of Agents MD to enforce coding standards consistently without repetitive prompting.

Combining and Overriding Rules with Granular Agents MD Files

The video demonstrates the ability to combine multiple Agents MD files and override rules at a directory level. A second rule is added to the root agents.md file: "second rule always no matter what use camel case when defining functions." The agent successfully implements the Lucas number function using camel case naming.

To illustrate granular control, a new agents.md file is created within the mathematics directory. This file instructs the agent to never use type hints in that specific directory, overriding the global rule. The agent then correctly implements the Lucas number function using camel case but without type hints, demonstrating the hierarchical rule application.

Best Practices for Effective Agents MD Files

The presenter outlines several best practices for creating effective Agents MD files, drawing from external resources and personal experience:

1. Commands Early: Place commands (e.g., uv run) at the beginning of the file to ensure they are prioritized.
2. Examples Over Explanations: Instead of lengthy explanations of coding styles, provide clear examples of correct and incorrect code.
   Quote: "It doesn't make a lot of sense to explain to the agent what exactly the coding style is composed of… It makes much more sense to show bad example and corrected example."
3. Specific Stack & Versions: Clearly specify the project's technology stack and version numbers (e.g., Python 3.12, UV package manager).
4. Project Structure: Include a file tree or project structure diagram to provide the agent with a clear understanding of the codebase organization. This can be generated using the tree command in the terminal.
5. Ground Rules & Boundaries: Define clear boundaries for the agent's actions, such as prohibiting the use of rm or Git commands to enhance security. However, acknowledge that these boundaries are not foolproof and the agent may override them if directly instructed.

Use Cases and Applications

The presenter suggests several practical use cases for Agents MD:

• Docker & UV Setups: Ensuring consistent environment configurations.
• Tailwind & Vit Integration: Guiding the agent through complex installation processes.
• Testing & Contribution Guidelines: Providing instructions for running tests and contributing to the project.
• Enforcing Coding Standards: Maintaining consistent code style and quality across the project.

Conclusion

Agents MD provides a powerful and flexible way to guide AI coding agents, promoting consistency, reducing errors, and improving code quality. By leveraging its vendor-agnostic nature and adhering to best practices, developers can significantly enhance their AI-assisted coding workflows. The key takeaway is that Agents MD is a central repository for project-specific instructions, eliminating the need for repetitive prompting and ensuring that agents operate within defined boundaries and coding standards.