CLAUDE.md, AGENTS.md, and Every AI Config File Explained

Every AI coding tool now reads a configuration file from your project. Claude Code looks for CLAUDE.md. Codex CLI reads AGENTS.md. Gemini CLI checks for GEMINI.md. Cursor has .cursorrules. GitHub Copilot uses copilot-instructions.md. Windsurf has .windsurfrules.

These files solve a fundamental problem: AI models have no persistent memory. Every session starts blank. Without a configuration file, you'd repeat the same instructions every time — your tech stack, coding conventions, project structure, deployment rules. These files give your AI assistant the context it needs to produce useful code from the first prompt.

This guide covers every major format, explains how they work, and shows you how to write effective instructions that actually improve your AI's output.

The Complete Landscape

Here's every AI configuration file format in use today:

Every tool has converged on the same core idea: a markdown file in your repository that the AI reads before doing anything. The differences are in naming and how they handle hierarchy.

How Each Format Works

CLAUDE.md — Claude Code

Claude Code reads CLAUDE.md files from three locations, merged in order:

1. ~/.claude/CLAUDE.md — Your personal global instructions (applied to all projects)
2. ./CLAUDE.md — Project root instructions (shared with your team via git)
3. Subdirectory CLAUDE.md files — Scoped instructions for specific parts of the codebase

Claude Code also reads AGENTS.md as a fallback if no CLAUDE.md is found in a directory. This means if your team uses multiple AI tools, you can maintain a single AGENTS.md and it will work with Claude Code automatically.

A key constraint: research suggests frontier LLMs can reliably follow around 150-200 instructions. Claude Code's system prompt already uses about 50 of those, so keep your CLAUDE.md concise — ideally under 300 lines.

AGENTS.md — The Cross-Tool Standard

AGENTS.md is the closest thing to a universal standard. It was popularised by OpenAI's Codex CLI and is now supported by:

• Codex CLI (primary config file)
• Cursor (reads alongside .cursorrules)
• Claude Code (fallback when no CLAUDE.md exists)
• Continue.dev, Aider, OpenHands

Codex CLI has the most sophisticated discovery process. It walks from your project root down to the current working directory, checking each level for AGENTS.md (or AGENTS.override.md for local overrides). You can configure fallback filenames and size limits in ~/.codex/config.toml:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

GEMINI.md — Gemini CLI

Gemini CLI uses GEMINI.md with a hierarchical discovery system similar to Codex:

1. ~/.gemini/GEMINI.md — Global defaults for all projects
2. Workspace root GEMINI.md — Project-level instructions
3. Subdirectory GEMINI.md files — Discovered dynamically when tools access files in those directories

A unique feature: you can inspect the loaded context at any time with the /memory show command, and force a reload with /memory refresh. The filename itself is configurable via settings.json if you prefer a different name.

.cursorrules / .cursor/rules/ — Cursor

Cursor has evolved through two formats:

Legacy: A single .cursorrules file in the project root. Still supported but deprecated.

Current (recommended): A .cursor/rules/ directory containing multiple .mdc files, each with its own scope:

• Always On — Applied to every interaction
• Auto Attached — Activated when matching files are open
• Model Decision — The AI decides whether to apply based on a description
• Manual — Only when explicitly mentioned via @

This is the most granular system — you can have frontend.mdc for React conventions and backend.mdc for API patterns, each activated only when relevant. Create rules quickly with the /rules slash command in Cursor's terminal.

copilot-instructions.md — GitHub Copilot

GitHub Copilot reads from .github/copilot-instructions.md for project-wide instructions. Since July 2025, it also supports scoped instructions via .github/instructions/*.instructions.md files with glob-pattern frontmatter:

---
applyTo: "**/*.tsx"
---
Use functional components with TypeScript interfaces.
Always use server components unless client interactivity is required.

This lets you define different rules for different file types — TypeScript vs Python, frontend vs backend — without cluttering a single file.

.windsurfrules / .windsurf/rules/ — Windsurf

Windsurf follows the same legacy-to-directory evolution as Cursor:

• Legacy: .windsurfrules in the project root
• Current: .windsurf/rules/ directory with individual rule files

Rules can be Always On, Manual (via @mention), or Model Decision. Note the character limits: individual rule files are capped at 6,000 characters, and total combined rules must not exceed 12,000 characters.

Which One Should You Use?

If your team uses a single AI tool, use that tool's native format. But most teams now use multiple tools — Cursor in the IDE, Claude Code in the terminal, Copilot for quick completions. Here's a practical approach:

your-project/
├── AGENTS.md              ← Universal instructions (works with Codex, Cursor, Claude Code)
├── CLAUDE.md              ← Claude-specific additions (if needed)
├── .github/
│   └── copilot-instructions.md  ← Copilot-specific (if your team uses it)
├── .cursor/
│   └── rules/             ← Cursor-specific scoped rules (if needed)
└── ...

Start with AGENTS.md as your single source of truth. It has the widest cross-tool support. Then add tool-specific files only when you need features that AGENTS.md can't provide (like Cursor's scoped activation or Copilot's glob patterns).

For Claude Code users: you can make your CLAUDE.md simply reference the shared instructions:

Strictly follow the rules in ./AGENTS.md

Writing Effective Instructions

The most common mistake is treating these files like comprehensive documentation. They're not — they're concise instructions that fit within a model's attention window. Here's what works.

What to Include

Build and test commands — The single most valuable thing you can provide:

## Commands
- Build: `npm run build`
- Test single file: `npm test -- path/to/test.ts`
- Lint: `npm run lint`
- Type check: `npx tsc --noEmit`

Tech stack and versions — Prevents the AI from guessing wrong:

## Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.7 (strict mode)
- Styling: Tailwind CSS 4.0
- Database: PostgreSQL 16 with Drizzle ORM
- Deployment: DeployHQ → Ubuntu 22.04 VPS

Project structure — Especially important for monorepos:

## Structure
- `apps/web/` — Next.js frontend
- `apps/api/` — Express API server
- `packages/shared/` — Shared types and utilities
- `infra/` — Terraform configuration

Critical conventions — Things the AI would otherwise get wrong:

## Conventions
- Use named exports, not default exports
- API routes return { data, error } shape
- Database migrations go in `drizzle/migrations/`
- Environment variables are validated in `src/env.ts`

What to Leave Out

Code style rules — Use ESLint, Prettier, and formatters instead. They're faster, deterministic, and don't consume your instruction budget.

Obvious things — Write clean code and follow best practices waste tokens. Be specific or don't include it.

Full API documentation — Link to it instead. Use a docs/ or agent_docs/ directory for supplementary context that the AI can pull in when needed.

Task-specific instructions — These belong in your prompt, not in a persistent config file.

A Deployment-Focused Example

Here's a complete AGENTS.md for a PHP team using DeployHQ:

## Project: Acme Web App

Laravel 11 application deployed via DeployHQ to Ubuntu 22.04 VPS.
Production: Nginx + PHP-FPM 8.3. Database: MySQL 8.

## Commands
- Run tests: `php artisan test --filter=TestName`
- Run all tests: `php artisan test`
- Lint: `./vendor/bin/pint`
- Static analysis: `./vendor/bin/phpstan analyse`
- DB migrate: `php artisan migrate`

## Deployment Rules
- Never modify production configs directly
- All database migrations must be reversible
- Run migrations before deploying code that depends on schema changes
- Include rollback steps in PR descriptions for risky changes
- Feature flags for anything touching payments or auth
- Run `composer install --no-dev` in production builds

## Structure
- `app/Services/` — Business logic (not in controllers)
- `app/Jobs/` — Background jobs (Laravel Queue)
- `app/Actions/` — Single-purpose action classes
- `deploy/` — DeployHQ build commands
- `tests/` — PHPUnit tests (mirror app/ structure)

## Conventions
- Action classes: single `handle()` method
- API responses: always use `JsonResource` classes
- Logging: use `Log::info()`, never `dd()` or `dump()`
- Secrets: use `config()` helper, never `env()` outside config files
- Validation: FormRequest classes, never inline in controllers

Common Mistakes

Writing a novel. If your config file is over 500 lines, most of it is being ignored. LLMs have limited instruction-following capacity — a focused 50-line file outperforms a sprawling 1,000-line one.

Duplicating across tools. Maintain one source of truth (AGENTS.md) and have tool-specific files reference it. Don't copy-paste the same rules into CLAUDE.md, .cursorrules, and copilot-instructions.md.

Using /init or auto-generators. Auto-generated config files tend to be generic and bloated. Write yours by hand — every line should earn its place by solving a real problem you've encountered.

Including things a linter handles. Use 2-space indentation and always add trailing commas are Prettier's job, not your AI config file's job.

Forgetting to update. These files rot just like any other documentation. When your stack changes, update the instructions. A wrong instruction is worse than no instruction.

Looking to automate your deployment pipeline? DeployHQ deploys code from Git to your servers automatically — one less thing to configure. Get started free.

Have questions? Reach out at support@deployhq.com or find us on X/Twitter.