Skip to main content
Tips

practitioner tip

Fix a CLAUDE.md That's Full of Junk

AIErudit angle: A CLAUDE.md is the shared context contract for your whole AI-delivery team, and every auto-inferrable line dilutes the instructions that matter. This tip gives the rule — document the why, not the what — and a setup flow to strip redundancy and keep only what Claude can't discover from the code. A lean CLAUDE.md saves context on every session and keeps guidance sharp.

claude-mdproject-setupclaude-codetips
Tip visual

Published: Mar 3, 2026 Updated: 2026-06-18

Original: https://wmedia.es/en/tips/claude-code-claudemd-project-setup

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

FileScopeShared withWhen to use
./CLAUDE.mdProjectTeam (via git)Shared instructions
./.claude/CLAUDE.mdProjectTeam (via git)Alternative to above
./CLAUDE.local.mdProjectJust youPersonal project preferences
~/.claude/CLAUDE.mdGlobalJust youPreferences across all projects
.claude/rules/*.mdProjectTeam (via git)Modular rules by topic or path

Best practices

DoDon't
Document the why behind every ruleList project dependencies
Concrete, verifiable instructions"Write clean code"
Keep under 200 linesCopy API documentation
Review periodicallyLeave outdated instructions
Use @imports to modularizeOne 500-line file

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. Jumping to another repo mid-session? /cd moves the session and brings in the new folder's CLAUDE.md, without restarting.