Siete errores en CLAUDE.md que degradan silenciosamente la salida de Claude Code

Esa duda es precisamente donde residen las malas configuraciones. Sin errores, sin advertencias, solo código vagamente genérico y ligeramente incorrecto, sesión tras sesión. Un archivo confuso o sobredimensionado no solo deja de ser útil; además consume recursos y obstaculiza la tarea real. Así que antes de cambiar ni una sola línea, analice con detenimiento su contenido y luego resuelva los problemas uno por uno.

Error 1: una descripción vaga del entorno

Una línea como Usamos React y una base de datos. no le dice casi nada a Claude. Él intentará adivinar si se trata del router de Next.js, elegirá una librería de estado más o menos al azar y escribirá pruebas en un framework que usted no utiliza. El resultado se compila, pero sigue sin adaptarse a su código.

Sé más específico en su lugar:

Framework: Next.js 15, app router only
State: TanStack Query v5 for server state, Zustand for client state
Testing: Vitest + React Testing Library
Package manager: pnpm

Las versiones exactas y las convenciones son lo que convierte una salida genérica en código que parece pertenecer a su repositorio. Asígnéles nombres.

Error 2: sin restricciones, sin “nunca hagas esto”

Este es el fallo silencioso más común. La gente describe el proyecto pero nunca establece límites claros. Sin restricciones, Claude ejecuta npm en un proyecto pnpm, edita los archivos generados y refactora código del que nunca se habló. Esos no son errores por alucinación; son suposiciones razonables hechas porque no hay regla que indique lo contrario.

Agregue un bloque de restricciones:

Constraints:
- Never install new dependencies without asking first
- Never edit files under /generated or /prisma/migrations
- Always use pnpm, never npm or yarn
- Do not refactor code outside the scope of the current task

Las reglas sobre qué no hacer le brindan más beneficios que las descripciones, ya que evitan errores costosos antes de que ocurran.

Error 3: ignorar agentes y subagentes

La mayoría de los archivos CLAUDE.md están escritos como si un único modelo funcionara por sí solo, sin indicaciones para subagentes especializados que operen junto a la sesión principal. Si utiliza subagentes para pruebas, documentación o despliegue, indíquelo en el archivo: enumere cada agente, la área de responsabilidad de cada uno y las situaciones en las que el agente principal debe transferirle el trabajo.

Agents & delegation:
- test-agent: runs Vitest, owns /tests — do not write tests in the main session
- docs-agent: handles JSDoc and README updates only
- main agent: feature code, routing, API handlers

Si aún está diseñando el modelo de delegación, es útil comprender cómo difieren las habilidades, los subagentes, los comandos de barra y MCP antes de decidir la estructura final.

Error 4: un archivo excesivo que agota su presupuesto de contexto

Más no significa mejor. Un archivo CLAUDE.md de 2,000 líneas repleto de guías de estilo completas, documentación de API y registros de cambios carga todo eso en cada sesión, ya sea relevante o no. Eso dificulta realizar la tarea real, y como la atención disminuye con un contexto ruidoso, al final se obtiene un modelo que técnicamente ha leído tus reglas pero aún no las aplica de manera fiable.

Limita todo a lo esencial. Indica los archivos o habilidades donde se encuentran los detalles en lugar de pegarlos directamente. Una regla relacionada con un solo paquete debe estar en un archivo específico, no en la raíz. Cuenta los tokens del archivo antes y después de hacer los ajustes para asegurarte de que realmente haya habido cambios.

Error 5: instrucciones que Claude no puede seguir

Toma como ejemplo Escribe código limpio, mantenible y de alta calidad. Claude ya cree que está haciendo eso, por lo que los adjetivos vagos no sirven de nada. Reemplázalos por reglas que puedas verificar:

- Functions must be under 40 lines
- No default exports
- Colocate test files next to source files
- No inline styles — use CSS modules

Las reglas operativas le brindan al modelo un objetivo medible. Las frases aspiracionales no le proporcionan ninguno.

Error 6: reglas obsoletas que contradicen el código

El problema de CLAUDE.md es real. Imagina que el archivo sigue indicando “use Redux” seis meses después de que el equipo haya pasado a usar Zustand. Esa regla no permanece inactiva sin causar problemas; hace que tu configuración entre en conflicto con el código real, y Claude alterna entre confiar en una u otra.

Revisa el archivo cada vez que las dependencias cambien significativamente, e incluye esa revisión como un punto en tu lista de verificación para las PR. Guárdala en Git para poder ver cuándo se modificó cada regla por última vez. Un CLAUDE.md obsoleto suele ser peor que no tenerlo en absoluto.

Error 7: un único archivo plano gigantesco

En un monorepo, un solo CLAUDE.md no estructurado hace que Claude aplique reglas del frontend al código del backend y viceversa. Cuando todo está combinado en un único bloque sin diferenciar, no hay forma de delimitar el contexto.

Coloque las reglas globales en un archivo CLAUDE.md raíz y agregue archivos específicos por paquete o servicio. Dentro del archivo raíz, utilice encabezados de sección claros:

# Project Overview
# Stack & Versions
# Constraints
# Agents & Delegation
# Per-Package Notes

La estructura indica a Claude qué reglas son aplicables dónde.

Una auditoría rápida y una lista de verificación

Deje de adivinar y evalúe el archivo según cuatro criterios: especificidad, restricciones, estructura y tamaño. Compararlo con un modelo bien formado también es útil, ya que muestra cómo debería verse un buen archivo en la práctica.

Responda a estas preguntas:

• ¿Menciona las versiones exactas del framework y las bibliotecas?
• ¿Existe un bloque de restricciones con reglas estrictas del tipo “nunca haga esto”?
• ¿Enumera qué agentes existen y qué es lo que cada uno maneja?
• ¿Tiene menos de 200 líneas, con los detalles distribuidos en habilidades o archivos vinculados?
• ¿Todas las instrucciones son prácticas y no meramente deseadas?

¿Alguien lo ha revisado en los últimos 30 días para verificar si hay reglas obsoletas?

¿Está dividido por encabezados, o por archivos específicos de cada paquete si se utiliza un monorepo?

Si responde que no a más de dos de estas preguntas, es probable que su CLAUDE.md le cueste más de lo que ahorra.