Pruning CLAUDE.md and AGENTS.md: The Ablation Protocol

Pruning context files means treating CLAUDE.md, .cursor/rules, and AGENTS.md as a budget to cut rather than a log to extend: instead of adding a rule after every mistake, the ablation protocol removes lines, watches for repeated failures over time, and restores only what demonstrably breaks without it. The practice reflects a July 2026 shift across tool vendors away from accretive instruction files toward smaller, evidence-tested ones.

Three months ago you added a line telling the agent never to run pnpm build while the dev server is up. This morning it ran pnpm build while the dev server was up. Your instinct is to rewrite the rule in bold, prefix it with “IMPORTANT”, and maybe add “YOU MUST” for good measure.

That is the wrong fix, and it has been the wrong fix for a while. What changed in July 2026 is that the people who build these tools stopped disagreeing about it.

What you’ll walk away with from the ablation protocol

A dated map of why every guide you have read contradicts every other guide, and a one-question test for telling which era a post belongs to
The mechanics each tool’s docs bury: which of your files load at launch, which load lazily, which “optimization” saves nothing at all, and the 32 KiB cut Codex makes without telling you
A routing table that answers “where does this line go” across all five destinations: root file, subdirectory file, path-scoped rule, skill, hook
Nine copy-paste prompts, with the per-tool deltas spelled out, that do the deleting and the moving for you
A protocol for re-running all of it the next time you change models, which is the trigger that actually matters

Why every guide you found contradicts every other guide

Here is the short version: the advice inverted, and almost nothing you will read is dated clearly enough for you to tell which side of the inversion it sits on.

Two words make the rest of this readable. They are not our coinages — they are the vocabulary Anthropic and the Claude Code team use themselves.

Accretion is growth by accumulation. Every time the model does something you did not want, you add a line telling it not to. The file only ever gets longer, and every rule is a scar from one specific past mistake.

Ablation is the opposite: deliberately cutting material away to see what happens without it. It is borrowed on purpose — ablation is the standard term in machine-learning research for removing a component to measure its contribution, and it is the word Anthropic used for what it did to Claude Code’s own system prompt.

The timeline:

December 2025. The Agent Skills spec lands. Every context-file guide written before this date had nowhere else to put conditional knowledge, so it all went in the main file. That is why 2025-era templates look maximalist. They were not wrong at the time — they predate the alternative.
January 2026 — accretion is the default. Boris Cherny, who created Claude Code and still runs it, describes the team’s own checked-in file: “Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time.” The companion tip: end every correction with “update your CLAUDE.md so you don’t make that mistake again.”
June 2026 — the tension shows. In a year-in-review conversation the same team describes itself as context-minimalist at the system-prompt level (“the minimal possible system prompt, the minimal possible tools, and then you let the model figure it out”), and restates the accretive project-file advice in the same breath.
24 July 2026 — the number. Anthropic publishes “The new rules of context engineering for Claude 5 generation models.” The Claude Code team removed over 80% of the system prompt for models like Opus 5 and Fable 5, with no measurable loss on coding evaluations.
26-27 July 2026 — ablation is the default. Opus 5 ships. The next day, the advice to users is the inverse of January’s: delete your context files, your skills and your hooks every six months, and see what the model can do without them before you add anything back.

Both camps say prune. They are opposite in default direction and cadence. Accretion says add on every error and edit occasionally. Ablation says delete everything periodically and add back rarely. Same team, inverted default, as the models crossed a capability threshold.

Which gives you the test: if a post about context files does not tell you when it was written, you cannot use it. Anything before December 2025 predates skills. Anything before late July 2026 predates the ablation turn. That includes most of the top search results, and it includes several articles on this site that we have since corrected.

The dial, not the doctrine

Before you go and delete anything, be clear about what the ablation advice is pegged to. The 80% cut was made for Opus 5 and Fable 5 specifically. The “delete everything” line came from an interview given the day after Opus 5 shipped. None of it was tested on, or claimed for, a mid-tier or older model — and plenty of people run Sonnet for cost, Haiku for volume, or a local model for privacy.

The principle underneath travels better than the specific advice:

The scaffolding you need is inversely proportional to the capability of the model reading it. Every rule you write is a bet that the model cannot work this out on its own. Better models win those bets back.

That reframes the whole argument as a dial you set, not a doctrine you follow.

Frontier thinking models (Opus 5, Fable 5, GPT-5.6 Sol and equivalents). Ablate aggressively. This is where the published advice applies as written. Expect to end up with a very short file.

