--- type: Blog Post title: "AGENTS.md: The Research-Backed Guide to Making AI Agents 29% Faster" description: "AGENTS.md: The Research-Backed Guide to Making AI Agents 29% Faster. A new study proves AGENTS.md files reduce AI coding agent runtime by 28.6% and token..." resource: "https://www.contextstudios.ai/blog/agentsmd-the-research-backed-guide-to-making-ai-agents-29-faster" tags: [AI, AGENTS.md, Coding Agents, Developer Tools, Context Engineering, Productivity] language: en timestamp: "2026-05-13T05:45:49.982Z" --- # AGENTS.md: The Research-Backed Guide to Making AI Agents 29% Faster AGENTS.md: The Research-Backed Guide to Making AI Agents 29% Faster A new arxiv study has proven it in black and white: AGENTS.md, the configuration file that defines how AI coding agents behave in your repository, makes AI coding agents 28.6% faster and save 16.6% on tokens. While most developers are still debating whether they need such a file, we at Context Studios have been using AGENTS.md since day one — and the research now confirms what we already knew from practice. In this guide, we show what the research says, how to optimally structure your AGENTS.md, and which specific contents have the biggest impact. With real examples from our own workspace. What Is AGENTS.md? AGENTS.md is an open format for guiding AI coding agents. Designed as a README for agents, the file is now used by over 60,000 open-source projects on GitHub and supported by a growing ecosystem — including OpenAI Codex, Google Jules, Cursor, Amp, and Factory. The concept is simple: While README.md is designed for humans (project descriptions, quickstarts, contribution guidelines), AGENTS.md provides the context that AI agents need — build steps, test commands, coding conventions, and project structure. Since January 2026, AGENTS.md is stewarded by the Agentic AI Foundation under the Linux Foundation. The format is not a proprietary tool but an open standard. The Research: 28.6% Faster, 16.6% Fewer Tokens The study "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" (Lulla et al., arxiv 2601.20404, January 2026) provides the first empirical evidence for the impact of AGENTS.md: Study Design - 10 repositories, 124 pull requests analyzed - Agent: GPT-5.2-Codex (OpenAI) - Paired design: Each task executed with and without AGENTS.md - Isolated Docker environments for reproducibility - Metrics: Wall-clock time and token consumption The Results | Metric | Without AGENTS.md | With AGENTS.md | Improvement | |--------|-------------------|----------------|-------------| | Median Runtime | 98.57s | 70.34s | −28.64% | | Mean Runtime | 162.94s | 129.91s | −20.27% | | Median Output Tokens | 2,925 | 2,440 | −16.58% | | Mean Output Tokens | 5,744 | 4,591 | −20.08% | | Mean Input Tokens | 353,010 | 318,651 | −9.73% | Statistics are significant (Wilcoxon signed-rank test, p < 0.05). Why Does It Work? The researchers hypothesize that AGENTS.md improves efficiency because agents spend less time on exploratory navigation. Instead of figuring out project structure and conventions themselves, they receive this information directly — fewer planning iterations, fewer repeated requests to the model. In the Hacker News discussion about the study, one commenter puts it perfectly: "AGENTS.md is context. Models have been trained to follow context since the dawn of the thing." Unlike Skills that agents must actively invoke, AGENTS.md is passive context — always available, no decision required. What Belongs in a Good AGENTS.md? GitHub analyzed 2,500+ repositories and identified the patterns of successful AGENTS.md files. The six core areas you should cover: 1. Commands Put executable commands at the beginning — with flags and options, not just tool names: 2. Testing Instructions 3. Project Structure 4. Code Style A single real code example beats three paragraphs of description: 5. Git Workflow 6. Boundaries Tell the agent what it should never touch: In Practice: Our AGENTS.md at Context Studios We run our AI workflows with Claude Opus 4.5 and Claude Code 2.1. Our own AGENTS.md file is a living document that has grown over months. Here are the core elements: Session Bootstrapping Our AGENTS.md defines what the agent should read at every session start — identity (SOUL.md), user context (USER.md), daily notes, and long-term memory. This completely eliminates the "Who am I?" phase. Memory System Instead of "mental notes" (which are lost on session restarts), we write everything to files: - Daily notes: memory/YYYY-MM-DD.md — raw logs - Long-term memory: MEMORY.md — curated memories The rule: "Text > Brain." What isn't in a file doesn't exist. Safety Guidelines Clear boundaries between "safe without asking" and "ask first": - Free: Read files, search the web, work within the workspace - Ask first: Send emails, post tweets, anything that leaves the machine Proactive Heartbeats Our agent doesn't just wait for commands — it uses regular heartbeats to check emails, review calendars, and do background work. Advanced: Using AGENTS.md in Monorepos with Nested Files For large monorepos, AGENTS.md supports nested files. The agent automatically reads the nearest file in the directory tree. OpenAI's own repository has 88 AGENTS.md files for different subprojects. AGENTS.md Agent Compatibility AGENTS.md works with all major coding agents: | Agent | Support | |-------|---------| | OpenAI Codex | Native — AGENTS.md originated here | | Claude Code 2.1 | Reads AGENTS.md automatically | | GitHub Copilot | Full support + custom agents | | Google Jules | Native support | | Cursor | Compatible via Rules | | Amp | Native support | | Aider | Configurable via .aider.conf.yml | | Gemini CLI | Configurable via settings.json | The Six Most Important AGENTS.md Rules Based on the research, GitHub's analysis, and our own experience: 1. Commands first — Setup, build, test, lint at the top 2. Code examples over prose — One snippet beats three paragraphs 3. Set clear boundaries — What the agent must never touch 4. Name your stack specifically — "Next.js 16.1 with TypeScript and Tailwind v4.1," not "React project" 5. Living document — Update regularly as conventions change 6. Keep it focused — No novel-length files; agents have context windows AGENTS.md ROI Calculation: Why It Pays Off Immediately Consider a typical development team of 5 developers running 20 agent tasks per day: - Without AGENTS.md: 100 tasks × 98.57s = ~2.7 hours agent runtime/day - With AGENTS.md: 100 tasks × 70.34s = ~1.95 hours agent runtime/day - Savings: ~45 minutes of agent runtime per day + 16.6% fewer token costs At current API prices over a year, this adds up to thousands of dollars in saved compute costs — not counting the time savings for developers. --- AGENTS.md: Frequently Asked Questions What is the difference between AGENTS.md and README.md? README.md is for humans — project descriptions, installation guides, contribution guidelines. AGENTS.md is for AI agents — build commands, test instructions, coding conventions, and project structure. Both files complement each other: the README explains what the project does, AGENTS.md explains how an agent should work on it. Do I need a separate config file for each AI agent? No. AGENTS.md is an open standard supported by all major coding agents — OpenAI Codex, Claude Code 2.1, GitHub Copilot, Google Jules, Cursor, and more. One AGENTS.md file works everywhere. Some agents (like Aider or Gemini CLI) need a short config line to read AGENTS.md. How long should an AGENTS.md file be? As short as possible, as long as necessary. AI agents have context windows (Claude Opus 4.5: 200K tokens, GPT-5.2: 400K tokens, Gemini 3 Pro: 2M tokens), and every unnecessary instruction consumes valuable capacity. The best AGENTS.md files focus on the six core areas: commands, testing, project structure, code style, git workflow, and boundaries. Can AGENTS.md files pose security risks? AGENTS.md files themselves are pure Markdown without executable code. However, you should never put secrets, API keys, or sensitive configurations in the file — those belong in environment variables. Instead, use the boundaries section to explicitly define which files and directories the agent must not touch. Is AGENTS.md worth it for small projects? Yes. The study shows significant improvements even for small pull requests (≤ 100 LoC). Even a minimal AGENTS.md with setup commands and test instructions can measurably improve your agents' efficiency. The effort to create one is 10–15 minutes — the time savings pay for themselves after just a few agent tasks. --- Using AI agents in your development workflow? Context Studios helps you create AGENTS.md files and optimize your agent workflows. Contact us for a free consultation.