AGENTS.md vs CLAUDE.md vs Cursor Rules (2026 Update)

This page was wrong for three weeks, and so was most of the internet. Until September 2026 the defining fact about these formats was that Claude Code — the single most-used agentic CLI — refused to read AGENTS.md, so every cross-tool repo needed a CLAUDE.md containing an @AGENTS.md import or a symlink. That changed on 18 September 2026.

Everything below is re-verified against primary vendor sources on 5 October 2026: Anthropic's Claude Code memory documentation and the public changelog, Cursor's Rules and CLI docs, the Codex AGENTS.md reference, GitHub's Copilot customization docs, the VS Code custom-instructions page, the Gemini CLI repository docs, and agents.md itself. Where a vendor's behaviour depends on a version number, the version is in the table — because that is the part that actually decides whether your file loads.

Does Claude Code read AGENTS.md?

Yes, since v2.1.277. The changelog entry is one line:

"Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config"

That release was published to npm on 18 September 2026 at 16:22 UTC. The extension to every runtime landed five days later in v2.1.281 (23 September 2026), which "Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled."

The feature request behind it, anthropics/claude-code#6235, was opened on 21 August 2025 and accumulated 6,685 reactions and 409 comments before being closed as completed on 17 August 2026 — one of the loudest single asks in the repository's history.

Mechanically, support ships as a built-in mod, not as core CLI behaviour. It lives at mods/agents-md in the Claude Code repository and registers as the plugin ID agents-md@builtin. You can switch it off entirely in /plugin, and when it is off the Project instructions row disappears from /config. That architecture is also why the first rollout was gated — more on that below.

What happens if I have both AGENTS.md and CLAUDE.md?

CLAUDE.md wins and AGENTS.md is skipped. This is the single most misunderstood part of the new behaviour, and Anthropic's docs state it as a lookup table:

Which files count for that check is not intuitive, and it is where the real bugs live:

• These suppress AGENTS.md: a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it.
• These do not, and keep loading alongside it: your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and .claude/rules/ files.

So a global ~/.claude/CLAUDE.md full of personal preferences does not break AGENTS.md loading. A single stray CLAUDE.md three directories up — in a monorepo parent, or in your home folder's checkout root — does.

The trap worth tattooing on your wrist: CLAUDE.local.md counts. If your team standardised on AGENTS.md and you add a personal, gitignored CLAUDE.local.md for your own uncommitted notes, you have just stopped Claude from reading the team's instructions — for you only, silently, with no warning. Anthropic calls this out explicitly in the docs. The fix is to set Project instructions to claude-md-and-agents-md.

How do I change the default?

Type /config in a session and set Project instructions to one of four values:

You can also set it in a settings file, under the built-in plugin's ID:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

But read this before you plan a team rollout: Claude Code ignores this key in project and local settings files. It is only honoured in ~/.claude/settings.json, a --settings file, or managed settings. You cannot commit .claude/settings.json to your repo and have every teammate load both files — each person sets it themselves, or your enterprise admin sets it through managed settings. If your repo genuinely needs both files read by everyone, the @AGENTS.md import is still the only mechanism that travels with the repository.

What else does Claude Code ignore?

Three filenames other agents understand are simply not read: AGENTS.local.md, AGENTS.override.md, and anything under a .agents/ directory. If you are migrating from Codex — which treats AGENTS.override.md as a hard replacement — that file becomes dead weight the moment Claude Code is in the mix.

Two subtler differences apply to an AGENTS.md read through the setting rather than through an import. InstructionsLoaded hooks do not fire for it (they fire normally for an imported or symlinked AGENTS.md), and directories added with --add-dir contribute their CLAUDE.md but not their AGENTS.md. If you have hook automation keyed to instruction loading, keep the import.

Do I still need the @AGENTS.md import workaround?

Mostly no — and Anthropic published explicit undo guidance, which is unusual and worth following literally. Four setups, four answers:

The prose-instruction case is the one that was quietly broken all along. "Read AGENTS.md before starting" in a CLAUDE.md was never a load — it was a suggestion the model could skip. Plenty of teams believed they had this wired up and did not.