Mid-tier and older models (Sonnet, Haiku, previous Opus generations, local models). Keep more — but understand that the trade is worse in both directions. These models genuinely benefit from explicit instruction: the package manager, the prerequisite, the gotcha. Their instruction budget is also tighter, because smaller and non-thinking models degrade faster as instructions pile up than frontier thinking models do. You need more rules and you can afford fewer of them, which makes prioritisation matter more, not less.

Mixed teams. If your repo is read by your Opus 5, a colleague’s Sonnet, and CI running something cheap, the file has to serve the least capable reader in the loop. Tune for that one. A strong model copes with a slightly over-specified file far better than a weak model copes with an under-specified one.

The practical upgrade to “delete it every six months”: re-ablate whenever you change models, not on a calendar. Six months is a proxy for “a model generation has probably passed.” A model switch is the actual trigger. And when you move down a tier — cost pressure, rate limits, an offline model — expect to add some back. That is the dial moving, not you regressing.

What the evidence actually says

There is much less rigorous work here than the confident blog posts imply, and what exists is not a ringing endorsement. Three studies matter.

Study	What it actually found
Chroma, Context Rot (2025)	18 frontier models, inputs from roughly 10k to 500k tokens. Every single one degrades as input length grows. Not most — all of them, at every increment tested. Degradation is non-uniform, and there is a pronounced lost-in-the-middle effect: a fact buried mid-context is far less likely to be used than the same fact at either end.
Jaroslawicz et al., How Many Instructions Can LLMs Follow at Once? (July 2025)	The IFScale benchmark: 500 instructions, 20 models, seven providers. The best frontier models reach 68% accuracy at 500 instructions. Crucially, adding instructions degrades adherence to all of them, not just the new ones — and there is a measurable bias toward instructions that appear earlier.
Gloaguen et al., ETH Zurich, Evaluating AGENTS.md (v1 Feb 2026, v2 Jun 2026)	The most direct study of whether repository context files help at all. The v2 abstract: context files “do not generally improve task success rates, while increasing inference cost by over 20% on average.” The v1 paper reported a granular split that v2 aggregates away: LLM-generated files about 3% worse, developer-written files about 4% better.

The most useful result is not the success rate. It is the mechanism. When a context file mentioned the uv tool, agents used it 1.6 times per instance versus under 0.01 when it was not mentioned — a 160-fold increase. Repo-specific tools showed a roughly 50-fold jump.

Instructions are followed. Sometimes to a fault. Every line you write is an attractor, pulling the agent toward whatever it names whether or not the task calls for it. That is the real cost of a long file, and it is why “harmless extra context” is not a thing.

The paper is equally direct about the single most common section in these files: “repository overviews, although popular and recommended by model providers, are not helpful.”

So do context files help? Less than the vendor consensus implies, and the honest answer is that this is not settled. A follow-up paper (Probe-and-Refine) points out that neither the ETH study nor its successors vary the agent’s step budget, which is a real confound, and notes that the two most rigorous studies in this area reach opposite conclusions. Treat the ~4% developer-written gain as v1’s finding within that study’s scope, not as a measured law.

What survives the disagreement is narrower, and the two halves of it carry different weight. Length has a real, measurable cost — that one is supported right across the table: Chroma measured it against input length, IFScale against instruction density, ETH against inference cost. Hand-written beats generated is the weaker claim: it is ETH v1’s result within its own scope, and neither of the other two studies compared authorship at all. Lead with the first. Neither depends on context files being a large win.

What actually defers loading

This is the section the official docs will not assemble for you, and it is where most wasted context lives. Everyone knows the main file loads every session. Almost nobody has checked which of the other mechanisms actually defer loading and which merely look like they do.

Loads every session: any .mdc rule with alwaysApply: true, plus User Rules and Team Rules. Team Rules are the easy one to forget, because they are managed from the dashboard rather than your repo — you can be paying for context you cannot see in your checkout.

Loads conditionally: rules with globs (only when you touch matching files), rules with only a description (only when the agent judges them relevant), and manual rules (only when you type @rule-name).

Loads lazily: AGENTS.md in subdirectories. This is newer than most guides and widely missed — Cursor reads AGENTS.md natively in the project root and in any subdirectory, applying it when you work with files in that directory or its children.

Two traps worth knowing:

