Every Harness Reads a Different Instruction File; Keep One Source of Truth

The moment a team runs more than one coding harness, it hits a problem the vendors created and have only partly fixed: each harness reads a different instruction file. The same project conventions get duplicated into CLAUDE.md, AGENTS.md, .cursor/rules, and .github/copilot-instructions.md, the copies drift, and the agent that read the stale one does the wrong thing. The fix is not more files. It is one source of truth, bridged to the harnesses that insist on their own filename, kept short, and backed by enforcement that lives in the environment rather than in prose.

Each harness reads a different file

There is no shared default. The table below is what each major harness reads, with the source for each.

Some harnesses already read several formats. Copilot's coding agent reads AGENTS.md, CLAUDE.md, and GEMINI.md in addition to its own file, and Cursor's CLI reads AGENTS.md and CLAUDE.md alongside its rules. The outlier that matters most is Claude Code, which reads CLAUDE.md and not AGENTS.md.

AGENTS.md is the closest thing to a neutral standard

If you standardize on one file, standardize on the one no single vendor owns. AGENTS.md describes itself as "a README for agents," is used in "over 60,000 open-source projects" (up from the 20,000+ reported at its August 2025 launch), and emerged from a multi-vendor effort spanning OpenAI Codex, Google Jules, Cursor, Factory, and others. As of December 2025 it is stewarded by the Agentic AI Foundation under the Linux Foundation, whose Platinum members include AWS, Anthropic, Google, Microsoft, and OpenAI. The vendor whose harness does not read the file is a Platinum backer of the foundation that governs it. Nested files are supported: agents read the nearest one in the directory tree, so a monorepo can ship per-package instructions.

Claude Code reads CLAUDE.md, so bridge it with an import or a symlink

Anthropic's own guidance closes the gap without duplication. Claude Code reads CLAUDE.md, not AGENTS.md; if a repository already uses AGENTS.md, the documented move is to create a CLAUDE.md that imports it with @AGENTS.md, or, when no Claude-specific content is needed, to symlink the two with ln -s AGENTS.md CLAUDE.md. Running /init in a repository that already has an AGENTS.md reads it, and also ingests rival formats like .cursorrules and .windsurfrules.

Practitioners confirm both bridges work: in a Hacker News thread, Simon Willison reports keeping CLAUDE.md synced with AGENTS.md and that @AGENTS.md "dumps the content into the system prompt," while others report the symlink working cleanly. The one reported snag is that a symlinked CLAUDE.md occasionally confuses the agent into several iterations before it follows the link, so on Windows, where symlinks need elevated permissions anyway, prefer the @AGENTS.md import.

Imports and symlinks assume the agent can read the repo; a split brain cannot

The import, the symlink, and the rule sync all work the same way: the harness opens a file in the checkout it is working in. That holds when the agent runs on a laptop, or inside the sandbox next to the code. It stops holding under the brain/hands split, where placement puts the repo checkout, along with everything else data-sensitive, in the hands. On that topology the machine the harness runs on holds no code, so there is no local AGENTS.md to open, import, or symlink. The file's content has to reach a machine with no checkout at all.

Three ways to deliver it:

• Inject at boot. The control plane renders the project context (the committed instruction file, plus what it already knows about the environment: services, ports, named commands) into the brain's boot payload, and the brain writes the content to whichever filename its harness reads before spawning it. The model's first token already has the instructions. Per-turn brains make this the standard channel, since the brain is rebuilt every message anyway.
• Fetch on the first tool call. The brain reads the file out of the hands over the same tool interface it uses for everything else. No new machinery, but orientation now costs tool calls at the top of every session, and nothing guarantees the model spends them before it starts acting.
• Mirror an instructions-only tree. At provision time, sync the instruction files, and only those, into the brain's ephemeral filesystem with paths preserved, so the harness's native discovery, nested per-package files included, works unchanged. The cost is a copy that can go stale mid-session; per-task or per-turn disposal bounds how stale.

In every channel the committed file stays canonical and the delivered copy is per-boot output nobody edits.

Shorter is better, because bloated context files can hurt

The instinct to pour every convention into one file is wrong, and there is now evidence for it. An ETH Zurich study (February 2026) evaluating repository-level context files found that they "tend to reduce task success rates compared to providing no repository context, while also increasing inference cost by over 20%," and concluded that human-written context files "should describe only minimal requirements." Anthropic's own guidance targets "under 200 lines" and warns that longer files "consume more context and reduce adherence"; GitHub's is to keep each instruction "short and self-contained." Put the build command, the test command, the project layout, and the few always-do rules in the file. Move multi-step procedures into load-on-demand skills or path-scoped rules, and let the agent discover the rest from the code.

Put enforcement in the environment, not the instruction file

The most important rule about instruction files is what does not belong in them. An instruction file shapes behavior; it does not constrain it. Anthropic states the boundary directly: CLAUDE.md content "is delivered as a user message" with "no guarantee of strict compliance," and "to block an action regardless of what Claude decides, use a PreToolUse hook" or managed permissions.deny settings. The glossary states the same rule: instructions in a prompt or CLAUDE.md are not access control; only infrastructure-enforced boundaries count. A do-not-touch path, a production guardrail, a credential the agent must never see belong in the environment's settings and hooks, not in a markdown file the model is free to disregard. Prompt-level policy loses to environment-level defaults, which is the whole argument for why environments hold and prompts do not.

A multi-harness team syncs one rule format

The clearest public example is Stripe, which runs three harnesses and refused to maintain three rule files. As its engineers describe, they decided "to avoid duplication of rule files in favor of our agent reading the same context that human-directed agents use," standardized on Cursor's rule format, and now "sync our Cursor rules into a format that Claude Code can read as well, so that our three most popular coding agents (minions, Cursor, and Claude Code) can all benefit from the guidance." They also scope rules to subdirectories and file patterns rather than loading everything globally, which mirrors both the keep-it-short finding above and how scope is a function of what the environment can verify.

There is an architectural reason the portability matters beyond convenience. Anthropic argues the harness is a swappable component, that "harnesses encode assumptions about what Claude can't do" that "go stale as models improve". If the harness is interchangeable, the instructions that steer it should not be welded to one vendor's filename. Anthropic does not draw that conclusion itself, but the direction is the same one the Linux Foundation backing points at: the instruction layer is converging on a neutral file, and a team is better off standardizing now than maintaining four copies.