What is AGENTS.md and How Does It Improve AI Coding Agent Performance?

Apr 2, 2026

My Claude Code agent kept suggesting useRouter() inside Server Components. Every time. I’d correct it, it would apologize, then suggest the same wrong pattern again in the next session.

The problem wasn’t the model. The problem was missing context.

The Frustrating Reality

I spent hours debugging AI-generated Next.js code that looked perfectly correct but crashed at runtime:

Error: useRouter cannot be used inside Server Components
  at app/posts/page.tsx:15

The agent swore this was the correct pattern. It wasn’t hallucinating randomly - it was using outdated knowledge from its training data. Next.js 13+ changed the rules, but the model didn’t know.

I tried everything:

Explicitly telling the agent “use Server Components”
Providing code examples manually
Using Context7 MCP server for documentation lookup

Each approach helped partially, but the agent still made mistakes on edge cases.

Discovery: AGENTS.md

Then I found Vercel’s benchmark results. They tested AI agents on Next.js tasks with and without AGENTS.md - a bundled documentation file format.

The results shocked me:

+------------------+-------------------+------------------+-------------+
| Model            | Without AGENTS.md | With AGENTS.md   | Improvement |
+------------------+-------------------+------------------+-------------+
| GPT 5.3 Codex    | 86%               | 100%             | +14%        |
| GPT 5.4          | 86%               | 95%              | +9%         |
| Claude Opus 4.6  | 71%               | 100%             | +29%        |
| Claude Sonnet 4.6| 67%               | 100%             | +33%        |
| Gemini 3.1 Pro   | 76%               | 100%             | +24%        |
+------------------+-------------------+------------------+-------------+

Wait - Claude Sonnet jumped from 67% to 100%? That’s a 33% improvement just from adding documentation context.

What AGENTS.md Actually Is

AGENTS.md is a single, comprehensive documentation bundle placed in your project root. It consolidates everything an AI agent needs to know about your framework:

+---------------------------------------------------------------+
|                    WITHOUT AGENTS.md                          |
+---------------------------------------------------------------+
| Agent searches:                                               |
|   -> Training data (potentially outdated)                    |
|   -> Web search (fragmented, inconsistent)                   |
|   -> MCP servers (slow, retrieval overhead)                  |
|                                                               |
| Result: Inconsistent context, hallucinations, errors         |
+---------------------------------------------------------------+

+---------------------------------------------------------------+
|                    WITH AGENTS.md                             |
+---------------------------------------------------------------+
| Agent reads:                                                  |
|   -> Single bundled file in project root                     |
|   -> Current API references                                   |
|   -> Version-pinned patterns                                  |
|   -> Framework-specific best practices                        |
|                                                               |
| Result: Consistent, accurate, up-to-date outputs             |
+---------------------------------------------------------------+

The Surprising Insight

The benchmark revealed something unexpected: GPT 5.3 Codex with AGENTS.md achieved 100% accuracy, while GPT 5.4 with AGENTS.md only reached 95%.

                    ACCURACY COMPARISON
    100% +----------------------------------------+
         |   * GPT 5.3 + AGENTS.md               |
     95% |                      * GPT 5.4 + AGENTS.md
         |                                        |
     86% |   x GPT 5.3 alone    x GPT 5.4 alone   |
         |                                        |
         +----------------------------------------+
              Documentation context > Model version

Proper documentation context can matter MORE than model version. A smaller, cheaper model with good documentation outperformed a larger model.

Why This Works

I analyzed why AGENTS.md delivers such dramatic improvements:

1. Eliminates Retrieval Latency

Without bundled docs, agents must search multiple sources. Each retrieval introduces latency and potential inconsistencies:

Traditional approach:
  Query -> MCP Context7 -> API call -> Parse -> Cache -> Use
  Query -> Web Search -> Multiple URLs -> Filter -> Use
  Query -> Training data recall -> Confidence check -> Use

AGENTS.md approach:
  Query -> Read local file -> Use

The bundled approach eliminates an entire class of retrieval errors.

2. Version-Pinned Accuracy

Training data contains mixed versions. AGENTS.md pins to your specific version:

## Next.js 14.2 App Router

### Server Components Restrictions
- NO `useRouter()` - use `usePathname()` or URL params
- NO `useState()` - state belongs in Client Components
- NO `useEffect()` - side effects belong in Client Components
- YES async functions for data fetching
- YES direct database access

### Client Component Marker
"use client" directive required for:
- Event handlers (onClick, onSubmit)
- Browser APIs (localStorage, window)
- React hooks (useState, useEffect, useRouter)

3. Pattern Consistency

Every agent session reads the same documentation. No variation between sessions:

Session 1: reads AGENTS.md -> applies same patterns
Session 2: reads AGENTS.md -> applies same patterns
Session 3: reads AGENTS.md -> applies same patterns