Frontmatter is honoured only in .mdc files. Put globs or alwaysApply at the top of a plain .md rule and it is ignored — the file applies as-is, which usually means always. This is the single most common reason a “scoped” rule is silently costing you context on every turn.
/migrate-to-skills skips exactly the rules you most need to review. It converts dynamic rules and slash commands into skills, but excludes rules with alwaysApply: true or specific glob patterns. Your always-on rules are the expensive ones, and the migration tool will walk straight past them.

Cursor’s stated guidance is to keep rules under 500 lines and split large ones into composable files. Precedence when rules conflict: Team Rules, then Project Rules, then User Rules — all applicable rules are merged, and earlier sources win.

Loads every session, in full: managed policy files, ~/.claude/CLAUDE.md, the project CLAUDE.md, CLAUDE.local.md, and every .claude/rules/*.md file that has no paths frontmatter. Also the first 200 lines (or 25KB) of auto memory’s MEMORY.md.

Loads conditionally: .claude/rules/*.md files with a paths glob — these enter context only when Claude reads a matching file.

Loads lazily: CLAUDE.md files in subdirectories below your working directory. Files in the hierarchy above it load in full at launch; files below load on demand when Claude reads something in that directory. That asymmetry is the whole game in a monorepo.

Three traps:

@path imports do not reduce context. The docs are explicit: imported files “are expanded and loaded into context at launch,” and splitting content into imports “helps organization but doesn’t reduce context.” Breaking a 400-line file into five tidy imports gives you the same 400 lines every session, just filed more pleasantly. Use imports when you want the content every session and just don’t want it inline. Do not use them expecting a saving.
Subagents multiply the cost. Explore and Plan skip CLAUDE.md entirely — which tells you something about how load-bearing Anthropic thinks it is for reading code. Every other subagent loads the full hierarchy. Fan out ten subagents and you have paid for that file eleven times. Heavy parallel workflows are an argument for a shorter file, not a weaker one.
Auto memory is accretion with you removed from the loop. It is on by default, and Claude writes its own notes to ~/.claude/projects/<project>/memory/ based on your corrections. The index loads into every session alongside your file. If you are going to ablate, this is part of the surface you are ablating. Run /memory and read what is in there.

One free win: block-level HTML comments are stripped before injection. Notes for human maintainers cost zero tokens.

Loads every session: the global file (~/.codex/AGENTS.override.md if present, otherwise ~/.codex/AGENTS.md), then every AGENTS.md from the repository root down to the directory you started the session in — at most one file per directory level.

Loads conditionally: nothing. Codex resolves the whole chain once, at session start, from the repo root through your startup directory. It is not lazy: cd-ing deeper mid-session does not pull in a file you did not start under. A subdirectory AGENTS.md applies to sessions launched in that directory or below it.

The merge order is the thing to internalise. Files are concatenated from the root downward, blank-line separated, so files closer to your startup directory appear later and override earlier guidance. AGENTS.md extends its parents. AGENTS.override.md replaces the level entirely.

Then the trap that costs people real debugging hours:

project_doc_max_bytes defaults to 32 KiB. It caps the combined size of the project files only — the global ~/.codex/AGENTS.md arrives as separate user instructions and does not consume this budget.
The file that crosses the limit is prefix-truncated, and every file below it is skipped entirely. You get the first N bytes of the crossing file and nothing at all from the ones after it.
It reads as silent. The loader does emit a tracing::warn! (“project doc exceeds remaining budget; truncating”), but it does not surface in the TUI, which is why this gets reported as silent truncation (openai/codex#7138).
The loss lands on your most specific instructions. Because files are ordered root-first, the ones nearest your startup directory land last — so they are the ones truncated and skipped. Most people assume they would lose the general guidance and keep the specific. It is the exact opposite.

Raise the ceiling in ~/.codex/config.toml if you must:

project_doc_max_bytes = 65536  # 64 KiB, double the default

Raising it is a worse answer than splitting, though — and OpenAI’s own guidance agrees, recommending you split guidance across nested directories as you approach the limit, and reserve formatting and lint checks for CI rather than prose.

Worth keeping in view: GPT-5.6 Sol advertises a roughly 1,050,000-token window, but Codex CLI caps input at 272,000 tokens, and auto-compaction fires well before that. Your budget is smaller than the marketing number, and AGENTS.md spends it before the work starts.

The routing table

Once you know what defers, “should this line stay” becomes the wrong question. The right one is where does this line go. There are five destinations, and the main file is only one of them.

What you have	Cursor	Claude Code	Codex
Universal rule, needed every session	`AGENTS.md`, or `.mdc` with `alwaysApply: true`	`CLAUDE.md` (target under 200 lines)	root `AGENTS.md`
Rule that applies to a file type	`.mdc` with `globs`	`.claude/rules/*.md` with `paths`	nested `AGENTS.md` (directory-scoped only)
Rule that applies to one part of the repo	subdirectory `AGENTS.md`	subdirectory `CLAUDE.md`	subdirectory `AGENTS.md`, or `.override.md` to replace
Multi-step procedure	`.cursor/skills/<name>/SKILL.md`	`.claude/skills/<name>/SKILL.md`	`.codex/skills/<name>/SKILL.md`
Something that must actually happen	hook	`PreToolUse` / `Stop` hook	hook (beta), or CI
Guidance only a weaker model needs	subagent definition in `.cursor/agents/`	subagent definition with `model:`	subagent definition
Personal preference, not the team’s	User Rules	`CLAUDE.local.md`	`~/.codex/AGENTS.md`
Note for human maintainers	README	HTML comment (costs zero tokens)	README

Two rules of thumb fall out of that table.

If a rule starts with the word “when”, it does not belong in the main file. “When working on API handlers, validate with the shared schema helper” is a path-scoped rule wearing a disguise. Move it, and it costs you nothing until the agent actually opens something under src/api/.

If you would be genuinely annoyed when the model ignores it, prose is the wrong tool. Context files are advisory. In Claude Code the file is delivered as a user message after the system prompt, which is the mechanical reason it never binds. Hooks are deterministic. “Never run the build while the dev server is up” is not a sentence, it is a PreToolUse hook.

Nine prompts that do the cutting

These are ordered as a protocol. Run 1 to establish what you actually need, 2 and 3 to delete, 4 through 6 to move what survives, 7 to harden what must not fail, 8 to consolidate, and 9 to prove any of it worked.

Each prompt has a shared core and a per-tool delta. The delta is genuinely all that differs — paths and a couple of tool-specific steps — so rather than printing three near-identical prompts, the core is stated once and the tabs carry only what changes.

1. Establish the ablation baseline

Do not start by editing. Start by finding out what the file is buying you. This is the one step everybody skips, and it is the one that makes every later decision evidence-based instead of aesthetic.

Move our agent context file to a dated archive path and replace it with a
single line pointing at our package manager. Then create a file called
CONTEXT-ABLATION.md at the repo root with this structure:

# Ablation log — started [today's date]
Archived file: [path], [N] lines
Model in use: [model]

## Stumbles observed
| Date | What the agent did wrong | Which archived line would have prevented it | Repeated? |

Do not add anything back yet. I will work normally for a week and log
what actually breaks.

The column that matters is the last one. Ablation says add a line back only after the model has failed the same way more than once. A single stumble is noise; the line you would have added is a bet you would have lost.

Archive .cursor/rules/ wholesale as well as AGENTS.md — and check the dashboard for Team Rules, which are not in your checkout and will keep applying while you think you have ablated.

Archive CLAUDE.md, CLAUDE.local.md and .claude/rules/. Then deal with auto memory, or you are ablating one accretive surface while another keeps growing — and archiving it alone is not enough, because Claude will simply write it back over the observation week. Set autoMemoryEnabled: false (or export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1) for the duration, archive what /memory shows, and restore the setting when you are done. Verify with /context that the Memory files list is actually empty before you start.

Archive both the project AGENTS.md tree and ~/.codex/AGENTS.md — rename them rather than emptying them. At the global level Codex uses the first non-empty file it finds, so an empty AGENTS.override.md does not shadow anything; it just falls through to AGENTS.md and you end up ablating nothing.

2. Apply the removal test, line by line

The official test is one question per line: would removing this cause the agent to make a mistake? If not, cut it. The reason it works better as a prompt than as a manual pass is that the agent has to state a reason for every verdict, and reading twenty weak reasons in a row is what finally makes you delete them.

Read our agent context file. For every single line, output a row:

| Line | Verdict | Reason |

Verdict is exactly one of: KEEP, CUT-DERIVABLE, CUT-LINTER, CUT-SELF-EVIDENT,
MOVE-PATH, MOVE-SKILL, MOVE-HOOK, CUT-STALE.

Rules for judging:
- CUT-DERIVABLE if you could reach the same conclusion by opening three files
  in this repo. Prove it by naming the three files.
- CUT-LINTER if our linter, formatter or type checker already enforces it.
  Check the actual config files before claiming this.
- CUT-SELF-EVIDENT for anything you would do correctly without being told.
- CUT-STALE if the line refers to a path, script or dependency that no longer
  exists. Verify each one against the current tree.
- MOVE-PATH if it only applies to some files. Name the glob.
- MOVE-SKILL if it is a multi-step procedure rather than a constraint.
- MOVE-HOOK if it is a "never do X" that would actually matter.
- KEEP only if removing it would cause a mistake AND you cannot derive it.

End with the KEEP-only version of the file and its line count. Do not soften
verdicts to be polite — I want the aggressive read.

Expect the KEEP set to be about a third of what you started with. If it is not, the audit was too polite — say so and run it again.

Add: “Also list every rule file with its application type (Always / Intelligent / Glob / Manual) and its line count. Flag any .md file carrying frontmatter — frontmatter is ignored outside .mdc, so those rules are applying always regardless of what their globs field says.”

Run /doctor first and let it propose trims — it cuts derivable content (directory layouts, dependency lists, architecture overviews) and keeps pitfalls, rationale and non-default conventions, which is the same policy as the prompt above. Requires v2.1.206 or later. Then run the prompt to catch what it left, and include .claude/rules/ files without paths frontmatter in the audit — those load at launch just like the main file.

Add: “Report the byte size of every AGENTS.md and AGENTS.override.md from the repo root down to my startup directory, with a running cumulative total in load order. Tell me the exact file at which the total crosses 32 KiB and the byte offset within it — that file loads only up to that offset, and every file after it is skipped entirely. List which specific instructions I am currently losing. Exclude the global ~/.codex/AGENTS.md from the total; it does not count against this budget.”

3. Cut the generated draft down to a file

Every tool ships a command that writes you a context file, and every one of them writes a document optimised for describing your project to a human reader rather than for changing a model’s behaviour. Those are different jobs. This is also the direction the research is least kind about: LLM-generated context files scored worse than no file at all.

Run the generator if you like — it does surface commands and conventions, which saves you the discovery. Then cut it, hard, by category.

This context file was auto-generated. Sort every section into one of four
categories and act on it:

1. PROJECT OVERVIEW / DESCRIPTION → cut all of it. You derive this from the
   README and the code in seconds, and it is paid for on every single turn.

2. COMMANDS → keep only the non-obvious ones. Delete anything I could work out
   by reading package.json. Keep: the package manager if it is not the obvious
   one, commands with prerequisites, and commands that are wrong to run.
   Target four lines, not twenty.

3. ARCHITECTURE → cut everything except decisions and their rationale. "Uses
   React with TypeScript" is visible from any file — cut. "Search runs through
   D1 rather than a hosted service because the whole app is on Cloudflare and
   we wanted one bill" is a why, and whys are not in the code — keep.
   Test: if you would reach the same conclusion by opening three files, cut it.
   If you would reach the WRONG conclusion, keep it.

4. FILE-BY-FILE MAP / DIRECTORY LAYOUT → cut, and cut this first.

For each cut, say which category and why in one clause. Then show the result.

The file map deserves its own note, because it fails differently from the others. The rest of a bloated file merely costs you tokens. A file map goes stale, and stale context is worse than no context — it sends the agent confidently to a path that no longer exists. Your agent has search tools and is very good at using them. It does not need your map. It needs your map to not be wrong.

Cursor generates rules from the Settings pane and via chat. Whichever you used, run the trim before committing — generated rules default to alwaysApply, which is the most expensive setting available.

/init is the generator. Set CLAUDE_CODE_NEW_INIT=1 for an interactive multi-phase flow that asks which artifacts you want, explores with a subagent, and shows you a reviewable proposal before writing anything — it also folds in existing AGENTS.md, Cursor, Windsurf and Cline rules. Still a draft, but a better-informed one.

/init scaffolds a starter AGENTS.md. Add to the prompt: “Also strip any section that duplicates our global ~/.codex/AGENTS.md — both are concatenated into the same budget, and duplication burns it twice.”

4. Move path-conditional rules out of the main file

This is the highest-value mechanical move available and the one people use least. Any section that begins “when working on X” is conditional content sitting in an unconditional file, costing you attention on every turn where X is irrelevant.

Find every rule in our context file that only applies to part of the codebase.
Look for: sections headed by a directory or layer name, rules naming a specific
framework we only use in one place, and anything phrased "when working on…",
"for API routes…", "in tests…".

For each cluster:
1. Name the narrowest glob that covers it. Verify the glob actually matches
   files in this repo — run it and show me the count.
2. Write it out as a separate scoped rule file in the correct format.
3. Show what is left of the main file afterwards.

Do not scope something to a glob just to shorten the main file. If a rule
genuinely applies everywhere, leave it where it is and say so.

Target is .cursor/rules/<topic>.mdc. The extension matters — frontmatter is ignored in .md:

---
description: "API endpoint conventions"
globs:
  - "services/api/**/*.ts"
