--- type: "BlogPosting" title: "AGENTS.md: The Research-Backed Guide to Making AI Agents 29% Faster" description: "A new study proves AGENTS.md files reduce AI coding agent runtime by 28.6% and token usage by 16.6%. We use AGENTS.md daily — here is the definitive practical guide." resource: "https://www.contextstudios.ai/blog/agentsmd-the-research-backed-guide-to-making-ai-agents-29-faster" language: "en" tags: ["AI", "AGENTS.md", "Coding Agents", "Developer Tools", "Context Engineering", "Productivity"] generated: by: "process:contextstudios-md/1" at: "2026-10-08T21:01:01.304Z" status: "stable" --- # AGENTS.md: The Research-Backed Guide to Making AI Agents 29% Faster Published: 2026-01-31 Tags: AI, AGENTS.md, Coding Agents, Developer Tools, Context Engineering, Productivity ![AGENTS.md: The Research-Backed Guide to Making AI Agents 29% Faster](https://wary-platypus-754.convex.cloud/api/storage/d977b78d-e7c0-4fc9-a671-bcc901048efd) # 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 agent](/blog/spotify-built-an-ai-coding-agent-that-replaced-writing-code-heres-what-developers-need-to-know)s **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](/blog/openai-codex-app-complete-guide-to-the-new-multi-agent-coding-desktop), 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: ```markdown ## Setup & Build - Install: \`pnpm install\` - Dev Server: \`pnpm dev\` - Build: \`pnpm build\` - Lint: \`pnpm lint --fix\` ``` ### 2. Testing Instructions ```markdown ## Testing - Unit Tests: \`pnpm test\` - Single Test: \`pnpm vitest run -t "test name"\` - E2E Tests: \`pnpm playwright test\` - All tests must pass before committing ``` ### 3. Project Structure ```markdown ## Architecture - \`src/app/\` — Next.js 16.1 App Router Pages - \`src/components/\` — React 19 Components (Shadcn UI) - \`convex/\` — Convex Backend (Queries, Mutations, Actions) - \`public/\` — Static Assets ``` ### 4. Code Style A single real code example beats three paragraphs of description: ```markdown ## Code Style - TypeScript strict mode - Tailwind v4.1 for styling (CSS-First Config) - Prefer functional patterns - No \`any\` types — always use explicit types ``` ### 5. Git Workflow ```markdown ## Git - Branch Naming: \`feat/\`, \`fix/\`, \`refactor/\` - Commit Messages: Conventional Commits - Always run \`pnpm lint && pnpm test\` before committing ``` ### 6. Boundaries Tell the agent what it should **never** touch: ```markdown ## Boundaries - ✅ Always: Write tests for new code - ⚠️ Ask first: Database schema changes - 🚫 Never: Commit secrets, modify .env files, touch production configs ``` ## In Practice: Our AGENTS.md at Context Studios We run our [AI workflows](/blog/build-your-own-ai-workflows-skills-cron-jobs-custom-mcp-tools-in-openclaw) 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. ```text my-monorepo/ ├── AGENTS.md ← Global instructions ├── packages/ │ ├── frontend/ │ │ └── AGENTS.md ← Frontend-specific │ ├── backend/ │ │ └── AGENTS.md ← Backend-specific │ └── shared/ │ └── AGENTS.md ← Shared libraries ``` ## 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](/contact) for a free consultation.* ## Sources - [arXiv 2601.20404: On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://www.alphaxiv.org/abs/2601.20404) - [AGENTS.md specification](https://agents.md) - [Hacker News discussion: Evaluating AGENTS.md](https://news.ycombinator.com/item?id=47034087) --- ## Roll out AI coding agents in your dev team In a hands-on workshop we set up Claude Code, Codex or Pi for your repositories: agent rules, review flow, permissions and cost limits. Your team leaves with a working setup, not slides. Start with a workshop, then scoping and a fixed-price offer. **[Request a workshop →](https://www.contextstudios.ai/services/ai-workshop?utm_source=blog&utm_medium=cta&utm_campaign=agentsmd-the-research-backed-guide-to-making-ai-agents-29-faster)** ## Related - [AI Development](https://www.contextstudios.ai/ai-development.md) - [AI Agent Development](https://www.contextstudios.ai/ai-agent-development.md) - [AI Workflow Automation](https://www.contextstudios.ai/ai-workflow-automation.md) - [AI Automation](https://www.contextstudios.ai/ai-automation.md)