Your CLAUDE.md Is Full of Junk — Here's How to Fix It

CLAUDE.md is the file Claude Code reads at the start of every session to understand your project. It lives at the repo root and is shared with your team via git. The problem: most CLAUDE.md files are packed with information Claude can already infer on its own — dependencies from package.json, folder structure, standard language conventions. Every unnecessary line consumes context and dilutes the instructions that actually matter.

The rule: if Claude can figure it out by reading the code, don't put it in CLAUDE.md. Document the why, not the what. Business decisions, team dynamics, the reasoning behind an architecture choice — that's what can't be inferred from a composer.json.

TL;DR Run /init to generate a base CLAUDE.md, then strip everything that's auto-inferrable. Keep only what Claude can't discover on its own: team decisions, non-standard conventions, and the why behind every rule.

Result:

# CLAUDE.md

## Business rules
- All prices must include tax for ES/EU customers — legal requirement since 2024
- Never delete user data; soft-delete only — compliance with our data retention policy

## Architecture decisions
- We chose SQLite over Postgres for the public site — single-server deployment, no need for connection pooling
- API responses are cached 5 min at CDN level — product decision to reduce costs, not a technical limitation

## Team conventions
- PRs require at least 1 review from @frontend-team before merging
- Feature branches use `feat/TICKET-description` format — matches Linear integration

## Non-obvious commands
- `npm run seed:staging` — resets staging DB with anonymized production data
- `./scripts/deploy-preview.sh` — deploys to Vercel preview, needs VERCEL_TOKEN in .env

Setup

1. Generate the base file

claude
# Inside the session:
/init

Claude analyzes the codebase — detects build system, frameworks, tests — and generates an initial CLAUDE.md. If one already exists, it suggests improvements instead of overwriting. For a leaner result from day one (and optionally skills + hooks), enable the /init interactive flow — it applies the conciseness rule from the start.

2. Strip what's redundant

Review the generated file and remove:

• Dependencies already in package.json, composer.json, Cargo.toml
• Folder structure (Claude sees it directly)
• Standard language conventions ("use camelCase in JavaScript")
• Public API explanations (link to docs instead of copying them)

3. Add what Claude can't infer

• Business decisions and their reasoning
• Team conventions that differ from the standard
• Internal scripts with usage context
• Legal or compliance constraints
• Workflows not documented in code

4. Import external files (optional)

Use @path/file to modularize without bloating the main file:

# CLAUDE.md
@docs/architecture-decisions.md
@docs/team-conventions.md

Maximum 4 hops of imports. Relative paths resolve from the file containing the import. Sharing the repo with Cursor, Codex or another tool via AGENTS.md? Import it with @AGENTS.md and Claude Code reads the same file: how to join AGENTS.md and CLAUDE.md.

Keep it sharp over time

CLAUDE.md isn't "set and forget" — it rots if you don't iterate. Every couple of weeks run /insights: it analyzes your recent sessions and suggests new rules pulled directly from the instructions you repeat most. Paste the good ones into CLAUDE.md and friction drops on the next session.

Is your CLAUDE.md still growing? Move the scope-specific rules out to conditional rules in .claude/rules/: they load only when Claude touches matching files, instead of weighing on every session.

Reference

Best practices

Official docs: Memory and CLAUDE.md

Part of the 10 habits to save tokens in Claude Code. Deep dive on @ syntax: Five ways to give Claude Code the right context. Not sure whether something belongs in CLAUDE.md or another file? Which Claude Code file each thing goes in. Heads-up, CLAUDE.md is not the system prompt: a custom output style does replace the engineering base unless you set keep-coding-instructions. Jumping to another repo mid-session? /cd moves the session and brings in the new folder's CLAUDE.md, without restarting. Want to document how you actually use Claude, not just the rules? /team-onboarding turns your last 30 days into a guide. What if Claude flagged the excess for you? /doctor now spots a bloated CLAUDE.md (and the lines it can already derive from the code) and trims it with your OK. Landing in a repo you don't know? The Explanatory style has Claude explain its patterns as it works.