Atlas ADE DOCS
Docs / Field guide / Setting up CLAUDE.md and AGENTS.md

Setting up CLAUDE.md and AGENTS.md

Published 29/10/2026

Both engines read a plain markdown file at the start of every session: Claude Code reads CLAUDE.md, Codex reads AGENTS.md. Think of it as the note taped to the workbench for whoever picks up the tools next. It works when it is short, current and about the bench itself, not a diary of everything that happened there.

One file for both engines#

Keep AGENTS.md as the shared file, and give Claude Code a CLAUDE.md that imports it and adds anything Claude-only:

MARKDOWN
@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

Claude Code also reads AGENTS.md on its own when a folder has no CLAUDE.md. Once both exist, it reads only CLAUDE.md, so the import line is what keeps the two in step.

How each engine loads them#

Claude CodeCodex
Where it looksthe working folder and every folder above it; sub-folders load when the agent works in them~/.codex, then each folder from the project root down to where it runs
Several filesall joined, root first, so the nearest file is read lastone per folder, root first; AGENTS.override.md beats AGENTS.md in its folder
Sizeaim for under 200 lines a filestops adding files at 32 KiB in total (project_doc_max_bytes)
Starter/init/init

An edit to the file mid-session doesn't reach the running conversation. Claude Code picks it up after /clear, /compact or a restart.

What belongs in it#

Write what an agent can't work out from the code, concretely enough to check:

  • the commands to build, test and lint, exactly as typed;
  • where things live, when it isn't obvious;
  • rules that are easy to break, each with its reason: "never edit migrations/ by hand: they are generated".

Leave out anything that changes: what is in progress, the last deploy, today's test count. That is state, and state in prose is stale within a day.

Docs of record, and keeping prose fresh#

Every page of prose an agent reads is a surface that can go stale, and an agent trusts it without checking. A few rules keep that small:

  • One owner per fact. Each fact lives in one file; every other mention points there. When two files disagree, the owner wins and the other gets fixed.
  • Derive, don't cache. "Run git log -1 for the current head" never goes stale. "The head is a1b2c3" does.
  • Generate numbers from their source. If a limit lives in config, the docs read it from config when they are built.
  • Date what you observe, with a day to check it again.
  • Audit it. In Claude Code, /doctor prompt-audit looks through your instruction files for outdated or conflicting lines and missing paths, and proposes edits without making them.

Where ADE fits#

ade init writes AGENTS.md and the Claude Code agent files from one roster in ade.toml, so the two engines can't drift apart. Project state (open cards, decisions, observations) goes into records rather than the instruction file, and reaches each session through a generated handover. This site follows the same rule: its limits and figures are read from the kit's own files when it is built. See How it flies.

PREVIOUSDay to day