Dale contexto a Claude: CLAUDE.md y mejores prompts

Claude Code funciona bien desde el principio, pero se vuelve notablemente más efectivo una vez que conoce las convenciones de tu proyecto y adoptas algunos hábitos de prompting. Esta guía cubre ambos.

CLAUDE.md es un archivo markdown simple que Claude lee automáticamente al inicio de cada sesión en ese directorio. Piénsalo como la orientación que le darías a un nuevo compañero de equipo capaz en su primer día: cómo hace las cosas el equipo, qué evitar y dónde viven las piezas importantes.

No necesitas referenciarlo en los prompts ni adjuntarlo manualmente. Si el archivo existe, Claude ya lo ha leído.

Claude busca en varios lugares y fusiona lo que encuentra, de lo general a lo específico:

La mayoría de los equipos solo necesitan el archivo de raíz del proyecto. Confirma en git para que todo el equipo se beneficie.

CLAUDE.md se lee una vez, al inicio de la sesión, y se coloca textualmente en el prompt del sistema de Claude. No hay resumen ni truncamiento, y no se relee del disco en cada turno; el mismo contenido permanece en contexto durante toda la conversación. Si editas el archivo durante la sesión, el cambio no entra en vigor hasta que inicies una nueva sesión.

Para clientes de Claude for Enterprise, el panorama de costos es mejor de lo que "cargado en cada solicitud" podría sugerir. Claude Code aplica el almacenamiento en caché de prompts de Anthropic al prompt del sistema, que incluye CLAUDE.md. La primera solicitud en una sesión paga el precio completo de tokens de entrada del archivo; las solicitudes posteriores dentro de aproximadamente cinco minutos entre sí acceden al caché y se facturan a la tasa mucho más baja de lectura de caché. El caché se direcciona por contenido, por lo que cualquier cambio en CLAUDE.md lo invalida y la siguiente solicitud paga el precio completo nuevamente.

En la práctica, esto significa que un CLAUDE.md considerable cuesta tokens completos una vez por sesión, más una vez después de cualquier pausa de inactividad lo suficientemente larga para que expire el caché, en lugar de una vez por mensaje. Aún vale la pena mantener el archivo ágil para el espacio de la ventana de contexto y la relación señal-ruido, pero no necesitas racionar líneas puramente para controlar el gasto por mensaje. En el panel de control de uso de Enterprise, la huella del archivo aparecerá casi en su totalidad como tokens de lectura de caché en lugar de tokens de entrada estándar.

En cualquier proyecto, escribe /init. Claude explorará la base de código y redactará un CLAUDE.md para ti, cubriendo comandos de compilación, comandos de prueba, una descripción general de la estructura y cualquier convención que detecte. Revisa el borrador, elimina cualquier cosa inexacta y confirma. Esto toma aproximadamente cinco minutos y se amortiza permanentemente.

Apunta a un archivo que sea corto y denso en señal—unas pocas cientos de líneas como máximo. Cada línea se carga en contexto en cada solicitud, por lo que cada una debe valer su costo.

Vale la pena incluir:

No vale la pena incluir:

Trátalo como un documento de incorporación vivo, no como una especificación.

También puedes añadirlo durante la sesión: escribe # seguido de una instrucción (p. ej. # siempre usa async/await, nunca .then()) y Claude se ofrecerá a añadirlo al CLAUDE.md correcto para ti.

Estos no son consejos genéricos de ingeniería de prompts; son los hábitos que más importan específicamente cuando Claude está leyendo y editando una base de código real.

Claude puede explorar la base de código por sí mismo. Dile qué quieres y por qué, y déjalo que descubra dónde.

❌ "Abre userService.ts, encuentra la función validate, añade una verificación nula en la línea 42."

✅ "Los usuarios sin correo electrónico están causando un bloqueo en el paso de validación. Haz que lo maneje con elegancia y añade una prueba."

Pega el seguimiento de pila completo en lugar de resumirlo. El nombre de archivo exacto, el número de línea y el mensaje son lo que permite a Claude encontrar la ubicación correcta rápidamente.

Para cualquier cosa que toque más de un par de archivos, presiona Shift+Tab en Plan Mode y pregunta:

"Planifica cómo añadirías limitación de velocidad a la API pública. No cambies nada todavía."

Revisa el plan, ajústalo en la conversación, luego cambia de modo y di "haz el paso 1." Esto atrapa malentendidos antes de que se conviertan en un diff de doce archivos.

Claude puede buscar en la base de código por su cuenta, pero si ya conoces el archivo relevante, díselo — es más rápido y usa menos tokens. Usa @ para referenciar rutas, por ejemplo @src/auth/login.ts.

Los ejemplos incluyen "las pruebas pasan," "coincide con el estilo de los otros manejadores," o "sin nuevas dependencias." Establecer criterios de aceptación por adelantado es más eficiente que varias rondas de revisión.

Las sesiones largas acumulan ruido. Cuando cambias de "arregla el error de inicio de sesión" a "refactoriza el módulo de facturación," ejecuta /clear y comienza de nuevo. Tu CLAUDE.md lleva el contexto duradero hacia adelante, por lo que el historial de chat no necesita hacerlo.

Si la primera respuesta no es correcta, no necesitas reformular toda la solicitud. Simplemente di qué está mal — por ejemplo, "Eso cambia la API pública; mantén la firma igual." Claude mantendrá todo lo demás y ajustará solo ese punto.