Cómo dirigir sesiones largas con Claude Code

El otro día vi que Anthropic había actualizado su curso Claude Code in Action y pensé coño, uso esta cosa a diario y nunca he hecho una formación oficial ni nada parecido.

Así que me puse con el curso, fui tomando apuntes y decidí traer al blog lo que vaya aprendiendo, traducido y contado a mi manera para que lo pueda aprovechar to kiski.

El primer capítulo trata sobre cómo guiar a Claude Code durante sesiones de varias horas. Pedirle una tarea rápida es fácil. Le dices lo que quieres, toca cuatro cosas y revisas el resultado. La cosa cambia cuando tiene que refactorizar un módulo entero, crear una funcionalidad grande o arreglar una batería de tests. Ahí puede pasarse mucho rato trabajando y cuanto más tengas que corregirlo, más larga se hará la sesión.

La idea principal del capítulo se resume en dos cosas muy sencillas. Acotar bien la tarea antes de empezar y corregir el rumbo mientras avanza. Parece obvio, pero buena parte de las liadas vienen precisamente de saltarse una de las dos.

Antes de tocar código, entra en modo plan

Para una errata o un cambio de nombre no hace falta montar una cumbre de la OTAN. Pero cuando la tarea toca a varios archivos o todavía no tienes claro cómo hacerla, hay que empezar en modo plan.

Puedes entrar pulsando Shift+Tab, usando /plan dentro de la sesión o arrancando Claude así.

claude --permission-mode plan

En este modo Claude Code puede leer archivos, buscar por el proyecto y ejecutar comandos de exploración, pero no modifica el código. Primero investiga cómo está montado todo y después te presenta un plan.

Aquí está la parte que a veces da palo, pero que más problemas te va a ahorrar. Hay que leerse el plan.

Yo comprobaría que ha entendido qué queremos conseguir, qué partes del proyecto va a tocar, cómo piensa verificar el resultado y qué cosas deben quedarse como están. Si falta algo, se lo dices y sigue planificando. Corregir tres líneas de un plan cuesta bastante menos que deshacer una refactorización que ha acabado metiendo mano donde no debía.

Cuando el plan esté bien, lo apruebas y Claude empieza a trabajar. Cuanto mejor esté definido el resultado desde el principio, menos probable será que a mitad del desarrollo te meta cuatro goles por la escuadra.

Cuando la conversación empieza a pesar

Las sesiones largas acumulan prompts, respuestas, pedazos de código, salidas de tests y unas cuantas decisiones tomadas por el camino. Todo eso llena la ventana de contexto.

Cuando se acerca al límite, Claude Code compacta la conversación automáticamente. También puedes hacerlo tú antes con /compact. El comando resume el historial, utiliza ese resumen como nuevo contexto y libera espacio para continuar.

El problema es que resumir siempre implica elegir. Una decisión que para ti era super importante tenerla presente puede acabar reducida a una frase ambigua o quedarse fuera. Por eso no conviene lanzar /compact a secas y confiar en la providencia.

Puedes indicarle qué debe priorizar en el resumen.

/compact Céntrate en la implementación del flag --version, las decisiones tomadas y los tests que todavía fallan

Lo que escribas después del comando guía la compactación. Si llevas dos horas con una migración, recuerda conservar el estado actual, las restricciones, los errores pendientes y cualquier decisión que no quieras volver a discutir.

Un buen resumen no necesita guardar cada mensaje. Necesita guardar lo que permita seguir trabajando sin contradecir lo ya decidido.

Rewind cuando Claude se va de paseo

A veces no necesitas explicar otra vez por qué el camino elegido es malo. Lo que necesitas es volver al momento anterior a que comenzara a chochear.

Claude Code crea un punto de control con cada prompt que envías. Si pulsas Escape dos veces con el campo vacío o ejecutas /rewind, se abre un menú con el historial de esos puntos.

Desde ahí puedes recuperar justo la parte que te interesa.

• Restaurar código y conversación devuelve los archivos y el chat al estado de aquel momento. Es la opción de borrón y cuenta nueva.

• Restaurar conversación rebobina el chat, pero conserva los archivos tal como están. Resulta útil cuando el código te vale y lo que quieres rehacer es la explicación o el siguiente paso.

• Restaurar código deshace los cambios en los archivos sin borrar lo aprendido durante la conversación.

• Resumir desde aquí conserva intacta la parte inicial y comprime todo lo ocurrido desde el punto elegido. Viene bien para quitar de en medio una conversación secundaria que no llevó a ninguna parte.

• Resumir hasta aquí comprime la parte inicial y mantiene completos los mensajes más recientes. Es útil cuando la preparación fue larga, pero quieres conservar con detalle la implementación en la que estás metido ahora.

Hay una limitación a tener en cuenta porque los puntos de control registran los cambios hechos por las herramientas de edición de Claude, pero no todo lo que ocurra mediante comandos de terminal, subagentes u otras sesiones. Si un comando borra o mueve archivos, puede que /rewind no sea capaz de recuperarlos.

