Vercel's engineering team recently proved something remarkable: adding a single AGENTS.md file to their codebase boosted their AI agent pass rates from 53% to a perfect 100%. That's not a typo — nearly doubling AI coding accuracy with one markdown file.

If you're using Claude Code as your primary AI coding agent, this guide shows you exactly how to set up AGENTS.md (called CLAUDE.md in Claude Code's ecosystem) to get similar results. We'll cover the structure, the strategy, and the real-world examples that make the difference between an AI agent that guesses and one that ships production code.

What Is AGENTS.md and Why Does It Matter for Claude Code?

AGENTS.md is a markdown file placed in your project root that provides persistent context to AI coding agents. Every time the agent starts a session, it reads this file automatically — no manual loading, no hoping it remembers from last time.

Claude Code uses CLAUDE.md as its equivalent. The concept is identical: a file that tells the agent everything it needs to know about your project before it writes a single line of code.

Here's why this matters specifically for Claude Code users:

Claude Code starts every session with zero memory. Without CLAUDE.md, you're re-explaining your project every time.
Training data gets outdated. If you're using Next.js 16, Python 3.13, or any recent framework, Claude's training data might not cover the latest APIs.
Context is everything. Vercel found that embedding a compressed docs index directly in the file — rather than relying on skills or tools the agent has to decide to use — produced dramatically better results.

The Vercel Data: 53% to 100% Pass Rate

Vercel's engineering team ran rigorous evaluations testing four configurations against Next.js 16 coding tasks:

Configuration	Pass Rate	vs Baseline
Baseline (no docs)	53%	—
Skills (default)	53%	+0pp
Skills + explicit instructions	79%	+26pp
AGENTS.md docs index	100%	+47pp

The key insight: agents don't reliably use tools they have to decide to invoke. In 56% of Vercel's eval cases, the skill was never triggered. But AGENTS.md content is always loaded — no decision required.

Step-by-Step: Setting Up CLAUDE.md for Your Project

Step 1: Generate the Starter File

Open your terminal in the project root and run:

claude
/init

This auto-generates a CLAUDE.md based on your detected tech stack. It's a solid starting point, but you'll want to trim and customize it. As Builder.io's guide emphasizes: every line competes for attention in the context window.

Step 2: Choose Your File Location

Claude Code supports a hierarchy of memory files:

File	Location	Purpose
CLAUDE.md	Project root	Team-shared project instructions (commit to git)
CLAUDE.local.md	Project root	Personal project preferences (gitignored)
~/.claude/CLAUDE.md	Home directory	Your global defaults across all projects
*.claude/rules/.md**	Project .claude folder	Modular, topic-specific rules

For most teams, start with a root-level CLAUDE.md committed to version control. Add CLAUDE.local.md for personal preferences like sandbox URLs or test credentials.

Step 3: Structure Your File

Here's the recommended structure based on what works in production:

# Project: MyApp

Next.js 16 SaaS application with App Router, Stripe billing, and Prisma ORM.

## Code Style

- TypeScript strict mode, no `any` types
- Named exports only (no default exports)
- Tailwind CSS utility classes, no custom CSS files
- Use `connection()` for dynamic rendering (Next.js 16)
- Use `'use cache'` directive instead of old caching patterns

## Commands

- `pnpm dev`: Start dev server (port 3000)
- `pnpm test`: Run Vitest suite
- `pnpm test:e2e`: Playwright end-to-end tests
- `pnpm lint`: ESLint + Prettier check
- `pnpm db:push`: Push Prisma schema changes

## Architecture

- `/app`: Next.js App Router pages and layouts
- `/components/ui`: Shadcn/UI components
- `/lib`: Utilities, API clients, shared logic
- `/prisma`: Database schema and migrations

## Important Rules

- NEVER modify `/lib/auth.ts` without review
- All API routes must validate with Zod schemas
- Stripe webhook handler MUST verify signatures
- Images served via Cloudinary, not local storage

## Docs Index

IMPORTANT: Prefer retrieval-led reasoning over pre-training for Next.js tasks.

See @docs/nextjs-16-apis.md for current API reference.
See @docs/prisma-patterns.md for database conventions.

