AI Agents and Code: Optimize Performance and Costs with AGENTS.md

In the fast-paced world of software development, the integration of Artificial Intelligence (AI) agents is transforming the way we interact with our systems. From automating routine tasks to deep code analysis and assisting in decision-making, AI agents promise unprecedented efficiency. However, for this promise to materialize, it is crucial to establish clear and effective communication between these agents and the complexities of our codebases.

This is where the AGENTS.md file comes into play, a seemingly simple interface that, if managed incorrectly, can become a significant bottleneck. A poorly conceived AGENTS.md not only hinders the performance of AI agents but also inflates operational costs and slows down the development cycle. In a business environment where every millisecond and every euro counts, optimizing this interaction is fundamental for the competitiveness and success of any software project, be it a custom ERP, a SaaS platform, or an automation system.

Addy Osmani, a prominent figure in engineering leadership at Google, offers us invaluable insight into how to strategically approach AGENTS.md management. His knowledge will guide us to transform what could be a source of noise into a powerful tool that boosts efficiency, reduces costs, and improves the quality of our AI agents' interaction with code.

AGENTS.md: Permanent Configuration or List of Pending Improvements?

One of the most common pitfalls when working with AGENTS.md is treating it as a static, immutable configuration file. Addy Osmani warns against the danger of this mindset, suggesting that a more useful mental model is to consider it a "living list of 'codebase smells' you haven't fixed yet," rather than a permanent configuration. This perspective is crucial for understanding the dynamic and evolving nature of a codebase.

When an AI agent interacts with code, it needs context. If AGENTS.md is filled with directives that should be implicit in the code or that have already been resolved, it becomes an obsolete and misleading artifact. Thinking of it as a record of "technical debt" or pending improvement areas allows the file to evolve with the project. Each entry should be a signal to the agent that there is a peculiarity, a non-standard convention, or a "trap" that needs attention, and that ideally, it should be refactored or more inherently documented in the code over time. This fosters a culture of continuous improvement, where the AGENTS.md is not just a manual, but a catalyst for cleaner, more understandable code.

The Danger of Auto-generated AGENTS.md and the Value of Human Content

The temptation to automate the creation of AGENTS.md is strong, especially in large projects. However, Osmani emphasizes that auto-generated AGENTS.md files are counterproductive. Why? Because they duplicate information that AI agents are already capable of discovering themselves through code analysis. This redundancy has two direct and negative consequences for any company: it harms agent performance and increases operational costs.

Every line of duplicated or irrelevant information in an auto-generated AGENTS.md forces the agent to process noise. This consumes unnecessary computational resources (CPU time, memory, API calls), which directly translates into higher economic expenditure and slower agent response times. It's like asking an expert to read an entire book to find a sentence they already know by heart.

In contrast, human-written AGENTS.md files are valuable only when they contain information that agents cannot discover on their own. This includes:

• Tooling gotchas: Unexpected behaviors or specific configurations of development tools that are not evident in the code.
• Non-obvious conventions: Coding or architectural design standards that have been adopted internally and do not follow generic patterns.
• Landmines: Areas of the code with known risks, fragile dependencies, or historical design decisions that could cause problems if modified without caution.
• Historical or business context: Reasons behind certain design decisions that are not reflected in the code structure.

Any other line that does not provide this type of undiscoverable information is, in Osmani's words, "noise." The key is conciseness and relevance, ensuring that each entry in the AGENTS.md adds unique value to the agent's understanding, thereby optimizing its performance and minimizing costs.

Beyond a Single File: The Need for an AGENTS.md Hierarchy

One of the most significant structural challenges in AGENTS.md management is the tendency to consolidate all information into a single file at the root of the repository. For any codebase of real complexity, this approach is insufficient and, in fact, detrimental. A monolithic AGENTS.md conflates concerns from across the entire project, overloading the agent with irrelevant context for the specific task it is performing in a particular module or directory.

What is truly needed, according to Osmani, is a hierarchy of AGENTS.md files. These files should be strategically located at the relevant directory or module level, so that each agent receives context precisely delimited to the code it is working on. Imagine a project with multiple microservices or well-defined modules; each could have its own AGENTS.md detailing its peculiarities.

This hierarchical structure not only improves the relevance of the context but also must be automatically maintained. This implies the implementation of tools or processes that ensure these module-level AGENTS.md files remain updated and reflect the current state of the code. By providing agents with only the information pertinent to their scope of work, several key benefits are achieved:

• Precise context: Agents are not distracted by information from other parts of the system.
• Improved performance: Less noise means faster and more efficient processing.
• Reduced costs: Fewer computational resources are used by avoiding the analysis of irrelevant data.
• Scalability: Context management becomes manageable even in large and increasingly complex projects.

In essence, it's about applying principles of modularity and encapsulation to how AI agents consume information about the code, ensuring that the AGENTS.md is a useful guide and not a labyrinth of data.

Conclusion

Effective management of AGENTS.md files is more than a simple configuration task; it is a fundamental strategy for maximizing the potential of Artificial Intelligence agents in software development. Adopting an AGENTS.md mindset as a living list of improvements, prioritizing human content that provides undiscoverable information, and structuring these files hierarchically are critical steps to optimize performance, reduce costs, and build more robust and efficient systems.

In the era of AI, how our agents understand and navigate our code can be the key differentiator between a project that thrives and one that stagnates. Reflecting on these practices will not only improve interaction with AI but also drive a culture of engineering excellence throughout the organization.

How Vernetica can help you

At Vernetica, we understand that the efficient integration of AI agents and the management of complex codebases are pillars of success in modern software development. As a company specializing in custom software development (ERP, SaaS, automation, BI, IoT), we offer solutions that not only meet your functional requirements but are also designed to be scalable, maintainable, and optimized for interaction with advanced technologies such as AI.

Our team of experts can advise you on implementing software architectures that facilitate hierarchical and efficient information management for your AI agents, as well as on creating automation tools to keep your AGENTS.md files updated. From strategic technology consulting to the development and integration of customized systems, we help you transform your code challenges into competitive advantages, ensuring that your AI agents operate with maximum efficiency and at the lowest possible cost.