---

# API rules

- Validate every request body with the shared Zod schema helper
- Error responses use the { error, code } shape, never a bare string

Target is .claude/rules/<topic>.md with a paths glob. Without paths the rule loads at launch, exactly like the main file, and you have saved nothing:

---
paths:
  - "services/api/**/*.ts"
---

# API rules

- Validate every request body with the shared Zod schema helper
- Error responses use the { error, code } shape, never a bare string

Brace expansion works (src/**/*.{ts,tsx}). Rules load recursively from subdirectories and can be symlinked in from a shared directory if you want the same set across projects.

Codex has no glob-scoped rule format — its only conditional axis is directory depth. So a file-type rule becomes a directory rule: put it in the AGENTS.md nearest the files it governs. Add to the prompt: “Where a rule is scoped by file extension rather than location, tell me so explicitly instead of inventing a glob — I will decide whether to place it by directory or leave it in the root file.”

5. Push content down into subdirectory files

In a monorepo the root file usually contains three teams’ worth of rules, and every one of them is paying for the other two. Subdirectory files are the fix, and in all three tools they are lazier than the root file.

Our root context file has grown to cover every package in this monorepo. Split it.

1. List every workspace package and what the root file currently says about it.
2. For each package, write a subdirectory context file containing only the
   rules that apply to that package.
