Claude Code no solo escribe tu código, te lo explica

TL;DR El estilo Explanatory hace que Claude Code intercale "Insights" mientras programa: por qué usa ese patrón, qué hace ese framework por debajo, qué decisión tomó y a cambio de qué. Lo enciendes con /config → Output style. Y si estás aterrizando en un repo que no conoces, fíjalo al proyecto (.claude/settings.local.json) para que te lo explique en cada sesión sin reactivarlo. Cuesta más tokens de salida (respuestas más largas por diseño), así que vuelve a Default cuando ya te muevas solo.

Aterrizas en un repo que no escribiste tú. Miles de líneas, un framework que casi no tocas, patrones que alguien decidió hace dos años y nadie documentó. Claude Code te resuelve la tarea, sí, pero tú sigues sin entender por qué el código es así. Hay un estilo de salida pensado justo para eso, y lo recomienda el propio creador de Claude Code: enciende Explanatory cuando estés cogiendo confianza con un codebase nuevo, y Claude te va explicando los frameworks y los patrones a medida que trabaja.

Qué es el estilo Explanatory

Un output style modifica el system prompt de Claude Code: cambia el rol, el tono y el formato de sus respuestas, no lo que sabe. Explanatory es uno de los cuatro estilos de serie (Default, Proactive, Explanatory, Learning). Su gracia: intercala bloques "Insight" entre los pasos de la tarea. No para el trabajo para darte una clase; suelta la explicación justa cuando toca una pieza que no es obvia (un patrón raro, un detalle del framework, un compromiso de arquitectura) y sigue.

Qué ves en pantalla

★ Insight ─────────────────────────────────
En SSR, Vue ejecuta el setup() completo de cada componente en
Node para producir el HTML; solo onMounted y los handlers quedan
sin ejecutar. Regla práctica: cualquier expresión en el cuerpo del
setup se evalúa también en el servidor.
────────────────────────────────────────────

Eso aparece intercalado en lo que Claude va haciendo, no en un chat aparte. Aprendes el repo mientras el trabajo avanza, sin salir a buscarlo tú.

Cómo se enciende

1. Actívalo en la sesión

/config → Output style → Explanatory. (El viejo comando /output-style se eliminó en la v2.1.91; si lo buscas, no está.) El cambio es parte del system prompt, que Claude lee al arrancar, así que aplica tras /clear o en una sesión nueva.

2. Fíjalo al repo que estás aprendiendo

Aquí está el movimiento que casi nadie hace. En vez de reactivarlo cada vez, déjalo puesto en el proyecto:

// .claude/settings.local.json  (tu ajuste local, no se commitea)
{ "outputStyle": "Explanatory" }

Así, cada sesión que abras en ese repo arranca ya en modo tutor. Y si quieres que todo el equipo que aterrice en el proyecto lo herede (onboarding), pon la misma línea en .claude/settings.json, que ese sí se commitea.

3. Sube un nivel con Learning

Si no quieres solo que te lo expliquen sino aprender haciendo, el estilo Learning hace lo mismo que Explanatory y además te pide que escribas tú las piezas clave: deja marcadores TODO(human) en el código para que los completes y sigue desde ahí. Es el modo para interiorizar un patrón, no solo para verlo pasar.

Ojo con el coste

Explanatory y Learning generan respuestas más largas por diseño, así que gastan más tokens de salida que Default. Vale la pena mientras aprendes; cuando ya te mueves solo por el repo, vuelve a Default y te ahorras el peaje. Y recuerda que el output style se lee al arrancar la sesión: cambiarlo a media sesión no aplica hasta el siguiente /clear o una sesión nueva, otra razón para dejarlo fijado en el proyecto en vez de ir tocándolo.

Referencia

Y ojo si en vez de un estilo de serie te montas el tuyo propio: un output style custom borra las instrucciones de ingeniería de Claude salvo que lo evites con una línea de frontmatter. Lo cuenta este tip. Para el contexto y las convenciones del propio proyecto, eso no va en el output style: va en tu CLAUDE.md.

Documentación oficial: Output styles