Home / Blog / Drop Agents.md and Claude.md news update
Tech News

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

Drop Agents.md and Claude.md news update
Image: 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

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 ConfigurationSWE-bench Lite DeltaBenchmark Success DeltaInference Cost Delta
LLM-Generated Files-0.5%-2%+20%
Developer-Written FilesBaseline+7% over generated+20%
Zero Context FilesEqual to contextEqual to context0%

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.

  1. Move unique rules into README.md or CONTRIBUTING.md before removing redundant files.
  2. Remove obsolete files using git rm AGENTS.md CLAUDE.md to clear old instructions.
  3. Generate symbolic links by executing ln -s README.md AGENTS.md in the root directory.
  4. 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

Dillip Chowdary

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

5-min tech signal

Weekday briefing for engineers who skip the noise.

No spam · Unsubscribe anytime

Advertisement

✈️ CareerPilot

Your AI job-search copilot

Match your resume against live Ashby, Greenhouse & Lever openings — fit scores, job-specific resume optimization and email alerts.

Find matching jobs →

Free Tools

Browse all tools →