Agent instruction files compared

Many of the formats recorded in this wiki do the same basic job. Each holds text that a coding agent loads as standing context, so that a project’s conventions do not have to be retyped every session. They differ in which tools read them, where they live, when their content enters the context, and what they are meant to hold. This page sets them side by side: AGENTS.md, CLAUDE.md, AGENT.md, GEMINI.md, GitHub Copilot’s instruction files, the per-IDE rule directories of AI IDE Rules, DESIGN.md, the file types of Agent Primitives, MentorScript, and the umbrella term Memory bank. It then covers how the wiki’s sources say these files load, how they split the context, what they say belongs in a file, how files are kept current, what the files are used for beyond coding, how they can be attacked, and what the evidence measures. It draws out differences and does not rank the formats.

Side by side

Format	Read by	Where it lives and how far it reaches	What it is meant to hold	Standing
AGENTS.md	Any agent that supports it; the format’s project calls it a README for agents	Conventionally the repository root; the codex-1 system message lets it appear anywhere, scoped to the directory tree below it, with a more deeply nested file taking precedence	Concrete commands and conventions — the project’s minimal example has dev environment tips, testing instructions and pull-request instructions	Open format published under MIT; described as donated to the Linux Foundation in December 2025
CLAUDE.md	Claude Code	Four scopes (managed policy, user, project, personal local); a root file loads at session start and is re-read after compaction, a subdirectory file loads when Claude reads a file there; files up the directory tree are concatenated rather than overriding one another	Standing project facts: build commands, directory layout, conventions, team norms	One vendor’s product mechanism
AGENT.md	Amp natively; several other tools through symbolic links, per its specification	MUST sit at the project root; implementations SHOULD support a hierarchy including a user-global ~/.config/AGENT.md, with more specific files taking precedence	Project structure, build/test commands, code style, architecture, testing, security	RFC-style specification dated July 2025, written for Sourcegraph
GEMINI.md	Gemini CLI; Google Antigravity reads rules from it as well as from AGENTS.md	Gemini CLI looks for a gemini.md file in the current directory when the gemini command runs; a later step of the same workshop writes guidelines into GEMINI.md	A persona, pointers to files and searches, and facts or rules to remember for the project	Described in a Google Codelabs workshop and an Antigravity changelog entry
Copilot instruction files	GitHub Copilot	.github/copilot-instructions.md for repository-wide rules; path-specific *.instructions.md files under .github/instructions/	Always-on rules specific to Copilot, for the whole repository or for particular paths	Vendor documentation, as recorded on the AGENTS.md page
AI IDE rules	One IDE each — .cursor/rules/, .windsurf/rules/, .trae/rules/, .qoder/rules/, .kiro/steering/	A per-tool directory; one vendor’s guide adds four trigger types (Manual, Model Decision, Always, Specific Files) and caps a file at 10,000 characters	Architectural constraints, coding style, library preferences, workflow	Per-tool product features, studied in one mining and survey study
DESIGN.md	An agent generating a user interface	A single file	Design-system tokens as machine-readable YAML, with the design intent in the Markdown body; ships with a lint and a diff command	Published by Google Labs in April 2026
Agent primitives	GitHub Copilot in VS Code, in the source’s examples	Separate files per concern; an .instructions.md file is activated only for paths matching its applyTo pattern	Six file types — instructions, chat modes, prompts, specs, memory and context — of which VS Code natively supports the first three	One author’s proposal on GitHub’s blog, with no evaluation reported
MentorScript	Agents in the proposed SASE framework	Codified team norms (“mentorship-as-code”); location not specified	Team norms, from granular checks to high-level principles, with each agent action traceable to the rules considered	A proposal in one paper, as part of the SASE framework
Memory bank	Any AI coding session in a codebase	Across all sessions, as opposed to per task	General context such as rules files and product or architecture descriptions — Kiro’s “steering”, Spec Kit’s “constitution”	A name Birgitta Böckeler adopts to separate this context from specs

Names, adapters and convergence

