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.
~/.claude/CLAUDE.mdYour 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
~/.codex/AGENTS.mdYour 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
AGENTS.mdProject 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
CLAUDE.mdClaude 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
src/AGENTS.mdFolder 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
.claude/skills/release/SKILL.mdA 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
~/.claude/projects/<repo>/memory/MEMORY.mdAuto 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
.claude/settings.jsonSettings 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
.claude/hooks/block-deploy.shA 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
.mcp.jsonMCP 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)
README.mdREADME 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.
docs/decisions.mdDecision 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.