Tu CLAUDE.md está lleno de basura, así es como puedes arreglarlo

CLAUDE.md es el archivo que Claude Code lee al inicio de cada sesión para entender tu proyecto. Vive en la raíz del repositorio y se comparte con el equipo via git. El problema: la mayoría de CLAUDE.md están llenos de información que Claude puede inferir solo — dependencias del package.json, estructura de carpetas, convenciones estándar del lenguaje. Cada línea innecesaria consume contexto y diluye las instrucciones que realmente importan.

La regla: si Claude puede descubrirlo leyendo el código, no lo pongas en CLAUDE.md. Documenta el por qué, no el qué. Las decisiones de negocio, las dinámicas de equipo, los motivos detrás de una arquitectura — eso sí que no se infiere de un composer.json.

TL;DR Ejecuta /init para generar un CLAUDE.md base, luego elimina todo lo que sea auto-inferible. Quédate solo con lo que Claude no puede descubrir por sí mismo: decisiones de equipo, convenciones no estándar y el por qué detrás de cada regla.

Resultado:

# 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

Configuración

1. Generar el archivo base

claude
# Dentro de la sesión:
/init

Claude analiza el codebase — detecta build system, frameworks, tests — y genera un CLAUDE.md inicial. Si ya existe uno, sugiere mejoras en lugar de sobreescribirlo. Si quieres un CLAUDE.md más quirúrgico desde el principio (y opcionalmente skills + hooks), activa el flujo interactivo de /init — aplica la regla de concisión desde el primer momento.

2. Limpiar lo que sobra

Revisa el archivo generado y elimina:

• Dependencias que aparecen en package.json, composer.json, Cargo.toml
• Estructura de carpetas (Claude la ve directamente)
• Convenciones estándar del lenguaje ("usar camelCase en JavaScript")
• Explicaciones de APIs públicas (enlaza a la documentación en lugar de copiarla)

3. Añadir lo que Claude no puede inferir

• Decisiones de negocio y sus razones
• Convenciones de equipo que difieren del estándar
• Scripts internos con contexto de uso
• Restricciones legales o de compliance
• Flujos de trabajo no documentados en código

4. Importar archivos externos (opcional)

Usa @ruta/archivo para modularizar sin sobrecargar el archivo principal:

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

Máximo 5 niveles de importación. Las rutas relativas se resuelven desde el archivo que contiene el import.

Mantenlo afilado en el tiempo

Un CLAUDE.md no es "una vez y olvidar" — se pudre si no lo iteras. Cada par de semanas ejecuta /insights: analiza tus últimas sesiones y te sugiere reglas nuevas sacadas literal de las instrucciones que más repites. Las buenas las pegas a CLAUDE.md y la fricción baja en la siguiente sesión.

Referencia

Buenas prácticas

Documentación oficial: Memory and CLAUDE.md

Forma parte de los 10 hábitos para ahorrar tokens en Claude Code. Mas sobre la sintaxis @: Cinco formas de darle a Claude Code el contexto correcto.