An AGENTS.md or CLAUDE.md file is useful when it prevents a repeated mistake. It is a liability when every task has to carry instructions for work it is not doing. The 2026 research on these files is not contradictory once the measured outcome is made explicit.
The three studies answer different questions. One measured runtime and output tokens, another measured task success and reasoning cost, and the third counted recurring configuration smells. Their results can disagree without any of them describing how 2dayapp would perform.
The useful question for this repository is narrower: if a root instruction file is added, what belongs in it, and what should stay next to the work that needs it?
Read the three studies as three different questions
On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents compared 124 pull requests across 10 repositories with and without AGENTS.md. The file condition reduced median runtime by 28.64% and output tokens by 16.58%. The study centered on time and output, not an improvement in correctness.
Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? evaluated repository tasks across multiple agents and models. Its context-file condition showed a tendency toward lower task success and more than 20% higher reasoning cost. More exploration and broader tests can be harmful when the added requirements are unrelated.
Configuration Smells in AGENTS.md Files examined 100 popular open-source repositories containing AGENTS.md or CLAUDE.md. It found Lint Leakage in 62% of the sample, Context Bloat in 42%, and Skill Leakage in 35%. Those numbers describe the prevalence of patterns defined by the researchers; they do not measure the performance penalty of each pattern.
| Study | Main question | Observation | Boundary |
|---|---|---|---|
| Efficiency study | Does persistent context reduce work? | Runtime and output tokens fell | It did not show higher correctness |
| Context evaluation | Can repository context make tasks harder? | Lower success trend and over 20% more reasoning cost | It did not show that every handwritten file is harmful |
| Smell analysis | What goes into these files in practice? | Context Bloat appeared in 42%, among other patterns | It did not measure each smell’s cost |
These results can all be true. A repository map and an exact verification command may prevent rediscovery. Unrelated rules can make an agent search wider and spend effort satisfying constraints that do not apply.
The root file has one job: shared context
OpenAI describes AGENTS.md as persistent Codex context for naming conventions, non-obvious business logic, known quirks, dependencies, verification commands, and contribution rules. Anthropic describes CLAUDE.md as project context loaded into sessions and recommends specific, concise guidance. The often-cited “under 200 lines” target is a Claude Code rule of thumb, not a universal product limit and not a proven optimum for Codex.
The common rule is scope. Put information in the root file only when most tasks need it. Put a deployment procedure, a directory-specific convention, or a one-off investigation beside the work that uses it.
A concrete check for this repository
At the time this article was written, the repository had neither AGENTS.md nor CLAUDE.md. The studies alone were not evidence that 2dayapp should add one or that its work would improve. I first checked where the repository’s rules already live: package.json is the source for verification commands, while deploy.yml is the source for deployment order.
The repository’s package.json does provide a concrete candidate for a shared rule: pnpm verify combines formatting, linting, Astro and TypeScript checks, tests, and the static build. A future root file could point to that command. It should not copy a general JavaScript tutorial or repeat every formatter setting already visible in the repository.
## Verification
- Before completing a change, run `pnpm verify`.
- Keep procedures for one directory or one deployment next to that scope.This is a proposed snippet, not a claim that the repository already contains it. That distinction matters: adding a file is an action, while proving that it helped requires comparable tasks and measurements.
Mapped onto this repository, the boundary looks like this:
| Information | Source or scope | Does it belong in the root file? |
|---|---|---|
Run pnpm verify before completing a change |
package.json plus a short root rule |
Only as a pointer if the command is easy to miss |
The verify → deploy → indexnow order |
deploy.yml |
Keep deployment detail in the deployment workflow |
| How internal links are checked | check-internal-links.mjs and its tests |
Do not copy executable behavior into prose |
The root file, if added, should contain the small entry point an agent might miss—not a duplicate of the workflow or script. Keeping the executable source in place makes the rule easier to update and easier to verify.
What to remove when the file grows
Start with content that is easy to verify elsewhere:
- rules copied from
package.json, the formatter, or the linter; - procedures for one deployment or one directory;
- generic programming advice and tool tutorials;
- stale paths and commands;
- repeated versions of the same instruction;
- abstract requirements with no observable check.
Codex can narrow the scope with nested AGENTS.md files. Claude Code can use path-scoped rules or skills. Splitting a file helps only if the loading scope actually becomes narrower. If every task loads every fragment, the context cost remains.
The decision that survives the evidence
The research does not justify a universal line limit or a universal yes/no answer. It supports a narrower rule: keep root instructions to information that is hard to infer from the code, applies to most tasks, and has a checkable effect. Move task-specific procedures out of the always-loaded path.
To evaluate a real change, compare similar tasks by success, elapsed time, input tokens, and unnecessary exploration. 2dayapp has not run that comparison for these files, so this page stops at the research-backed decision rule.