Drop Agents.md and Claude.md news update
Developer benchmarks reveal agent context files raise inference costs by over 20 percent without improving coding success, prompting moves to README links.
By Dillip Chowdary • Nov 19, 2026 • Source: drmike.xyz

At a glance
- Standard steward
- Agentic AI Foundation
- Adoption count
- Over 60,000 open-source repositories
- Research date
- February 2026
- Inference penalty
- Over 20% cost increase on average
- Codex doc cap
- 32 KiB default limit
- Claude line limit
- Under 200 lines per file
In this post
Software developer Mike announced an alternative workflow to eliminate dedicated instruction files for autonomous coding agents, documenting the approach in drmike.xyz's report. Instead of maintaining bespoke configuration documents across repositories, the proposal replaces separate agent instruction files by consolidating developer guidance into standard project documentation.
This report examines how eliminating specialized prompt files simplifies repository management, cuts context overhead, and prevents documentation drift. The analysis covers software teams using coding assistants like Claude Code, Codex, and Cursor who want single-source project instructions.
01Proliferation of competing instruction formats
Developer tools initially adopted conflicting instruction formats to guide language model behavior across repositories. Cursor parsed .cursorrules, GitHub Copilot evaluated .github/copilot-instructions.md, and Claude Code looked for CLAUDE.md. Windsurf read .windsurfrules, Cline targeted .clinerules, Gemini CLI tracked GEMINI.md, and Amp parsed AGENT.md.
To resolve fragmented formats, a coalition consisting of OpenAI Codex, Amp, Factory, Cursor, and Google Jules launched the AGENTS.md standard. In December 2025, governance of AGENTS.md transitioned to the Agentic AI Foundation hosted under the Linux Foundation. Claude Code adopted fallback support for AGENTS.md starting in version 2.1.277 when CLAUDE.md is absent.
The AGENTS.md registry tracks adoption across more than 60,000 open-source repositories. The standard defines plain Markdown filenames without mandatory schema fields, defaulting to the closest file when repositories contain multiple copies.
02Redundancy in standard project guidance
Sample configuration files published by the AGENTS.md project highlight standard onboarding instructions such as setup commands and code style. The official examples list commands like pnpm install, pnpm dev, and pnpm test alongside rules for TypeScript strict mode and single quotes.
Human engineers require identical setup steps, build scripts, and style conventions on their first day on a project. Smaller codebases historically maintain these instructions inside the development section of README.md. Larger codebases host the same instructions inside CONTRIBUTING.md, which GitHub linked to pull request forms in 2012.
Maintaining separate build instructions across README.md and AGENTS.md creates documentation drift when dependency commands diverge. Language models with repository write permissions can parse human-facing onboarding documentation without requiring separate prompt text.
03Benchmark evaluations on task resolution
Advertisement
Tech Pulse Daily
Get tomorrow's pulse first
Join engineers who read Tech Pulse before stand-up. Free, weekday mornings.
A February 2026 empirical study led by Thibaud Gloaguen alongside researchers from ETH Zurich and LogicStar.ai evaluated context file effectiveness. The team tested Claude Code with Sonnet 4.5, Codex with GPT-5.2 and GPT-5.1 mini, and Qwen Code with Qwen3-30B-coder across real GitHub issues.
| Setup Configuration | SWE-bench Lite Delta | Benchmark Success Delta | Inference Cost Delta |
|---|---|---|---|
| LLM-Generated Files | -0.5% | -2% | +20% |
| Developer-Written Files | Baseline | +7% over generated | +20% |
| Zero Context Files | Equal to context | Equal to context | 0% |
The study concluded that context files do not generally improve task success rates while increasing inference cost by over 20 percent on average. The researchers found that general repository overviews offered no measurable performance benefits over basic repository documentation.
04Instruction file sizing and tool limits
Instruction loaders inject file contents directly into model context windows on every active session. OpenAI Codex caps project documentation files at 32 KiB by default, while Claude Code documentation recommends restricting instructions to under 200 lines per file.
Behavioral constraints such as permissions and execution hooks operate through local configuration rather than Markdown context files. User-level execution preferences belong in tool setting files rather than shared repository documentation.
Detailed conventions exceeding context thresholds can be split into CONTRIBUTING.md or dedicated directories. Standard human documentation practices keep repository instructions compact enough for model ingestion.
05Symbolic links and fallback configurations
Teams adopting unified documentation can replace root instruction files with symbolic links pointing directly to existing README.md files.
- Move unique rules into README.md or CONTRIBUTING.md before removing redundant files.
- Remove obsolete files using git rm AGENTS.md CLAUDE.md to clear old instructions.
- Generate symbolic links by executing ln -s README.md AGENTS.md in the root directory.
- Stage the link with git add AGENTS.md to expose the README to compatible harnesses.
Note: Claude Code edit tools refuse to write through symbolic links, requiring agents to target README.md directly by its real name.
Tools also support explicit fallback configuration without symbolic links. Claude Code imports external files by including references like @README and @package.json inside CLAUDE.md. Codex accepts fallback definitions via project_doc_fallback_filenames in ~/.codex/config.toml, while Gemini CLI configures context.fileName in .gemini/settings.json and Aider supports read parameters in .aider.conf.yml.
Frequently asked questions
Why do developers replace AGENTS.md with README.md?
Build commands, setup steps, and style rules in AGENTS.md duplicate standard human onboarding docs. Consolidating instructions into README.md prevents documentation drift and provides one accurate source.
Did academic testing show benefits from context files?
An ETH Zurich and LogicStar.ai study found context files do not generally improve task success rates and raise inference costs by over 20 percent. Agents without context files solved about as many issues.
How does Claude Code handle symbolic links to README.md?
Claude Code reads AGENTS.md symlinks starting in version 2.1.277 if no CLAUDE.md exists. However, its editing tools refuse to write through symbolic links, so edits must target README.md directly.
How can tools load README.md without symbolic links?
Codex configures project_doc_fallback_filenames in config.toml, Gemini CLI sets context.fileName in settings.json, Aider sets read in .aider.conf.yml, and CLAUDE.md can reference @README.
Sources
Author
Dillip Chowdary
Writes Tech Bytes coverage of AI, engineering, and the tools that actually ship. Editor of Tech Pulse Daily.
Related on Tech Bytes
Advertisement