What makes a good AGENTS.md?

2025-04-24 · Source: Ben's Bites · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering, Emerging Technologies & Innovation · Depth: Intermediate, medium

Summary

The article details the optimal use of AGENTS.md and CLAUDE.md files, which are pre-loaded instruction sets for AI models, functioning similarly to system prompts. It clarifies that while CLAUDE.md is specific to Claude products, AGENTS.md works across various tools like Codex/Droid/Pi, and they can be symlinked. Contrary to earlier beliefs, including detailed tech stacks or file maps in these instruction files is detrimental, increasing cost by 20% and hurting performance. Instead, these files should contain user preferences and nudges for agent behavior, such as using specific web search tools, defining planning file locations, or requesting video recordings of output. The article also highlights the utility of conditional blocks for dynamic instruction loading and notes that skill frontmatter is automatically pre-loaded, making explicit mention unnecessary. These instructions also apply to ChatGPT/Claude Desktop app personalization settings.

Key takeaway

For AI Engineers or Prompt Engineers configuring agent behavior, you should streamline your AGENTS.md or CLAUDE.md files. Focus on clear, concise preferences and behavioral nudges, such as specifying tools or output formats, rather than detailing technical environments. This approach will reduce token usage, improve agent performance, and ensure your agents adapt more effectively to different project requirements without unnecessary overhead.

Key insights

Optimize AI agent behavior and cost by providing concise, preference-based instructions rather than detailed technical maps.

Principles

• Concise instructions improve AI agent performance.
• Avoid redundant information in agent prompts.
• Conditional blocks enable dynamic agent behavior.

Method

Configure AGENTS.md/CLAUDE.md with user preferences and behavioral nudges. Utilize conditional blocks for context-specific instructions. Do not include detailed tech stacks or skill lists, as these are often automatically handled or inferred.

In practice

• Symlink AGENTS.md to CLAUDE.md for unified instructions.
• Specify preferred tools (e.g., Exa for web search).
• Use conditional blocks for project-specific agent behaviors.

Topics

• AI Agents
• Large Language Models
• AI Development Tools
• Generative AI
• AI Infrastructure

Code references

• yazinsai/OpenOats

Best for: AI Engineer, Prompt Engineer, Software Engineer

Related on AIssential

• We're sharing our internal AI engineering cheatsheets — Pre-made engineering decisions and architectural guidelines accelerate AI development and improve output quality.
• Why I Moved My Agentic Coding Harness from Claude Code to Codex — Daily operational factors like rate limits and reliability outweigh benchmarks for agentic coding harness adoption.
• Writing a Good AGENTS.md — Effective `AGENTS.md` files are concise, human-written, and focus on essential, non-redundant information.
• Week3 — Take care of your AI: a 10-week field guide for 2026 — Optimizing AI agent system prompts by reducing "CLAUDE.md" file size significantly improves agent behavior and decision-making.
• 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.
• The Agentic AI Toolkit: MCP vs. Agent Skills vs. AGENTS.md — MCP, Agent Skills, and AGENTS.md form a standardized toolkit for AI agent connectivity and behavior.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Ben's Bites.