Writing a Good AGENTS.md

2026-02-24 · Source: philschmid.de - RSS feed · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering · Depth: Intermediate, quick

Summary

An `AGENTS.md` or `GEMINI.md` file serves as a critical configuration point for coding agents, injected into every conversation to onboard the agent to a codebase. Research from "Evaluating AGENTS.md" (ETH Zurich, 2025) and practical experience from HumanLayer indicate that poorly configured `AGENTS.md` files actively degrade performance. Auto-generated files reduce task success rates by approximately 3% and increase inference costs by over 20%, while human-written files offer only marginal improvements of about 4% but still raise costs by up to 19%. Stronger models like GPT-5.2 do not consistently generate better context files, and codebase overviews within `AGENTS.md` do not accelerate agent navigation. The primary issue is that agents follow unnecessary instructions, increasing reasoning tokens by 14-22%, especially when content duplicates existing documentation.

Key takeaway

For AI Engineers configuring coding agents, you should meticulously craft your `AGENTS.md` file, prioritizing brevity and clarity over comprehensive detail. Focus on providing essential context like your tech stack, project purpose, and build/test instructions, while omitting redundant overviews or auto-generated content. This approach will reduce inference costs and improve task success rates by preventing agents from following unnecessary or duplicated instructions.

Key insights

Effective `AGENTS.md` files are concise, human-written, and focus on essential, non-redundant information.

Principles

• Less is more for agent context files.
• Instructions are followed, so be precise.
• Prefer pointers over embedded content.

Method

Structure `AGENTS.md` with "WHAT" (tech stack), "WHY" (project purpose), and "HOW" (build/test instructions), keeping it under 300 lines and using progressive disclosure for task-specific documentation.

In practice

• Avoid auto-generated `AGENTS.md` files.
• Exclude detailed codebase overviews.
• List non-obvious tooling (e.g., `uv`, `bun`).

Topics

• AGENTS.md Configuration
• Coding Agents
• LLM Performance
• Codebase Documentation
• Agent Instruction Design

Best for: AI Engineer, Machine Learning Engineer, Prompt Engineer

Related on AIssential

• Does AGENTS.md Actually Help Coding Agents? — Context files for coding agents are beneficial only when they provide unique, non-redundant information.
• Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents — Configuration "smells" in AGENTS.md/CLAUDE.md files are widespread, increasing costs and reducing coding agent effectiveness.
• the history of agents.md, the problems with agents.md and what makes a good one — Effective LLM agent configuration requires model-specific, concise "agents.md" files to optimize behavior and context window usage.
• Do AGENTS.md/CLAUDE.md Files Help Coding Agents? A New Paper Challenges this — Context files for coding agents often increase cost and steps without improving task success in well-documented repositories.
• How to Write a Good Spec for AI Agents — Effective AI agent specs require clear structure, modularity, and iterative refinement to guide agents and manage context.
• How to Optimize Your AI Coding Agent Context — Effective context management is paramount for optimizing AI coding agent performance and engineer efficiency.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by philschmid.de - RSS feed.