CLAUDE.md, AGENTS.md & Copilot Instructions: Configure Every AI Coding Assistant

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 — CLAUDE.md, AGENTS.md, GEMINI.md, copilot-instructions.md, Cursor rules, and Windsurf rules — explains how each discovery process works, 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, discovery order, and how each handles 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 file (the claude md global file that applies to every project on your machine)
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.

You can also place a CLAUDE.md inside .claude/ at the project root for settings you want separated from the canonical top-level file — Claude Code will load .claude/CLAUDE.md alongside the root one.

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. Originally popularised by OpenAI's Codex CLI, it's now an open format stewarded by the Linux Foundation with adoption across 60,000+ open-source projects. It's 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 discovery: AGENTS.md, AGENTS.override.md, and config.toml

Codex CLI has the most sophisticated discovery process of any coding agent. It walks from your project root down to the current working directory, checking each level for AGENTS.md. Alongside each AGENTS.md, it will also load an AGENTS.override.md file if one exists — that's the mechanism for local-only overrides you don't want committed to git (personal tweaks, machine-specific paths, experiment flags).

You can configure discovery behaviour in ~/.codex/config.toml:

# Fallback filenames Codex will try if AGENTS.md is missing in a directory
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Hard cap on how many bytes of doc content Codex will load per file
project_doc_max_bytes = 65536

• project_doc_fallback_filenames tells Codex which alternative filenames to look for when there's no AGENTS.md in a directory. Useful when your team already has an established doc filename and you don't want to rename everything.
• project_doc_max_bytes controls the per-file size limit (default: 32 KiB on older versions, 64 KiB on current). Anything past the cap is silently truncated, which is why a sprawling 500-line instruction file often stops working on recent Codex releases.

The practical rule: AGENTS.md is committed and shared, AGENTS.override.md is gitignored and personal, and the config knobs let you adapt without renaming files.

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.

CLAUDE.md vs AGENTS.md vs copilot-instructions.md

The three files that most teams end up choosing between are CLAUDE.md, AGENTS.md, and copilot-instructions.md. They overlap in purpose but differ in reach and mechanics:

CLAUDE.md or AGENTS.md? If your team uses Claude Code alongside any other agent, start with AGENTS.md and let Claude Code fall back to it. Only add a CLAUDE.md when you have Claude-specific instructions that shouldn't leak to Codex or Cursor sessions — things like use the Serena MCP server for symbol navigation or prefer `Task` tool over bash for searches.

CLAUDE.md vs copilot-instructions.md? They don't compete. If you use both tools, write AGENTS.md for Claude Code and copilot-instructions.md for Copilot, and keep the two narrowly focused on what each tool actually needs. Copilot's glob-scoped .github/instructions/*.instructions.md files are unique and worth using for frontend-vs-backend rule splits.

The copilot equivalent of CLAUDE.md is .github/copilot-instructions.md — same idea (persistent project-wide instructions), different filename and location.

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)
├── AGENTS.override.md     ← Local-only overrides (gitignored)
├── 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

If you're still evaluating which CLI to standardise on, our Claude Code vs Codex CLI vs Gemini CLI comparison walks through the tradeoffs in more depth.

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`

For a deeper treatment of what belongs in each section, see our guide on developer CLIs that AI coding agents use well — the CLI inventory it covers is exactly what goes in the Commands block.

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 automatic deployments from Git:

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

If you're already thinking about wiring these agents into CI, our walkthrough on running AI coding agents in CI/CD headless mode shows how AGENTS.md carries through to automated pipelines.

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. Codex CLI will also silently truncate anything past project_doc_max_bytes, so oversized files actively lose context.

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.

Committing AGENTS.override.md. The override file is meant for local, machine-specific tweaks. Add it to .gitignore the same day you create one — once it's committed, it stops being an override and becomes another source of drift.

Looking to automate your deployment pipeline? DeployHQ deploys code from Git to your servers automatically — one less thing to configure, with automated deployments straight from your repository. Get started free.

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