Step 4: Add a Compressed Docs Index

This is the technique Vercel used to hit 100%. Instead of expecting the agent to look up documentation, embed a compressed index directly in your CLAUDE.md that maps concepts to file paths.

The key instruction to include:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
for any [framework] tasks.

This tells Claude to consult the docs you've provided rather than relying on potentially outdated training data.

The Index-Based Approach: Pipe-Delimited Compression

For larger projects, you can use a pipe-delimited index format to pack maximum information into minimal tokens. This approach condenses documentation references into a scannable format:

## [Index]
|root: /home/user/myproject
|config: {tsconfig.json,next.config.ts,.env.local}
|api: /app/api/{auth,billing,webhooks}
|components: /components/{ui,forms,layouts}
|docs: {docs/api-ref.md,docs/db-schema.md,docs/auth-flow.md}

This approach is especially powerful for monorepos or full-stack applications where Claude needs to understand the project topology at a glance. At Serenities AI, we use this index-based approach across our own projects to keep Claude Code oriented when working across multiple services.

CLAUDE.md Imports: The @path Syntax

Claude Code supports importing additional files using the @path/to/file syntax. This is how you keep your main CLAUDE.md concise while still giving the agent access to detailed documentation:

See @README for project overview.
See @package.json for available commands.
See @docs/api-conventions.md for API design rules.

# Git Workflow
- @docs/git-instructions.md

Imports resolve relative to the file containing them. They support up to 5 levels of recursive imports. This is how you build the "docs index" approach that Vercel proved so effective.

Common Mistakes and How to Avoid Them

