AGENTS.md vs CLAUDE.md: Can One File Control Every AI Coding Agent?

AI coding agents are converging on a simple repository primitive: a Markdown file that tells the agent how the project works. Claude Code's new AGENTS.md fallback makes an important question practical: can teams maintain one portable instruction file instead of duplicating the same rules for every coding agent?

Why AGENTS.md matters now

Repository-level instructions are becoming part of the interface between a codebase and an AI agent. They can describe commands, architecture boundaries, test requirements, style rules and files an agent should avoid touching.

The problem is fragmentation. Tool-specific instruction files make sense when an agent needs unique configuration, but duplicating ordinary project knowledge across several files creates drift. If one file says to use pnpm and another still says npm, the agent's behavior depends on which tool a developer happens to launch.

Claude Code adding AGENTS.md fallback is therefore more interesting than a small convenience feature. It gives teams another path toward a shared baseline that can travel between agent environments.

AGENTS.md vs CLAUDE.md

Question	AGENTS.md	CLAUDE.md
Goal	Portable repository instructions	Claude-specific project instructions
Best content	Build, test, architecture, conventions	Claude-specific behavior or workflow
Portability	Designed to be useful across supporting agents	Primarily Claude Code
Duplication risk	Lower if used as shared baseline	Higher when common rules are copied into multiple agent files
Tool-specific control	Limited to what consuming tools understand	Better place for Claude-specific instructions

The pattern we recommend testing

repository/
├── AGENTS.md          # shared project contract
├── CLAUDE.md          # only Claude-specific additions, if required
├── package.json
├── src/
└── tests/

The useful mental model is AGENTS.md as the portable project contract, not a dumping ground for every prompt trick. Put stable facts about the repository in the shared layer. Keep vendor-specific behavior separate only when it is genuinely necessary.

What belongs in a portable agent file?

Build and test commands

Tell agents the exact commands that prove a change works. Prefer commands they can execute over prose such as "make sure tests pass."

## Verification
- Install: pnpm install --frozen-lockfile
- Type check: pnpm typecheck
- Unit tests: pnpm test
- Production build: pnpm build

Architecture boundaries

Describe constraints that are expensive to rediscover from source code: which layer owns database access, where shared types live, whether services can import UI code, and which generated directories must not be edited.

Change boundaries

Explicitly list dangerous or irrelevant areas. An instruction such as "do not modify migrations unless the task requires a schema change" is easier to verify than a vague request to be careful.

Repository conventions

Package manager, naming rules, test placement, error handling and preferred APIs are good shared instructions because they should remain true regardless of which coding agent is used.

What should stay tool-specific?

Do not force every instruction into AGENTS.md just to achieve a single-file ideal. Tool-specific hooks, permission behavior, custom commands, memory semantics or features understood by only one agent can remain in that tool's native configuration.

The objective is not literally one file. It is one source of truth for shared repository knowledge.

The AiFolder cross-agent benchmark

We are preparing a controlled repository test. Each agent receives the same codebase, same task description and equivalent access to tools. The shared instruction file remains unchanged.

Task 1 — Architecture convention

Add a feature that could be implemented in several layers. We measure whether the agent follows the repository's documented dependency boundaries.

Task 2 — Code style

Introduce a small API change with explicit naming and error-handling conventions. We count violations rather than judging style subjectively.

Task 3 — Forbidden files

Create a task where editing a generated or protected file looks tempting. A successful agent must solve the task without touching it.

Task 4 — Verification requirements

Require a type check, targeted tests and production build. We record which commands were actually run and whether failures were resolved.

Task 5 — Project-specific command

Give the repository a non-obvious command that cannot reliably be guessed from generic ecosystem knowledge. This tests whether the agent retrieves and uses repository instructions instead of relying on priors.

Metrics we will publish

• Task success rate — does the final change satisfy the acceptance tests?
• Instruction-following rate — percentage of explicit rules followed.
• Hard violations — protected files, forbidden dependencies or skipped required checks.
• Human interventions — corrections needed before completion.
• Context/token usage where the agent exposes reliable usage data.
• Unrelated changes — files or behavior changed outside task scope.
• Setup duplication — how much tool-specific configuration remains necessary.

The conflict test is the most important one

Real repositories will not instantly become clean. Some will contain AGENTS.md plus older tool-specific instructions. So we will deliberately create conflicting rules and document which instruction wins in each agent.

For example, AGENTS.md may require pnpm test while a legacy tool file says npm test. The benchmark will record the observed precedence instead of assuming that all agents merge instructions in the same way.

Can one AGENTS.md really control every coding agent?

Not completely. Support, discovery rules, precedence and vendor-specific features can differ. A portable file can nevertheless remove a large category of duplicated repository context if agents consistently consume the same core instructions.

That distinction matters: interoperability does not require every agent to behave identically. It requires teams to avoid rewriting stable project knowledge for each tool.

A minimal AGENTS.md template

# Repository instructions

## Stack
- Node.js 24
- TypeScript
- pnpm

## Architecture
- Keep database access inside the data layer.
- Do not import UI modules from services.

## Commands
- Type check: pnpm typecheck
- Test: pnpm test
- Build: pnpm build

## Change rules
- Do not edit generated files.
- Keep changes scoped to the requested task.
- Add or update tests for behavior changes.

## Before finishing
1. Run the relevant tests.
2. Run the type checker.
3. Report any verification you could not run.

A future AiFolder tool: AGENTS.md Generator + Validator

This trend also maps naturally to a practical AiFolder utility. A generator could inspect framework and package metadata, suggest build/test commands and produce a conservative starting file. A validator could flag contradictory commands, missing verification steps, overly broad instructions and duplicated rules across agent-specific files.

The useful version should not pretend to understand an entire repository automatically. It should generate an auditable draft and explain where each recommendation came from.

Frequently asked questions

Should I replace CLAUDE.md with AGENTS.md today?

Not automatically. Move stable cross-tool repository knowledge only after checking the behavior and precedence rules of the agents your team actually uses. Keep Claude-specific configuration where it provides value.

Should AGENTS.md contain coding style rules?

Only the important, repository-specific rules that cannot be enforced more reliably by formatters, linters or tests. Executable enforcement is preferable to long prose whenever possible.

Can AGENTS.md replace documentation?

No. It should be a compact operational contract for agents, with links or pointers to deeper architecture documentation when needed.

How will AiFolder compare agents fairly?

We will use the same repository snapshot, tasks and acceptance tests, record agent/version information and separate deterministic test results from subjective observations.

Related AiFolder guides

• Best AI VS Code extensions — coding-agent workflows inside the editor.
• OpenAPI to SDK, CLI and MCP — deterministic interfaces for agent tooling.
• Jev vs LLMs for AI decisions — testing which agent decisions need a generative model.
• AI coding tools — the broader AiFolder coding-agent cluster.

Methodology and freshness

Checked September 22, 2026. Claude Code's recent release behavior is the trigger for this article. Cross-agent benchmark numbers are intentionally not invented: AiFolder will add first-hand results only after running the controlled tests and recording exact tool versions, repository commit, instructions and acceptance criteria.