Stop Stuffing Your CLAUDE.md
The first time most people set up Claude Code, the impulse is to dump everything into CLAUDE.md or AGENTS.md. Coding conventions. Style rules. The whole onboarding doc. Save it all to one big file at the top of the project, and the agent will know what to do.
That's the trap.
Anthropic's official Claude Code guidance is the opposite: keep these files short. Their docs put it bluntly: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions."
The reason is structural. CLAUDE.md (and AGENTS.md, when present) loads at the top of every conversation. Every line costs context budget on every session. When the file gets long, the model starts losing earlier instructions to later ones, the same way a long Slack thread loses the original ask. The rule you wrote in line 43 doesn't outweigh the user's most recent message, even if you put it in caps.
Lightweight wins. The pattern below shows how.
What Anthropic Actually Says
The official Claude Code best-practices doc gives a single test for what belongs in CLAUDE.md: "Would removing this cause Claude to make mistakes?" If the answer is no, cut it.
The same doc offers a clean include-or-exclude table. Worth memorizing.
| ✅ Include | ❌ Exclude |
|---|---|
| Bash commands the agent can't guess | Anything the agent can figure out by reading code |
| Code style rules that differ from defaults | Standard language conventions the model already knows |
| Testing instructions and preferred test runners | Detailed API documentation (link to docs instead) |
| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |
| Architectural decisions specific to your project | Long explanations or tutorials |
| Developer environment quirks (required env vars) | File-by-file descriptions of the codebase |
| Common gotchas or non-obvious behaviors | Self-evident practices like "write clean code" |
Most CLAUDE.md files break the rule on the right column. Things you can already figure out from the code, things the model already knows, things that are too specific to belong at the top of every session.
The pattern that works: short and human-readable. Twenty to fifty lines for a typical project. Forty to ninety for a large one. If yours is bigger than that, you almost certainly have content that should live in a Skill instead.
CLAUDE.md vs AGENTS.md (the 2026 Split)
CLAUDE.md is Claude-specific. AGENTS.md is the cross-tool standard.
AGENTS.md emerged in mid-2025 from a collaboration between Sourcegraph, OpenAI, Google, Cursor, and Factory, and it's now stewarded under the Linux Foundation by the Agentic AI Foundation. As of 2026, the format is supported by Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, Cursor, plus a handful of community tools (Cline, Windsurf, OpenCode). One file, every agent.
CLAUDE.md handles things AGENTS.md doesn't, like @imports for additional files, Skills triggers, and hook configuration. Claude Code reads both files when both are present.
The practical split:
- If you only use Claude Code, just write CLAUDE.md.
- If your team uses multiple agents, write AGENTS.md for shared rules and CLAUDE.md for the Claude-specific extensions.
- If you're starting fresh, default to AGENTS.md for portability and add a CLAUDE.md only if you need Claude features.
Either way, the same rule applies: keep them short. Both files have the same job (give the agent enough orientation to start working) and the same failure mode (bloat).
The Lightweight Pattern
A working CLAUDE.md is mostly a directory. From this site:
# CLAUDE.md
Claude Code reads this file. Shared rules (voice, banned phrases, canonical
vocabulary) live in AGENTS.md, read that first. This file adds the
Claude-Code-specific bits.
## Before pushing
Run `npm run check`. It runs the full gate.
## Canonical sources (don't hardcode, read these)
- `src/messaging.mjs`: positioning for /course, /coaching, /consult.
- `src/siteData.mjs`: pages, cohort, features.
- `supabase/functions/submit-intake/`: the Edge Function behind every form.
## Skills index
Skills live in `.agents/skills/<name>/SKILL.md`. Load the matching skill
before doing the work.
| Skill | Use when |
|---|---|
| `adding-posthog` | Creating any new HTML page. |
| `brand-colors` | Choosing colors, building UI, styling components. |
| `cohort-updates` | Updating seats / price / start date / Stripe link. |
| `editing-the-harness` | Editing /harness or /scope-filter. |
That's the whole pattern. Around fifteen lines of useful content. The rest of the project context lives in Skills, which load on demand when they're relevant.
Notice what's not in there:
- No coding conventions Claude already knows
- No file-by-file architecture
- No long explanations of why we built it this way
- No voice rules (those live in a writing-blog-posts Skill)
- No contributing guide for humans (that's a CONTRIBUTING.md, separate concern)
What's in there:
- Where the canonical sources live (read these before doing X)
- The pre-push gate (one command)
- An index of Skills with one-line descriptions
CLAUDE.md is a directory, not a manual.
Where the Real Context Lives: Skills
A Skill is a directory with a single file called SKILL.md. The frontmatter has a name and description; the body has the instructions the agent follows when the Skill triggers. Anthropic's own framing: "Skills are usually short, they help every collaborator, and they are easier to review than long CLAUDE.md files."
The mechanic that makes this work is called progressive disclosure. At session start, Claude Code pre-loads only the name and description of every installed Skill into the system prompt. The full body loads only when the Skill is triggered. So a thirty-Skill library costs roughly the same context budget as no Skills at all, until one of them is actually needed.
This changes what should go in CLAUDE.md.
- The voice rules for blog posts? That's a writing-blog-posts Skill, triggered when you draft or edit a post.
- The deployment runbook? A deployment Skill.
- The brand colors and typography? A brand-colors Skill.
- The intake email rules? An intake-emails Skill.
CLAUDE.md just lists them. The actual rules live in their SKILL.md files, loading on demand.
The compounding play here is real. Skills are reusable across projects. The sparring-partner Skill described in Argue With Claude Before You Write Anything followed me from one project to the next without modification. CLAUDE.md doesn't compound. Skills do.
How to Write Yours
The fastest path to a clean CLAUDE.md (or AGENTS.md):
Step 1: Run /init, or have the agent draft AGENTS.md.
Claude Code's /init command analyzes your codebase and produces a starter file based on what it sees. If you're writing AGENTS.md instead, ask your agent to scan the repo and generate the first draft. The output will be too long. That's fine. You're going to prune it.
Step 2: Run the "would removing this cause mistakes?" test on every line.
Read each line and ask the question literally. Most lines fail the test. Cut them.
Step 3: Move sometimes-relevant content to Skills.
For anything that survives the test but only matters for specific work (writing blog posts, deploying, generating brand assets), pull it into a SKILL.md in .claude/skills/. Leave a one-liner in CLAUDE.md pointing at it.
Step 4: Test the change by observing behavior.
The Anthropic docs put it well: treat CLAUDE.md like code. Observe whether Claude's behavior actually shifts when you add or remove a rule. If the behavior doesn't change, the rule wasn't pulling weight. Cut it.
Step 5: Re-prune every couple of months.
Bloat creeps back in. A pull request adds a rule that doesn't really need to be there. Six months later you have forty lines of dead rules. Schedule a CLAUDE.md review the same way you'd schedule a dependency audit.
This site's CLAUDE.md went through the exercise twice. The first version was sixty lines. The current one is fifteen. The agent's behavior didn't change when we cut forty-five of them. Most of those rules were Claude already knew, things I was telling it twice.
If you want a starting harness with this pattern already wired in (AGENTS.md, CLAUDE.md, scope filter, slash commands), grab the free teamvince agent harness. Drop it into any project.
Why This Pattern Will Outlast the Tools
Anthropic's developer conference, Code with Claude, ran today (May 6, 2026). Three new Claude Managed Agents features landed: multi-agent orchestration, Outcomes, and a research preview called Dreaming where the agent inspects its previous sessions and self-improves overnight. The Claude Code surface kept moving too: doubled session limits, Code Review built into every team's workflow, CI auto-fix, Routines for async automations.
The specific tools update on a roughly sixty-day rhythm. The lightweight pattern doesn't.
Whatever your stack looks like a year from now, the underlying constraint stays the same: every line you put at the top of a conversation has to earn its place. Bloated context files drag every session that follows. Short, well-pointed orientation files plus on-demand Skills win.
Older guides recommended loading everything into the prompt or the spec file. The 2026 pattern is the opposite: load less, point at more, save the heavy content for when it's actually needed.
That's the practice. Worth keeping when the model name on the box changes again.
If you want the full case for why context (not prompts, not models) is the AI skill that compounds, start here. This post is the implementation. That one is the argument.