Hand-written AGENTS.md files offer a modest improvement in AI coding performance, but AI-generated files can degrade performance and increase costs.
Imagine having to explain your company’s complex coding standards and testing protocols to every new hire from scratch every single day. Walking into the office and repeating, “For our project, name your variables this way,” or “Use this specific library for testing,” is an exhausting and unproductive task.
Recently, developers have been buzzing about a “secret sauce” file for AI coding tools: AGENTS.md. Does this file truly make our coding AI smarter?
Why is this important?
As AI coding agents become mainstream, many developers are looking for ways to extract better code quality. AGENTS.md helps inject project-specific preferences and rules into the AI, ensuring they persist throughout the entire coding session. Source: Improve Your AI Assisted Coding With AGENTS.md by Lance Cleveland ∥ Real-World AI Authority When utilized effectively, this file allows developers to maintain consistent code quality without having to explain project context to the AI every time. Source: How to teach your coding agent with AGENTS.md
In simple terms
You can think of AGENTS.md as a “project guidebook.”
To use an analogy, it’s like hiring a chef. Rather than simply saying, “Make me something delicious,” you hand them a detailed note covering your household’s preference for low-sodium meals, a list of forbidden spices, and specific instructions on how to clean the sink after cooking. By having the AI coding agent automatically pull this file into the prompt at the start of a task, the AI gains a clear understanding of what coding style to adopt and which rules to strictly follow. Source: My agent.md to improve LLM-assisted code quality
| However, there is a catch. Just like training a “smart chef,” this file only works if it is crafted meticulously by a human. According to recent benchmark evaluations conducted by researchers at ETH Zurich, hand-written context files provided an average performance boost of 4%. Source: Does AGENTS.md Actually Help Coding Agents? A New Study Has … While not a massive leap, it represents a tangible increase in efficiency that daily coders cannot ignore. [Source: Evaluating AGENTS.md: are they helpful for coding agents? | Hacker News](https://news.ycombinator.com/item?id=47034087) |
Current state of affairs
Unfortunately, a common mistake many developers make is assuming, “The AI is smart, so why not just ask the AI to write my AGENTS.md for me?” The research results showed the exact opposite. Using an AI-generated context file can actually degrade agent performance by 2% to 3%. Source: Controlling Claude Code & Coding Agent Behavior with AGENTS … It is the equivalent of giving a chef a note with incorrect recipes, causing the AI to learn flawed rules.
Furthermore, you cannot overlook the financial impact. Utilizing context files like AGENTS.md increases the cost of using AI coding agents by at least 20%. Source: Does AGENTS.md Actually Help Coding Agents? A New Study Has … Since the file is included in every prompt sent to the model, you are effectively paying more for the increased data usage. [Source: Evaluating AGENTS.md: are they helpful for coding agents? |
Hacker News](https://news.ycombinator.com/item?id=47034087) |
Future outlook
Experts emphasize that these files are not magic wands; they are precision-tuning tools that require developer effort. Some critics argue that AGENTS.md is merely redundant abstraction, suggesting that standard documentation practices are sufficient if AI tools can correctly reference project documents. Source: My agent.md to improve LLM-assisted code quality
In conclusion, if you want improved performance, don’t leave it to the AI. Invest the time to create your own AGENTS.md, detailing your project’s core rules, testing styles, and tool usage. Source: How to teach your coding agent with AGENTS.md Although the structure requires paying 20% more for a 4% performance gain, it is an investment worth considering for environments where productivity and code quality are the top priorities. [Source: Evaluating AGENTS.md: are they helpful for coding agents? |
Hacker News](https://news.ycombinator.com/item?id=47034087) |
MindTickleBytes AI Reporter’s Perspective
The era of AI agents doing our coding is here, but providing “good questions and clear rules” remains the responsibility of the human developer. Instead of relying blindly on tools, the true skill lies in figuring out how to communicate the project’s philosophy to the AI.
References
- My agent.md to improve LLM-assisted code quality
- Improve Your AI Assisted Coding With AGENTS.md by Lance Cleveland ∥ Real-World AI Authority
- How to teach your coding agent with AGENTS.md
-
[Evaluating AGENTS.md: are they helpful for coding agents? Hacker News](https://news.ycombinator.com/item?id=47034087) -
[How to Build Your AGENTS.md (2026): The Context File That Makes AI Coding Agents Actually Work Augment Code](https://www.augmentcode.com/guides/how-to-build-agents-md) -
[Stop Getting Average Code from Your LLM Krzysztof Zabłocki](https://merowing.info/posts/stop-getting-average-code-from-your-llm/) - New Research Reassesses the Value of AGENTS.md Files for AI Coding - InfoQ
-
[My agent.md to improve LLM-assisted code quality Hacker News](https://news.ycombinator.com/item?id=49410932) - What AGENTS.md Actually Does to Your Coding Agent
- Does AGENTS.md Actually Help Coding Agents? A New Study Has …
- Controlling Claude Code & Coding Agent Behavior with AGENTS …
- My agent.md to improve LLM-assisted code quality
- How to write a great agents.md: Lessons from over 2,500 …
- [2511.04427] Speed at the Cost of Quality: How Cursor AI …What AGENTS.md Actually Does to Your Coding AgentHow to Build Your AGENTS.md (2026): The Context File That …
- About 4%
- About 20%
- About 50%
- Significantly improves performance
- Has no effect on performance
- Can actually degrade performance
- There is no adoption cost
- Usage costs increase by at least 20%
- AI fees are discounted by 50% upon adoption