Estilos de salida (Output Styles): Cambiar de programa sin cambiar de presentador
📚 Navegación de la serie: El artículo anterior 31 settings.json: Configuración a nivel de usuario y proyecto te enseñó en qué archivo escribir tus opciones y qué nivel tiene prioridad. En este artículo profundizaremos en un interruptor que vive dentro de esa misma configuración: los estilos de salida (output styles). No controlan "qué sabe Claude", sino "cómo te responde". Con una sola línea de configuración, puedes hacer que pase de ser un "ingeniero enfocado en picar código" a un mentor que explica lo que hace sobre la marcha, o incluso adoptar un rol totalmente ajeno al software.
Todos dicen: "si quieres que Claude te escuche, mételo en CLAUDE.md": amontona allí convenciones, reglas y todo lo que deba recordar.
A decir verdad, esa afirmación solo es correcta a medias. CLAUDE.md es, en efecto, un excelente lugar para el contexto del proyecto (ver artículo 18), pero hay un tipo de necesidades que, si las guardas allí, las estás metiendo en el cajón equivocado.
¿Cuáles? Aquellas que dicen "quiero que cambie el tono, el rol o el formato de sus respuestas en cada ocasión". Por ejemplo: si quieres que dibuje un diagrama antes de explicar, que te enseñe por qué escribe el código de esa forma mientras programa, o si quieres usarlo como asistente de redacción en lugar de como programador. Escribir estas directrices en CLAUDE.md dará un resultado inconsistente, ya que CLAUDE.md es simplemente "un mensaje de usuario añadido después de la instrucción del sistema", una petición que Claude lee, pero no un interruptor que modifique su "comportamiento base". La herramienta diseñada para alterar la forma de responder de Claude se llama output styles.
Podemos expresarlo así: CLAUDE.md es la documentación técnica del proyecto que le entregas a un nuevo desarrollador; output styles redefine directamente su descripción de puesto: "tu rol aquí es ser un desarrollador enfocado en escribir código, o ser un tutor que explica lo que hace mientras trabaja". En este artículo te enseñaremos cómo configurar este interruptor.
Un escenario típico donde verás su utilidad de inmediato: permitir que alguien sin conocimientos de programación use Claude Code para redactar su currículum. Si usas la identidad de ingeniero por defecto, Claude intentará "refactorizar secciones en funciones" o te preguntará si quieres "añadir pruebas unitarias", aplicando un enfoque técnico de ingeniería que no tiene sentido para un currículum. Esto no es algo que debas resolver con CLAUDE.md; es la razón de ser de los output styles.
Al terminar de leer este artículo, obtendrás:
- Una explicación en una frase de qué modifican los output styles (pista: alteran el "cómo responde", no el "qué sabe").
- Los estilos de salida integrados en Claude Code (Default, Proactive, Explanatory, Learning), para qué sirven y cuándo activarlos.
- Cómo cambiar el estilo de salida y un cambio importante de versión: el comando
/output-styleha sido eliminado, te mostraremos cómo cambiarlo ahora. - Cómo definir tu propio estilo de salida personalizado: la estructura del archivo Markdown, qué hace cada opción del frontmatter y cómo configurar la opción crucial
keep-coding-instructions. - Una tabla comparativa detallada para distinguir los output styles de
CLAUDE.md,--append-system-prompt, Subagents y Skills, para que no los confundas.
01 Primero entiende: Modifica el "cómo responde", no el "qué sabe"
Comencemos con la regla central de este artículo:
Los estilos de salida modifican la forma de responder de Claude, no lo que Claude sabe.
Esta es una cita directa de la documentación oficial. Significa que los output styles no inyectan conocimientos nuevos sobre tu proyecto; lo que hacen es alterar la instrucción del sistema de Claude (system prompt, el mensaje base inyectado al inicio de cada conversación que define quién es Claude y cómo debe actuar) para establecer su rol, tono y formato de salida.
Analogía: Un mismo presentador de televisión adoptando tonos distintos según el programa. La persona es la misma, su capacidad, vocabulario y conocimientos no varían; sin embargo, si presenta el telediario de la noche adoptará un tono serio y formal, si presenta un programa infantil usará un tono dinámico y gestual, y si presenta un documental educativo hablará pausadamente, deteniéndose a explicar y haciendo preguntas. Lo que cambia es "lo que exige el formato del programa sobre su forma de hablar", no la persona en sí. Los output styles cambian el "programa" de Claude: el modelo y sus capacidades son los mismos, lo que cambia es su rol, tono y formato al interactuar contigo.
¿Cuándo resulta útil? La documentación oficial nos da una pauta clara:
Usa un estilo de salida cuando te encuentres repitiendo las mismas indicaciones sobre tono o formato en cada turno, o cuando quieras que Claude adopte un rol distinto al de ingeniero de software.
Se resume en dos señales claras:
- "Tengo que repetirle la misma instrucción en cada turno" → Por ejemplo, si tienes que decirle en cada mensaje "explícamelo dibujando primero un diagrama de flujo". Si lo repites por quinta vez, es señal de que esa regla no debe ser manual, sino un estilo de salida fijo.
- "La tarea que le pido no es de programación" → Por ejemplo, si lo usas para redactar textos o analizar datos. La instrucción del sistema por defecto de Claude Code está optimizada para resolver tareas de desarrollo de software con eficiencia; si le pides que escriba una historia, las reglas de "limitar el alcance de los cambios, documentar y probar" solo estorbarán.
Volviendo al caso de redactar un currículum: esta es la segunda señal. Toda la identidad por defecto de Claude Code está orientada al desarrollo de software; pedirle que revise un currículum con esa configuración genera ruido. Resolver esto pidiéndole en CLAUDE.md "olvida que eres un programador" no funcionará bien; CLAUDE.md es una indicación secundaria, mientras que el output style es la herramienta para redefinir su rol de partida.
💡 Resumen en una frase: Los output styles modifican la instrucción del sistema de Claude para redefinir su rol, tono y formato. Altera el "cómo responde", no el "qué sabe"; actívalo si repites la misma instrucción en cada turno o si no estás realizando tareas de programación.
02 Cuatro estilos integrados: Opciones listas para usar
Claude Code incorpora varios estilos de salida que puedes activar de inmediato, sin necesidad de configurarlos.
El estilo Default (por defecto) es el que hemos usado en las secciones anteriores. Su instrucción del sistema está diseñada específicamente para resolver tareas de desarrollo de software con eficiencia: cambios concisos, validaciones continuas y foco en la resolución. Es el estilo a usar por defecto si no tienes necesidades especiales.
Además del predeterminado, el sistema incluye tres estilos adicionales:
Proactive (proactivo): Más autónomo al tomar decisiones, prioriza la acción frente a la planificación. En palabras de la documentación oficial: "ejecuta tareas inmediatamente, asume decisiones lógicas en lugar de detenerse a preguntar y prefiere la acción a la planificación". Básicamente, reduce las preguntas de confirmación y los planes detallados, tomando decisiones lógicas por su cuenta para avanzar más rápido.
Nota: La documentación oficial aclara que Proactive ofrece directrices para una ejecución más autónoma, pero no modifica tu configuración de permisos (ver artículo 20). Por tanto, seguirás viendo las solicitudes de confirmación de herramientas antes de su ejecución según tu nivel de seguridad. Una cosa es el estilo de comportamiento (Proactive) y otra el nivel de seguridad (permisiones).
Explanatory (explicativo): Acompaña el código con explicaciones de valor. Al realizar los cambios técnicos, insertará explicaciones o "Insights" (conclusiones técnicas) para ayudarte a entender por qué implementa el código de esa forma o qué patrones sigue la base de código. Es ideal si buscas aprender además de obtener el resultado.
Learning (aprendizaje): Desarrollo interactivo donde te asigna tareas. Este es el estilo más singular. No solo incluye explicaciones como Explanatory, sino que introducirá marcas TODO(human) en el código para que tú mismo completes secciones clave del desarrollo. Claude diseña la estructura y te cede el teclado para las partes estratégicas, fomentando tu participación activa en lugar de dejar que lo haga todo él solo.
Veamos cómo se comportarían ante una misma petición: "añadir paginación a esta lista":
- En Proactive, procederá a realizar los cambios de inmediato, reduciendo preguntas sobre qué estrategia usar.
- En Explanatory, implementará el código y te explicará: "utilizo paginación por cursor en lugar de offset porque el proyecto maneja un gran volumen de datos, tal como se hace en el módulo Y".
- En Learning, preparará el andamiaje del código y dejará una línea indicando
// TODO(human): implementa aquí la extracción del cursor, cediéndote el turno.
Compara los estilos en esta tabla de referencia:
| Estilo | Diferencia con Default | Cuándo activarlo | ¿Genera respuestas más largas? |
|---|---|---|---|
| Default | Estilo base | Tareas comunes de desarrollo de software | Estándar |
| Proactive | Más autónomo, prioriza la acción | Quieres reducir preguntas y avanzar rápido | Similar |
| Explanatory | Explica conceptos y patrones del código | Quieres entender la lógica detrás del código | Sí, significativamente |
| Learning | Te asigna partes de código con TODO(human) | Quieres aprender escribiendo las partes clave | Sí, significativamente |
Presta atención a la última columna: la documentación oficial advierte que los estilos Explanatory y Learning generan respuestas más largas por diseño (al incluir explicaciones y guías). Respuestas más largas consumen más tokens de salida (ver facturación en el artículo 06). Evita usarlos como estilo global permanente; actívalos para aprender y regresa a Default al terminar, controlando el gasto de tokens y evitando respuestas demasiado largas en tareas cotidianas.
Una estrategia habitual: usa Default para el trabajo diario; si entras en un repositorio desconocido y quieres entender su arquitectura a medida que haces cambios, activa Explanatory; si quieres estudiar una biblioteca nueva escribiendo tú mismo las partes clave, usa Learning. Activar Proactive responde a una preferencia de estilo personal: actívalo si prefieres que actúe de forma directa reduciendo las consultas previas.
💡 Resumen en una frase: Dispones de cuatro estilos: Default para desarrollo ágil, Proactive para una ejecución con menos consultas, Explanatory para aprender con explicaciones y Learning para colaborar completando el código tú mismo; los dos últimos consumen más tokens de salida, por lo que se recomienda usarlos de forma puntual.
03 Cómo cambiar de estilo: El comando /output-style ha sido eliminado
Es importante aclarar esto, ya que es un cambio de versión importante: muchos tutoriales y guías antiguos siguen indicando comandos que ahora darán error en la terminal.
Si lees en otros manuales "usa el comando /output-style para cambiar de estilo", debes saber que este comando ha sido eliminado. La documentación oficial lo detalla:
El comando independiente
/output-stylefue declarado obsoleto en la versión v2.1.73 y eliminado en la versión v2.1.91. Usa el menú/configo edita directamente la opciónoutputStyle.
Por lo tanto, dispones de dos vías válidas que detallamos a continuación:
Vía 1: A través del menú /config (recomendado)
Escribe /config en la conversación, navega hasta la opción Output Styles (estilos de salida) en el menú y selecciona el que desees. Palabras oficiales:
Ejecuta
/configy selecciona Output Styles en el menú. Tu elección se guardará en tu archivo local del proyecto.claude/settings.local.json.
Nota dónde se guarda: el estilo seleccionado se escribirá en .claude/settings.local.json de tu proyecto. Como vimos en el artículo 31, este archivo es específico del proyecto y personal (no se incluye en git). De este modo, el estilo elegido solo te afecta a ti y a este repositorio, evitando imponer tu preferencia a tus compañeros de equipo al subir código.
Vía 2: Editar la opción outputStyle en el archivo de configuración
Puedes escribir la configuración directamente en el archivo JSON de tu nivel de preferencia añadiendo el campo outputStyle:
{
"outputStyle": "Explanatory"
}El valor será el nombre del estilo (los del sistema: Explanatory, Learning, Proactive, o el de tu estilo personalizado). El archivo donde lo escribas determinará su ámbito (escríbelo a nivel de usuario en ~/.claude/settings.json para aplicarlo globalmente, o en el proyecto para que sea específico). Las reglas de prioridad de niveles son las mismas que estudiamos en el artículo 31.
Un detalle crucial sobre el momento de aplicación
Sin importar la vía elegida, debes tener en cuenta cuándo se aplican los cambios. La documentación oficial lo detalla:
Los estilos de salida forman parte de la instrucción del sistema, que Claude Code lee únicamente al inicio de la sesión. Los cambios tendrán efecto tras ejecutar
/clearo al iniciar una conversación nueva.
Analogía: El guion del programa se entrega al presentador antes de empezar la emisión. Si el programa ya lleva media hora emitiéndose y le entregas un guion nuevo, no lo aplicará en esta emisión; tendrás que esperar al siguiente programa para que lo use. Con los output styles ocurre lo mismo: son parte de la instrucción del sistema y Claude los lee una sola vez al iniciar la sesión. Si cambias de estilo a mitad de una conversación, Claude no cambiará de comportamiento de inmediato; tendrás que limpiar el chat con /clear (que vimos en el artículo 19 para restablecer la mesa de trabajo) o iniciar una nueva sesión para aplicar el nuevo estilo.
Este detalle suele confundir a los usuarios nóveles: seleccionan Explanatory en /config, regresan al chat y ven que Claude sigue programando sin dar explicaciones, pensando que la opción no funciona. El problema es no haber ejecutado /clear para aplicar la nueva instrucción del sistema. Al ejecutar /clear, el nuevo estilo entrará en funcionamiento. Recuérdalo para evitar frustraciones.
💡 Resumen en una frase: El comando
/output-styleha sido eliminado; los estilos se cambian en el menú/config(se guarda ensettings.local.json) o editandooutputStyleen tu configuración; el cambio requiere ejecutar/clearo iniciar una sesión nueva para aplicarse.
04 Crear un estilo personalizado: Estructura del archivo Markdown
Si las opciones integradas no cubren tus necesidades, puedes crear tu propio estilo. Su diseño es muy sencillo: un archivo Markdown define tu estilo personalizado.
La documentación oficial define su estructura de forma directa:
Un estilo de salida personalizado es un archivo Markdown: el frontmatter define los metadatos y el cuerpo contiene las instrucciones que se añadirán a la instrucción del sistema.
Consta de dos partes: el frontmatter inicial (metadatos delimitados por ---) y el cuerpo del texto (las instrucciones de comportamiento que se sumarán a la instrucción del sistema). Sigue estos tres pasos para crearlo:
Paso 1: Guardar el archivo en la ruta adecuada
Igual que ocurre con otras extensiones (como Skills o Subagents), los estilos de salida se organizan en diferentes niveles jerárquicos, determinando en qué proyectos estarán disponibles:
| Nivel | Carpeta | Ámbito |
|---|---|---|
| Usuario | ~/.claude/output-styles | Disponible para todos tus proyectos |
| Proyecto | .claude/output-styles (en la raíz del repositorio) | Específico de este proyecto; se comparte en git con tus compañeros |
| Administrado | .claude/output-styles (en el directorio administrado) | Distribuido por la organización corporativa |
La lógica de "usuario frente a proyecto" es la misma que vimos para settings en el artículo 31 y para la memoria en el artículo 25: si es un estilo de uso personal para todos tus desarrollos, guárdalo en tu carpeta de usuario (~/.claude/output-styles); si es un estilo específico para las normas de un proyecto que tus compañeros también deben usar, guárdalo en el repositorio (.claude/output-styles) para distribuirlo en git.
Ten en cuenta esta regla de nomenclatura:
El nombre del archivo se convierte en el nombre del estilo, a menos que definas la clave
nameen el frontmatter.
Es decir, si creas el archivo code-reviewer.md, el estilo se llamará code-reviewer, a menos que definas otro valor en el campo name del frontmatter, en cuyo caso prevalecerá este último.
Paso 2: Redactar el frontmatter y el cuerpo de instrucciones
Revisemos el ejemplo oficial de un estilo diseñado para "dibujar diagramas antes de explicar". Lo analizaremos campo por campo:
---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---
When explaining code, architecture, or data flow, start with a Mermaid diagram showing the structure, then explain in prose.
## Diagram conventions
Use `flowchart TD` for control flow and `sequenceDiagram` for request paths. Keep diagrams under 15 nodes.El bloque inicial entre --- es el frontmatter; abajo se detallan las instrucciones (en este caso, pedirle que al explicar arquitectura o flujos empiece mostrando un diagrama Mermaid y luego explique con texto). Estas instrucciones se sumarán al system prompt de Claude, por lo que a partir de ese momento dibujará diagramas en cada una de sus explicaciones de la conversación.
El frontmatter soporta cuatro campos de configuración:
| Campo frontmatter | Función | Por defecto |
|---|---|---|
name | Nombre del estilo | Heredado del nombre del archivo si se omite |
description | Breve descripción que se mostrará en el menú de /config | Ninguno |
keep-coding-instructions | Determina si se conservan las instrucciones de programación nativas de Claude Code | false |
force-for-plugin | Uso para plugins: aplica el estilo automáticamente al activar el plugin | false |
Los dos primeros campos definen el identificador y la descripción para el menú. Los dos siguientes tienen funciones avanzadas; en particular, keep-coding-instructions es la opción del frontmatter donde es más habitual cometer errores, por lo que le dedicaremos la siguiente sección. El campo force-for-plugin se usa en la creación de plugins (que vimos en el artículo 24 para empaquetar y distribuir recursos); permite asociar el estilo al plugin de forma obligatoria y no lo necesitarás en tus estilos personales de uso cotidiano.
Paso 3: Activar tu estilo personalizado
Una vez creado y guardado el archivo, abre la sesión y escribe /config. En el menú de estilos de salida aparecerá tu nuevo estilo con la descripción que configuraste. Selecciónalo y ejecuta /clear para que entre en funcionamiento.
💡 Resumen en una frase: Un estilo personalizado es un archivo Markdown con metadatos en el frontmatter y directrices de comportamiento en el cuerpo; guárdalo a nivel de usuario o de proyecto, selecciónalo en
/configy ejecuta/clearpara aplicarlo.
05 La opción crítica: keep-coding-instructions
El campo keep-coding-instructions del frontmatter merece una explicación detallada, ya que configurarlo de forma incorrecta alterará drásticamente el comportamiento de tu estilo personalizado.
Por defecto, la instrucción del sistema de Claude Code incluye directrices orientadas al desarrollo de software (cómo verificar el código, cómo documentar, delimitar cambios, etc.). Al crear un estilo personalizado, estas instrucciones nativas se eliminan por defecto. Palabras oficiales de la documentación:
Los estilos de salida personalizados omiten las instrucciones de programación nativas de Claude Code... a menos que
keep-coding-instructionsse establezca comotrue.
El valor por defecto es false. Esto significa que, si no configuras esta opción, tu estilo personalizado eliminará por completo las instrucciones nativas de programación, aplicando únicamente las directrices que tú escribas. Para decidir qué valor usar, hazte esta pregunta:
"¿Quiero que Claude siga programando y escribiendo código en este estilo?"
- Sí, quiero que programe pero adaptando su forma de responder (por ejemplo, "programa de forma habitual pero dibuja diagramas en las explicaciones") → Configura
keep-coding-instructions: truepara conservar las directrices nativas de desarrollo de software. Este es el caso del ejemplo "Diagrams first" anterior: Claude debe seguir programando con rigor, por lo que se activa la opción. - No, este estilo no es para programar (por ejemplo, para usarlo como editor de texto, traductor o analista) → No incluyes el campo (dejando que aplique su valor por defecto
false) para eliminar todas las directrices de programación del contexto. Al no programar, reglas como "escribir pruebas unitarias" o "delimitar los cambios en git" solo estorbarían y consumirían contexto innecesariamente.
La recomendación oficial define claramente este criterio:
Consérvalas cuando modifiques la forma de comunicar de Claude pero sigas programando (por ejemplo, si quieres que responda siempre usando diagramas). Elimínalas cuando Claude no vaya a realizar tareas de desarrollo de software (como en estilos de asistente de redacción o analista de datos).
Compara las consecuencias de configurar esta opción de forma incorrecta:
| Objetivo del estilo | Valor recomendado | Consecuencia de configurarlo al revés |
|---|---|---|
| Seguir programando con otro formato (diagramas, estilo de respuesta...) | true (conservar instrucciones) | ❌ Con false: pierde el rigor técnico de la herramienta (pruebas, límites de cambios, control de calidad). |
| No programar (redacción, traductor, consultor...) | Omitir (por defecto es false) | ❌ Con true: intentará estructurar tus textos como código o refactorizarlos, alejándose de la tarea de redacción. |
Volviendo al caso del currículum de la sección 01: la clave es esta. Para esa tarea se busca un rol de redactor de texto, por lo que se debe omitir keep-coding-instructions (permitiendo que sea false por defecto) para eliminar las directrices de desarrollo de software. Esta opción define en la práctica: ¿este nuevo rol conserva las responsabilidades del ingeniero de desarrollo?. Si las conserva, ponla en true; si no, déjala en false.
💡 Resumen en una frase:
keep-coding-instructionsesfalsepor defecto, lo que elimina las directrices de programación nativas; establécelo entruesi Claude debe seguir picando código con este estilo, u omítelo si el rol no implica tareas de desarrollo de software.
06 Funcionamiento en segundo plano: Integración en la instrucción del sistema
Hemos mencionado que los estilos "se añaden a la instrucción del sistema", "se leen una vez al iniciar" y "eliminan las directrices de programación". Analicemos cómo funciona esto en segundo plano. Entender esta mecánica te ayudará a comprender los comportamientos de la herramienta: por qué requiere ejecutar /clear al cambiar de estilo, por qué afecta a cada mensaje y cómo gestiona la opción keep-coding-instructions.
La documentación oficial detalla su funcionamiento en tres principios:
- Todos los estilos de salida añaden sus directrices personalizadas al final de la instrucción del sistema (system prompt).
- El sistema incluye avisos recordatorios durante la conversación para que Claude respete las directrices del estilo.
- Los estilos personalizados eliminan las instrucciones nativas de desarrollo de software de Claude Code, a menos que
keep-coding-instructionsse establezca comotrue.
Principio 1: las directrices de tu estilo se añaden "al final" de la instrucción del sistema. La instrucción del sistema se carga al inicio de la conversación defininedo la identidad base del agente; al sumarse tus directrices al final de este bloque, afectarán a cada uno de los mensajes de la conversación, y no solo a una petición concreta.
Principio 2: el sistema introduce recordatorios periódicos durante la conversación. Con el paso de los mensajes, los modelos de IA pueden perder el foco de las directrices iniciales. Esta medida de seguridad inyecta recordatorios de forma transparente en la conversación para asegurar que Claude mantenga el comportamiento del estilo.
Principio 3: explica el comportamiento de la sección anterior: los estilos personalizados reemplazan las directrices nativas de desarrollo de software por defecto; al establecer keep-coding-instructions: true le indicamos al motor de Claude Code que conserve ese bloque en la instrucción del sistema. Esta opción determina si el bloque de directrices de desarrollo se incluye o se excluye al ensamblar el mensaje base.
Visualicemos cómo se construye la instrucción del sistema:
Al iniciar la conversación, Claude Code ensambla la instrucción del sistema según el estilo elegido: los estilos del sistema y los personalizados con keep=true incluyen el bloque de desarrollo de software; los estilos personalizados con keep=false excluyen ese bloque y solo aplican tus directrices. El resultado se mantendrá activo en toda la conversación; si cambias de estilo a mitad del chat, debes usar /clear o iniciar otra sesión para que el sistema vuelva a realizar el ensamblaje con la nueva configuración (el motivo del error del artículo 03).
Por último, hablemos del consumo de tokens (ver detalles de facturación en el artículo 06). Palabras oficiales de la documentación:
El consumo de tokens varía según el estilo de salida. Añadir instrucciones a la instrucción del sistema incrementa los tokens de entrada, aunque el almacenamiento en caché de prompts (prompt caching) reduce este costo a partir del segundo mensaje de la conversación.
Básicamente: las instrucciones del estilo se suman a la instrucción del sistema, consumiendo algunos tokens de entrada adicionales. Gracias a la tecnología de caché de prompts de Claude (prompt caching), la instrucción del sistema se almacena en memoria y se reutiliza, por lo que este coste se reduce drásticamente tras el primer mensaje, evitando que sea una preocupación. El incremento de gasto real vendrá de los estilos como Explanatory o Learning que generan respuestas más detalladas de forma continua (afectando a los tokens de salida). A mayor extensión de las respuestas de Claude, mayor consumo de tokens de salida. Usa los estilos con criterio.
💡 Resumen en una frase: Las directrices del estilo se suman al final del system prompt, aplicando el comportamiento a cada respuesta y reforzándolo con recordatorios; los estilos personalizados eliminan las directrices nativas de desarrollo de software por defecto (
keep=truepara conservarlas); cambiar de estilo requiere/clearpara volver a ensamblar la instrucción; el impacto en tokens de entrada es bajo gracias a la caché de prompts.
07 output styles frente a CLAUDE.md / Skill / Subagent
Llegados a este punto, te preguntarás: ¿qué diferencia hay entre los estilos de salida y otras herramientas como CLAUDE.md, Skills o Subagents si todas ellas sirven para personalizar el comportamiento de Claude? Analicemos sus diferencias. En el artículo 30 vimos las diferencias enfocadas en las necesidades de desarrollo; aquí nos enfocaremos en sus diferencias estructurales frente a los output styles.
La característica exclusiva de los output styles es que modifican la instrucción del sistema directamente y se aplican a cada respuesta de la conversación. Otras extensiones se añaden como mensajes secundarios o se cargan en momentos específicos. La documentación oficial resume estas diferencias:
| Recurso | Funcionamiento | Cuándo elegirlo (frente a un estilo de salida) |
|---|---|---|
| Output Style | Modifica el system prompt directamente; aplica a cada respuesta | Quieres que actúe de forma permanente con un rol, tono o formato específico. |
| CLAUDE.md | Se añade después del system prompt como mensaje de usuario | Quieres facilitarle convenciones y detalles del repositorio, no cambiar su tono. |
--append-system-prompt | Suma instrucciones al system prompt de la sesión | Quieres añadir una instrucción temporal de forma rápida para una única sesión. |
| Subagent | Utiliza su propio system prompt, modelo y herramientas aisladas | Delegas una tarea específica y pesada a un agente secundario con su ventana de contexto. |
| Skill | Se carga únicamente al ser invocado o coincidir | Tienes un flujo de trabajo reutilizable que se ejecuta bajo demanda. |
La diferencia más importante a asimilar es la de las dos primeras filas: output style frente a CLAUDE.md. Al ser ambas vías para dar directrices a Claude, suelen confundirse. Quédate con esta distinción:
CLAUDE.md almacena "información y contexto"; output style define "el tono, rol y formato". El primero responde a "cómo se desarrolla en este proyecto y qué herramientas usa"; el segundo define "cómo te habla Claude y qué formato de salida utiliza". Retomando la analogía: CLAUDE.md es la guía técnica del proyecto; output style es la descripción de su puesto de trabajo. No metas reglas como "usa pnpm en lugar de npm" en un output style (es una convención de desarrollo, pertenece a CLAUDE.md), ni intentes forzar "dibuja un diagrama en cada explicación" en CLAUDE.md (es una regla de formato, pertenece a un output style). La documentación oficial nos da una directriz clara:
Para instrucciones sobre tu proyecto, convenciones o base de código, edita el archivo CLAUDE.md.
La opción --append-system-prompt modifica el system prompt igual que los estilos, pero de forma temporal frente al carácter persistente de los estilos: --append-system-prompt se pasa como parámetro al iniciar claude y se aplica solo a esa sesión; los estilos se guardan en la configuración y se aplican de forma continua. Si quieres hacer una prueba rápida de tono, inicia la sesión de esta forma:
claude --append-system-prompt "Responde siempre en español y de forma muy concisa"Al cerrar la sesión se perderá la directriz. Si es un estilo que quieres usar a diario, no pases el parámetro cada vez; crea un estilo de salida personalizado. Parámetro para pruebas rápidas; estilo personalizado para configuraciones fijas.
También cabe distinguir los Skills: un Skill es un procedimiento a demanda que no consume recursos de la instrucción del sistema y solo se carga al invocarlo o al coincidir con su descripción; un estilo de salida está siempre activo y se aplica a todas las respuestas del chat. Si buscas programar un flujo para una tarea específica, crea un Skill; si quieres redefinir el tono y comportamiento de Claude en toda la conversación, crea un estilo de salida.
El error de escribir "quiero respuestas breves y directas" en CLAUDE.md se debe a esto. Los cambios de tono y estilo deben gestionarse modificando la instrucción del sistema (output styles) y no a través de las peticiones secundarias de CLAUDE.md. Coloca cada configuración en su herramienta correspondiente.
💡 Resumen en una frase: Los output styles destacan por modificar la instrucción del sistema y aplicarse a cada mensaje; se diferencian de
CLAUDE.mden queCLAUDE.mdcontiene el contexto del repositorio (contenido) y el estilo define el tono y rol (forma); usa--append-system-promptpara directrices temporales de una sesión y Subagents para aislar tareas en contextos secundarios.
08 Práctica: Crear el estilo personalizado "Diagrams first"
Pasemos a la práctica. Crearemos un estilo personalizado que fuerce a Claude a dibujar un diagrama antes de explicar, lo activaremos y comprobaremos su funcionamiento, sin necesidad de contar con un proyecto complejo.
Paso 1: Crear el archivo del estilo personalizado
Lo guardaremos a nivel de Usuario (~/.claude/output-styles) para tenerlo disponible en todos nuestros proyectos. Crea la carpeta y el archivo:
mkdir -p ~/.claude/output-stylesUsa tu editor de texto para crear el archivo diagrams-first.md dentro de ~/.claude/output-styles/ e introduce la siguiente configuración:
---
name: Diagrams first
description: Dibuja un diagrama Mermaid antes de explicar con texto
keep-coding-instructions: true
---
Al explicar código, arquitectura o flujos de datos, incluye siempre primero un diagrama Mermaid que ilustre la estructura, y luego detalla la explicación en texto.
## Convenciones de dibujo
Para flujos de control usa `flowchart TD`; para flujos de peticiones usa `sequenceDiagram`. Limita los diagramas a un máximo de 15 nodos.Establecemos keep-coding-instructions: true porque Claude debe seguir programando con normalidad en este estilo, por lo que conservamos las instrucciones de desarrollo nativas (el criterio de la sección 05).
Paso 2: Activar el estilo en la configuración
Inicia la conversación con Claude Code, escribe /config y accede al menú de estilos de salida para seleccionar tu nuevo estilo Diagrams first.
claudeEscribe /config en la sesión, desplázate hasta la opción de estilos de salida con las flechas, pulsa Enter y selecciona Diagrams first.
Resultado esperado: el menú mostrará la opción Diagrams first con la descripción en español que escribiste. Verlo en la lista confirma que el archivo ha sido detectado correctamente. Si no aparece, asegúrate de haber creado la carpeta en la ruta correcta y de que el frontmatter está bien cerrado.
Paso 3: Limpiar el chat con /clear para aplicar los cambios
Antes de hacer una pregunta, ejecuta /clear para forzar a Claude Code a volver a ensamblar la instrucción del sistema (el detalle que vimos en la sección 03):
/clearPaso 4: Hacer una pregunta para verificar la activación
Haz una pregunta técnica que requiera una explicación para verificar si dibuja el diagrama al principio:
Explica cómo viaja una petición de inicio de sesión de usuario desde el cliente hasta la base de datosResultado esperado: la respuesta de Claude comenzará con un diagrama Mermaid (seguramente un sequenceDiagram que ilustre el flujo cliente → servidor → base de datos) y luego continuará con la explicación en texto. Observar este orden de salida confirma que el estilo personalizado está activo y funcionando.
Como contraste, puedes volver a /config, seleccionar el estilo Default, ejecutar /clear y hacer la misma pregunta: verás que responde directamente con texto sin dibujar ningún diagrama. Esta prueba demuestra cómo el estilo de salida modifica la forma de responder del agente.
Paso 5: Eliminar el archivo de prueba (opcional)
Si no quieres conservar el estilo, elimina el archivo del sistema:
rm ~/.claude/output-styles/diagrams-first.mdEl estilo desaparecerá de las opciones del menú /config (si lo tenías activo, recuerda volver a seleccionar Default en el menú antes de eliminarlo).
Completando estos cinco pasos habrás comprobado el flujo de trabajo de los estilos personalizados: crear el archivo, seleccionarlo, aplicar con /clear, verificar el comportamiento y limpiar. El diseño de cualquier estilo que necesites en el futuro seguirá esta misma estructura.
💡 Resumen en una frase: Practica la creación de un estilo personalizado: crea el archivo
.md→ selecciónalo en/config→ aplica los cambios con/clear→ haz una pregunta para verificar que inicia con el diagrama → elimina el archivo al terminar; comparar su comportamiento frente al estilo Default te ayudará a entender cómo modifica las respuestas.
09 Resumen
En este artículo hemos estudiado en profundidad los estilos de salida (output styles) como herramientas para personalizar el comportamiento y la identidad de Claude Code.
Repasemos los conceptos clave:
| Objetivo | Acción / Configuración | Detalle clave |
|---|---|---|
| Qué son | Modificar la instrucción del sistema | Cambian el tono, rol y formato de respuesta; no añaden conocimientos del repositorio. |
| Estilos del sistema | Cuatro opciones integradas | Default (desarrollo), Proactive (autónomo), Explanatory (explicaciones) y Learning (educativo con tareas). |
| Cómo cambiar de estilo | Menú /config o campo outputStyle | El comando /output-style ha sido eliminado; los cambios requieren ejecutar /clear para aplicarse. |
| Crear estilos propios | Archivo Markdown de configuración | El frontmatter define el nombre y metadatos; el cuerpo detalla el comportamiento del estilo. |
| Decidir sobre directrices de desarrollo | Opción keep-coding-instructions | Ponlo en true si el rol sigue picando código; omítelo (false) si el rol no es de desarrollo. |
| Diferencia con CLAUDE.md | Contenido frente a formato | CLAUDE.md define las convenciones técnicas del código; el estilo define el tono y la forma de responder. |
Ahora deberías ser capaz de: explicar la función de los estilos de salida, seleccionar las opciones integradas según tus necesidades de desarrollo, cambiar de estilo en caliente y aplicar los cambios con /clear, diseñar y estructurar estilos personalizados definiendo correctamente la opción de programación, y establecer los límites de uso de esta herramienta frente a otras como CLAUDE.md o los Skills. Dominar los estilos de salida te permite adaptar la identidad de Claude para que actúe como programador, tutor o redactor según las necesidades de tu desarrollo.
Recuerda organizar cada configuración en su herramienta correspondiente: utiliza CLAUDE.md para las convenciones técnicas del repositorio, y los output styles para redefinir el tono, rol y formato de las respuestas de Claude.
En el próximo artículo, 33 "Hooks (Ganchos)", nos enfocaremos en la automatización del flujo de trabajo. Los estilos de salida definen la forma de hablar de Claude, pero la ejecución de las acciones sigue dependiendo de su evaluación. En la siguiente sección explicaremos una herramienta para garantizar que ciertas acciones se ejecuten siempre ante eventos específicos de forma automática y sin depender del agente (como ejecutar el linter al guardar o bloquear comandos inseguros). Estudiaremos la sintaxis y los eventos de los Hooks que introdujimos en el artículo 30. Piensa en esto: ¿qué acciones manuales repites con frecuencia al programar que te gustaría delegar en un automatismo seguro? Lo analizaremos en el próximo artículo.