He probado docenas de configuraciones de Claude Code.
Lo único que realmente cambió mi resultado: un archivo de 60 líneas llamado CLAUDE.md.
Guarda esto como referencia 🔖
Aquí está exactamente cómo funciona, por qué la mayoría de las personas lo pasan por alto por completo, y la plantilla completa que puedes copiar hoy:
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 algo en tu sesión.
Claude lee un archivo. Solo uno.
CLAUDE.md.
Y lo trata como la verdad absoluta para toda la sesión. No como una sugerencia. No como un contexto entre otros. Como el resumen definitivo que enmarca cada decisión que tomará.
Por eso este archivo es la variable más subestimada de todo el stack de Claude Code.
La mayoría de las personas no tienen uno. Y quienes lo 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 experimentado que piensa paso a paso".
Ambos son inútiles. Por diferentes razones.
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 manera confiable entre 150 y 200 instrucciones por sesión. Esta es una limitación estructural, no una cuestión de buena voluntad.
Problema: el prompt del sistema interno de Claude Code ya contiene alrededor de 50 instrucciones. Eso significa que tu CLAUDE.md en realidad tiene de 100 a 150 espacios de instrucción antes de que Claude empiece a omitirlas.
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 manera medible.
"Actúa como un ingeniero senior." → Claude ya sabe lo que eso significa y no ancla ningún comportamiento específico. "Piensa paso a paso." → Eso está en su entrenamiento. Estás desperdiciando una línea. "Escribe código limpio y mantenible." → Sin criterios concretos. Claude no sabe lo que significa "limpio" en tu contexto específico.
Cada línea que no previene un error específico y concreto es una línea robada a instrucciones que realmente importan. La prueba es simple: si eliminas esta línea, ¿cometerá Claude algún error específico? 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 meten todo en el mismo lugar.
~/.claude/CLAUDE.md → Global (aplica a todos tus proyectos)
.claude/CLAUDE.md → Proyecto (compartido con el equipo, en git)
./CLAUDE.local.md → Local (anulaciones personales, en gitignore)
El nivel global es para reglas que repetirías en cada proyecto. El nivel de proyecto es para el contexto específico de tu stack y 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 verdaderamente efectivo. Poner todo en un solo archivo es como construir un embudo para ahogar tus reglas importantes bajo el ruido.
Las 5 secciones que componen un CLAUDE.md efectivo
Después de examinar docenas de archivos CLAUDE.md en producción — proyectos de código abierto, documentación oficial de Anthropic, repositorios de mejores prácticas de la comunidad — aquí están las 5 secciones que todos los archivos efectivos tienen en común:
Sección 1: Comandos críticos
Claude comienza cada sesión sin saber cómo construir tu proyecto, ejecutar tus pruebas o corregir errores de lint. Lo adivinará. Y sus suposiciones te costarán turnos.
Indícale exactamente qué escribir:
Comandos
- Build:
npm run build - Dev:
npm run dev - Prueba un solo archivo:
npm test -- ruta/al/archivo - Prueba completa:
npm test - Lint + corrección:
npm run lint:fix - Verificación de tipos:
npx tsc --noEmit
Corto. Preciso. Directamente utilizable.
Sin esta sección, Claude intentará npm test cuando tu proyecto se ejecuta con pnpm vitest. Gastará tres turnos depurando un problema de comando que nunca iba a funcionar. Tres turnos que podrías haber usado en trabajo real.
Sección 2: Mapa de arquitectura
Claude inicia cada sesión con cero conocimiento de tu código. 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 API no deben contener lógica de negocio.
Dale un mapa:
Arquitectura
- src/lib/services/ → toda la lógica de negocio
- src/components/ → solo componentes de UI sin estado
- src/lib/store/ → estado global (Zustand)
- src/app/api/ → rutas API, sin lógica de negocio aquí
- Acceso a BD solo mediante Server Actions o rutas API
No es un listado exhaustivo de tu estructura de árbol. 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 previene 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 motivo para estar ahí.
Ejemplo de reglas de alto valor:
Reglas
- NUNCA confirmar archivos .env o secretos
- Todas las llamadas asíncronas deben envolverse en un try/catch
- Solo componentes funcionales, cero componentes de clase
- Prefijos de confirmación obligatorios: feat:, fix:, docs:, refactor:
- Cada PR debe pasar
npm run verifyantes de fusionar - Solo exportación estática, sin SSR (desplegado en S3)
- IMPORTANTE: ejecutar verificación de tipos después de cada modificación de código
Dos cosas que notar sobre esta lista.
Primero, las reglas negativas son tan importantes como las positivas. "Nunca confirmar archivos .env" es una regla que solo parece obvia hasta el día en que Claude lo hace. Ponla.
Segundo, los marcadores de énfasis como IMPORTANTE o DEBES realmente funcionan.
Esto no es anecdótico. Anthropic lo confirma en su propia documentación: agregar IMPORTANTE o DEBES antes de una regla mejora de forma medible la adherencia de Claude a esa regla.
Úsalos con moderación: resérvalos para 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 has experimentado esto. Le pides a Claude que corrija una línea. Reescribe tres archivos, renombra tus funciones y refactoriza una clase que no tenía nada que ver con tu solicitud.
Esta sección previene eso:
Flujo de trabajo
- Haz preguntas aclaratorias antes de comenzar tareas complejas
- Haz cambios mínimos, no refactorices código no relacionado
- Ejecuta pruebas después de cada cambio, corrige fallos antes de continuar
- Crea confirmaciones separadas por cambio lógico, no una confirmación gigante
- En caso de duda entre dos enfoques, explica ambos y déjame elegir
Cada línea aquí responde a un punto de dolor concreto. La confirmación 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 otras. Quizás más.
No incluyas:
- Instrucciones de personalidad ("sé un ingeniero senior")
- Reglas de formato que tu linter ya maneja
- Importaciones @ que traen documentos completos a cada sesión
- Reglas duplicadas (si el global dice "ejecuta pruebas", el proyecto no lo repite)
- Cualquier cosa que Claude aprenda por sí mismo mediante la memoria automática
Este último punto está ampliamente 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 algunas 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 desperdicies tus instrucciones limitadas en cosas que Claude ha recordado por sí mismo.
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 llenar todo. El objetivo es mantener solo lo que cambia el comportamiento de Claude de manera medible.
Las líneas que tuvieron mayor impacto en mi resultado: resultados concretos
Después de probar docenas de configuraciones, aquí están las cinco líneas que marcaron la diferencia más visible:
IMPORTANTE: ejecutar verificación de tipos después de cada modificación de código → Evita que Claude entregue código con tipos rotos que no detecta sin que se le pida explícitamente que verifique.
Haz cambios mínimos, no refactorices código no relacionado → Evita la reescritura completa y no solicitada de archivos enteros.
Crea confirmaciones separadas por cambio lógico, no una confirmación gigante → Evita la confirmación monstruosa e ilegible de 47 archivos mezclados.
En caso de duda entre dos enfoques, explica ambos y déjame elegir → Evita que Claude tome decisiones arquitectónicas solo, que deberían haber sido tuyas.
Solo exportación estática, sin 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 previene 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 resumen. Es pensamiento mágico.
Tu CLAUDE.md debe 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. Para el tercer mes, ha capturado tus convenciones y stack con suficiente precisión como para que Claude funcione casi como un miembro del equipo.
Para el sexto mes, contiene cada error que Claude haya cometido en este proyecto y los previene todos automáticamente.
El archivo se capitaliza. Mejora con cada corrección. Se convierte progresivamente en el mejor resumen de incorporación que hayas escrito.
No para Claude. Para ti.