Keep the import deliberately in three situations: you are pinned below v2.1.277; you also need a CLAUDE.md for Claude-specific rules; or you depend on InstructionsLoaded hooks. To check what actually loaded, run /memory and look for the path. One version caveat: before v2.1.280, /memory and /context did not list an AGENTS.md that Claude read directly, so on 2.1.277–2.1.279 an absent path is not proof of absent loading.

Why was the AGENTS.md rollout controversial?

Because the first version only worked if you let Anthropic collect telemetry — and the mod architecture is what made that possible.

The launch hit the Hacker News front page on 18 September 2026 as "Claude Code now reads AGENTS.md if there is no Claude.md" and finished at 741 points and 285 comments. Five days later a second post, "Claude Code reads AGENTS.md only when telemetry is on [fixed]", reached 486 points and 284 comments. Users on Bedrock, Vertex AI and corporate LLM gateways — and anyone who had set telemetry off — were silently getting the old behaviour while the changelog said the feature had shipped. v2.1.281 removed the gate the same week.

The practical lesson survives the news cycle: when a feature ships as a built-in plugin, "is it in my version?" is not the only question. "Is it active in this session?" matters too. Anthropic now documents four reasons AGENTS.md support can be unavailable — a version before v2.1.277, the agents-md plugin disabled in /plugin, some first sessions immediately after upgrading from v2.1.276 or earlier, and on versions before v2.1.281 a Bedrock or telemetry-disabled session. In all of them Project instructions is missing from /config, which is the fastest way to tell.

Does Cursor read AGENTS.md?

Yes, natively, with nothing to configure. Cursor's Rules documentation supports exactly four rule types — Project Rules, User Rules, Team Rules and AGENTS.md — and describes AGENTS.md as "a plain markdown file without metadata or complex configurations," to be placed "in your project root as an alternative to .cursor/rules."

Three consequences worth knowing:

• No frontmatter, no schema. That is the entire point of the format, and the one design decision that has survived every proposal to change it.
• It is not second-class. Cursor's own docs steer you to AGENTS.md over dropping a plain .md into .cursor/rules — a .md file in that folder is silently ignored, because Project Rules need the .mdc extension and frontmatter.
• The Cursor CLI reads it too, along with CLAUDE.md: "The CLI also reads AGENTS.md and CLAUDE.md at the project root (if present) and applies them as rules alongside .cursor/rules."

Cursor also helped create the convention — agents.md credits it to collaboration between OpenAI Codex, Amp, Google's Jules, Cursor and Factory. This was never a rival standard bolted on grudgingly.

Where exactly does Cursor look for AGENTS.md?

Two places, plus one that people assume exists and does not.

A typical monorepo layout:

project/
  AGENTS.md              # repo-wide defaults
  frontend/
    AGENTS.md            # React/Tailwind conventions
    components/
      AGENTS.md          # component-specific rules
  backend/
    AGENTS.md            # service + migration rules

There is a real gap between the spec and Cursor's implementation. The AGENTS.md FAQ says "the closest AGENTS.md to the edited file wins" — pure nearest-file-wins. Cursor describes something softer: nested files "will be automatically applied when working with files in that directory or its children," combined with their parents, with more specific instructions taking precedence. So in Cursor a nested file layers onto the root rather than replacing it. If your root says "always use pnpm" and a nested file is silent on package managers, Cursor still applies the root rule. Write nested files as deltas, not as standalone replacements — that shape behaves correctly under both interpretations.

How do I set up a global AGENTS.md for Cursor?

You can't — not as a file. This is the most common false assumption about Cursor's rules system and the source of most "my global AGENTS.md is ignored" reports. There is no home-directory AGENTS.md location. There are three sanctioned alternatives:

• User Rules. Defined in Customize → Rules inside Cursor, stored in your Cursor environment rather than a repo file, applied across all projects. Documented caveat: they are used by Agent (Chat) only — not Inline Edit (Cmd/Ctrl+K), and no rule type affects Cursor Tab.
• Team Rules. Team and Enterprise plans, managed from the Cursor dashboard, applied across every repository for everyone. Free-form text, support a glob for file-scoped application, and can be marked "Enforce this rule" so individuals cannot toggle them off.
• Remote rules imported from GitHub. Customize → Rules → Add Rule → Remote Rule (GitHub), pointed at a repo of .mdc files. Cursor syncs them into .cursor/rules/imported/<repoName>, preserving relative paths. This is the closest official thing to "one shared rule set, many projects."

