One Instructions File to Rule Your Agent: What AGENTS.md and CLAUDE.md Can and Can't Fix

Fabien Sanglard's "My agent.md to improve LLM-assisted code quality" spent the weekend parked on the Hacker News front page: 325 points, 138 comments, and a thread full of engineers trading rule files like recipes. One tab over, GitHub's trending chart belongs to andrej-karpathy-skills, a repo built around a single CLAUDE.md distilling Andrej Karpathy's public observations about LLM coding pitfalls; it's sitting at roughly 206,000 stars, and Karpathy didn't even write it (more on that below). If you wanted proof that the single-file agent instructions pattern owns the current discourse, this was the week.

Why is everyone shipping a single instructions file?#

Because every vendor finally agreed to read one. AGENTS.md, the open format now stewarded by the Linux Foundation's Agentic AI Foundation, is consumed by OpenAI Codex, Cursor, GitHub Copilot, Google Jules, Zed, Aider, and a long tail of others, with over 60,000 open-source projects already carrying the file. Copilot picks it up anywhere in your repo, plus CLAUDE.md or GEMINI.md at the root. Claude Code reads CLAUDE.md and documents a one-line @AGENTS.md import so both tools share a source. We've mapped the format differences in CLAUDE.md vs AGENTS.md vs Cursor rules.

The demand side is just as loud. Sanglard describes the itch precisely: he kept typing the same corrections into every session ("don't use magic numbers," "keep function names short") until he wrote them down once. And the star velocity on the Karpathy-derived repo, which packages four behavioral principles a community developer extracted from Karpathy's January post on X (Karpathy has no affiliation with the repo), says a few hundred thousand people share that itch. The repo's four principles (think before coding, simplicity first, surgical changes, goal-driven execution) fit in 65 lines, which is arguably the whole point: the pattern's pitch is that 65 well-chosen lines beat any amount of scaffolding.

What does the pattern actually get right?#

More than the skeptics admit. A single agent instructions file is portable across tools, versioned with your code, reviewable in a pull request, and needs zero infrastructure. That last property is quietly radical: your agent's operating guidance gets the same diff-and-review treatment as the code it governs, instead of living in chat history and tribal memory.

There's evidence it helps, though it's thinner than the star counts suggest. A February 2026 arXiv study across four agent-model pairings found that developer-written context files nudged task success up by about 2.4% on average, a lift that fell short of statistical significance, and it confirmed that agents follow the instructions inside them closely. The authors' own conclusion lands where the practitioners have: these files earn their keep by specifying non-standard practices, not by boosting raw performance. And notice what Sanglard's rules and the Karpathy principles have in common: they're stable preferences. "Always use braces," "extract magic numbers," "make surgical changes" will be just as true next quarter. That's the sweet spot. Sanglard's own arc is instructive here: his mid-2025 attempts at LLM-assisted work produced code that didn't compile, while by 2026 the models could implement an indexed binary heap and pinpoint an obscure bug, yet still emitted what he calls spaghetti until the rules file reined in the style. His verdict is appropriately unsentimental: "LLMs constantly hallucinate and cannot be trusted." The file doesn't fix that. It just makes the review cheaper by making the output predictable.

The craft guidance is converging too. Claude's docs recommend staying under 200 lines, Copilot's docs advise keeping instructions under two pages, Codex caps combined size at 32 KiB by default, and Cursor suggests keeping rules under 500 lines. Short files get followed; sprawling ones get skimmed. If yours has sprawled, here's how to audit and fix a bloated CLAUDE.md.

Where does one file hit its ceiling?#

The same place every static artifact does: the moment reality moves. Your team migrates test frameworks, renames a service, or reverses an architectural decision, and the file keeps confidently asserting the old world. Nobody gets paged when it drifts. We've traced that failure mode in rules file rot and in keeping agent instructions up to date.

Contradictions are worse, because they fail silently. Claude's own memory documentation is blunt: "if two rules contradict each other, Claude may pick one arbitrarily." Copilot's docs likewise warn against "conflicting sets of instructions." There's no compiler for your rules, no error, no lint. You find out when the agent does the wrong thing convincingly.

