Agent Atlas

Reference

Field guide to agent files

Each specimen below is a file you will meet in projects built with coding agents. The same entries power Plate II, where you can watch them load.

  1. ~/.claude/CLAUDE.md

    Your personal Claude Code instructions Factual

    Preferences that follow you into every project: how you like answers written, tools you always use.

    Claude Code
    Loaded into the context when the session starts, every time.
    Codex
    This harness does not use it.
    Committed to Git
    No
    - Explain commands before running them.
    - I use pnpm, not npm.

    Watch out: Putting project facts here, where every other project also sees them.

    How we know: Claude Code memory documentation.

    Sources: How Claude remembers your project

  2. ~/.codex/AGENTS.md

    Your personal Codex instructions Factual

    The Codex equivalent of a personal instruction file.

    Claude Code
    This harness does not use it.
    Codex
    Loaded into the context when the session starts, every time.
    Committed to Git
    No
    - Prefer small commits.
    - Ask before adding dependencies.

    Watch out: Assuming Claude Code reads it. It lives in Codex’s own folder.

    How we know: Codex AGENTS.md documentation.

    Sources: Custom instructions with AGENTS.md

  3. AGENTS.md

    Project instructions for any agent Factual

    The map of the project: how to build and test it, rules that are easy to break, and where the deeper documents live. Shared by every agent and every teammate.

    Claude Code
    Loaded into the context when the session starts, every time.
    Codex
    Loaded into the context when the session starts, every time.
    Committed to Git
    Yes
    # My app
    - Run `npm test` before you call anything done.
    - Never edit files in `generated/`.
    - Architecture: docs/architecture.md

    Watch out: Writing an encyclopedia. Every line is paid for on every turn of every session.

    How we know: Codex: AGENTS.md documentation. Claude Code: tested in fresh headless sessions of 2.1.319 on 2026-11-08 with codeword files. With no CLAUDE.md, AGENTS.md loaded at the start. With a CLAUDE.md beside it and no import line, AGENTS.md was ignored.

    Sources: Custom instructions with AGENTS.md, How Claude remembers your project

  4. CLAUDE.md

    Claude Code’s project file Factual

    Claude Code’s own instruction file. A common pattern is one line, @AGENTS.md, which imports the shared file so the rules live in one place.

    Claude Code
    Loaded into the context when the session starts, every time.
    Codex
    This harness does not use it.
    Committed to Git
    Yes
    @AGENTS.md

    Watch out: Having both files without the @AGENTS.md line. In our test Claude Code then read only CLAUDE.md and ignored AGENTS.md completely.

    How we know: Observed in Claude Code 2.1.319 on 2026-11-08, in the session that built this page. This repository’s CLAUDE.md is exactly that one import line, and both files appeared in context. In a separate test, a CLAUDE.md without the import line meant AGENTS.md never loaded.

    Sources: How Claude remembers your project

  5. src/AGENTS.md

    Folder rules Simplified

    Rules that only matter inside one folder, such as how the database code must be tested.

    Claude Code
    Not loaded automatically. The agent reads it only if something points it there.
    Codex
    Loaded at the start only when you launch the session in that folder or below it.
    Committed to Git
    Yes
    - Every query goes through `db.ts`.
    - Migrations are never edited after merge.

    Watch out: Assuming every harness finds it. Point to it from the root file so any agent knows it exists.

    How we know: Claude Code 2.1.319, fresh headless sessions on 2026-11-08: with only AGENTS.md files, sub/AGENTS.md loaded when the agent read a file in sub/. With a CLAUDE.md at the root, sub/AGENTS.md did not load. This example repo has a CLAUDE.md, so it shows the second case. Codex CLI 0.167.0, startup input captured on 2026-11-08: launching in src/ included the root and src/ files, root first. Launching at the root left src/AGENTS.md out, even when the request named a file in src/. An AGENTS.override.md in src/ replaced src/AGENTS.md. Whether Codex reads it later, on file access, was not tested.

    Sources: Custom instructions with AGENTS.md, How Claude remembers your project

  6. .claude/skills/release/SKILL.md

    A skill Factual

    A recipe for one kind of task, such as cutting a release. Its short description is always visible, so the agent knows it exists. The long body loads only when needed.

    Claude Code
    Only a one-line description loads at the start. The full file loads when a task matches it.
    Codex
    This harness does not use it.
    Committed to Git
    Yes
    ---
    name: release
    description: Use when publishing a new version.
    ---
    1. Run the full test suite.
    2. Update CHANGELOG.md.
    3. Tag the commit.

    Watch out: A vague description. The description is the trigger; if it does not match how people ask, the skill never loads.

    How we know: Observed in Claude Code 2.1.319 on 2026-11-08, in the session that built this page. Skill names and descriptions were listed at the start; a skill’s full text arrived only when it was invoked. Codex CLI 0.167.0 listed skills from .agents/skills and .codex/skills, never .claude/skills, and no skill body was in its startup input.

    Sources: Extend Claude with skills, Agent Skills specification, Build skills

  7. ~/.claude/projects/<repo>/memory/MEMORY.md

    Auto memory index Factual

    Notes the agent keeps for itself across sessions, about you and your preferences. The index loads every time; each note is its own small file.

    Claude Code
    Loaded into the context when the session starts, every time.
    Codex
    This harness does not use it.
    Committed to Git
    No
    - [Preview URLs](previews.md): tailnet ports per project

    Watch out: Storing project facts here instead of in the repository, where teammates and other agents can see them.

    How we know: Observed in Claude Code 2.1.319 on 2026-11-08, in the session that built this page. The memory index was loaded into the session’s instructions.

    Sources: How Claude remembers your project

  8. .claude/settings.json

    Settings and permissions Factual

    Configuration the harness enforces: which commands are allowed, which need approval, which hooks run. The model never reads it, so it cannot argue with it.

    Claude Code
    Never enters the context. The harness reads it and acts on it.
    Codex
    This harness does not use it.
    Committed to Git
    Yes
    {
      "permissions": { "deny": ["Bash(rm -rf:*)"] }
    }

    Watch out: Writing "never delete files" in AGENTS.md and assuming that is a lock. It is a request.

    How we know: Claude Code settings and permissions documentation.

    Sources: Settings files and precedence, Configure permissions

  9. .claude/hooks/block-deploy.sh

    A hook Factual

    A script the harness runs at a set moment, for example before every shell command. It can block the command and explain why. Enforcement, not advice.

    Claude Code
    Never enters the context. The harness reads it and acts on it.
    Codex
    This harness does not use it.
    Committed to Git
    Yes
    case "$COMMAND" in
      *"wrangler deploy"*) echo "Deploys need a human." >&2; exit 2 ;;
    esac

    Watch out: A hook that blocks without saying why. The message is what the agent reads to recover.

    How we know: Observed in Claude Code 2.1.319 on 2026-11-08, in the session that built this page. A command-guard hook blocked one of the commands used to build this page and returned its reason to the agent.

    Sources: Hooks reference

  10. .mcp.json

    MCP servers Simplified

    Connects extra tools, such as a database or an issue tracker, through the Model Context Protocol. Each tool’s description costs context, so newer harnesses load some of them lazily.

    Claude Code
    Loaded into the context when the session starts, every time.
    Codex
    This harness does not use it.
    Committed to Git
    Yes
    {
      "mcpServers": { "tracker": { "command": "tracker-mcp" } }
    }

    Watch out: Connecting twenty servers “just in case”. Their tool descriptions crowd the window.

    How we know: Observed in Claude Code 2.1.319 on 2026-11-08, in the session that built this page. Some tools were listed by name only, with their full definitions fetched on request.

    Sources: Connect Claude Code to tools via MCP, Model Context Protocol: Tools (2025-06-18)

  11. README.md

    README Factual

    For humans arriving at the project. Agents read it only if they decide to, or if an instruction file points there.

    Claude Code
    Not loaded automatically. The agent reads it only if something points it there.
    Codex
    Not loaded automatically. The agent reads it only if something points it there.
    Committed to Git
    Yes
    # My app
    A small web app. Run `npm install` then `npm run dev`.

    Watch out: Putting agent rules only in the README and wondering why agents ignore them.

    How we know: Follows from the load rules above: neither harness lists README among its instruction files.

  12. docs/decisions.md

    Decision log Factual

    Why things are the way they are. Too big to load every session, so the instruction file points to it and the agent reads it when a task needs it. This is progressive disclosure.

    Claude Code
    Not loaded automatically. The agent reads it only if something points it there.
    Codex
    Not loaded automatically. The agent reads it only if something points it there.
    Committed to Git
    Yes
    ## 2026-11-07 Static site
    No backend until a feature needs one.

    Watch out: Pasting the whole log into AGENTS.md.

    How we know: A convention, not a harness feature.

    Sources: Effective context engineering for AI agents