If you insist on a single file on disk, the pragmatic hack is a symlink: keep a canonical copy at ~/agents/AGENTS.md, run ln -s ~/agents/AGENTS.md AGENTS.md in each checkout, and add the link to your global gitignore. It works because Cursor only cares that a file resolves at the project root. It is a filesystem trick, not a supported feature, and it will break on a Windows clone.

One genuine exception: skills do have a global location. Cursor's Agent Skills docs load SKILL.md packages from ~/.agents/skills/ and ~/.cursor/skills/ as well as project-level .agents/skills/ and .cursor/skills/. So the real answer to "how do I share agent behaviour across every project" is often "make it a skill, not a rules file."

How does AGENTS.md interact with .cursor/rules?

They coexist. AGENTS.md does not replace or disable .cursor/rules — Cursor loads both. The difference is expressiveness. Project Rules are .mdc files with YAML frontmatter, and three fields decide when each one enters the context window:

A concrete example:

---
description: RPC service conventions for the backend
globs: src/services/**/*.ts
alwaysApply: false
---

- Define each service in its own file under `src/services/`
- Validate inputs at the service boundary before internal calls
- Return structured errors with a `code` and `message`; never throw raw strings

Cursor's documented precedence for the three rule types is Team Rules → Project Rules → User Rules, with all applicable rules merged and earlier sources winning conflicts. Note what is missing: AGENTS.md is not placed in that ordering. Treat it as your always-on baseline, use .mdc rules for conditional activation, and avoid writing directly contradictory instructions in both — undocumented resolution order is undocumented for a reason. Keep each rule under 500 lines, per Cursor's own guidance, and split larger ones. For the rest of the workflow, see our Cursor IDE complete guide.

Does Cursor still support .cursorrules?

Cursor's current Rules documentation does not mention .cursorrules anywhere. It documents exactly four rule types, and the legacy single-file format is in none of them.

That absence is the signal. Legacy .cursorrules files still sit in thousands of repositories and other tools still scan them — Claude Code's /init, for instance, explicitly reads ".cursor/rules/ or .cursorrules" when generating a CLAUDE.md. But an undocumented format gets no new capabilities: none of the glob scoping, activation modes, agent-selected rules or team enforcement above apply to it. Migrate — and the cheapest migration is not to .mdc. Rename it to AGENTS.md. You get a plain-markdown file Cursor documents, and now Claude Code reads it too.

Does Cursor read CLAUDE.md?

The Cursor CLI does, explicitly. The IDE's Rules documentation does not list CLAUDE.md as a rule type. So a CLAUDE.md-only repo loads fine under cursor-agent in the terminal; open the same repo in the Cursor editor and you should not count on it.

Which gives the mixed-team configuration a cleaner answer than it had in August. If your team runs Cursor and Claude Code, put the shared content in AGENTS.md and do not create a CLAUDE.md at all unless you have genuinely Claude-specific rules. The IDE reads AGENTS.md, the CLI reads AGENTS.md, and Claude Code now reads AGENTS.md — adding an empty-ish CLAUDE.md actively suppresses it.

What does Codex do with AGENTS.md?

Codex has the most explicit resolution model of any tool here, and it is the only one with a documented byte cap. Per the Codex AGENTS.md reference (note the URL — the old developers.openai.com/codex/guides/agents-md path now 308-redirects here):

• Global scope. In the Codex home directory — ~/.codex by default, or CODEX_HOME — it reads AGENTS.override.md if present, otherwise AGENTS.md.
• Project scope. Starting at the project root (typically the Git root) it walks down to your working directory, checking each directory for AGENTS.override.md then AGENTS.md.
• Merge order. "Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt." Deeper wins — by position in the prompt, not by a precedence engine.
• Limits. At most one file per directory, empty files skipped, the walk stops at your current directory, and the total is capped by project_doc_max_bytes — 32 KiB by default.

