Vercel's engineering team proved something remarkable in January 2026: adding an AGENTS.md file to a project boosted AI agent pass rates from 53% to a perfect 100%. That's not a marginal improvement — it's the difference between an AI coding agent that guesses and one that knows your codebase.
But here's the question most developers are asking right now: how do you set up AGENTS.md for both Claude Code and Google's Gemini CLI? The two most popular terminal-based AI coding agents handle project context files differently, and getting the configuration right can make or break your AI-assisted workflow.
This guide walks you through setting up AGENTS.md for both tools, highlights the key differences, and gives you practical tips for teams using both. At Serenities AI, we've been tracking how developers configure their AI coding agents, and the AGENTS.md approach is clearly winning.
What Is AGENTS.md and Why Does It Matter?
AGENTS.md is a markdown file placed in your project root that provides persistent context to AI coding agents. Unlike skills or plugins that agents must choose to invoke, AGENTS.md content is loaded automatically on every interaction. The agent doesn't need to decide whether to read it — it's always there.
Vercel's eval results tell the story clearly:
| Configuration | Pass Rate | vs Baseline |
|---|---|---|
| No docs (baseline) | 53% | — |
| Skills (default) | 53% | +0pp |
| Skills + explicit instructions | 79% | +26pp |
| AGENTS.md docs index | 100% | +47pp |
The key insight: agents don't reliably invoke skills on their own. In Vercel's testing, skills were never triggered in 56% of cases. AGENTS.md eliminates this problem entirely by making the context always available.
Claude Code: CLAUDE.md Setup Guide
Claude Code uses CLAUDE.md as its native context file (functionally identical to AGENTS.md). It also reads AGENTS.md files automatically — Anthropic added AGENTS.md support to ensure cross-tool compatibility.
Step 1: Create Your CLAUDE.md File
Place a CLAUDE.md file in your project root:
# Project: My SaaS App
## Tech Stack
- Next.js 16 with App Router
- TypeScript (strict mode)
- Prisma ORM with PostgreSQL
- Tailwind CSS v4
## Code Style
- Use 'use cache' directive for cacheable routes
- Prefer server components by default
- Use connection() for dynamic rendering
- All API routes use proxy.ts pattern
## Project Structure
/src/app - App router pages
/src/components - Shared UI components
/src/lib - Utility functions and database
/src/actions - Server actions
## Important Patterns
- ALWAYS use async cookies() and headers()
- Use cacheLife() and cacheTag() for granular cache control
- Use forbidden() and unauthorized() for auth errors
- Run pnpm typecheck before committing
Step 2: Add Directory-Level Context
Claude Code supports nested CLAUDE.md files. Place additional files in subdirectories for scoped context:
project-root/
├── CLAUDE.md # Global project context
├── src/
│ ├── CLAUDE.md # Source-level conventions
│ └── components/
│ └── CLAUDE.md # Component-specific rules
└── tests/
└── CLAUDE.md # Testing conventions
Step 3: Configure User and Project Settings
Claude Code also reads from ~/.claude/CLAUDE.md for global preferences that apply across all projects:
# Global Claude Code Preferences
- Use American English in all comments and documentation
- Prefer functional components over class components
- Always add JSDoc comments to exported functions
- Use descriptive variable names (no single-letter vars)
Key Claude Code Context Features
- Auto-loaded: CLAUDE.md is read on every session start
- Hierarchical: Supports nested files at any directory level
- AGENTS.md compatible: Also reads AGENTS.md if present
- User-level config: Global ~/.claude/CLAUDE.md for personal preferences
- Project memory: Can save learned patterns with /memory command
Gemini CLI: GEMINI.md Setup Guide
Google's Gemini CLI uses GEMINI.md as its native context file. While it doesn't read AGENTS.md by default, you can configure it to do so through .gemini/settings.json. This flexibility makes Gemini CLI adaptable to teams already using the AGENTS.md standard.
Step 1: Create Your GEMINI.md File
Place a GEMINI.md file in your project root:
# Project: My SaaS App
## Tech Stack
- Next.js 16 with App Router
- TypeScript (strict mode)
- Prisma ORM with PostgreSQL
- Tailwind CSS v4
## Code Style
- Use 'use cache' directive for cacheable routes
- Prefer server components by default
- All API routes use proxy.ts pattern
## Important: Prefer retrieval-led reasoning over pre-training-led reasoning
When working on this project, always consult the local docs and code
before relying on your training data. The project uses bleeding-edge
APIs that may not be in your training set.
## Commands
- Build: npm run build
- Test: npm test
- Lint: npm run lint
Step 2: Configure AGENTS.md Support (Optional)
If your team already uses AGENTS.md and you want Gemini CLI to read it, add a context configuration to .gemini/settings.json:
{
"context": [
{
"type": "file",
"path": "AGENTS.md"
}
]
}
This tells Gemini CLI to load the AGENTS.md file as additional context alongside its native GEMINI.md. You can include multiple context files this way.
Step 3: Add Global Configuration
Gemini CLI supports global settings at ~/.gemini/settings.json for user-level preferences:
{
"model": "gemini-2.5-pro",
"context": [
{
"type": "file",
"path": "AGENTS.md"
}
],
"tools": {
"shell": true,
"fileSystem": true
}
}
Key Gemini CLI Context Features
- Auto-loaded: GEMINI.md is read on every session start
- Configurable context: Load any file via .gemini/settings.json
- AGENTS.md support: Requires manual configuration in settings.json
- User-level config: Global ~/.gemini/settings.json
- Memory features: Built-in context persistence across sessions
- Free tier: Generous free usage with Google account login
Side-by-Side Comparison: Claude Code vs Gemini CLI AGENTS.md Support
| Feature | Claude Code | Gemini CLI |
|---|---|---|
| Native context file | CLAUDE.md | GEMINI.md |
| AGENTS.md support | ✅ Native (auto-reads) | ⚙️ Via settings.json config |
| Nested context files | ✅ Any directory level | ❌ Root level only |
| Global user config | ~/.claude/CLAUDE.md | ~/.gemini/settings.json |
| Config format | Markdown only | Markdown + JSON settings |
| Multi-file context | Via nested CLAUDE.md files | Via settings.json context array |
| Memory persistence | ✅ /memory command | ✅ Built-in memory |
| MCP support | ✅ Full MCP integration | ✅ Full MCP integration |
| Cost | API usage (pay per token) | Free tier + API key option |
| Open source | ❌ Proprietary | ✅ Open source |
Setting Up AGENTS.md for Both Tools (Universal Config)
If your team uses both Claude Code and Gemini CLI, here's how to create a universal setup that works with both:
Step 1: Create a Shared AGENTS.md
Start with an AGENTS.md file in your project root. Claude Code reads this natively. For Gemini CLI, you'll add the settings.json config.
# AGENTS.md - Universal AI Agent Context
## Project Overview
[Your project description]
## Tech Stack
[Your technologies]
## Coding Standards
[Your code style rules]
## Important: Prefer retrieval-led reasoning
Always consult project files and local documentation
before relying on training data for this project.
## File Structure
[Key directories and their purposes]
## Testing
[How to run tests, what testing frameworks you use]
## Common Gotchas
[Framework-specific issues agents should know about]
Step 2: Add Tool-Specific Overrides
Create tool-specific files for features unique to each agent:
project-root/
├── AGENTS.md # Shared context (both tools read this)
├── CLAUDE.md # Claude Code-specific additions
├── GEMINI.md # Gemini CLI-specific additions
├── .gemini/
│ └── settings.json # Tells Gemini CLI to read AGENTS.md
└── src/
└── CLAUDE.md # Nested context (Claude Code only)
Step 3: Keep Context Under 8KB
Vercel's research found that a compressed 8KB docs index achieved a 100% pass rate. Don't dump your entire documentation into AGENTS.md — instead, create a focused index that points to relevant docs files. Think of it as a table of contents, not the full book.
Tips for Teams Using Both Tools
- Standardize on AGENTS.md first. Write your shared context in AGENTS.md, then add tool-specific files only for features that differ between Claude Code and Gemini CLI.
- Use the "retrieval-led reasoning" instruction. Both tools benefit from being told to prefer local project files over training data. This single instruction was key to Vercel's 100% pass rate.
- Keep it concise. More context isn't always better. Focus on information that's not in the model's training data — new APIs, project-specific patterns, and non-obvious conventions.
- Version control your context files. Commit AGENTS.md, CLAUDE.md, and GEMINI.md to your repo. These are project documentation that benefits the whole team, not just AI agents.
- Test both agents. After setting up your context files, run the same coding task through both Claude Code and Gemini CLI. Compare the output quality. You might find one tool handles your specific stack better. For more on getting the most out of Claude Code specifically, check out our Claude Code tips and tricks guide.
- Update context files when APIs change. The whole point of AGENTS.md is giving agents knowledge they don't have from training data. When your framework releases new APIs, update your context files immediately.
Which Tool Handles AGENTS.md Better?
Claude Code has the edge for AGENTS.md support right now. It reads both CLAUDE.md and AGENTS.md natively without any configuration, supports nested context files at any directory level, and has a mature memory system for persisting learned patterns.
Gemini CLI is catching up fast. While it requires a settings.json configuration to read AGENTS.md, its open-source nature means the community is actively pushing for native AGENTS.md support (there's an active discussion on GitHub about making it a default). Plus, the free tier makes it accessible for individual developers experimenting with context-driven workflows.
For teams comparing these two tools head-to-head on other metrics, our Claude Code vs Codex CLI comparison covers performance benchmarks and pricing — many of the same considerations apply when evaluating Gemini CLI.
The Future of AGENTS.md
The Agent Rules initiative is pushing AGENTS.md as an open standard for AI coding agents — think of it like EditorConfig but for AI. The goal is a single file that works across Claude Code, Gemini CLI, OpenAI Codex CLI, Aider, and every other tool.
We're not there yet, but the trajectory is clear. Google's Gemini CLI team is engaging with the standard, Anthropic's Claude Code already supports it, and the developer community is rallying around the simplicity of "one markdown file to rule them all."
If you're building with AI coding agents in 2026, setting up AGENTS.md isn't optional — it's the single highest-impact thing you can do to improve code quality. For a deeper look at how AI pricing affects your tool choice, check out our Claude API pricing guide.
FAQ
Does Claude Code read AGENTS.md or only CLAUDE.md?
Claude Code reads both. It natively supports CLAUDE.md as its primary context file and also auto-reads AGENTS.md if present in your project root. You don't need any extra configuration — just drop the file in and it works.
Can Gemini CLI use AGENTS.md without GEMINI.md?
Yes, but you need to configure it. Add a context entry in .gemini/settings.json pointing to your AGENTS.md file. Gemini CLI will then load it as context alongside any GEMINI.md that exists.
Should I use AGENTS.md or tool-specific files (CLAUDE.md / GEMINI.md)?
Use both. Put shared project context in AGENTS.md for cross-tool compatibility, then add tool-specific overrides in CLAUDE.md or GEMINI.md for features unique to each agent. This gives you the best of both worlds.
How big should my AGENTS.md file be?
Aim for under 8KB of compressed, focused content. Vercel achieved their 100% pass rate with a compact docs index, not a massive documentation dump. Include only information the model likely doesn't have from training data — new APIs, project-specific patterns, and non-obvious conventions.
Will other AI coding tools support AGENTS.md in the future?
Very likely. The Agent Rules initiative (agent-rules.org) is establishing AGENTS.md as an open standard. Tools like Aider already support configurable context files, and the community is pushing for universal adoption. Standardizing on AGENTS.md now future-proofs your setup.