Category: Blog

Un lunes por la mañana abrí la terminal en la raíz de un monorepo, escribí "arregla el checkout, está fallando en producción" y me fui a por un café.

Volví a los veinte minutos. Claude Code había tocado catorce archivos, había reescrito medio servicio de notificaciones que no tenía nada que ver con el bug y había dejado la suite en rojo por sitios nuevos. Novecientas líneas de diff. Tardé más en revisar aquello que lo que habría tardado en arreglar el bug a mano.

La lectura fácil es "la IA todavía no está para esto". La honesta es otra: le di a un agente autónomo un objetivo ambiguo, un repositorio entero y ninguna forma de avisarme de que se estaba perdiendo. Lo raro habría sido que saliera bien.

Desde entonces trabajo con él todos los días. Y lo que ha cambiado no son los prompts. Ha cambiado la forma del día: cómo arranco la sesión, qué le suelto entero, dónde pongo los límites y cuándo la corto. Este post es el mapa de ese flujo: cómo usar Claude Code un día entero de trabajo real, desde que arrancas la sesión hasta que la cierras. Cada pieza tiene después su propio post con el detalle.

Qué es Claude Code y por qué no es un chat que escribe código

Un chat te devuelve texto. Un agente ejecuta.

Claude Code es el agente de codificación de Anthropic que corre en la terminal: lee los archivos de tu proyecto, ejecuta comandos, lee la salida real y vuelve a intentarlo hasta cumplir el criterio que le diste. No es un autocompletado ni un chat con contexto del repositorio: es un proceso que actúa sobre tu disco, tu git y a veces tu infraestructura.

Eso cambia dos cosas de golpe. La primera: el contexto deja de ser gratis, porque cada archivo que lee entra en la ventana y se queda ahí compitiendo con lo que de verdad importa. La segunda: cada acción tiene consecuencias en tu disco, en tu git y a veces en tu infraestructura.

Un compañero de turno necesita tres cosas para no estorbar: saber dónde trabaja, saber qué puede tocar y saber cuándo parar. Lo demás es decoración encima de eso.

Los tres primeros minutos de la sesión

Aquí se decide el resto. La mayoría de las sesiones que se van al garete estaban perdidas antes del primer prompt.

Arranca donde trabajas, no en la raíz. El directorio desde el que lanzas claude determina qué ficheros CLAUDE.md se cargan —Claude Code sube por el árbol de directorios desde donde arrancas y los concatena— y qué rutas puede editar sin pedirte permiso extra. Abrir en la raíz de un monorepo para tocar un solo módulo es empezar con ruido. Si necesitas acceso puntual a otra carpeta, --add-dir te la añade sin mover la sesión.

Arrancar acotado tiene un segundo efecto: lo que queda fuera del árbol de la sesión no entra en la ventana, y ahí viven los .env, los dumps y los logs que no quieres que se lean ni acaben citados en un commit.

Comprueba qué se ha cargado de verdad. /context te enseña en qué se está yendo la ventana y qué ficheros de memoria han entrado. Es el primer sitio donde mirar cuando Claude ignora una regla que juras haber escrito: si el archivo no aparece ahí, no la ha leído. Punto.

Ten un CLAUDE.md que sirva. /init genera uno inicial leyendo el proyecto, pero la versión buena la construyes tú. La regla que uso: si me oigo corregir lo mismo por segunda vez, deja de ser una corrección y pasa a ser una línea del archivo. Cómo estructurarlo para que no acabe siendo un vertedero de cuatrocientas líneas —que es lo que reduce la adherencia, no lo que la mejora— lo desarrollé en CLAUDE.md para proyectos.

Un matiz que ahorra frustración: CLAUDE.md es contexto, no configuración. Pide, no impone. Para que algo sea imposible hace falta otra pieza, y llegamos a ella al final.

Arranca en modo plan si la tarea no es trivial. Shift+Tab cicla entre los modos de permisos: manual, aceptar ediciones y modo plan. En modo plan investiga y te propone un plan sin tocar el código: solo edita cuando lo apruebas. Para planificar un prompt suelto, prefíjalo con /plan.

Leer quince líneas de plan cuesta treinta segundos. Ese es el precio de no repetir el diff de novecientas líneas del principio de este post.

Qué le delego entero y qué no

La frontera no es "tareas fáciles contra tareas difíciles". Es reversibilidad y verificabilidad: si puedo comprobar el resultado con un comando y deshacerlo con un git, va entero. Si el coste del error se paga dentro de seis meses, lo conduzco yo.

Esa tabla no sale de ningún framework. Sale de haberme equivocado en las dos direcciones. Si quieres el criterio completo para decidir de qué lado cae una tarea, lo desglosé en clasificar tareas con IA.