Two portability notes fall straight out of that. AGENTS.override.md is a Codex-only concept — Claude Code does not read it, and Cursor does not document it. And 32 KiB is roughly 8,000 tokens of instructions; if you are anywhere near that ceiling you have a different problem, which the research section below covers.

How do Copilot and VS Code handle AGENTS.md?

Copilot is the most permissive reader and the least predictable merger. GitHub's docs say you can place one or more AGENTS.md files "anywhere within the repository," and "the nearest AGENTS.md file in the directory tree will take precedence" — true nearest-wins, matching the spec rather than Cursor's layering. Alternatively you can use "a single CLAUDE.md or GEMINI.md file stored in the root of the repository."

The catch is rank. GitHub's documented precedence for repository custom instructions is: path-specific .github/instructions/**/*.instructions.md, then repository-wide .github/copilot-instructions.md, then agent instructions (for example an AGENTS.md), then organization instructions. AGENTS.md sits below both Copilot-native formats, and GitHub notes agent instructions are "currently not supported by all Copilot features." If you are a GitHub-native shop, .github/copilot-instructions.md is the file with universal surface coverage; AGENTS.md is what buys you portability if you ever switch tools.

In VS Code (docs page dated 30 September 2026) AGENTS.md is "a cross-agent format for project guidance" with "the primary file at the repository root." The Local agent gates it behind chat.useAgentsMdFile, and nested files need the separate chat.useNestedAgentsMdFiles setting, which is experimental and disabled by default and "might change or be removed." That is a genuine portability trap: a nested layout that works perfectly in Cursor and Copilot's coding agent is, by default, only read at the root in VS Code.

VS Code's guidance on conflicts is also the most honest sentence any vendor has written on this topic: "Applicable instruction sources are additive," followed by the warning to "not depend on a file order or precedence rule to resolve conflicts because discovery and merge behavior can differ by harness." Design your files so that no conflict needs resolving.

Does Gemini CLI read AGENTS.md?

Only if you tell it to — and this is a widely-repeated error worth correcting, including in earlier versions of this page. Gemini CLI's default context filename is GEMINI.md, loaded hierarchically from ~/.gemini/GEMINI.md, then workspace directories and their parents, then just-in-time from a directory and its ancestors when a tool touches a file there. Nothing in that chain looks for AGENTS.md out of the box.

To make it read AGENTS.md you set context.fileName in settings.json:

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

It accepts a list, so you can support both names at once. The repository is active — google-gemini/gemini-cli is not archived and was last pushed on 5 October 2026 — so this is current behaviour, not a legacy quirk. Treat "Gemini CLI reads AGENTS.md" as one line of configuration away from true rather than true.

Which tool reads which file?

This is the table to bookmark. Every row verified against the vendor's own documentation on 5 October 2026, with the version that decides the behaviour where one exists.

