If you've opened a repository that's been through more than a couple months of AI-assisted development lately, you already know the mess I'm talking about. There's a CLAUDE.md sitting at the root. Next to it, an AGENTS.md. Maybe a .cursor/rules/ folder with three separate .mdc files. Somewhere buried in .github/ there's a copilot-instructions.md nobody has touched since March. They all say roughly the same thing — use pnpm, don't touch the vendor folder, run npm run typecheck before you're done — and they're all slowly drifting out of sync with each other, because nobody remembers to update four files when they only meant to update one.

This is the state of AI coding agent context files heading into the second half of 2026, and honestly, it's a weirder situation than most write-ups admit. AGENTS.md was supposed to fix this. It got donated to the Linux Foundation's new Agentic AI Foundation back in December 2025, alongside Anthropic handing over the Model Context Protocol and Block donating Goose. It's now sitting in more than 60,000 public repositories and gets read natively by Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Windsurf, Zed, and a growing list of others. By any normal definition, that's what winning looks like for an open standard.

And yet Claude Code — arguably the single most talked-about coding agent of the last year — still doesn't read it. Not natively, anyway. There's a GitHub issue with thousands of upvotes asking Anthropic to add support, and as of this writing there's no committed timeline. If you're a developer working across tools, which is most of us now, you're stuck either maintaining two files or reaching for a workaround that feels more like a plumbing fix than a real solution.

