Claude Certified Architect PrepGet certified in 6 months · start now
Sign inSign up free
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.

Last updated

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

FileRead byStatusUse when
CLAUDE.mdClaude CLI, Claude CodeAnthropic-specificYour repo targets Anthropic tooling only.
AGENTS.mdOpenAI Codex, Cursor, several others (and Claude as a fallback)Cross-tool emerging conventionYour repo is touched by multiple agentic IDEs or CLIs.
BothEach tool reads its own; common content can live in AGENTS.md and be referenced from CLAUDE.mdPragmatic dual-specMixed-runtime teams where Claude-specific directives matter but cross-tool coverage is required.
03 · What is shared

The conventions both files agree on

  • 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

  1. Use tool-agnostic markdown for the bulk of the file. Plain prose, code fences, lists - nothing runtime-flagged.
  2. Isolate tool-specific sections under clearly labeled H2s (e.g., ## Claude-only directives) so other runtimes can ignore them by convention.
  3. Version-control the file and test initialization behavior per tool you target. Do not assume; verify each runtime actually reads what you wrote.
  4. 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

Are CLAUDE.md and AGENTS.md conventions portable across other AI coding tools?
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.
What is the practical difference between CLAUDE.md and AGENTS.md?
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.
What conventions are shared across both files?
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.
Which tool-specific directives break portability?
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.
What does the CCA-F want me to distinguish?
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.
What is the practical portability checklist?
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.
What is the anti-pattern flagged on the CCA-F?
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.
Where does this concept land on the exam blueprint?
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.