3. Rewrite the root file to contain only what is true across ALL packages.
   If a rule is true for three of four packages, it goes in the three, not
   the root — near-universal is not universal.
4. Show me the before and after line counts for the root and each new file.

Flag anything you cannot place confidently rather than guessing.

Place AGENTS.md in each package directory. Cursor applies it automatically when you work with files in that directory or its children — no frontmatter, no configuration.

AGENTS.md                    # only what is true everywhere
apps/web/AGENTS.md           # Next.js app conventions
services/api/AGENTS.md       # API service conventions
packages/ui/AGENTS.md        # component library conventions

Same layout with CLAUDE.md. The asymmetry to remember: files above your working directory load in full at launch, files below load on demand. So launching Claude from the repo root means the root file loads and the package files do not, until Claude reads something in them.

In a large monorepo where other teams’ files get picked up anyway, claudeMdExcludes in .claude/settings.local.json skips them by glob. One caveat: subdirectory files are not re-injected after /compact — they reload the next time Claude reads a file there.

Same layout with AGENTS.md, and this is the tool where it matters most, because splitting is also how you stay under 32 KiB.

Choose the filename deliberately: AGENTS.md extends its parents, AGENTS.override.md replaces the level. Use override when a package genuinely contradicts the root — a service on a different runtime, say — and plain AGENTS.md everywhere else. Add to the prompt: “After splitting, report the cumulative byte total for the deepest path in the repo and confirm it is under 32 KiB.”