Two format facts that keep getting mis-reported. AGENTS.md has no frontmatter spec. agents.md still states flatly that "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." The v1.1 proposal that would have added optional YAML description and tags fields (issue #135, opened 8 January 2026) was closed on 24 August 2026 without being adopted. Any tool asking you for AGENTS.md frontmatter is inventing it. And SKILL.md is the other convention that crossed vendors — Cursor loads skill packages from .claude/skills/, ~/.claude/skills/, .codex/skills/ and ~/.codex/skills/ alongside its own .cursor/skills/ and the neutral .agents/skills/. A skill written for Claude Code runs in Cursor unchanged.

Meta's Muse Code, launched 5 August 2026, is the clearest sign the naming war is over: there is no MUSE.md. It adopted AGENTS.md and reads CLAUDE.md as a fallback. Our Muse Code complete guide covers its configuration model.

How do these formats handle monorepos?

All of them have an answer, and they differ in shape more than in power:

• AGENTS.md — directory nesting, one file per package. Resolution varies by tool, which is the real hazard: nearest-wins in Copilot and the spec, layered in Cursor, position-in-prompt in Codex, root-only by default in VS Code. Write deltas and the differences stop mattering.
• CLAUDE.md — the hierarchy above your working directory loads at launch; subdirectory files load on demand when Claude reads files there. claudeMdExcludes drops other teams' files. The same on-demand model now applies to subdirectory AGENTS.md files, but only in subdirectories that have none of the three CLAUDE.md filenames of their own.
• .cursor/rules — glob-driven rather than nested. A single backend.mdc with globs: services/api/** behaves like a nested file but lives centrally. Nested .cursor/rules directories are also discovered.
• Copilot — one .github/copilot-instructions.md plus .github/instructions/*.instructions.md scoped by applyTo, with nested AGENTS.md honoured on top.

The monorepo failure mode nobody warns you about is a parent-directory CLAUDE.md. In a repo with per-package AGENTS.md files and one legacy CLAUDE.md at the root, Claude Code reads the root CLAUDE.md and none of the package files. Delete it or set claude-md-and-agents-md.

Does an AGENTS.md actually improve agent output?

Less than the ecosystem assumes — and this is worth knowing before you write a 400-line file. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? by Thibaud Gloaguen, Niels Mündler-Sasahara, Mark Niklas Müller, Veselin Raychev and Martin Vechev (arXiv:2602.11988, submitted 12 February 2026, revised through 29 September 2026) evaluated agents on SWE-bench tasks with LLM-generated context files and on a new collection of issues from repositories with developer-committed context files. The finding:

"Surprisingly, we find that providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average."

The actionable nuance is in the breakdown: "while instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful." Instructions work. Architecture summaries — exactly what every template and every /init run loves to generate — do not.

Both vendors now independently agree. Anthropic's /doctor prompt audit proposes trimming "directory layouts, dependency lists, and architecture overviews" while keeping "pitfalls, rationale, and conventions that differ from tool defaults." Cursor's docs say the same thing differently: don't copy style guides (use a linter), don't document commands the agent already knows, don't duplicate what is in the codebase.

So: write commands and constraints, not descriptions. Anything the agent could discover by reading three files is costing you tokens for nothing — and under Codex's 32 KiB cap, crowding out the instructions that do work.

Which file should you actually adopt?

For what belongs inside one of these files — structure, length, what to cut — see our AGENTS.md complete guide. For the wider landscape of tools that consume them, the AI coding agents complete guide, and for a head-to-head on the two CLIs most affected by this change, Claude Code vs OpenAI Codex.

FAQ

Does Claude Code read AGENTS.md?

Yes, since v2.1.277, published 18 September 2026. The changelog reads: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead." Support reaches every runtime — Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and telemetry-disabled sessions — from v2.1.281 (23 September 2026). It ships as the built-in agents-md plugin, so it can be switched off in /plugin.

What happens if I have both AGENTS.md and CLAUDE.md?

By default Claude Code reads your CLAUDE.md files only and skips AGENTS.md entirely. A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it triggers this. Your ~/.claude/CLAUDE.md, your org's managed file and .claude/rules/ do not. To load both, set Project instructions to claude-md-and-agents-md in /config.

Do I still need the @AGENTS.md import workaround?

Usually not. Keep it only if teammates are on builds before v2.1.277, if you also need Claude-specific rules in a CLAUDE.md, or if you depend on InstructionsLoaded hooks, which do not fire for an AGENTS.md read through the setting. Keeping the import is harmless — it never causes a double read. Two things you should remove: a SessionStart hook that prints AGENTS.md (now a duplicate copy), and a CLAUDE.md that merely tells Claude in prose to go read AGENTS.md (that was never a reliable load). A CLAUDE.md symlinked to AGENTS.md can stay or go.

Which tools support AGENTS.md?

Natively and with no configuration: OpenAI Codex, Cursor (IDE and CLI), GitHub Copilot, VS Code's Local agent, and Claude Code from v2.1.277. agents.md lists 20+ supporting tools including Aider, Devin, Zed, Jules, Amp and Factory, and says the format is "used by over 60k open-source projects." Gemini CLI is the notable exception — it defaults to GEMINI.md and reads AGENTS.md only if you add it to context.fileName in settings.json.

Does Cursor read AGENTS.md?

Yes. Cursor's Rules documentation lists AGENTS.md as one of four rule types, alongside Project Rules, User Rules and Team Rules. It is read from the project root and from any subdirectory, with no setting to enable and no frontmatter required. Nested files combine with their parents rather than replacing them. The Cursor CLI reads it too, and additionally reads CLAUDE.md at the project root.

Where do I put a global AGENTS.md for Cursor?

Nowhere — Cursor has no home-directory AGENTS.md location, and ~/.cursor/AGENTS.md is ignored. Use User Rules in Customize → Rules for personal cross-project instructions, Team Rules on Team and Enterprise plans for org-wide ones, or import a shared .mdc rule set from GitHub. A symlink from a canonical file into each repo root also works, unofficially.

Do context files actually improve results?

Not reliably. The ETH Zurich study Evaluating AGENTS.md (arXiv:2602.11988) found that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average." The split matters: instructions in context files are followed well, but repository overviews — architecture summaries and directory layouts — are not helpful. Write constraints and commands; cut descriptions.

Does AGENTS.md override .cursor/rules in Cursor?

Neither overrides the other; Cursor loads both. Its documented precedence covers only the three rule types — Team Rules, then Project Rules, then User Rules, merged with earlier sources winning conflicts — and does not place AGENTS.md in that order. Treat AGENTS.md as your always-on baseline and avoid writing directly contradictory instructions in both.

Does AGENTS.md support YAML frontmatter?

No. agents.md states that "AGENTS.md is just standard Markdown." The v1.1 proposal that would have added optional description and tags frontmatter fields (issue #135, opened January 2026) was closed on 24 August 2026 without adoption. Frontmatter belongs to Cursor's .mdc Project Rules, Claude Code's .claude/rules/ paths: lists, and Copilot's .instructions.md applyTo — not to AGENTS.md.

My AGENTS.md isn't loading in Claude Code — what do I check?

In order: look for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it, other than ~/.claude/CLAUDE.md; run claude --version and confirm v2.1.277 or later, or v2.1.281 on Bedrock, Vertex, Foundry, a gateway or with telemetry off; open /config and confirm Project instructions is not claude-md or managed-only. If that row is missing from /config entirely, this session cannot load AGENTS.md at all. Run /memory to see what did load — though on v2.1.277–2.1.279 /memory did not list a directly-read AGENTS.md.

How long should an AGENTS.md or CLAUDE.md be?

Anthropic targets under 200 lines per CLAUDE.md; Cursor says keep a rule under 500 lines and split larger ones; Codex caps the whole concatenated set at 32 KiB by default via project_doc_max_bytes. Given the measured 20%+ inference-cost penalty with no reliable success gain, treat those as ceilings you should stay well under rather than budgets to fill.

Are these files safe to commit?

Yes, provided they hold conventions rather than credentials. Every one of these formats is designed to be version-controlled and read by external services, so treat them as public. The exceptions built for private content are CLAUDE.local.md and Cursor User Rules — but note that a CLAUDE.local.md now has a side effect: it suppresses AGENTS.md for you, and only you, which is a confusing bug to debug on a team.

What should you actually do?

Write one AGENTS.md at your repo root and delete the CLAUDE.md if it contains nothing Claude-specific — that single change is now the correct configuration for a Cursor + Claude Code + Codex + Copilot team, where six weeks ago it would have broken Claude Code entirely. Keep the @AGENTS.md import only if you have teammates on older builds, Claude-specific rules, or hooks that depend on instruction loading. Add .cursor/rules/*.mdc or .claude/rules/ only when you hit a real need for glob-scoped activation. And keep all of it short: the measured cost of a bloated context file is real, and the measured benefit of a repository overview is not.

If you are standardising this across a team of engineers who each run a different agent, the convention is the easy part — getting everyone's versions and local files aligned is where it actually breaks. That is the kind of thing a senior engineer who has already shipped it sorts out in an afternoon.

Last verified 5 October 2026 against the Claude Code memory documentation and public changelog, the npm registry publish times for v2.1.277 and v2.1.281, anthropics/claude-code issue #6235, Cursor's Rules and CLI documentation, the Codex AGENTS.md reference at learn.chatgpt.com, GitHub's Copilot customization docs, the VS Code custom-instructions page, the google-gemini/gemini-cli repository docs, agents.md, and arXiv:2602.11988.