AGENTS.md and AGENT.md fill the same role and differ in name. The AGENT.md specification says it prefers the singular because its authors own the agent.md domain and commit to keeping it vendor-neutral, and that it is willing to compromise. The adopter account in Taming Agents in the Mercari Web Monorepo records a team consolidating its Cursor and Claude rules into an AGENT.md, then switching to the plural after OpenAI secured the agents.md domain. AIに渡す指示書の役割分担: AGENTS.md/SKILL.md/DESIGN.mdと仕様駆動開発の現在地 describes the plural form as promoted jointly by OpenAI, Google, Cursor, Factory and others before its donation to the Linux Foundation. Impact de l’IA sur l’état de l’art de l’ingénierie logicielle en 2026 describes it as an attempt to harmonise each assistant’s own file into a kind of README for AI.

Several sources describe tool-specific filenames kept working as adapters to one shared file, so that the content is not maintained twice:

• Symbolic links. The AGENT.md specification gives migration commands that move a tool’s own file to AGENT.md and leave a link behind. The Mercari team made CLAUDE.md and its other rule files links to its AGENTS.md. The three-layer post gives the format project’s recommendation as making AGENTS.md the real file and CLAUDE.md a link to it. The practitioner in Keep Agentic AI Simple: A Practical Workflow for Software Development links the two with a symlink or an @AGENTS.md reference.
• References between files. Harness Engineering for Agentic AI Coding Tools: An Exploratory Study found, in repositories with more than one context-file type, that CLAUDE.md was typically created first and AGENTS.md added later. CLAUDE.md most often pointed to AGENTS.md (301 cases), and AGENTS.md received 353 incoming references, far more than any other file type. The authors read this as bottom-up convergence on AGENTS.md as a tool-agnostic standard, driven by developer practice rather than vendor mandate.
• Fallbacks in the tool. OpenCode falls back to a project CLAUDE.md when no AGENTS.md exists and to ~/.claude/CLAUDE.md when no global OpenCode file exists. The first match wins in each category, so AGENTS.md is used over CLAUDE.md when both are present.

The grounding pages describe Claude Code’s handling of AGENTS.md differently. The three-layer post states that Claude Code reads CLAUDE.md and not AGENTS.md, and the practitioner in Keep Agentic AI Simple: A Practical Workflow for Software Development says the same of his own setup. The configuration study notes that Claude Code did not support AGENTS.md natively at the time of its February 2026 snapshot. The CLAUDE.md page and the Claude Code page record Claude Code’s documentation as saying it can read a repository’s AGENTS.md. The CLAUDE.md page adds that by default this happens only when no CLAUDE.md or CLAUDE.local.md exists, that a setting enables reading both, and that @AGENTS.md imports are the way to share one file. These accounts may describe different points in time; each is recorded here as its page gives it.

When the content loads

The formats differ in how a file comes into context, and in what happens when two files disagree:

• Directory scope with nesting. The codex-1 system message scopes an AGENTS.md to the directory tree containing it, gives the more deeply nested file precedence, and ranks direct system, developer or user instructions above the file. The AGENT.md specification likewise asks that more specific files take precedence over general ones. Custom Code Review rules for Codex uses the same nesting for review rules: repository-wide rules at the root, and service-specific rules in the relevant directory’s own AGENTS.md.
• Concatenation. Claude Code’s documentation says CLAUDE.md files found up the directory tree are concatenated rather than overriding one another, so instructions closer to where Claude was launched are read last. @path imports expand at launch to a maximum depth of four hops, and block-level HTML comments are stripped before injection. Rules under .claude/rules/ load at launch unless a paths field limits them to matching files.
• First match wins. OpenCode looks first for local files by traversing up from the current directory, then for the global file, then for the Claude Code file. Further files listed in the instructions field of opencode.json, including glob patterns and remote URLs, are combined with the AGENTS.md files. OpenCode does not parse file references written inside AGENTS.md.
• Path patterns. An agent-primitives .instructions.md file is activated only for paths matching its applyTo pattern. GitHub’s documentation, as recorded on the AGENTS.md page, separates path-specific *.instructions.md files from the repository-wide copilot-instructions.md.
• Trigger types. Alibaba Cloud’s guide for Lingma sorts rules by how they are triggered — by name in the chat, by the model deciding a rule’s description fits, on every request, or by file glob — and states that where a rule and the assistant’s memory conflict, the rule takes precedence.
• Organisation-wide policy. Claude Code’s managed CLAUDE.md, deployed through MDM or configuration management, cannot be excluded by individual settings.
• User-written and agent-written memory. Claude Code sets CLAUDE.md, written by the user, beside Auto Memory, written by Claude itself. Both are loaded at the start of every conversation as context rather than as enforced configuration. Only the first 200 lines or 25KB of the auto-memory index load.