vs. traditional approach:
Session 1: web search -> finds blog post A -> applies pattern A
Session 2: MCP lookup -> finds docs page B -> applies pattern B
Session 3: training recall -> uses pattern C (outdated)

My Implementation

I created an AGENTS.md for my Next.js project. The structure follows a clear pattern:

# Next.js 14.2 Documentation for AI Agents

## Core Concepts

### App Router Architecture
[Explain file-based routing, conventions]

### Server vs Client Components
[Clear rules, restrictions, examples]

### Data Fetching Patterns
[Server Component async patterns, caching]

### Metadata and SEO
[Static and dynamic metadata exports]

## Common Patterns

### Route Handler Examples
[REST API patterns in route.ts]

### Middleware Configuration
[Request interception patterns]

## Anti-Patterns to Avoid

- Using client hooks in Server Components
- Mixing fetch strategies incorrectly
- Incorrect metadata export syntax

The key sections:

Core Concepts: Foundational knowledge the agent needs
Common Patterns: Correct implementations to reference
Anti-Patterns: Explicit warnings about common mistakes

Cost Efficiency Breakthrough

This finding changed how I think about model selection:

+------------------+------------------------+-------------------------+
| Configuration    | Accuracy | Cost Factor | Recommendation          |
+------------------+----------+-------------+-------------------------+
| GPT 5.4 alone    | 86%      | High        | Overkill without docs   |
| GPT 5.3 + AGENTS | 100%     | Medium      | Best value combination  |
| Claude Sonnet    | 67%      | Low         | Insufficient alone      |
| Claude + AGENTS  | 100%     | Low-Medium  | Maximum cost efficiency |
+------------------+----------+-------------+-------------------------+

For Next.js tasks, Claude Sonnet 4.6 + AGENTS.md achieves the same 100% accuracy as GPT 5.4 alone, but at significantly lower cost.

Common Mistakes I Made

Mistake 1: Assuming Large Models Don’t Need Docs

I thought Claude Opus was smart enough to know Next.js patterns. Wrong. Opus improved 29% with AGENTS.md. Even the best models benefit from explicit context.

Mistake 2: Using Fragmented Documentation

I tried providing docs through multiple channels: Context7 for official docs, web search for tutorials, codebase context for local patterns. The agent struggled to reconcile conflicting information from different sources.

Mistake 3: Outdated Documentation Bundles

My first AGENTS.md contained Next.js 13 patterns. Next.js 14 changed several conventions. The agent generated correct code for version 13 that failed in my version 14 project.

Mistake 4: Creating AGENTS.md Manually

I spent hours copying documentation snippets. The smarter approach: use automated tools to generate AGENTS.md from official sources, pinning to your specific version.

How to Create AGENTS.md

Option 1: Framework-Provided

Some frameworks now provide official AGENTS.md files. Check your framework’s documentation repository.

Option 2: Generate from Official Docs

1. Identify your framework version
2. Fetch official documentation for that version
3. Extract relevant sections:
   - API references
   - Core concepts
   - Common patterns
   - Known anti-patterns
4. Consolidate into single markdown file
5. Place in project root as AGENTS.md

Option 3: Use Context7 MCP

The Context7 MCP server can fetch official documentation. Export relevant sections into your AGENTS.md:

Query Context7 for: "Next.js 14.2 App Router patterns"
Extract sections:
  - Server Components rules
  - Data fetching patterns
  - Metadata API
  - Route handlers
Consolidate into AGENTS.md

When AGENTS.md Helps Most

AGENTS.md delivers maximum value for:

Framework-specific work: Next.js, React, Spring Boot, Django
Version-sensitive APIs: When training data contains mixed versions
Complex conventions: When rules aren’t obvious from code alone
Multi-file context: When patterns span multiple files
Production code: When accuracy matters more than exploration

When You Might Not Need It

AGENTS.md adds overhead for:

Exploratory coding: When you want the agent to discover patterns
Simple tasks: Generic programming that doesn’t need framework knowledge
Already-covered topics: When training data is accurate and current
One-off scripts: Quick tasks where accuracy tolerance is higher

The Bottom Line

AGENTS.md transformed my AI coding workflow. The 33% accuracy improvement for Claude Sonnet means fewer errors, less debugging, and more confidence in AI-generated code.

The key insight: documentation context often matters more than model size. A well-documented cheaper model beats an under-documented expensive model.

For Next.js specifically, Claude Sonnet 4.6 + AGENTS.md at 100% accuracy costs less than GPT 5.4 alone at 86% accuracy. That’s both better performance AND lower cost.

My agent stopped suggesting useRouter() in Server Components. It now consistently generates correct Next.js 14 patterns. The frustration is gone.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!