Delega el ciclo, no el snippet

Esto es lo que más separa a quien va rápido de quien se pelea.

Pedir "escríbeme una función que valide el email" es usar un agente como un autocompletado caro. La unidad de trabajo no es la función. Es el ciclo.

Un encargo bien montado lleva cuatro cosas: objetivo, criterio de éxito comprobable, límites y comandos permitidos.

Migra src/billing para quitar la dependencia de legacy-lib.
Los tests de billing tienen que seguir pasando: ejecuta npm test -- billing y corrige hasta que estén en verde.
No toques src/auth ni las migraciones de base de datos.
Cuando esté verde, resume en cinco líneas qué has cambiado y por qué.

La pieza que hace el trabajo ahí es el criterio de éxito. "Que funcione" no es un criterio. "Que npm test -- billing pase" sí, porque el agente puede ejecutarlo, leer la salida real y volver a intentarlo sin ti en medio. Ese bucle es el valor de la herramienta.

Cuando el encargo es más grande que un ciclo —una feature entera, no una migración— el prompt se queda corto y necesitas una especificación escrita antes de tocar código. Es la metodología que desarrollo entera en el libro de Spec-Driven Development: el agente no falla por falta de inteligencia, falla por falta de contrato.

Qué hago cuando Claude Code se atasca

Este es el momento que decide si el día te cunde o lo tiras.

La señal es siempre la misma. Tres intentos, el test sigue rojo, las disculpas se repiten y las soluciones giran en círculo: toca el mismo archivo, lo revierte, lo vuelve a tocar.

Cuando pasa eso, el problema ya no es el prompt. Es el contexto: la conversación está llena de intentos fallidos y cada intento nuevo se construye encima de esa basura.

Insistir es la reacción natural y es la equivocada. Lo que funciona es rebobinar.

/rewind —o Esc dos veces con el input vacío— abre el menú de puntos de la sesión y te deja restaurar el código, la conversación o las dos cosas. Volver al mensaje anterior al desvío y reformular la tarea con lo que acabas de aprender resuelve más bugs que cualquier prompt heroico.

Dos limitaciones antes de que te confíes: los cambios que hizo un comando de bash (rm, mv, cp) no se revierten, y las ediciones que aplicó un subagente tampoco. Para eso está git. El checkpoint es un "deshacer" de sesión, no control de versiones.

Si el atasco viene de haber cambiado de tarea sin darte cuenta, la herramienta es otra: /clear para empezar limpio y /compact para comprimir lo hablado. Arrastrar una conversación entera hacia una tarea que no tiene nada que ver es la forma más silenciosa de degradar los resultados, y está en la lista corta de errores comunes con Claude Code que veo una y otra vez.

Y si la tarea es larga por naturaleza —una investigación que va a leer treinta archivos—, no la hagas en tu ventana. Delégala a un subagente, que trabaja en su propio contexto y te devuelve solo la conclusión.

El cierre de sesión: la parte que casi nadie hace

Casi todo el mundo cierra la terminal cuando el test se pone verde. Ahí se pierde la mitad del valor.

Reviso el diff completo. Yo, con git diff, no un resumen escrito por el agente que acaba de hacer los cambios. Para diffs grandes lanzo /code-review antes de mirarlo: es rápido detectando lo mecánico —el error tragado, el caso borde sin cubrir, el any que se coló— y me deja la cabeza para lo que requiere criterio. Cómo montar esa revisión para que produzca señal y no ruido lo desarrollé en code review agéntico.

Miro qué he corregido a mano. Si he tenido que decir "aquí validamos con Zod, no con yup", falta una línea en el CLAUDE.md. Claude Code también toma notas por su cuenta y las conserva entre sesiones, pero lo que quiero que se cumpla siempre lo escribo yo. La diferencia entre lo que anota él y lo que escribes tú, y cómo se comporta en sesiones largas, está en CLAUDE.md, memoria y contexto en un flujo real.

Y cierro la sesión. En serio. Ocho horas arrastrando cuatro tareas distintas rinden peor que cuatro sesiones limpias, y encima cuestan más.

Cuándo dejas de escribir prompts y empiezas a construir el entorno

Llega un punto en el que te oyes repitiendo las mismas instrucciones. Ese es el aviso: el trabajo ya no es escribir mejores prompts, es configurar el entorno para no tener que escribirlos.

Un skill es un SKILL.md con un procedimiento, y su cuerpo solo se carga cuando se usa, al revés que CLAUDE.md, que entra entero en cada sesión. Lo que es un procedimiento va a un skill; lo que es un hecho va a CLAUDE.md: crear un skill en Claude Code.