6. Extract procedures into skills

Rules are constraints. Skills are procedures. If a block of your context file reads like a runbook — numbered steps, a sequence, “first do this, then that” — it is in the wrong place, and it has been since December 2025.

The difference is loading. A rule in your main file is read on every turn forever. A skill is read when it is relevant.

Find every block in our context file that describes a multi-step procedure
rather than a constraint. Signals: numbered steps, a sequence of commands,
"first… then…", anything that reads like a runbook.

For each one, create a skill:
- Directory named for the task, in kebab-case
- SKILL.md with frontmatter: name (matching the directory) and description
- The agent decides from the skill's metadata — name, description and path —
  without reading the body, and the description carries almost all of that
  signal. So it must say WHEN to use this skill, not just what it does
- Move the full procedure into the body, and expand it: a skill is not read
  every turn, so detail is cheap here in a way it never was in the main file

Then delete the block from the context file and replace it with nothing.
Do not leave a pointer — the agent discovers skills on its own.

List what moved and the line count you removed.

The last instruction is the one people resist. Leaving “see the deployment skill for deployment steps” in your main file re-adds the cost you just removed. Skill discovery is automatic in all three tools.

Skills live in .cursor/skills/ or .agents/skills/, with ~/.cursor/skills/ and ~/.agents/skills/ for personal ones. Cursor also reads .claude/skills/ and .codex/skills/, so a shared skill directory works across all three tools.

