Agent Atlas

Atlas · agents

Instruction files

AGENTS.md, CLAUDE.md and their relatives: text the harness loads before your request.

Established practiceDepth 1 of 4Reviewed 2026-11-08

See it working: Plate II, Plate III

In plain words

An instruction file is a note for the agent that lives in your project. The harness reads it before your first message, so its rules apply from the start.

How it works

Codex searches for AGENTS.md from the project root down to the folder you launch in. Claude Code reads CLAUDE.md, loads nested ones on demand, and reads AGENTS.md directly only when there is no CLAUDE.md in the folder or above it. A CLAUDE.md can import AGENTS.md with a line like @AGENTS.md.

Going deeper

Everything loaded at the start is paid for on every turn. Keep these files short, point to deeper documents, and keep each fact in one place. Plate II lets you see the cost.

Sources

  1. How Claude remembers your project Anthropic
    • Personal preferences for all projects
    • using @path/to/import syntax.
    • Files in subdirectories load on demand.
    • no CLAUDE.md in your working directory or above it.
    • target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.
    • Imports help you organize a long file but don’t reduce its context cost, because imported files load together with the CLAUDE.md that imports them.
    • Auto memory lets Claude accumulate knowledge across sessions without you writing anything.
    • The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation.
  2. Custom instructions with AGENTS.md OpenAI
    • defaults to ~/.codex
    • Codex stops searching once it reaches your current directory
    • Codex includes at most one file per directory.

Quotes were checked against the live pages on 2026-11-08.