Then there's scale. One file per repo, times fifty repos, times three formats, is a synchronization problem masquerading as a documentation pattern; we've covered keeping CLAUDE.md, AGENTS.md, and .cursorrules in sync. The same arXiv study found LLM-generated instruction files made agents slightly worse in most of its test settings, and every kind of context file inflated inference cost by over 20% on average. Commenters on Sanglard's thread pushed further: plenty of these files are fossilized workarounds for model behaviors that no longer exist. Two more threads of skepticism from the discussion are worth stealing. First, anything a linter can enforce should live in the linter, where compliance is deterministic instead of probabilistic; the file should hold what tooling can't check. Second, frontier models need far less procedural coaching than their 2024 ancestors did, so a rule that made sense two model generations ago may now be pure context tax. Both arguments point the same direction: the file's honest scope keeps shrinking toward judgment calls only your team can make.

What belongs in the file, and what gets retrieved at runtime?#

Split by rate of change. Stable and repo-scoped earns a line in the file:

• Build, test, and lint commands, and the order to run them
• Naming conventions, layering rules, and style calls your tooling can't enforce
• The always/never list: approval workflows, forbidden directories, deployment rules
• Pointers to deeper docs the agent should read before touching sensitive areas

Everything that changes weekly stays out. What shipped yesterday, what's in flight on a neighboring branch, what the ticket actually asks for, what that Slack thread decided at 4pm: none of it can live in a static file, because the file was true when it was committed and the work is happening now. This is the part of the pattern nobody's markdown template solves, and it's why teams that stop at the file keep watching their agent make confident, well-formatted mistakes.

That second half is what a context engine is for. Unblocked connects your repos, issue trackers, Slack, and docs so the agent queries current institutional context instead of trusting a snapshot; rules files vs a context engine walks through the architecture, and why not just Claude Code covers where the built-in memory stops. It's the difference between handing your agent a laminated card and giving it someone to ask.

Here's what that looks like in practice, from an engineer at Clio:

I built a step called 'enrich' that runs before any code gets written. The agent asks Unblocked for everything — the ticket, the Slack context, what's been done in related repos — and then it starts implementing. It's especially powerful for cross-repository work where you'd otherwise have to do all that archaeology yourself.

Arthur Rodolfo — Software Engineer, Clio

The file tells the agent how your team writes code. Retrieval tells it what's actually going on, which is the job of institutional memory and a shared team memory hub, not a markdown snapshot.

Frequently asked questions#

Should I write AGENTS.md or CLAUDE.md?#

Write AGENTS.md and bridge from there. It's the vendor-neutral format with the widest support, and tools that prefer their own filename can consume it: Claude Code documents a one-line @AGENTS.md import (or a plain symlink), and Copilot reads the shared file natively. Maintaining parallel hand-edited copies is exactly how instruction files drift apart, so pick one canonical file and generate or import the rest. Monorepos get nesting for free: Codex walks from the git root down and lets closer files override earlier guidance, and Cursor combines nested files with the more specific instructions taking precedence, so per-service rules can live next to the service.

How long should an agent instructions file be?#

Shorter than the one you have. The vendors are unusually aligned here: under 200 lines (Claude), two pages (Copilot), 32 KiB combined (Codex), under 500 lines (Cursor). Adherence drops as length grows, because instructions compete with your actual task for attention. A useful habit: every time you add a rule, delete or verify one. Treat the file like an API surface, not an append-only log.

Do these files measurably improve agent output?#

Barely, and only when humans write them. The arXiv evaluation found a 2.4% average lift from developer-written files that didn't reach statistical significance, a small negative effect from LLM-generated ones, and wide variance by model; Claude Sonnet 4.5 actually scored slightly worse with them while a smaller open model gained nearly eight points. The study's headline is blunter: context files don't generally improve success rates, and they add over 20% to inference cost. Benchmarks don't capture everything (consistency, review burden, avoided rework), but the data supports writing a small, deliberate file rather than generating a big one.

The file you should still write#

Write the file. Keep it under a couple hundred lines, limit it to rules that were true last quarter and will be true next quarter, version it, and prune it on a schedule. Treat contradictions as bugs, because your agent will resolve them by coin flip, and treat every rule a linter could enforce as a rule that belongs in the linter. The pattern earned its moment on the front page honestly: cheap, portable, reviewable guidance beats re-typing corrections into a chat box forever, and the research agrees with the narrow version of the pitch, a file that encodes your non-standard practices, even if it won't move a benchmark.

Just don't ask a markdown file to be your team's memory. It's the stable layer of a two-layer system, and the dynamic layer, the tickets and threads and cross-repo history your agent needs mid-task, belongs to retrieval from a single source of truth that updates when your team does. One file to rule your agent's style. A context engine for everything the file can't know.