Por eso los puntos de control son un deshacer rápido, no un sustituto de Git. Los commits siguen siendo los puntos de referencia.

Dejarlo trabajar con un objetivo

Hay tareas en las que es más fácil describir cómo se ve el final que enumerar todos los pasos. Para esos casos está /goal.

/goal todos los tests de src/billing pasan, el chequeo de tipos termina sin errores y no se modifican archivos fuera de ese módulo

El comando establece una condición para finalizar el trabajo y arranca el trabajo. Al terminar cada turno, un evaluador rápido revisa la conversación y decide si la condición ya se cumple. Si todavía no se cumple, Claude Code inicia otro turno y continúa.

La condición debe ser concreta y comprobable. Mejora el código por ejemplo no valdría porque es demasiado abierto a interpretaciones. npm test termina con código 0 y no hay errores de tipado se puede demostrar con la salida de los comandos.

Esto importa porque el evaluador no abre archivos ni ejecuta pruebas por su cuenta. Solo puede juzgar lo que Claude haya dejado reflejado en la conversación. Si quieres que confirme algo, pide también una comprobación cuyo resultado aparezca en el chat.

Un objetivo tampoco cambia los permisos de la sesión. Si una herramienta necesita tu aprobación, Claude seguirá esperándote. /goal evita que tengas que escribir continúa después de cada turno, pero no le da barra libre para hacer cualquier cosa.

Puedes consultar el estado ejecutando /goal sin añadir nada. Si quieres detenerlo antes de que termine, usa este comando.

/goal clear

Loop para esperar acontecimientos

/loop se parece a /goal, pero resuelve otro problema. En vez de trabajar sin parar hasta cumplir una condición, repite un prompt cada cierto tiempo.

Un ejemplo bastante claro es vigilar un despliegue.

/loop 5m comprueba si ha terminado el despliegue y revisa los errores si ha fallado

En este caso la comprobación se ejecuta cada cinco minutos. También puedes omitir el intervalo y dejar que Claude decida cuánto esperar entre una vuelta y la siguiente.

/loop comprueba si la CI ha terminado y corrige los fallos que aparezcan

/goal va bien cuando la pregunta es hemos llegado ya al resultado. /loop es para cuando la pregunta es ha cambiado algo fuera. Una migración, una refactorización o una suite de tests suelen cuadrar mejor con el primero. Una CI, un despliegue o los comentarios nuevos de una pull request cuadran mejor con el segundo.

El bucle vive dentro de la sesión y necesita que Claude Code siga abierto. Para pararlo mientras espera la siguiente ejecución, pulsa Escape.

Un worktree para cada sesión

Si lanzas varias sesiones sobre el mismo directorio, todas pueden editar los mismos archivos. Una puede estar refactorizando una clase mientras otra intenta arreglar un bug en ella. Lo más probable es que terminen pisándose.

Los worktrees de Git permiten tener varios árboles de trabajo del mismo repositorio, cada uno con sus propios archivos y su propia rama. Claude Code puede crear uno y arrancar la sesión dentro con este comando.

claude --worktree refactor-billing

Así puedes dejar una sesión con una funcionalidad y abrir otra para un bug sin que ambas escriban sobre el mismo código. Comparten el historial del repositorio, pero no el directorio de trabajo.

Como el worktree nace de un checkout limpio, los archivos ignorados por Git no aparecen dentro. Esto suele notarse enseguida con .env, configuraciones locales o certificados de desarrollo. Para copiar los que necesites puedes crear un archivo .worktreeinclude en la raíz del proyecto.

.env
.env.local
config/local.json

La sintaxis es la misma que en .gitignore y solo se copian archivos que también estén ignorados por Git.

Al salir de una sesión interactiva, Claude Code comprueba si el worktree contiene cambios. Si está limpio y la sesión no tiene nombre, lo elimina automáticamente. Si hay archivos modificados o commits nuevos, pregunta si quieres conservarlo o borrarlo. No da por terminado un trabajo con cambios y lo manda al carrer sin avisar.

La rutina con la que me quedo

Después de ver el capítulo, mi forma de afrontar una tarea tocha queda bastante clara. Primero entro en modo plan y discuto el enfoque hasta que no haya dudas o ambiguedades. Después dejo que Claude Code ejecute y reviso los cambios importantes.

Si la conversación se hace muy grande, uso /compact diciendo qué debe conservar. Si se empieza a liar el mismo, vuelvo al último punto bueno con /rewind en vez de intentar arreglar veinte mensajes malos con otros veinte mensajes.

Cuando el resultado se puede medir, dejo un /goal bien definido. Cuando dependo de algo externo, tiro de /loop. Y si voy a tener varias sesiones tocando el mismo repositorio, cada una trabaja en su worktree.

No hay ningún comando que convierta una petición vaga en un buen trabajo por la cara. Lo que sí hay son herramientas para pensar antes de tocar, corregir pronto y comprobar al final.

EA! Nos vemos en los bares! 🍻