He probado docenas de configuraciones de Claude Code.
Lo único que realmente cambió mis resultados: un archivo de 60 líneas llamado CLAUDE.md.
Guarda esto en marcadores 🔖
Aquí te explico exactamente cómo funciona, por qué la mayoría lo pasa por alto por completo y la plantilla completa que puedes copiar hoy mismo:
Lo que nadie te cuenta sobre Claude Code
Antes de tu primer prompt. Antes de una sola línea de código. Antes de que ocurra cualquier cosa en tu sesión.
Claude lee un archivo. Solo uno.
CLAUDE.md.
Y lo trata como la verdad absoluta durante toda la sesión. No como una sugerencia. No como un contexto entre otros. Sino como el brief definitivo que enmarca cada decisión que tomará.
Por eso este archivo es la variable más infravalorada de todo el stack de Claude Code.
La mayoría de la gente no tiene ninguno. Y los que sí tienen han cometido uno de dos errores: o el archivo está vacío de contenido, o tiene 300 líneas de "sé un ingeniero senior con experiencia que piensa paso a paso".
Ambos son inútiles. Por razones distintas.
Por qué la mayoría de los archivos CLAUDE.md no funcionan: las 3 razones reales
Razón 1: Demasiado largo
Claude puede seguir de forma fiable entre 150 y 200 instrucciones por sesión. Esto es una limitación estructural, no una cuestión de buena voluntad.
Problema: El prompt de sistema interno de Claude Code ya contiene unas 50 instrucciones. Eso significa que tu CLAUDE.md tiene en realidad de 100 a 150 espacios de instrucción antes de que Claude empiece a descartarlas.
Si tu archivo tiene 200 líneas, Claude no ignora tus reglas a propósito. Las olvida mecánicamente. No tienes un problema de cumplimiento. Tienes un problema de presupuesto de atención.
Razón 2: Mal contenido
La mayoría de los archivos CLAUDE.md están llenos de cosas que Claude puede deducir por sí solo o que no cambian su comportamiento de forma medible.
"Actúa como un ingeniero senior". → Claude ya sabe lo que significa y no fija ningún comportamiento concreto.
"Piensa paso a paso". → Eso ya está en su entrenamiento. Estás desperdiciando una línea.
"Escribe código limpio y mantenible". → Sin criterios concretos. Claude no sabe qué significa "limpio" en tu contexto específico.
Cada línea que no evita un error concreto y específico es una línea robada a instrucciones que realmente importan. La prueba es simple: si eliminas esta línea, ¿Claude se equivocará en algo concreto? Si la respuesta es no, la línea no debería estar ahí.
Razón 3: Jerarquía cero
La mayoría ignora que hay tres niveles de instrucciones en Claude Code, y lo meten todo en el mismo sitio.
~/.claude/CLAUDE.md→ Global (aplica a todos tus proyectos).claude/CLAUDE.md→ Proyecto (compartido con el equipo, en git)./CLAUDE.local.md→ Local (preferencias personales, ignorado por git)
El nivel global es para reglas que repetirías en todos los proyectos. El nivel de proyecto es para el contexto específico de tu stack y tu equipo. El nivel local es para tus preferencias personales que no necesitan compartirse.
Usar correctamente los tres niveles es lo que mantiene cada archivo corto, enfocado y realmente efectivo. Poner todo en un solo archivo es como construir un embudo para ahogar tus reglas importantes bajo ruido.
Las 5 secciones que conforman un CLAUDE.md efectivo
Después de examinar docenas de archivos CLAUDE.md en producción —proyectos open source, documentación oficial de Anthropic, repositorios comunitarios de mejores prácticas—, estas son las 5 secciones que todos los archivos efectivos tienen en común:
Sección 1: Comandos críticos
Claude empieza cada sesión sin saber cómo compilar tu proyecto, ejecutar tus tests o corregir errores de lint. Lo adivinará. Y sus suposiciones te costarán turnos.
Dile exactamente qué escribir:
Commands
- Build:
npm run build - Dev:
npm run dev - Test single file:
npm test -- path/to/file - Full test:
npm test - Lint + fix:
npm run lint:fix - Type check:
npx tsc --noEmit
Concreto. Preciso. Directamente utilizable.
Sin esta sección, Claude intentará npm test cuando tu proyecto use pnpm vitest. Perderá tres turnos depurando un problema de comandos que nunca iba a funcionar. Tres turnos que podrías haber usado en trabajo real.
Sección 2: Mapa de arquitectura
Claude empieza cada sesión con cero conocimiento de tu código base. Cero. No sabe dónde vive tu lógica de negocio. No sabe si tus componentes deben ser sin estado. No sabe que tus rutas de API no deben contener lógica de negocio.
Dale un mapa:
Architecture
- src/lib/services/ → toda la lógica de negocio
- src/components/ → componentes de UI sin estado únicamente
- src/lib/store/ → estado global (Zustand)
- src/app/api/ → rutas de API, sin lógica de negocio aquí
- Acceso a BD solo mediante Server Actions o rutas de API
No es un listado exhaustivo de tu estructura de directorios. Solo lo suficiente para que Claude sepa dónde viven las cosas y, más importante, dónde NO deben ir.
Esta distinción... dónde va vs. dónde no va... es lo que evita los errores arquitectónicos más frecuentes.
Sección 3: Reglas estrictas
Esta es la sección más importante de todo el archivo. Sin excepción.
Cada regla aquí debe responder a una sola pregunta: "Si elimino esta línea, ¿cometerá Claude un error concreto?"
Si sí → la regla se queda. Si no → no tiene razón de estar ahí.
Ejemplo de reglas de alto valor:
Rules
- NEVER commit .env files or secrets
- All async calls must be wrapped in a try/catch
- Functional components only, zero class components
- Mandatory commit prefixes: feat:, fix:, docs:, refactor:
- Every PR must pass
npm run verifybefore merge - Static export only, no SSR (deployed on S3)
- IMPORTANT: run type check after every code modification
Dos cosas que destacar de esta lista.
Primero, las reglas negativas son tan importantes como las positivas. "Never commit .env files" es una regla que solo parece obvia hasta el día en que Claude lo hace. Ponla.
Segundo, los marcadores de énfasis como IMPORTANT o YOU MUST realmente funcionan.
Esto no es anecdótico. Anthropic lo confirma en su propia documentación: agregar IMPORTANT o YOU MUST antes de una regla mejora de forma medible la adherencia de Claude a esa regla.
Úsalos con moderación: resérvalos para las reglas que tengan las consecuencias más graves si se ignoran.
Mantente por debajo de 15 reglas en esta sección. Más allá de eso, diluyes la atención en las que importan.
Sección 4: Preferencias de flujo de trabajo
Ya te ha pasado. Le pides a Claude que arregle una línea. Y reescribe tres archivos, te renombra las funciones y refactoriza una clase que no tenía nada que ver con tu petición.
Esta sección lo evita:
Workflow
- Ask clarifying questions before starting complex tasks
- Make minimal changes, do not refactor unrelated code
- Run tests after every change, fix failures before continuing
- Create separate commits per logical change, not one giant commit
- In case of uncertainty between two approaches, explain both and let me choose
Cada línea aquí responde a un punto de dolor concreto. El commit gigante de 47 archivos. La reescritura completa no solicitada. La decisión arquitectónica que Claude toma solo cuando debería haberte preguntado.
Sección 5: Lo que NO debes poner en tu CLAUDE.md
Esta sección es tan importante como las demás. Quizás más.
Do NOT include:
- Personality instructions ("be a senior engineer")
- Formatting rules that your linter already handles
- @ imports that pull entire docs into every session
- Duplicate rules (if global says "run tests", the project doesn't repeat it)
- Anything Claude learns on its own via auto-memory
Este último punto está muy subestimado.
Claude mantiene sus propias notas en ~/.claude/projects/<project>/memory/. Ejecuta /memory en tu sesión para ver lo que ya ha aprendido sobre tu proyecto. Después de unas cuantas sesiones, a menudo te darás cuenta de que Claude ya ha capturado información que ibas a escribir a mano en tu CLAUDE.md.
No malgastes tus instrucciones limitadas en cosas que Claude ya ha recordado por sí solo.
La plantilla completa en menos de 60 líneas, lista para usar
Elimina las secciones que no apliquen a tu proyecto. El objetivo no es llenarlo todo. El objetivo es conservar solo lo que cambie el comportamiento de Claude de forma medible.
Las líneas que más impacto tuvieron en mis resultados: resultados concretos
Después de probar docenas de configuraciones, estas son las cinco líneas que marcaron la diferencia más visible:
- IMPORTANT: run type check after every code modification → Evita que Claude entregue código con tipos rotos que no detecta sin que se le pida explícitamente que los revise.
- Make minimal changes, do not refactor unrelated code → Evita la reescritura completa y no solicitada de archivos enteros.
- Create separate commits per logical change, not one giant commit → Evita el commit monstruoso e ilegible de 47 archivos mezclados.
- In case of uncertainty between two approaches, explain both and let me choose → Evita que Claude tome decisiones arquitectónicas solo, cuando deberían haberte pertenecido a ti.
- Static export only, no SSR → Evita que Claude agregue código de servidor en un proyecto desplegado estáticamente en S3.
Lo que estas cinco líneas tienen en común: cada una evita un error específico, frecuente y costoso en tiempo de depuración.
Esta es la prueba definitiva para cada línea de tu CLAUDE.md.
El error fundamental y por qué está tan extendido
La gente trata su CLAUDE.md como una lista de deseos o un prompt de personalidad.
" Sé senior." " Sé minucioso." " Piensa como un experto."
Esto no es un brief. Es pensamiento mágico.
Tu CLAUDE.md debería ser un documento técnico, no un discurso motivacional. Stack, comandos, arquitectura, reglas concretas, flujo de trabajo. Todo lo demás es ruido que compite con las instrucciones que realmente importan.
Mantén el archivo por debajo de 80 líneas. Revísalo cada vez que Claude cometa un error que podrías haber prevenido.
Y sobre todo: entiende en qué se convierte este archivo con el tiempo.
Un buen CLAUDE.md en el primer mes te ahorra tiempo en cada sesión. Al tercer mes, ya ha capturado tus convenciones y tu stack con la precisión suficiente para que Claude funcione casi como un miembro del equipo.
Al sexto mes, contiene todos los errores que Claude ha cometido en este proyecto y los previene todos automáticamente.
El archivo capitaliza. Mejora con cada corrección. Se convierte progresivamente en el mejor brief de incorporación que hayas escrito.
No para Claude. Para ti.