The sources describe the file’s position in the model’s input differently. Skill Issue: Harness Engineering for Coding Agents describes CLAUDE.md and AGENTS.md as injected by the harness into the agent’s system prompt. Claude Code’s memory documentation, as recorded on the CLAUDE.md page, says CLAUDE.md content is delivered as a user message after the system prompt, and that there is therefore no guarantee of strict compliance. Writing a good CLAUDE.md reports that Claude Code injects the file with a system reminder saying the context may or may not be relevant.

Splitting the context

Several sources split this context by what it covers or when it applies, rather than by which tool reads it:

• Three layers by subject. AIに渡す指示書の役割分担: AGENTS.md/SKILL.md/DESIGN.mdと仕様駆動開発の現在地 reads the files as three non-overlapping layers: AGENTS.md (with CLAUDE.md as its tool-specific equivalent) for an agent’s premises, roles and prohibitions, SKILL.md for reusable tasks, and DESIGN.md for appearance. It offers three questions for splitting an existing CLAUDE.md, and presents the split as an option to adopt where it earns its place rather than as a target state.
• Standing context against per-task specs. The memory-bank framing separates files relevant to every session in a codebase from specs relevant only to the tasks that change the functionality they describe. Spec-Driven Development for Agentic Software Engineering: Harnessing Human–Agent Teamwork makes a similar cut. It separates system specifications, materialised in agent rule files such as AGENTS.md or CLAUDE.md, from feature specifications that are created per task and archived once delivered. It distinguishes both from skills, which are procedural and loaded on demand rather than normative and always active.
• Facts in the file, procedures elsewhere. Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents counts seven places for Claude Code instructions and puts facts in CLAUDE.md, procedures in skills, one-path constraints in path-scoped rules, and personal preferences in user-level files. Using skills to accelerate OSS maintenance divides the work differently: the skill encodes the repository’s definition of “verified”, and short if/then rules near the top of AGENTS.md make using the skill mandatory.
• An entrypoint pointing elsewhere. The Mercari team’s root AGENTS.md is a short file whose sections each point to a separate document under docs/. HumanLayer keeps task-specific instructions in separate files that CLAUDE.md lists, and lets Claude decide which to read.
• Tiers by loading strategy. Codified Context: Infrastructure for AI Agents in a Complex Codebase argues that single-file manifests such as AGENTS.md, CLAUDE.md or .cursorrules do not scale past a small project. It describes three tiers used on a 108,000-line codebase: a constitution of about 660 lines loaded into every session, 19 specialised agent specifications, and 34 subsystem documents served on demand through an MCP retrieval server.
• Beyond a static file. Stop Using /init for AGENTS.md treats a single static file as a limitation for tasks of different kinds. It relays a proposed three-layer alternative — a minimal routing file, task-scoped files loaded selectively, and a maintenance subagent — and notes that no major coding agent yet exposes the lifecycle hooks needed to build it. Agentic Context Engineering is cited as another response to the same “static file problem”, maintaining the context as an evolving playbook.

What belongs in the file

The pages record different answers to what such a file should contain:

• A discovery filter. Stop Using /init for AGENTS.md argues that a fact the agent could discover by reading the code does not belong in the file, and that an auto-generated codebase overview is redundant. It also describes an anchoring effect: a technology mentioned in the file stays in context on every prompt and can bias the agent toward an outdated pattern.
• Procedures in the file. A practitioner account recorded on the AGENTS.md page stores the folder layout, working rules and auto-generation procedures in the file, and argues that fuller rule files make for simpler prompts. The AGENTS.md page records the two positions without reconciling them.
• Procedures out of the file. Anthropic’s guidance, recorded on the CLAUDE.md page, moves multi-step procedures to skills, part-of-the-codebase concerns to path-scoped rules, and anything that must always or never happen to hooks or permissions, because a prompted rule can fail to be followed.
• Onboarding content. Writing a good CLAUDE.md frames the file as onboarding Claude to the project’s what, why and how. 谈谈 AI 编程工具的进化与 Vibe Coding takes a new team member’s needs as its model: the technology stack, the directory structure, what files are named and for what, and common commands such as install, lint, test and build, kept in a CLAUDE.md or .github/copilot-instructions.md. The AGENT.md specification suggests what a new team member would need on their first day.
• Project-wide decisions only. Effizientes Agentic Coding splits decisions three ways. Some can be derived by pointing the agent at existing code, some hold for the whole project and belong in an AGENTS.md, and anything specific to the current task belongs in the prompt. 소프트웨어 3.0 시대를 맞이하며 compares CLAUDE.md to package.json or pom.xml. It says that a file being edited often probably holds something that does not belong there, such as the current issue or the day’s priorities.
• Shape-based and runtime defects. AI가 팀 규칙을 지키도록 하는 방법 sends conventions recognisable from the shape of the code to hook-triggered rules. It keeps defects that only appear at runtime, such as N+1 queries, in always-loaded context.
• What not to put there. HumanLayer, the AI IDE rules study and the Codex review post all leave formatting and other mechanical checks to linters, formatters or CI rather than to the file.
• Size. Anthropic recommends keeping a CLAUDE.md under 200 lines. HumanLayer reports a general consensus that under 300 lines is best, keeps its own root file under sixty lines, and states that Anthropic has no official length recommendation. Claude Code’s documentation offers the test “would removing this cause Claude to make mistakes?” One post gives 500 to 2,000 tokens as a rough figure for a well-organised CLAUDE.md. The Unity SDD account keeps its resident rules to about 30 lines. None of these is presented as a measured threshold.
• Whether to generate it. OpenCode’s /init creates or updates an AGENTS.md, and Claude Code’s /init generates a starter CLAUDE.md. Keep Agentic AI Simple: A Practical Workflow for Software Development notes the file can be generated by the agent and should be reviewed regularly. HumanLayer and Stop Using /init for AGENTS.md argue against generating it. The AI IDE rules study found that 71.72% of surveyed developers generate rules with AI and then refine them.
• No settled answer. The paper proposing MentorScript states that the community has no consensus on what such files should contain or at what level of detail.

Keeping the files current

The sources agree that these files change over time, and describe different ways of managing that:

• Added after failures. Agent Harness Engineering describes encoding each agent mistake as a rule in AGENTS.md, a hook or a reviewer subagent check, removed once a more capable model makes it redundant. The practitioner in Keep Agentic AI Simple: A Practical Workflow for Software Development adds recurring mistakes to the file. The AI IDE rules study found that 48.48% of surveyed developers add rules only when the AI makes a mistake. It also found that adding dominates rule changes, so files grow and can come to contain contradictions.
• Written by the agent. Self-Improving Coding Agents treats AGENTS.md as long-term memory that every iteration of an autonomous loop reads and can append to. It suggests sections for conventions, gotchas, preferences and recent learnings, and warns of context bloat as the file grows. For pull requests with significant impact on higher-level design, the Mercari team has an agent read the changeset together with the rules folder and suggest edits to the rules.
• Checked in review. In Orchestrating AI Code Review at scale, a dedicated reviewer agent flags merge requests that make material architectural changes without updating the repository’s AGENTS.md. It also penalises filler content and overly long files. Anthropic recommends giving CLAUDE.md an owner and reviewing changes to it like code.
• Staleness as the failure. The codified-context paper names specification staleness as its primary failure mode, and reports about one to two hours of maintenance a week. 谈谈 AI 编程工具的进化与 Vibe Coding warns that stale information in an instruction file does more harm than leaving it out. The AI IDE rules study found compliance peaking at the commit that introduces a rule and falling back toward 65% over the following commits.

Uses beyond coding context

Some sources use the same files for jobs other than supplying context to a coding task:

• Review rules. Custom Code Review rules for Codex describes Codex Code Review applying rules kept in AGENTS.md to a change and citing them in its findings. The AGENTS.md page records that Copilot reads custom instructions, agent instructions and skills from a pull request’s head branch during review.
• Community AI policies. A First Look at Coding Agents’ Compliance with AI Contribution Rules in Open-Source Communities lists agent instruction files such as AGENTS.md among the places where open-source communities write rules for AI contributions. It tested quoting a policy clause verbatim in AGENTS.md. For disclosure and verification rules, it recommends the file an agent already reads at session start plus a feedback loop. It recommends enforcing bans and human-approval rules outside the agent.

Where a rule in the file stops working

Several sources describe limits on what a file can make an agent do:

• Following fades over a session. AI가 팀 규칙을 지키도록 하는 방법 reports that an agent reads a project-root AGENTS.md at the start of a session and follows it early on, but stops as the session lengthens. The author attributes this to Lost in the Middle. The team’s response is to re-inject relevant rules through Agent Hooks after each file write and before the agent finishes.
• Length dilutes adherence. Anthropic says a growing CLAUDE.md dilutes adherence to the instructions that matter. Claude Code’s documentation says a bloated file causes instructions to be ignored, and suggests emphasising a single skipped line rather than many.
• Enforcement lives elsewhere. Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents names hooks and permissions as the deterministic enforcement methods, and says “never do this” is the wrong job for an instruction.
• Rules that undo work. The AI-contribution study found that quoting a ban verbatim in AGENTS.md left refusal at 0% for three of four agents and moved the fourth to 10%.

Security

The property that makes these files useful also makes them a target. Indirect AGENTS.md Injection describes a malicious dependency that runs during a build, writes an AGENTS.md whose directives claim precedence over the user’s request, and has the agent follow them. The page states that the file’s trust model is deliberate. It notes that the attack presupposes code execution through a compromised dependency. The countermeasures it records are about the file’s integrity rather than its content: limiting which files an agent may read and write, integrity controls on configuration files, and alerts on unexpected modifications. The AGENTS.md page notes that the codex-1 precedence rule is a documented default, not something an injected file cannot contest.

What the evidence measures

The studies and reports held here each measure something different:

• Efficiency with and without AGENTS.md. On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents ran OpenAI Codex on 124 pull-request tasks from 10 repositories, with and without the root AGENTS.md. Median wall-clock time fell by 28.64% and median output tokens by 16.58%. The authors stress that this is not a correctness evaluation, and the study covers one agent and small code-only changes.
• Task success by who wrote the file. As reported in Stop Using /init for AGENTS.md, an ETH Zurich study found that LLM-generated context files reduced task success by 2–3% while raising cost by over 20%. Developer-written files improved success by about 4% while raising cost by up to 19%. With existing documentation stripped from the test repositories, the same generated files improved performance by 2.7%. The post reconciles the efficiency and success studies by what the file contains, not whether it exists.
• Adoption across tools. Harness Engineering for Agentic AI Coding Tools: An Exploratory Study found 4,768 context files in 2,586 of 2,853 sampled repositories. CLAUDE.md was the most common (34.4%), followed by AGENTS.md (31.6%) and copilot-instructions.md (29.2%). 493 repositories (17.3%) used AGENTS.md without any tool-specific configuration. The heuristics detect the files’ presence rather than active use.
• What rule files contain and how well they are followed. Rule Taxonomy and Evolution in AI IDEs: A Mining and Survey Study, as recorded on the AI IDE rules page, mined 7,310 rules from 83 projects. System Architecture and AI Context Management were among the highest-rated subcategories but made up only 2.67% and 1.76% of the rules. Updating a rule raised compliance by 22.99% on average, concentrated in concrete, statically checkable constraints. The projects are predominantly TypeScript web development by solo developers or teams of one to three.
• Whether agents find a rule at all. The AI-contribution compliance study found that the focal policy file was opened in 12 of 347 unaided non-anchor runs, and that 242 of 248 unaided violations happened without the policy ever being opened.
• Review rules. OpenAI reports that rule-guided Codex Code Review recovered 98% of the required custom findings, against 58.3% for a baseline, on its own eval suite. This is an internal result rather than an independent measurement.
• One large project. The codified-context paper is a single developer’s experience report on one project, with observational case studies and no causal claims.
• Read together. Agentic Agile-V: From Vibe Coding to Verified Engineering in Software and Hardware Development presents the evidence on repository instruction files as genuinely mixed. It also relays a factorial study finding limited evidence that file size, position or structure alone produce reliable adherence effects. Impact de l’IA sur l’état de l’art de l’ingénierie logicielle en 2026 reports that whether a change to a context file is actually an improvement remains an open question for the teams it spoke to.

The remaining formats rest on other kinds of standing: AGENT.md, MentorScript and the agent primitives on proposals, DESIGN.md on its publisher’s specification and tooling, GEMINI.md on a workshop and a changelog, and CLAUDE.md on vendor documentation and outside companies’ recommendations.