Concept · D1 Agentic Architectures + D3 Claude Code Configuration & Workflows · 47% of CCA-F
Are CLAUDE.md and AGENTS.md Portable Across AI Coding Tools?
First time I dropped a CLAUDE.md into a Codex repo I lost an afternoon to silent instruction drop. CLAUDE.md is Claude-specific. AGENTS.md is the emerging cross-tool pattern. Portability is partial - here is the boundary, the checklist, and the anti-pattern that costs candidates D1 points.
Loading your plan…
Mental modelUse AGENTS.md as the portable baseline; isolate tool-specific instructions and verify that every runtime actually reads them.
Last updated
Share
01 · Summary
TLDR
CLAUDE.md is a Claude-specific convention (read automatically by the Claude CLI and Claude Code at session start). AGENTS.md is an emerging cross-tool pattern recognized by OpenAI Codex, Cursor, and others. Neither is a ratified standard - portability is partial and tool-dependent. The CCA-F anti-pattern: assuming CLAUDE.md is automatically honored by non-Anthropic agents in a multi-agent pipeline.
02 · The boundary
Where CLAUDE.md ends and AGENTS.md begins
File
Read by
Status
Use when
CLAUDE.md
Claude CLI, Claude Code
Anthropic-specific
Your repo targets Anthropic tooling only.
AGENTS.md
OpenAI Codex, Cursor, several others (and Claude as a fallback)
Cross-tool emerging convention
Your repo is touched by multiple agentic IDEs or CLIs.
Both
Each tool reads its own; common content can live in AGENTS.md and be referenced from CLAUDE.md
Pragmatic dual-spec
Mixed-runtime teams where Claude-specific directives matter but cross-tool coverage is required.
Project-root placement - both files are discovered by the runtime walking up from the working directory.
Markdown prose - both are read as markdown, parsed conservatively, and surfaced to the model as context.
Instruction priority hierarchy - both honor section ordering as an implicit priority signal.
A well-structured AGENTS.md can be adopted by multiple runtimes with minimal editing as long as it sticks to these three conventions and avoids tool-specific directives.
04 · The portability checklist
Four steps to make instruction files portable
Use tool-agnostic markdown for the bulk of the file. Plain prose, code fences, lists - nothing runtime-flagged.
Isolate tool-specific sections under clearly labeled H2s (e.g., ## Claude-only directives) so other runtimes can ignore them by convention.
Version-control the file and test initialization behavior per tool you target. Do not assume; verify each runtime actually reads what you wrote.
Document which directives are no-ops outside Claude so future maintainers do not assume cross-tool effect that does not exist.
05 · What the exam tests
The agent-instruction-file vs system-prompt distinction
For the CCA-F, you must distinguish agent instruction files (persistent, file-system-resident context loaded at session start) from system prompts (runtime-injected, often per-request, sometimes dynamic). Portability breaks down precisely at this boundary - tools differ in how they inject or override file-based instructions, and confusing the two leads to D1 design errors.
Instruction files are the persistent layer. System prompts operate on top of them. A change to CLAUDE.md follows every future session for the project; a change to the system prompt applies only to the next call. Mixing the two in your head is the most common D1 conceptual error.
06 · Anti-pattern
The silent-instruction-loss failure mode
Assuming CLAUDE.md is honored by non-Anthropic agents
This is the canonical CCA-F D1 anti-pattern. In a multi-agent pipeline where a non-Anthropic runtime takes over part of the workflow, CLAUDE.md is silently ignored. The agent runs without the conventions you thought were binding, and the failure mode is invisible because no error is raised. Behaviors drift, conventions decay, and the cause is buried.
Mitigation: use AGENTS.md as the cross-tool baseline, and explicitly test each runtime against your instructions before relying on them in production.
07 · FAQ
Frequently asked
Showing 8 of 8 questions
Partial and tool-dependent. CLAUDE.md is a Claude-specific convention (read automatically by Claude CLI / Claude Code at session start). AGENTS.md is an emerging cross-tool pattern recognized by OpenAI Codex, Cursor, and several other agentic coding tools. Neither is a ratified standard - portability depends on which runtime reads which file, and on whether the instructions inside are written in tool-agnostic language.
CLAUDE.md is read by Anthropic tooling specifically. AGENTS.md is the broader cross-tool convention that competing agentic IDEs and CLIs have converged on. In repos targeting only Claude, CLAUDE.md is canonical. In repos targeting multiple agentic tools (Codex, Cursor, Aider, Claude Code), AGENTS.md is the portable baseline and CLAUDE.md typically references or extends it.
Three: (1) project-root placement so the runtime finds the file on session start, (2) markdown prose for human readability and tool-agnostic parsing, and (3) instruction priority hierarchy where earlier sections carry more weight. A well-structured AGENTS.md can be adopted by multiple runtimes with minimal editing as long as it sticks to these conventions and avoids tool-specific directives.
Anything that names a specific runtime's feature. Claude-specific examples: bash-permission blocks, MCP server declarations, slash-command references. Cursor-specific examples: composer rules, .cursorrules-style flags. Codex-specific examples: tool-allow lists in a particular schema. These must be conditionally gated or stripped for non-target agents - otherwise they become noise that pollutes the context window of the wrong runtime.
Agent instruction files (persistent, file-system-resident context loaded at session start) from system prompts (runtime-injected, dynamic, often per-request). Portability breaks down precisely at this boundary: tools differ in how they inject or override file-based instructions. The exam tests whether you understand that an instruction file is not a system prompt - it is the persistent layer that shapes what the system prompt then operates on.
Four steps: (1) use tool-agnostic markdown for the bulk of the file, (2) isolate tool-specific sections under clearly labeled H2s so other runtimes can ignore them, (3) version-control the file and test initialization behavior per tool you target, (4) document which directives are no-ops outside Claude so future maintainers do not assume cross-tool effect. This four-step pattern is the citable answer for portability questions on the exam.
Assuming CLAUDE.md is automatically honored by non-Anthropic agents in a multi-agent pipeline. This causes silent instruction loss - the agent runs without the conventions you thought were binding, and the failure mode is invisible because no error is raised. The exam classifies this as a D1 agentic-architecture failure mode. The mitigation is to use AGENTS.md (or both files) and to explicitly test each runtime against your instructions before relying on them.
D1 (Agentic Architectures, 27%) and D3 (Claude Code Configuration & Workflows, 20%). D1 questions test whether you can design a multi-tool agentic pipeline that does not silently drop instructions when an agent switches runtimes. D3 questions test whether you can detect and debug the silent-instruction-loss failure mode in production observability.