Cursor ships /migrate-to-skills, which converts dynamic rules and slash commands automatically. Run it first — but know that it excludes rules with alwaysApply: true or specific globs, which is precisely the expensive set. Those you move by hand with the prompt above.

Cursor’s own framing: “compared to always-on, declarative rules, skills are better for dynamic context discovery and procedural how-to instructions.”

Skills live in .claude/skills/<name>/SKILL.md for the project and ~/.claude/skills/ for personal ones. One note if you install from the wider ecosystem: Claude Code looks in ~/.claude/skills while the open Agent Skills spec says ~/.agents/skills — symlinking one to the other is the current workaround.

Skills live in .codex/skills/<name>/SKILL.md for the project and ~/.codex/skills/ for personal ones. A skill directory can also carry scripts/, references/ and assets/. Invoke explicitly with $skill-name or /skills, or let Codex activate it implicitly on a task match.

This move pays double in Codex: content in a skill is not part of the AGENTS.md byte budget at all, so every procedure you extract buys back headroom against the 32 KiB ceiling.

7. Harden the rules that must not fail

Some rules you would be mildly disappointed to see broken. Others cost you an hour. The second kind does not belong in prose at all — context files are advisory, and a “never do this” line in markdown is a strong suggestion to a probabilistic system.

Find every rule in our context file phrased as an absolute: "never", "always",
"must", "do not". For each one, answer honestly: if the agent ignored this,
would I be genuinely annoyed, or only mildly?

For the genuinely-annoyed set, write a hook that enforces it deterministically.
For each hook:
- Name the lifecycle event it fires on and why that one
- Write the actual script, not pseudocode
- Show me how to verify it fires, and how to verify it does NOT fire on the
  cases it should allow
- Then delete the corresponding prose line — a rule enforced by a hook does
  not also need to be a sentence

For the mildly-annoyed set, leave them as prose and tell me which they are.

The related principle, put well by HumanLayer: your agent is not an expensive linter. Never spend context describing rules a deterministic tool already enforces. If Biome reformats it on save, do not also tell the model about it.

Cursor supports hooks, managed alongside plugins, skills, MCP servers, subagents, rules and commands from the Customize page at user, team or workspace level.

PreToolUse is the wall: it can block a tool call before it happens, which is what “never run the build while the dev server is up” actually needs. Stop hooks handle “always do X before finishing” — running the formatter, for example.

While you are in there, InstructionsLoaded logs exactly which instruction files loaded, when and why. It is the fastest way to confirm a path-scoped rule is firing when you expect it to and staying quiet when you do not.

8. Consolidate to one source of truth, then check the budget

If more than one agent touches your repo, you almost certainly have two files saying nearly the same thing, drifting apart at the rate you edit them.

AGENTS.md is the open cross-tool format for this — plain markdown, no required fields, nearest-file-wins in monorepos, and natively read by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, Cline and others. Claude Code reads CLAUDE.md only, does not read AGENTS.md, and does not fall back to it despite what several posts claim.

The fix is one line.

We have more than one agent context file in this repo. Consolidate them:

1. Diff them. Show me every rule that appears in one but not the others, and
   every pair that contradicts each other. Do not resolve contradictions
   silently — list them and ask me.
2. Merge everything tool-agnostic into AGENTS.md.
3. Reduce each tool-specific file to only the instructions genuinely unique to
   that tool. Do not duplicate anything that now lives in AGENTS.md — tell me
   instead how this tool picks AGENTS.md up, since they differ.
4. Report the final byte size and line count of every file that will be
   loaded, and the combined total.

If a "tool-specific" rule turns out to be tool-agnostic, move it up. I expect
the tool-specific remainder to be nearly empty.

