Prune Context File
Audit and prune a CLAUDE.md or AGENTS.md file using findings from Gloaguen et al. (2025), the first rigorous study of whether context files improve coding agent performance.
Evidence Base (key findings)
- LLM-generated context files reduce performance by 0.5–2% and increase cost 20%+. Never suggest auto-generating a context file.
- Developer-written files marginally help (+4% avg) — except for Claude Code, which showed no benefit from developer-written files either.
- Codebase overviews don't work. Agents find relevant files at the same speed with or without directory listings and project structure sections.
- Context files are redundant with existing docs. They only help when a repo has *no other documentation at all*.
- Tooling instructions are reliably followed. Naming a specific tool (e.g.
uv,pytest, a repo CLI) increases its usage 1.6–2.5× vs. not naming it. This is the highest-value content. - Instructions cause more testing and exploration, increasing steps and cost. Unnecessary requirements make tasks harder.
Paper: "Evaluating AGENTS.md" — Gloaguen et al., arxiv.org/abs/2602.11988
The Decision Test
For every line or section, ask: *Would the agent write different code, run different commands, or make different assumptions without this?*
- Yes, always relevant → keep in root
- Yes, but only when working in a specific subdirectory → move to a nested
CLAUDE.mdin that directory - No / agent can discover it from the codebase → cut it
Classification
Cut (low value)
- Directory listings and project structure sections
- Tech stack entries discoverable from
package.json/requirements.txt/go.mod(e.g. React, Express, Tailwind, TypeScript) - Links to docs files the agent can find itself
- General coding standards Claude already applies by default (e.g. "use descriptive variable names", "avoid magic numbers")
- Project overview prose beyond one sentence
Keep in root (high value, always relevant)
- Specific commands: build, test, migrate, seed, lint — only if non-obvious or not already expressed as
package.json/Makefile/ config scripts the agent can read directly - Non-obvious tooling: libraries or CLIs the agent wouldn't default to (e.g. Better Auth vs. Passport,
uvvs.pip) - Architectural constraints that would cause wrong assumptions if missing (e.g. non-standard i18n strategy, monorepo layout quirks)
- Behavioral rules: git workflow, PR requirements, test requirements — things that must be enforced, not inferred
- Project-specific conventions the agent can't infer from code alone
Move to subdirectory CLAUDE.md (relevant only in specific contexts)
Root CLAUDE.md loads every session regardless of task — content irrelevant to most work has a standing token cost. Subdirectory CLAUDE.md files (e.g. /web/CLAUDE.md, /api/CLAUDE.md) load on-demand only when the agent reads files in that subtree.
Move content here when it only applies to a specific part of the codebase:
- Frontend-only conventions (component patterns, CSS framework rules, specific UI libraries)
- Backend-only conventions (ORM patterns, API design rules, service layer constraints)
- Any subsystem with its own tooling, patterns, or non-obvious constraints
Process
- Read the target context file
- Classify each section and bullet against the Cut/Keep criteria above
- Present a proposed diff: list what you'd remove and why (one line per item)
- Wait for approval before rewriting
- Write the pruned file, keeping the same structure but leaner
Output Format
When presenting the proposed changes, group by action:
REMOVE
- [Section/item] — [one-line reason]
KEEP
- [Section/item] — [one-line reason]
REWRITE
- [Section/item] → [what it becomes] — [one-line reason]Then ask for confirmation before applying.