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 5 levels of imports. Relative paths resolve from the file containing the import.

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.

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.