NAME
AGENTS.md — instruction file for GitHub Copilot, OpenAI Codex CLI, Lovable
SYNOPSIS
~/.codex/AGENTS.md
./AGENTS.md
./<subdir>/AGENTS.md
METADATA
DESCRIPTION
AGENTS.md is a shared instruction file read by both GitHub Copilot and OpenAI Codex CLI (as well as Lovable and other tools). It follows a similar philosophy to CLAUDE.md — a Markdown file committed to your repository that tells AI agents how to work with your codebase.
The critical behavioral difference between tools is the scoping model. Codex CLI concatenates all AGENTS.md files from the Git root down to the current working directory, with later files overriding earlier guidance. Each file appears as its own user-role message with a header like '# AGENTS.md instructions for <directory>'. GitHub Copilot uses nearest-ancestor-only resolution — it walks up from the current file and uses only the first AGENTS.md it finds, ignoring all parent files.
Codex CLI also supports AGENTS.override.md at each directory level: if found, the regular AGENTS.md in that directory is skipped. This enables personal overrides without modifying team files. Additionally, Codex supports fallback filenames (configurable via project_doc_fallback_filenames in config.toml) and a configurable max file size (project_doc_max_bytes, default 64KB).
AGENTS.md has no special syntax — it is plain Markdown. There are no include directives, no YAML frontmatter, and no glob patterns.
Lower numbers load first. Higher-priority files override lower ones.
STRUCTURE
ANNOTATED EXAMPLE
1# AGENTS.md
2
3## Project Overview
4
5This is a Next.js 14 e-commerce application using the App Router,
6Server Components, and Drizzle ORM with PostgreSQL.
7
8## Code Conventions
9
10- Use TypeScript strict mode throughout
11- Prefer Server Components; use "use client" only when necessary
12- Name files with kebab-case: `product-card.tsx`, not `ProductCard.tsx`
13- Co-locate tests: `product-card.test.tsx` next to `product-card.tsx`
14
15## Architecture
16
17- `app/` — Next.js App Router pages and layouts
18- `components/` — Shared UI components
19- `lib/` — Utilities, database client, auth helpers
20- `actions/` — Server Actions for mutations
21
22## Testing
23
24- Use Vitest for unit tests, Playwright for E2E
25- Mock database calls using `lib/test-utils.ts` helpers
26- Every new component needs at least one test
27
28## Build Commands
29
30```bash
31pnpm dev # Start dev server
32pnpm build # Production build
33pnpm test # Run Vitest
34pnpm test:e2e # Run Playwright
35pnpm lint # ESLint check
36```
COMMON MISTAKES
Like CLAUDE.md, the filename must be exactly AGENTS.md with uppercase letters. Both Codex CLI and GitHub Copilot look for this exact name.
This is a critical difference. Codex CLI walks from the Git root down to CWD and concatenates ALL AGENTS.md files found along the path — later files override earlier ones. GitHub Copilot uses nearest-ancestor-only: it walks up from the current directory and uses only the first AGENTS.md it finds, ignoring parent files entirely. Subdirectory files must be self-contained for Copilot but can be incremental for Codex.
There is no include directive. If you need to reference other documentation, link to it or copy the relevant sections directly into the file.
Codex CLI checks for AGENTS.override.md before AGENTS.md at each directory level. If the override file exists, AGENTS.md in that same directory is skipped entirely. This allows personal customizations without modifying team files. Not supported by GitHub Copilot.
Codex CLI enforces a configurable max bytes limit (default 65536) when building project instructions. AI agents read this on every interaction, so verbose files waste context window. You can adjust the limit in ~/.codex/config.toml.
Codex CLI can be configured to look for alternative filenames like TEAM_GUIDE.md or .agents.md via the project_doc_fallback_filenames setting in config.toml. These are only checked if no AGENTS.md or AGENTS.override.md is found. GitHub Copilot only looks for AGENTS.md.