Back to Details

prune-context-file

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
基于Gloaguen等人（2025年）的研究成果，审核并精简CLAUDE.md或AGENTS.md文件，该研究是首项针对上下文文件是否能提升编码Agent性能的严谨性研究。

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
  • LLM生成的上下文文件会使性能下降0.5–2%，成本增加20%以上。绝对不要建议自动生成上下文文件。
  • 开发者编写的文件仅略有帮助（平均提升4%）——但Claude Code除外，开发者编写的文件对其完全没有益处。
  • 代码库概览毫无作用。无论有无目录列表和项目结构章节，Agent查找相关文件的速度都一样。
  • 上下文文件与现有文档重复。只有当仓库完全没有其他文档时，它们才会发挥作用。
  • 工具使用说明会被可靠遵循。指定具体工具（如
    uv
    、
    pytest
    、仓库CLI）会使其使用率比不指定时提高1.6–2.5倍。这是价值最高的内容。
  • 额外指令会增加测试和探索步骤，导致步骤数和成本上升。不必要的要求会让任务更难完成。
论文：《Evaluating AGENTS.md》——Gloaguen等人，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.md
    in that directory
  • No / agent can discover it from the codebase → cut it
对于每一行或每个章节，问自己：如果没有这部分内容，Agent编写的代码、执行的命令或做出的假设会有所不同吗？
  • 是，始终相关 → 保留在根目录文件中
  • 是，但仅在特定子目录工作时相关 → 移至该子目录下的嵌套
    CLAUDE.md
    文件
  • 否 / Agent可从代码库中自行发现 → 删除

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
  • 目录列表和项目结构章节
  • 可从
    package.json
    /
    requirements.txt
    /
    go.mod
    中发现的技术栈条目（如React、Express、Tailwind、TypeScript）
  • Agent可自行找到的文档链接
  • Claude默认已遵循的通用编码规范（如“使用描述性变量名”、“避免魔法数”）
  • 超过一句话的项目概述性文字

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, 
    uv
    vs. 
    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
  • 特定命令：构建、测试、迁移、数据填充、代码检查——仅当命令非显而易见，或未在
    package.json
    /
    Makefile
    /配置脚本中明确体现（Agent可直接读取这些文件）时保留
  • 非通用工具：Agent不会默认使用的库或CLI（如Better Auth而非Passport，
    uv
    而非
    pip
    ）
  • 架构约束：如果缺少会导致Agent做出错误假设的内容（如非标准国际化策略、单仓库布局的特殊规则）
  • 行为规则：Git工作流、PR要求、测试要求——必须强制执行而非推导的规则
  • Agent无法从代码中推导的项目特定约定

Move to subdirectory 
CLAUDE.md
(relevant only in specific contexts)

移至子目录
CLAUDE.md
（仅在特定场景下相关）

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
根目录下的
CLAUDE.md
会在每次会话中加载，与任务无关的内容会持续消耗token成本。子目录下的
CLAUDE.md
文件（如
/web/CLAUDE.md
、
/api/CLAUDE.md
）仅在Agent读取该子目录下的文件时按需加载。
当内容仅适用于代码库的特定部分时，将其移至此处：
  • 前端专属约定（组件模式、CSS框架规则、特定UI库）
  • 后端专属约定（ORM模式、API设计规则、服务层约束）
  • 任何拥有独立工具、模式或非通用约束的子系统

Process

处理流程

  1. Read the target context file
  2. Classify each section and bullet against the Cut/Keep criteria above
  3. Present a proposed diff: list what you'd remove and why (one line per item)
  4. Wait for approval before rewriting
  5. Write the pruned file, keeping the same structure but leaner
  1. 读取目标上下文文件
  2. 分类：根据上述删除/保留标准，对每个章节和条目进行分类
  3. 呈现修改建议：列出要删除的内容及原因（每项一行）
  4. 等待批准后再重写文件
  5. 编写精简后的文件，保留原有结构但更简洁

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.
呈现修改建议时，按操作类型分组：
REMOVE
- [章节/条目] — [一行原因]

KEEP
- [章节/条目] — [一行原因]

REWRITE
- [章节/条目] → [修改后内容] — [一行原因]
然后在应用修改前请求确认。