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

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:

## Setup & Build
- Install: \`pnpm install\`
- Dev Server: \`pnpm dev\`
- Build: \`pnpm build\`
- Lint: \`pnpm lint --fix\`

2. Testing Instructions

## 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

## 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:

## 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

## 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:

## 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 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.

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:

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.