Cursor reads AGENTS.md natively, root and nested, so there is nothing to wire up. What to check instead is overlap: if you have both AGENTS.md and .cursor/rules/*.mdc with alwaysApply: true, they are merged and you are likely paying twice for the same guidance. Add: “List every rule that appears in both AGENTS.md and an always-applied .mdc rule.”

Make @AGENTS.md the first line of CLAUDE.md. This is a native import — AGENTS.md loads at session start, Claude-specific additions sit below it, and drift is structurally impossible because there is only one source:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) also works if you need no Claude-specific content, but on Windows it requires Administrator privileges or Developer Mode — so the import is the better default for a team with mixed machines. Confirm either worked by running /context and checking that CLAUDE.md appears under Memory files.

AGENTS.md is already the native format, so consolidation here is about the byte budget instead. Add: “Report the cumulative size of the project files in load order — repo root first, then each level down to the deepest startup directory I use. Tell me the exact file at which the running total crosses 32 KiB, because that file loads only partially and everything after it is skipped.”

The global ~/.codex/AGENTS.md sits outside that budget, so trimming it buys you no headroom against the limit. It is still worth deduplicating against the project files, because anything stated twice is paid for twice in the context window.

9. Prove it worked, and schedule the next round

The step everyone skips. If you added a rule and cannot point to a behaviour change, you added noise — and noise is not free, because every line is an attractor.

I want to know whether this rule is doing anything: "[paste the rule]"

Design a test:
1. Name a real task from this repo where the rule should change your behaviour.
   Real files, not a toy.
2. Tell me exactly what you would do WITH the rule loaded and WITHOUT it, and
   where those diverge.
3. Name the observable artifact that differs — a file written, a command run,
   an import chosen. If you cannot name one, say so plainly: that means the
   rule is unfalsifiable and should be deleted.

I will run the task in two sessions and compare.

Then put the next round on a trigger rather than a date. Six months is a proxy for “a model generation has probably passed”; a model switch is the real event.

We just switched from [old model] to [new model]. Re-run the ablation.

1. Read CONTEXT-ABLATION.md for the rules we added back and why.
2. For each, judge whether the new model plausibly needs it. Be specific about
   which capability makes it redundant — do not just assert "newer model".
3. Propose the half of the file most likely to be redundant now, ordered by
   confidence, and delete that half.
4. Append a new dated section to CONTEXT-ABLATION.md recording what we cut and
   what to watch for.

If we moved DOWN a tier, do the reverse: propose which archived rules to
restore. Adding back is the correct outcome there, not a regression.

When context-file pruning goes wrong

You shortened the file and the rule is still ignored. Shortening is the right first move, but it is not the only failure mode. Check for a contradiction: if two rules give different guidance for the same behaviour, the agent may pick one arbitrarily, and no amount of shortening fixes that. In Claude Code, run /context and confirm the file actually loaded — a rule in a file that never loaded looks exactly like a rule being ignored. Then check whether the rule is falsifiable at all. “Write maintainable code” cannot be followed or violated, so it cannot be fixed by making it louder.

You deleted something load-bearing and found out in CI. This is the expected cost of ablation, not a sign you did it wrong — and it is why the archive in prompt 1 is a dated copy rather than a deletion. Restore the single line, not the section it came from. The temptation after one failure is to restore everything, which puts you back where you started.

Codex is ignoring your instructions and you blamed the model. Check the byte budget before anything else. The 32 KiB cut never shows up in the TUI, and because project files load root-first it takes your nearest ones first — the specific ones you most recently wrote. The file that crosses the limit loads only partially, so you can also get half a rule. The symptom — deep, precise instructions ignored while vague global ones are followed — reads exactly like a model regression and is not one. Prompt 2’s Codex delta finds it in one pass.

Auto memory rebuilds what you deleted. In Claude Code this is the failure mode with the longest fuse. You ablate the file, and over the following weeks Claude writes its own notes about your corrections into a file you never review, which loads into every session. Accretion, automated. Run /memory on the same cadence you review the main file, or set autoMemoryEnabled: false and curate by hand.

Your team disagrees about what got cut. Treat the archive and the log as the artifact under review, not just the resulting file. A PR that shows “we removed 140 lines, here is the log of what actually broke over three weeks” is arguable. A PR that shows a 140-line deletion is not. Block-level HTML comments are free in Claude Code, so the rationale can live in the file itself without costing context.

Everything you just read went stale. It will. The advice inverted once in seven months and the tooling moves faster than that — /doctor gained the trim check in v2.1.206, Cursor added nested AGENTS.md and /migrate-to-skills in the 2.4 line, Codex’s context ceiling moved twice in July 2026 alone. Apply the same test to this article that you apply to the others: check the date, then check the tool’s own docs before you act on a specific flag or path.

Where to go next after pruning context files

Using Documentation as Effective AI Context The other half of the job: what to write in the lines that survive the cut, with templates for all three tools.

Memory Patterns Auto memory, learned patterns, and cross-session knowledge — the accretive surface that keeps growing while you prune.

Cost Per Context Put a number on what a long context file actually costs you across a month of sessions.

Skills Best Practices Where the procedures you extracted in prompt 6 should actually live, and how to write descriptions that get them loaded.

Config Reference Side-by-side syntax for .cursor/rules, CLAUDE.md, AGENTS.md and config.toml when you need the exact field name.