El hook es la única pieza que se cumple sí o sí. CLAUDE.md pide; el hook impone. Si tienes una regla que no puede saltarse nunca —no tocar producción, no commitear sin formatear—, eso es un PreToolUse, no un "IMPORTANTE" en mayúsculas dentro del CLAUDE.md: hooks y guardrails.

Y por encima están las routines: esa misma configuración ejecutándose sola en la nube de Anthropic, por horario, por API o por eventos de GitHub. En research preview a agosto de 2026, trátalas como tal, pero marcan el salto de "asistente que abro" a "trabajo que ocurre mientras duermo".

Lo que haría yo mañana

No montes el sistema entero de golpe. No funciona así y además no lo vas a mantener.

Mañana, antes del primer prompt, dedica tres minutos:

1. Lanza claude en la carpeta del módulo que vas a tocar, no en la raíz del monorepo.
2. Ejecuta /context y comprueba que tu CLAUDE.md aparece entre los ficheros de memoria.
3. Añade al CLAUDE.md la única cosa que corregiste a mano ayer.
4. Arranca en modo plan con Shift+Tab y lee el plan antes de aprobarlo.

Ese es todo el cambio del primer día.

Cuando eso sea automático, añade la siguiente pieza: un skill para el procedimiento que repites, un hook para la regla que no puede saltarse, un subagente para la investigación que te llena la ventana.

Si quieres ver este flujo aplicado a un producto real de principio a fin, es lo que construimos en el curso Construye con IA. Y si prefieres ver cómo trabaja gente que ya lo tiene integrado en su día a día, esa conversación pasa en Dominicode Labs.

Entre agosto de 2025 y agosto de 2026 la herramienta ha cambiado más que tu forma de usarla. Ahí está casi toda la diferencia.

Preguntas frecuentes

¿Cuánto contexto le doy a Claude Code al empezar una sesión?

El mínimo que le permita hacer la tarea. Arranca en la carpeta del módulo en el que vas a trabajar, no en la raíz del monorepo, y usa --add-dir si necesitas acceso puntual a otro directorio. Después ejecuta /context para ver qué se ha cargado realmente: si tu CLAUDE.md no aparece en la lista de ficheros de memoria, Claude no lo está leyendo y ninguna de tus reglas está en juego.

¿Qué hago cuando Claude Code se atasca y repite el mismo error?

Deja de insistir. Si lleva tres intentos con el mismo fallo, el problema es el contexto contaminado por los intentos anteriores, no el prompt. Usa /rewind (o Esc dos veces con el input vacío) para volver al punto anterior al desvío y reformula la tarea con lo que has aprendido. Ten en cuenta que el rewind no revierte los cambios hechos por comandos de bash ni las ediciones de un subagente: para eso necesitas git.

¿Pongo la regla en CLAUDE.md o en un hook?

Depende de si es una guía o una ley. CLAUDE.md se carga como contexto: Claude lo lee y trata de seguirlo, pero no hay garantía de cumplimiento estricto, sobre todo si el archivo es largo o tiene instrucciones que se contradicen. Un hook se ejecuta en un evento del ciclo de vida y bloquea la acción decida lo que decida el modelo. Convenciones y estilo, a CLAUDE.md. Cosas que no pueden pasar nunca, a un hook.

¿Es seguro dejar que ejecute comandos sin confirmar cada uno?

Depende del modo de permisos y del entorno. El modo manual pregunta antes de cada acción que no sea de lectura. El de aceptar ediciones va más lejos de lo que sugiere su nombre: además de las ediciones de archivo, aprueba comandos de sistema de ficheros —mkdir, touch, mv, cp, sed y también rm— sobre rutas dentro de tu directorio de trabajo. Ese rm se ejecuta sin preguntarte y /rewind no lo deshace. El modo plan investiga sin editar. El modo auto ejecuta con un clasificador aparte que revisa cada acción y bloquea lo que se sale de lo que pediste. Y el que salta todas las comprobaciones, bypassPermissions, solo tiene sentido dentro de un contenedor o una VM aislada, nunca sobre tu máquina de trabajo.

¿Claude Code sirve para proyectos grandes o solo para cosas pequeñas?

Sirve para proyectos grandes, pero cambia lo que tienes que preparar. En un repositorio pequeño te vale con arrancarlo y hablar. En un monorepo necesitas CLAUDE.md por zona, reglas con paths para que solo se carguen cuando toca, y subagentes para que la exploración no llene la ventana principal. El tamaño del proyecto no limita la herramienta: limita cuánto puedes improvisar antes de configurarla.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.