Casi todo el mundo conoce una: el CLAUDE.md. Y como es la única que conoce, mete ahí todo. Procedimientos de quince pasos, reglas que solo aplican a una carpeta, instrucciones de tono, cosas que deberían ser obligatorias y no lo son.
El resultado es un archivo de seiscientas líneas donde la instrucción importante se perdió, y la conclusión de que "Claude no hace caso". Claude sí hace caso; el mecanismo estaba mal elegido.
Hay siete formas de dirigir Claude Code. No compiten: viven en capas distintas, cargan en momentos distintos y tienen fuerza distinta. Esta guía es cuál usar para qué.
Las tres capas, antes de las siete
Si entiendes esto, el resto se acomoda solo. Una instrucción puede vivir en tres lugares, y de ahí sale toda su fuerza:
- En el prompt de sistema. Es lo primero que ve el modelo y lo que más pesa. Ahí viven los estilos de salida y lo que agregas con la bandera de prompt de sistema.
- En un mensaje de usuario. Ahí viven el
CLAUDE.mdy las reglas: llegan justo después del prompt de sistema, como si tú los hubieras escrito. Claude los lee y trata de seguirlos, pero no hay cumplimiento garantizado. - Fuera del modelo. Los hooks no son texto: son comandos que Claude Code ejecuta en puntos fijos. Pasan sí o sí, decida lo que decida el modelo.
De ahí sale la regla más útil de toda esta guía: si algo tiene que pasar siempre, no lo escribas, ejecútalo. Todo lo demás es cuestión de cuándo quieres que la instrucción entre al contexto.
Las 7 formas
1. CLAUDE.md ./CLAUDE.md
Qué hace: le da a Claude los hechos permanentes de tu proyecto: comandos, convenciones, decisiones de arquitectura, trampas conocidas.
Cuándo carga: completo, al inicio de cada sesión. Se recorre el árbol de directorios hacia arriba desde donde arrancaste, y todos los archivos encontrados se concatenan de lo general a lo específico. Hay cuatro niveles: política de organización, tus preferencias en ~/.claude/CLAUDE.md, el del proyecto, y tu CLAUDE.local.md personal.
Cuánto pesa: medio. Llega como mensaje de usuario, no como prompt de sistema, así que es contexto y no configuración obligatoria. Y pesa menos entre más largo sea: la recomendación oficial es quedarse debajo de 200 líneas por archivo.
Úsalo para: hechos que aplican a todo el proyecto, todo el tiempo. Nada más. El detalle completo está en la guía del archivo más importante.
2. Reglas por ruta .claude/rules/
Qué hace: lo mismo que el CLAUDE.md, pero partido por tema y —esta es la gracia— con la opción de amarrarlo a rutas de archivo.
Cuándo carga: depende. Un archivo de reglas sin encabezado especial se carga al arranque, con la misma prioridad que el CLAUDE.md del proyecto. Si le pones un campo paths con patrones tipo src/api/**/*.ts, esa regla solo entra al contexto cuando Claude toca un archivo que coincide.
Cuánto pesa: igual que el CLAUDE.md. La ventaja no es fuerza, es puntería: tus reglas de API dejan de ocupar contexto mientras estás en otra parte del código.
Úsalo para: convenciones que aplican a una zona del repositorio. También hay una versión personal en ~/.claude/rules/ que aplica a todos tus proyectos.
3. Skills .claude/skills/nombre/SKILL.md
Qué hace: empaqueta un procedimiento o un cuerpo de conocimiento que solo hace falta a veces. Un archivo con un encabezado —nombre y descripción— y las instrucciones abajo. Puede traer archivos de apoyo en su carpeta.
Cuándo carga: bajo demanda. Claude ve la descripción y decide si aplica, o tú la invocas directo escribiendo /nombre-de-la-skill. El cuerpo no ocupa contexto hasta que se usa, y eso cambia toda la economía: un manual de doscientas líneas cuesta casi nada mientras no lo llames.
Cuánto pesa: alto cuando está cargada, cero cuando no. Si es un flujo con efectos secundarios que solo tú debes disparar, se marca en el encabezado con disable-model-invocation: true para que Claude no la invoque solo.
Úsalo para: todo lo que sea un procedimiento. Si una sección de tu CLAUDE.md se convirtió en una lista de pasos, esa sección ya no es memoria: es una skill mal ubicada. Los comandos personalizados de .claude/commands/ se fusionaron con este mecanismo y siguen funcionando igual.
4. Subagentes .claude/agents/nombre.md
Qué hace: define un asistente aparte, con su propio prompt de sistema, su propio conjunto de herramientas permitidas, su propio modelo y sus propios permisos. Corre en una ventana de contexto aislada y regresa un resumen.
Cuándo carga: cuando Claude delega, o cuando lo llamas por su nombre. Arranca en frío: no hereda tu conversación, ni el estilo de salida de la sesión principal, ni la memoria automática. Sí hereda los archivos CLAUDE.md. La excepción es una bifurcación de la conversación actual, que sí se lleva todo el contexto.
Cuánto pesa: total dentro de su burbuja: su prompt de sistema es el que tú escribiste, no el de Claude Code. Y cero fuera de ella.
Úsalo para: dos cosas. Investigar sin ensuciar tu contexto, y revisar con ojos frescos. Un revisor que solo puede leer, definido con su lista de herramientas acotada, es más útil que uno que puede escribir. También se puede correr una sesión entera como un subagente con la bandera correspondiente al arrancar.
5. Hooks .claude/settings.json
Qué hace: ejecuta comandos de shell en puntos fijos del ciclo de vida. No le pide nada al modelo: le pasa por encima.
Cuándo carga: nunca entra al contexto como instrucción. Se dispara por evento. Hay eventos para casi todo: antes de una llamada a herramienta, después, al enviar un prompt, al arrancar la sesión, al terminarla, antes de compactar, cuando termina un subagente, cuando Claude termina de responder.
Cuánto pesa: el máximo. Un hook de PreToolUse puede cancelar una acción antes de que ocurra y explicarle a Claude por qué. Un hook de Stop puede impedir que el turno termine hasta que tu verificación pase.
Úsalo para: lo innegociable. Correr el formateador después de cada edición, bloquear escrituras a la carpeta de migraciones, registrar cada comando ejecutado. Puedes pedirle a Claude que te escriba el hook, y /hooks abre el navegador de lo que tienes configurado.
6. Estilos de salida .claude/output-styles/
Qué hace: cambia cómo responde Claude, no lo que sabe. Modifica directamente el prompt de sistema para fijar rol, tono y formato.
Cuándo carga: al inicio de la sesión, y por eso un cambio no surte efecto hasta que corres /clear o abres una sesión nueva. Se elige desde /config, en la opción de estilo de salida, o fijando el campo outputStyle en un archivo de ajustes.
Cuánto pesa: alto: está en el prompt de sistema. Vienen varios integrados —uno proactivo que ejecuta en vez de preguntar, uno explicativo y uno de aprendizaje— y puedes escribir el tuyo en un archivo de markdown. La decisión clave del encabezado es keep-coding-instructions: si lo dejas en falso, se van las instrucciones de ingeniería de software que trae Claude Code de fábrica, que es lo que quieres si lo vas a usar para escribir o analizar y no para programar.
Úsalo para: cuando te descubras repitiendo la misma indicación de formato en cada turno. Ojo: aplica solo a la conversación principal, no a los subagentes.
7. El prompt de sistema --append-system-prompt
Qué hace: agrega texto al prompt de sistema sin quitar nada de lo que ya trae. Es la forma de meter una instrucción al nivel más alto sin escribir un estilo de salida completo.
Cuándo carga: en esa invocación y nada más. Hay que pasarlo cada vez.
Cuánto pesa: el máximo del lado del texto. Por eso mismo, es el mecanismo más incómodo para uso interactivo y el más natural para automatización.
Úsalo para: corridas en modo no interactivo. Cuando lanzas claude -p desde un script o desde una tarea programada y necesitas fijar el rol de esa corrida en particular, esta es la vía.
El paso que todo mundo se salta: comprobar que la instrucción llegó. /context te dice qué archivos de memoria se cargaron en esta sesión, y existe un evento de hook que registra exactamente qué archivo de instrucciones se cargó, cuándo y por qué. He visto reescribir la misma regla cinco veces cuando el problema era que el archivo estaba en una carpeta que no se recorre. Antes de mejorar la redacción, verifica que existe en el contexto.
Cómo elegir en diez segundos
Cuatro preguntas, en orden. La primera que conteste que sí, gana:
- ¿Tiene que pasar siempre, sin excepción? Es un hook. No lo escribas como regla y esperes disciplina del modelo.
- ¿Es un procedimiento de varios pasos que solo aplica a veces? Es una skill.
- ¿Es un hecho que solo importa en cierta parte del código? Es una regla con
paths. - ¿Es un hecho que importa siempre? Ahora sí, va al
CLAUDE.md.
Y aparte de esas cuatro: si lo que quieres es cambiar el tono de todas las respuestas, es un estilo de salida. Si lo que quieres es aislar una tarea con sus propias herramientas, es un subagente.
En qué orden montarlas
La tentación es configurar las siete el primer día. No sirve: acabas con una máquina que no entiendes y que no sabes cuál pieza está fallando.
- Semana 1 — el
CLAUDE.md, corto. Corre/init, quítale la mitad, y vive con eso. - Semana 2 — la primera skill. El procedimiento que más veces repites a mano.
- Semana 3 — el primer hook. Uno solo, el más obvio: formateo o verificación después de editar.
- Semana 4 — un subagente revisor. Solo lectura, con criterios escritos.
- Después — reglas por ruta, cuando el
CLAUDE.mdempiece a crecer de nuevo. Ese crecimiento es la señal, no el calendario.
Los estilos de salida y la bandera de prompt de sistema quedan al final a propósito. Son los que menos gente necesita: el primero solo si vas a usar Claude Code fuera de programación, el segundo solo si ya estás automatizando corridas.
Lo que ninguna de las siete arregla
Ninguna hace que Claude sepa si su trabajo quedó bien. Puedes tener las siete perfectamente configuradas y seguir siendo tú el único que verifica.
Esa pieza va aparte y es la que más rinde: darle una comprobación que produzca un pasa o no pasa. Cuando eso existe, todo lo demás de esta lista funciona sin supervisión. Sin eso, lo único que lograste es que se equivoque con mejor estilo.