Understanding AGENTS.md: History, Problems, and Best Practices for Efficient LLM Prompts

Geoffrey Huntley

The Origin Story of AGENTS.md [00:01:21]

• The AGENTS.md file was created to standardize coding agent configurations.
  • Initially, various coding tools created model-specific configuration files like Jules.md and Claude.md, cluttering repositories.
  • This led to frustration within the developer community.
• Sourcegraph acquired the agent.md domain due to similar frustrations.
  • An informal RFC (Request for Comments) was circulated online to advocate for standardizing on a single filename.
  • The agents.md domain was unavailable, being parked by a domain parker and linking to inappropriate content, making agent.md the preferred neutral option.
• OpenAI and Google had already standardized on agents.md.
  • OpenAI later purchased agents.md, aligning with Google.
  • The community, including the speaker, redirected agent.md to agents.md and provided instructions for using symlinks to manage different model-specific files under the unified agents.md name.

    

Problems with a Singular AGENTS.md [00:04:38]

• Standardizing on a single AGENTS.md might have been premature.
  • A file name per model (e.g., agents/gpt5.md, agents/claude.md) would be more effective.
• Different Large Language Models (LLMs) respond differently to instructions.
  • AGENTS.md and "cursor rules" are often tailored for specific LLM models.
  • The behavior of models, and how they react to human language, varies significantly.
• Example: GPT-5's "timid" behavior [00:05:59]
  • When GPT-5 was released, developers noted its "timid" responses, feeling it lacked confidence.
  • OpenAI's own guidelines for GPT-5 for Coding advised against using "firm language" or shouting (e.g., using ALL CAPS) as it makes the model "timid."

    

  • In contrast, Anthropic's models sometimes benefit from more direct or "firm" instructions.
  • This discrepancy highlights the problem: a single AGENTS.md file cannot effectively cater to the nuanced needs of different LLMs, leading to suboptimal performance or "noise" in the community when people switch models.

Understanding Allocations and Context Windows [00:08:32]

• How coding agents and harnesses work:
  • They typically use an array where the first slot (position zero) contains the harness prompt (e.g., Cursor's prompt, Claude's prompt).
  • The next slot (slot one) is usually automatically injected with the AGENTS.md or Claude.md content.
• The AGENTS.md content is always allocated.
  • This means it consumes a portion of the LLM's context window.
  • A large AGENTS.md reduces the available memory for actual work, increasing the likelihood of operating in the "dumb zone" where the LLM loses context or performs poorly.

What Makes a Good AGENTS.md [00:09:37]

• Conciseness is Key: An effective AGENTS.md should be very small, ideally around 70 lines of text.
  • Verify the token count of your AGENTS.md using an OpenAI tokenizer.
  • Minimize its size to maximize the LLM's context window for problem-solving.
• Regular Pruning:
  • AGENTS.md files tend to grow over time as new instructions are added, often without removing old ones, becoming "forgotten knowledge."
  • Periodically "mow it down" or "destroy it" and regenerate it from first principles to ensure only essential instructions remain.
• Just Enough Information: The goal is to provide just enough information to "tickle the latent space" of the LLM and evoke desired behaviors, rather than being overly specific or concrete.
  • Example 1: Checking Web Server: Instead of specifying nginx or caddy, a prompt like "check the webserver, use journald to diagnose" is sufficient. The LLM can infer related commands like systemctl status and journalctl because they reside in the same latent space.

    

    

  • Example 2: Server Deployment Status: A prompt like "is my server deployed, if so moo" successfully triggers the LLM to check deployment status, service status, and health endpoints, because the latent behavior was observed and tuned previously.

    

• Tuning is an Iterative Process:
  • If the agent repeatedly fails during tests or exhibits "cache misses" (e.g., trying multiple commands before finding the right one), it's a sign that the AGENTS.md needs tuning.
  • There is no single "right" prompt; it requires experimentation and observation to find what works best for a specific application and model.
  • The effort put into tuning pays off by enabling higher levels of abstraction in prompts, driving complex behaviors with minimal input.