Mistake	Why It Hurts	Fix
Too long (500+ lines)	Wastes context tokens, dilutes important rules	Keep under 300 lines; use @imports for details
Vague instructions	"Write clean code" means nothing to an agent	Be specific: "Use named exports, not default"
No commands section	Agent guesses build/test commands, often wrong	List exact commands: `pnpm test`, `pnpm build`
Outdated content	Agent follows stale patterns, introduces bugs	Review CLAUDE.md every sprint; version with code
No "gotchas" section	Agent modifies sensitive files or uses wrong patterns	Document files to never touch and known quirks
Relying on skills alone	Agent may not invoke them (56% failure in Vercel's tests)	Embed critical info in CLAUDE.md directly

Before and After: Real-World Impact

Before (No CLAUDE.md)

> claude "Add a cached API route for products"

// Agent generates outdated pattern:
export const revalidate = 60;
export async function GET() {
  const products = await db.product.findMany();
  return Response.json(products);
}

After (With CLAUDE.md + Docs Index)

> claude "Add a cached API route for products"

// Agent uses Next.js 16 patterns from docs:
'use cache';
import { cacheLife } from 'next/cache';

export async function GET() {
  cacheLife('minutes');
  const products = await db.product.findMany();
  return Response.json(products);
}

The difference? With CLAUDE.md, the agent reads the docs index, discovers the correct Next.js 16 caching API, and generates code that actually works with your framework version.

CLAUDE.md Templates for Different Project Types

React / Next.js Projects

# Project: [Name]
[Framework] [version] with [router type], [state management], [styling].

## Code Style
- Component pattern: functional with hooks only
- State: Zustand for global, React state for local
- Styling: Tailwind CSS, cn() utility for conditionals
- Testing: Vitest + React Testing Library

## Commands
- `pnpm dev` / `pnpm build` / `pnpm test`

## Architecture
- /app: Pages and layouts
- /components: Reusable UI (Shadcn/UI base)
- /hooks: Custom React hooks
- /lib: Utilities and API clients

## Rules
- No `useEffect` for data fetching — use server components
- All forms use react-hook-form + Zod validation

Python / FastAPI Projects

# Project: [Name]
Python 3.13 FastAPI service with SQLAlchemy ORM and Alembic migrations.

## Code Style
- Type hints required on all functions
- Pydantic v2 models for request/response
- async/await for all I/O operations
- Ruff for linting, Black for formatting

## Commands
- `uv run dev`: Start Uvicorn dev server
- `uv run test`: Run pytest suite
- `alembic upgrade head`: Run migrations

## Architecture
- /app/api: Route handlers
- /app/models: SQLAlchemy models
- /app/schemas: Pydantic schemas
- /app/services: Business logic layer

## Rules
- Never raw SQL — always SQLAlchemy ORM
- All endpoints require auth dependency injection
- Background tasks via Celery, not in-request

Full-Stack Monorepo

# Project: [Name]
Turborepo monorepo: Next.js frontend + FastAPI backend + shared types.

## [Index]
|root: /packages
|frontend: packages/web (Next.js 16, App Router)
|backend: packages/api (FastAPI, Python 3.13)
|shared: packages/shared (TypeScript types, Zod schemas)
|infra: packages/infra (Pulumi IaC)

## Commands
- `turbo dev`: Start all services
- `turbo test`: Run all test suites
- `turbo build`: Production build

## Cross-Package Rules
- Shared types in /packages/shared — never duplicate
- API contracts defined as Zod schemas, generated for both TS and Python
- All PRs must pass `turbo test` before merge

Advanced Tips for Power Users

Use .claude/rules/ for modular rules. Instead of one massive file, split rules by topic: .claude/rules/testing.md, .claude/rules/api-design.md. Claude loads these alongside CLAUDE.md.
Leverage auto memory. Claude Code automatically saves learnings to ~/.claude/projects/<project>/memory/. Tell Claude "remember that we use pnpm, not npm" and it persists across sessions.
Use CLAUDE.local.md for personal config. Your sandbox URLs, preferred test data, and personal workflow shortcuts. Add it to .gitignore.
Review and prune regularly. Treat CLAUDE.md like documentation — it rots if you don't maintain it. Review every sprint.
Add the "prefer retrieval" instruction. Vercel's key finding: telling the agent to prefer docs over training data produces dramatically better results for newer frameworks.

For more tips on getting the most out of Claude Code, check out our Claude Code tips and tricks guide which covers 15 power user secrets most developers miss.

FAQ

Does Claude Code support AGENTS.md or only CLAUDE.md?

Claude Code specifically uses CLAUDE.md as its memory file. The AGENTS.md standard is used by other tools like Cursor, Zed, and OpenCode. The concepts are identical — only the filename differs. If you're using multiple AI coding tools, you can maintain both files with shared content.

How long should my CLAUDE.md file be?

Keep it under 300 lines. Every token in CLAUDE.md competes with the actual work you're asking Claude to do. Use @imports to reference detailed documentation without bloating the main file. Vercel's successful index was only 8KB compressed.

Can I use CLAUDE.md with Claude Code in VS Code?

Yes. Claude Code's VS Code extension reads CLAUDE.md the same way the CLI does. The file hierarchy (project root, .claude folder, home directory) works identically regardless of whether you're in terminal or VS Code.

Do I need to restart Claude Code after editing CLAUDE.md?

CLAUDE.md files in the project root and parent directories are loaded at the start of each session. For files in child directories, they load on demand when Claude reads files in those directories. Starting a new session picks up any changes.

What's the difference between CLAUDE.md and Claude's auto memory?

CLAUDE.md contains instructions you write for Claude — project rules, conventions, commands. Auto memory contains notes Claude writes for itself — patterns it discovers, debugging insights, your preferences. Both persist across sessions, but CLAUDE.md is deterministic while auto memory is emergent.

Start Writing Better CLAUDE.md Files Today

The data from Vercel is clear: the right project context file can take your AI coding agent from barely passing to perfect scores. For Claude Code users, that file is CLAUDE.md.

Start with /init, trim the fat, add your project-specific rules and a docs index for any framework newer than Claude's training data. Commit it to version control so your whole team benefits.

If you're exploring how AI coding agents fit into your development workflow, our Claude Code vs Codex CLI comparison breaks down the strengths of each tool. And for a deeper look at what these tools cost in practice, see our Claude API pricing guide for 2026.

The gap between developers who configure their AI agents properly and those who don't is only getting wider. One markdown file is all it takes to close it.

How to Make AI Coding Agents Actually Follow Your Rules