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 current Claude Code guidance is the opposite: keep CLAUDE.md concise. The docs recommend targeting fewer than 200 lines and reviewing every instruction for whether removing it would cause mistakes. Read Anthropic's current guidance.
The reason is structural. Claude Code loads CLAUDE.md into the working context. Every line competes with the task, the code, and the rest of the conversation. A long file also gets harder for people to maintain, so stale or contradictory rules stick around.
Lightweight wins. The pattern below shows how.
What Anthropic Actually Says
The official Claude Code docs give a useful test for what belongs in CLAUDE.md: would removing this instruction 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 for me is short and human-readable: roughly 20 to 50 lines for a typical project and 40 to 90 for a large one. Those are my working ranges, not Anthropic limits. The official target is under 200 lines. If yours is much bigger than my range, look for topic-specific content that can live in a Skill or a linked doc instead.
CLAUDE.md vs AGENTS.md (the 2026 Split)
CLAUDE.md is Claude Code's project-memory file. AGENTS.md is an open convention that several coding agents use for repository instructions.
The AGENTS.md specification documents the portable format and the tools that support it. Claude Code isn't one of the tools that reads it automatically. If you want Claude Code to share those rules, put @AGENTS.md at the top of CLAUDE.md (or use a symlink) so the import is explicit.
CLAUDE.md also supports @imports for additional files. That makes it a useful thin Claude-specific adapter around shared repository instructions.
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 begin CLAUDE.md with
@AGENTS.md, followed by any Claude-specific extensions. - If you're starting fresh, choose the file each tool actually reads. Don't assume one tool discovers another tool's instruction file.
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:
@AGENTS.md
# Claude Code additions
Shared rules (voice, banned phrases, and canonical vocabulary) are imported
from AGENTS.md above. This file adds only 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 SKILL.md file. The frontmatter has a name and description; the body has the instructions the agent follows when the Skill triggers. Anthropic's Skills documentation covers the current structure and discovery behavior.
The mechanic that makes this work is called progressive disclosure. Claude Code can discover a Skill from its description, then load the full instructions when the Skill is relevant. That keeps topic-specific detail out of the always-loaded project file.
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.