I want to walk through why this split exists, what actually belongs in these files (there's real research on this now, and it's more surprising than you'd think), and what a sane setup looks like if you're building with Next.js, TypeScript, or really any modern stack where you're bouncing between Claude Code, Cursor, and Copilot depending on the day.

What AGENTS.md Actually Is

AGENTS.md emerged out of a 2025 collaboration between OpenAI, Sourcegraph, Google, Cursor, and Factory, originally built to solve a very specific problem for Codex: agents starting every session blind to a project's real conventions. The spec repo describes it plainly — think of it as a README, except the audience is the agent instead of the human developer who just cloned the repo.

It's deliberately unopinionated. There's no required schema, no mandatory fields, no YAML frontmatter to fight with. It's just markdown, placed at the root of your project, and the sections that show up again and again across real repositories are the ones you'd expect: project overview, exact build and test commands, coding conventions, testing instructions, security considerations, and PR guidelines. GitHub's own analysis of over 2,500 repositories using the convention found that the single most common useful rule, by a wide margin, was some version of "never commit secrets or .env files." Not architecture diagrams. Not tech philosophy. A boundary.

That's worth sitting with for a second, because it cuts against how most people instinctively write these files.

Where CLAUDE.md Fits — and Why It's Not Going Anywhere

Claude Code uses its own file, CLAUDE.md, and it's genuinely richer than a plain AGENTS.md in a few ways that matter if you're deep in the Claude Code workflow. It supports a layered memory model — project-level, user-level, and local overrides that don't get committed to git. It has an @import syntax for pulling in additional files without bloating the root document. And more recently, Claude Code has picked up auto-memory, where the agent itself can persist learnings across sessions without you hand-editing a file every time it makes the same mistake twice.

The practical reason Anthropic hasn't just adopted AGENTS.md wholesale is that CLAUDE.md does things AGENTS.md's minimal spec was never designed to do. It's less "README for agents" and more a small configuration system with its own conventions. If you're a Claude Code-only shop, there's genuinely no reason to fight this — CLAUDE.md is a better fit for how you're already working.

The friction only shows up the moment your team, or your own workflow, spans more than one agent. And in 2026, that's most of us. I use Claude Code for anything that needs long context and careful multi-file reasoning, but I'll still reach for Cursor when I want fast inline edits, and clients occasionally hand me repos already wired up for Copilot. Maintaining three near-identical instruction files by hand is exactly the kind of tedious, error-prone busywork that AI tooling is supposed to eliminate, not create.

The Symlink Workaround Everyone's Using

The pattern that's become the de facto standard for multi-tool teams is almost comically low-tech: write AGENTS.md as your canonical source of truth, then symlink CLAUDE.md to point at it.

mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

That's it. Claude Code reads the symlink, thinks it's reading CLAUDE.md, and gets the same content everything else is reading. You maintain one file. Everyone stays in sync. I've seen more than one production AGENTS.md now literally open with a comment along the lines of "Note: CLAUDE.md is a symlink to this file. They are the same file." — which tells you how normalized this hack has already become, even though it's a workaround for a gap that arguably shouldn't exist a year and a half into the agentic coding era.

Cursor's situation is a little different again. Its .cursor/rules/ system uses .mdc files with YAML frontmatter that supports glob-pattern scoping — so you can write a rule that only activates when the agent is touching files matching src/api/**, which neither AGENTS.md nor CLAUDE.md does natively. It's a genuinely useful feature if you're working in a large monorepo where blanket instructions cause more harm than good. Cursor does read AGENTS.md as well, for what it's worth, so it's not adding to the fragmentation the way Claude Code currently is.

The Research That Should Change How You Write These Files

Here's the part most guides gloss over, and it's the reason I think this topic deserves more than another dry comparison table: a 2026 study out of ETH Zurich actually measured whether these context files help, and the results are not what the "just add an AGENTS.md" crowd wants to hear.

The researchers evaluated multiple coding agents and LLMs across two benchmarks, comparing outcomes with LLM-generated context files, developer-written context files, and no context file at all. The findings split cleanly into two categories, and they're both counterintuitive.

LLM-generated context files hurt performance in five out of eight tested settings. Agents took roughly 2.45 to 3.92 additional reasoning steps per task when working from an auto-generated file, and inference costs rose by 20 to 23 percent. The mechanism turned out to be redundancy — when you run /init or an equivalent generator, it tends to summarize things the agent could already discover on its own by reading the actual code and existing README. You end up paying extra tokens for the agent to re-read a worse version of information it already had access to.

Developer-written files did help, but modestly — around a 4 percentage point improvement on the AGENTbench benchmark, still with meaningful token overhead attached. In a follow-up experiment, the researchers stripped all other documentation out of the repo before re-testing, and under those stripped-down conditions the LLM-generated files actually did improve performance by about 2.7 percent. That confirms the core insight rather than complicating it: these files are only useful when they contain information the agent genuinely cannot get anywhere else. If your README already explains the architecture, restating it in AGENTS.md isn't harmless — it actively costs you accuracy and money at the same time.

Using Claude Sonnet pricing as a reference point, that 20 percent overhead is not trivial at scale. On a baseline agentic task running around 50K input tokens and 5K output tokens, the difference works out to roughly $45 a month at 1,000 tasks, climbing to around $4,500 a month once you're running 100,000 tasks — the kind of volume a mid-sized engineering org burns through without much thought. Prompt caching softens this considerably, since cached reads run about 90 percent cheaper than standard input pricing, but the underlying lesson doesn't change: bloated context files are not a free insurance policy.

What Actually Belongs in the File

Based on that research plus patterns from real production repos — Vercel's Next.js repo, the Inngest website repo, and others that have been iterated on for months — the content that consistently earns its place falls into a few categories, and none of them are "explain the architecture."

Exact versions and non-default tooling choices. If your team uses pnpm instead of npm, or pixi instead of pip, say so explicitly and say it's non-negotiable. Left unstated, an agent defaults to whatever's most common in its training data, which for most stacks means npm and pip. This is exactly the kind of thing a model cannot infer from reading your code — it can only guess, and it'll usually guess wrong.

Real commands with full flags, not descriptions of commands. "Run tests" is nearly useless. node --test --test-name-pattern "pattern" tells the agent precisely what to type. The more specific and copy-paste-ready the command, the less the agent has to reconstruct from memory, which is where hallucinated flags creep in.

Counterintuitive patterns, with the reasoning included. This is where AGENTS.md earns the most signal per line, by a wide margin. One real example that circulates in a few production repos: an API client where every method returns an ApiResult<T> instead of throwing, meaning wrapping calls in try/catch is always wrong for that codebase. Without that one sentence, an agent will wrap every API call in try/catch by default, because that's the statistically normal pattern everywhere else. A single sentence explaining the mechanism — not just the rule — is what lets the agent generalize correctly to situations you didn't explicitly cover.

A three-tier permission boundary. Most effective files split rules into what the agent can do freely, what it should ask about first, and what it should never touch:

• Always allowed: read files, run lint, run a single test file

• Ask first: installing or removing dependencies, deleting files, opening PRs

• Never: committing secrets or .env files, force-pushing to protected branches, modifying vendor/ or dist/

That structure gives the agent an explicit priority order for when rules seem to conflict, rather than leaving it to infer intent from a flat list.

What consistently should not be there: architecture overviews, directory structure diagrams, and anything already covered in your README. The ETH study specifically found that removing an "Architecture" section while keeping only commands, constraints, and non-standard patterns produced the same agent behavior at meaningfully lower token cost. Structural documentation also goes stale the moment your codebase changes shape, and a stale structural reference is worse than no reference — it actively misleads the agent into looking in the wrong place.

Skills Are a Different Layer, and Conflating Them Is a Common Mistake

One thing that trips people up, myself included at first, is treating SKILL.md files as just another variant of the same idea. They're not. AGENTS.md and CLAUDE.md are always-loaded context — the agent reads them at the start of every session whether it needs to or not. SKILL.md files use progressive disclosure: the agent only sees the skill's name and description up front, and loads the full body only when a task actually matches that skill's domain.

That distinction matters for where you put things. A rule that must apply to literally every edit — "always run lint before committing" — belongs in CLAUDE.md or AGENTS.md, because a skill only fires when the agent judges it relevant, and "every single edit" isn't a reliable trigger for that kind of matching. Deployment procedures, release checklists, or anything you'd only invoke occasionally are a much better fit for a skill, because they don't need to compete for attention in every session's context window. If you've watched a CLAUDE.md slowly grow from a short list of facts into a sprawling multi-step deployment runbook, that's usually the signal it's time to carve that section out into its own skill.

How Big Is Too Big

There's a rough consensus forming around file size, and it lines up with what you'd expect from the token-cost research above: start with a single root file, and once it crosses somewhere around 150 to 200 lines, split it into subdirectory-level files instead of letting the root file keep growing. Nested files take precedence over the root when there's a conflict, so a services/payments/AGENTS.md can override the root's testing conventions for that one service without touching anything else.

Codex enforces a hard 32 KiB limit on AGENTS.md and silently truncates anything past that — which is a good forcing function, honestly, even if it feels arbitrary. The CBMC project's repo sits near the upper bound most people cite as reasonable, at 371 lines, and that's treated as an edge case rather than a target to aim for. Shorter files perform better in practice, not just because of token cost, but because frontier models reliably follow something in the neighborhood of 150 to 200 discrete instructions before quality starts to degrade — past that, you're not adding rules so much as diluting the ones that matter.

A Setup That Actually Holds Up

If you're working the way I do — mostly Claude Code for the heavier reasoning work, Cursor for quick edits, occasional Copilot repos from clients — here's the setup that's held up without turning into a maintenance chore:

1. Write AGENTS.md as the single source of truth, keeping it under roughly 150 lines.

2. Symlink CLAUDE.md to it so Claude Code picks up the same content without a second file to maintain.

3. Skip /init or any auto-generator as your final output. Use it as a rough first draft if you want, but go back through and delete anything that just restates what's already in your README or obvious from the package.json.

4. Reserve actual SKILL.md files for procedures you invoke occasionally — deployment steps, release checklists — rather than cramming them into the always-loaded file.

5. Add rules reactively, when an agent actually gets something wrong twice, not speculatively because you think it might someday matter.

6. Version-control every change to these files and review them the way you'd review any other code change, because a bad instruction that ships silently degrades every session downstream of it.

That last point is the one I'd push back on hardest if I saw a team skipping it. These files feel like documentation, so they get treated with documentation-level rigor — which in most teams means none at all. But they're closer to configuration that runs on every single agent invocation. A vague or outdated line in there doesn't just sit unused like a stale paragraph in a wiki; it actively shapes what the agent does, every time, until someone notices and fixes it.

Where This Is Actually Headed

The fragmentation isn't fully resolved and I don't think it's going to be this year. AGENTS.md has won the standards battle in terms of adoption numbers, but CLAUDE.md's richer memory model gives Anthropic a real reason to keep it separate rather than fold it into the open spec, and I wouldn't bet on that changing just because a GitHub issue has a lot of upvotes. What's actually shifting is more interesting than the file-naming fight: the conversation on Hacker News and in dev communities has moved past "should I have one of these files" into "is my file actually helping or just burning tokens," which is a much better question to be asking a year and a half into agentic coding tools being a normal part of the job.

If you're setting this up for the first time, skip the temptation to auto-generate a comprehensive-looking file and call it done. Start small, write only what your agent genuinely can't infer on its own, and let the file grow from real, observed mistakes instead of anticipated ones. That's the difference between a context file that pays for itself and one that's quietly costing you accuracy and money every single session, without anyone noticing until someone finally runs the numbers.