When using an LLM for tasks like software development, one of the problems to solve is how to give the AI context around your workflow. Crafted prompts were the first attempt, then something called AGENTS.md came onto the scene early in 2025. This AI-readable README file for code repositories was designed to capture institutional knowledge and skills in a format that LLMs can parse, thereby improving the quality of the output code.

It was also designed for agentic coding tools so they would not require human intervention, and it probably helped at the time. It's become a de facto standard across the industry, but a recent research paper by ETH Zurich puts some doubt on its usefulness. That could simply be due to the rapid pace of the AI industry over the last year, but perhaps something else is at play, and better prompting and other skills are a better use of your time when starting agentic coding tasks.

What is CLAUDE.md, and why are people using it?

Or more non-specifically, AGENTS.md

AGENTS.md is an open format for guiding coding agents, designed by OpenAI, that works with pretty much any agentic coding tool and is now stewarded by the Agentic AI Foundation. OpenAI's site says its main repo has 88 AGENTS.md files, and they're made up of natural-language notes, like you would use to onboard a junior developer at a software company.

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where 

It's a mix of documentation and instructions, and the fact it makes you think about your workflow and put it down in writing is my favorite part. Institutional knowledge disappears as people move to other companies, and without codification, someone will have to rebuild processes in the future.

Where the context files break down

Research points toward minimal impact at best

Repository-level context files have been extensively studied over the years. The earlier papers show up to 36% improvement when utilizing this method, so you can't blame any of the LLM creators for pushing the use of AGENTS.md or similar files. The problem is that the studies showing improvement on that scale are two years old or older, which is an eon in AI development.

Recent studies from 2026 show up to 5% over-baseline output, or, in some cases, a negative effect when those context files are generated by AI. That surprised me. I would have thought that LLM-generated context files would work better, because it can see the connections between the codebase, but I was mistaken.

But while that's interesting, the tests showing that human-created context files only barely make a difference are more consequential. After all, these files take considerable time to create and tweak. They're probably still worth creating, but as a proper organizational handbook of what to do, because the improvements to agentic coding over the last year alone make them obsolete.

The other piece of the puzzle is that context files increase the number of steps the agents take to find solutions, and increase reasoning token use by up to 20%. That's a high cost when API usage is involved, especially for single-digit improvements at best.

What could we do instead?

The authors of the latest study offer some suggestions here, like including the minimum necessary requirements, such as specific tools or commands, if using AGENTS.md or CLAUDE.md files. High-level overviews are functionally useless, as the LLM can glean this from studying your codebase.

The other insight is that the current agent-developer "best practices" are anything but, and lag behind the actual implementation of frontier coding models. If anything, going back to basic principles is the way forward, using tighter context and retrieval methods instead of monolithic instructions, and tighter prompting using explicit restrictions like "respond with (1) analysis, (2) patch, (3) tests to update.

Really, anything you would have put in an AGENTS.md file could be better placed in a Model Context Protocol (MCP) server or a retrievable document, and have the agent call the relevant domain knowledge as it needs, rather than front-loading the context window with instructions it might not need.

AGENTS.md might be of limited use, but it does make you think about your workflow

Having large, per-repository AGENTS.md files to give context to your LLM was designed to work around context window restrictions. Reality is often not as neat, and the additional token burn combined with additional instruction space might actually be hurting your projects instead. But the general idea is good, and that's why Claude has Claude Skills, essentially the same file format for repeatable individual tasks instead of building repository-specific ones.