How to Structure AGENTS.md as an Index for AI Agents

You will structure your root AGENTS.md as an index under 200 lines that delegates deep instructions to targeted reference files. Keeping standing instructions compact prevents modern high-intelligence LLMs from diluting adherence, wasting context tokens, or thrashing prompt caches across platforms like Claude Code, Gemini CLI, Cursor, or Codex. Modern agents navigate file trees effectively, so standing files must index essentials rather than duplicate documentation.

Before you start

An AI coding agent or platform supporting instruction files, such as Cursor, Claude Code, Gemini CLI, or GitHub Copilot.
A git repository with established build and test commands.

How it works

flowchart LR
  A[Session starts] --> B[Read root AGENTS.md index]
  B --> C[Execute core build and test commands]
  B --> D{Task requires deep domain rules?}
  D -- yes --> E["Read referenced manual in docs/"]
  D -- no --> F[Proceed without extra context]

Step 1: Write the core AGENTS.md index

Put essential metadata, commands, and guardrails in AGENTS.md at the repository root. Modern LLMs have higher reasoning capacity and do not need basic language syntax explained; they need project-specific commands, directory layouts, and hard boundaries.

# AGENTS.md

## Project Overview
Next.js 16 application using App Router, Tailwind CSS, and TypeScript.
- Database: PostgreSQL via Prisma ORM.
- Architecture: See `docs/architecture.md` for system diagrams.

## Commands
Run all commands from repository root.
- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test`
- Single Test: `pnpm vitest run -t "<test_name>"`
- Lint: `pnpm lint --fix`

## Directory Structure
- `src/app/`: Routes and UI pages.
- `src/lib/db/`: Database schemas and client.
- `docs/`: Reference documentation loaded on demand.

## Guardrails
- DO NOT edit `src/generated/` manually.
- DO NOT force-push (`git push -f`) to `main` or `dev`.
- DO NOT commit secrets; follow `.env.example`.
- DO NOT install new dependencies without approval.

Step 2: Offload detailed specifications to on-demand files

Do not place long API schemas, styling guidelines, or testing manuals in the standing instruction file. Place them in a docs/ folder and link to them so modern agents read them only when relevant to the task.

Create docs/conventions.md:

# Coding Conventions

## State & Data
- Use React Server Components by default; add 'use client' only when state or lifecycle hooks are required.
- Use Server Actions for mutations; do not expose database clients to the client bundle.

## Styling
- Use Tailwind utility classes. Do not write custom CSS files.

Step 3: Manage monorepos with nested instruction files

In monorepos or multi-package projects, keep the root AGENTS.md focused on repository-wide commands. Place secondary AGENTS.md files in subdirectories so agents read localized context when operating within those paths.

├── AGENTS.md
├── apps/
│   ├── api/
│   │   └── AGENTS.md
│   └── web/
│       └── AGENTS.md

Step 4 (optional): Connect multi-agent tool configs to AGENTS.md

If your team uses multiple AI coding tools alongside universal agents, route tool-specific files back to AGENTS.md rather than maintaining duplicate instruction files.

For Claude Code, create CLAUDE.md:

@AGENTS.md

For tools requiring symlinks, link to the root file:

ln -s AGENTS.md .cursorrules

Step 5 (optional): Enforce line limits in CI

To prevent instruction bloat from accumulating over time, add a check to your continuous integration pipeline that flags AGENTS.md when it exceeds 200 lines.

test $(wc -l < AGENTS.md) -le 200

Common mistakes

Treating AGENTS.md as an API manual. Modern LLMs already understand public library documentation and standard framework patterns. Use AGENTS.md only for repository-specific deviations, commands, and constraints.
Letting the file exceed 200 lines. Bloated instruction files fill context windows, dilute adherence to critical guardrails, and cause prompt-cache misses on every request. Keep the index under 150 to 200 lines.
Duplicating instructions across tool-specific files. Maintaining separate instructions for Cursor, Claude Code, Copilot, and Gemini leads to configuration drift. Use AGENTS.md as the single source of truth and link to it.
Omitting executable commands. Agents struggle when guessing package managers or test flags. Explicitly specify build, test, and lint commands.