Las cuatro tareas más comunes: explorar código, arreglar bugs, refactorizar y escribir pruebas
📚 Navegación de la serie: El artículo anterior 15 Cómo preguntar y dar instrucciones te enseñó "cómo hablar" (desglosar una necesidad difusa en instrucciones precisas). Este artículo cambia la perspectiva: el 80% de las tareas diarias recae en solo cuatro categorías, y para cada una te daré una plantilla de instrucciones que puedes copiar directamente y rellenar.
Muchachos, hoy hablaremos de lo más práctico.
Piénsalo, ¿qué haces todo el día frente al código? Básicamente, das vueltas en torno a cuatro cosas: hacerte con un proyecto incomprensible, arreglar un bug misterioso, refactorizar un bloque de código espantoso y añadir pruebas a una función. Claro que hay otras cosas, pero estas cuatro se llevan la mayor parte de nuestro tiempo.
El artículo anterior trataba sobre "técnicas de comunicación" generales, este aterriza en escenarios concretos: estas cuatro tareas tienen patrones estándar, la rutina es fija. Tras usar Claude Code durante un tiempo, lo que queda son cuatro plantillas guardadas en tus notas; cuando surge la necesidad, las sacas y rellenas los huecos.
Digámoslo así: las técnicas generales son la fuerza interior, estas cuatro plantillas son los movimientos de artes marciales. Ya practicaste la fuerza interior, hoy te paso los movimientos.
Al terminar este artículo, tendrás:
- Cuatro plantillas de instrucciones listas para copiar y usar para las tareas más frecuentes (explorar / reparar bugs / refactorizar / escribir pruebas).
- La lógica clave de "por qué se hace así" para cada tarea, para que no memorices plantillas a ciegas.
- Una tarjeta de referencia rápida para las cuatro tareas que puedes guardar y consultar en cualquier momento.
- Un ejercicio práctico completo con resultados esperados (reparar un bug real siguiendo el flujo).
01 Antes que nada: cuatro tareas, cuatro herramientas
Antes de empezar, debes entender la "personalidad" de estas cuatro tareas. Cada una le exige algo completamente diferente a Claude; si te equivocas de enfoque, los resultados caerán en picado.
Analogía: cuatro herramientas en la caja, cada una para lo suyo. Un destornillador es para tornillos y una llave inglesa para tuercas. Si intentas apretar un tornillo con una llave inglesa, será un desastre. Explorar, reparar, refactorizar y probar son como cuatro herramientas diferentes: la clave no es solo "saber usar Claude", sino "saber qué herramienta sacar".
La principal diferencia se reduce a una sola pregunta: ¿Esta tarea modifica tu código?
| Tarea | ¿Modifica código? | Qué hace principalmente Claude | En qué debes fijarte tú |
|---|---|---|---|
| Explorar código | No (solo lectura) | Lee archivos, te explica | ¿Lo que explica es correcto? |
| Arreglar bugs | Sí | Localiza la causa raíz + repara | ¿Encontró la raíz? ¿Añadió pruebas de regresión? |
| Refactorizar | Sí (pero el comportamiento no cambia) | Reescribe de forma equivalente | ¿Cambió el comportamiento al terminar? |
| Escribir pruebas | Añade archivos | Genera pruebas + cubre límites | ¿Cubrió bien los casos límite (edge cases)? |
¿Lo ves? Explorar tiene cero riesgo (solo lee, no escribe), así que puedes preguntar libremente. Arreglar bugs y refactorizar son cirugías, debes pedirle que explique antes de actuar. Escribir pruebas está en un punto intermedio: crea archivos pero no toca el código original, pero debes vigilar que no sea perezoso y solo pruebe los "casos normales".
Recuerda la lógica de esta tabla, y en las siguientes cuatro secciones desglosaremos cómo usar cada "herramienta".
💡 Resumen en una frase: Primero clasifica las cuatro tareas según si "modifican o no el código". Explorar no tiene riesgos, pregunta libremente; las cirugías requieren que explique antes de actuar.
02 Explorar código desconocido: de mayor a menor, pregunta en tres niveles
Empecemos con el escenario más frecuente: te haces cargo de un proyecto totalmente desconocido y tu primera tarea es entenderlo.
¿Cómo se hacía esto antes? Abrías la carpeta, mirabas decenas de directorios en blanco, pinchabas uno por uno, y dos horas después seguías sin entender nada. Ahora ya no: Claude Code usa el directorio actual como espacio de trabajo, puede leer todo el proyecto él solo, y tú simplemente preguntas.
Analogía: cuando llegas a una nueva empresa, no te pones directamente a leer el código de un módulo. Buscas a un veterano y le preguntas en tres niveles. Nivel uno: "¿Qué hace exactamente la empresa, cómo es la arquitectura general?"; Nivel dos: "¿Dónde está el código de pagos?"; Nivel tres: "¿Cómo fluye un pedido desde que se crea hasta que se cobra?". De mayor a menor, del plano a la línea, este es el ritmo estándar de exploración.
Según las demostraciones de la documentación oficial, estos tres niveles corresponden a tres tipos de preguntas:
Dame una visión general de este repositorio de código, cuéntame sus principales patrones arquitectónicos¿En qué archivos está el código responsable de la autenticación de usuarios? ¿Cómo colaboran estos archivos?Rastrea el flujo de inicio de sesión, desde el frontend hasta la base de datosUn hábito seguro es hacer las dos primeras preguntas en el Plan Mode (Modo Planificación). Es decir, antes de empezar, presiona Shift+Tab dos veces para pasar al Modo Planificación (la primera pasa a acceptEdits, la segunda a plan). ¿Por qué? Porque en la fase de exploración solo queremos que lea y nos cuente, no queremos que se emocione y empiece a modificar archivos. En Plan Mode, no tocará tu código fuente, no importa cuánto preguntes.
Por ejemplo, al tomar un proyecto en Go heredado de 30,000 líneas, el primer día puedes hacer esto: primero una "visión general" para saber cuántos servicios tiene; luego localizar "¿dónde está el código de X?"; finalmente, elegir una ruta clave para "rastrear cómo fluye esta petición". En medio día le coges el truco; antes, esto tomaba dos o tres días.
Aquí tienes tu plantilla de exploración, simplemente rellena los espacios:
Acabo de hacerme cargo de este proyecto, ayúdame a empezar rápidamente. En tres pasos:
1. Dame una visión general de la arquitectura, explica los módulos principales y sus responsabilidades.
2. ¿En qué archivos se encuentra el código responsable de [función que te interesa, p. ej. "pago de pedidos"]?
3. Rastrea la ruta de ejecución completa de [un flujo central, p. ej. "creación a pago de un pedido"].
Explícalo para que un principiante lo entienda, y no modifiques ningún código todavía.💡 Resumen en una frase: La exploración tiene un ritmo: desde la arquitectura general hasta archivos específicos y finalmente la ruta de ejecución; pregunta de mayor a menor en tres niveles, es más seguro usar Plan Mode en los primeros dos.
03 Arreglar un bug: error -> raíz -> reparación -> prueba de regresión
Arreglar bugs es la otra tarea frecuente, y la que más a menudo sale mal.
¿Por qué? Porque el error típico de principiante es: pegar el error y soltar un "ayúdame a arreglarlo", y Claude te da una "reparación que hace desaparecer el error". Ojo, "error que desaparece" no significa "problema resuelto": a menudo solo enmascara los síntomas, pero la causa raíz sigue ahí, lista para estallar en cuanto cambien las condiciones.
Analogía: cuando vas al médico con dolor. No entras pidiendo "dame analgésicos". Le explicas "dónde duele, cuándo empezó, qué movimientos lo empeoran", para que el médico primero diagnostique la causa y luego te recete algo. Arreglar bugs es igual: haz que primero encuentre la causa raíz, no dejes que intente calmar el síntoma inmediatamente.
Las mejores prácticas oficiales insisten en una regla de oro que deberías tener enmarcada:
Repáralo y verifica que el build pase. Resuelve la causa raíz, no te limites a ocultar el error.
Así que el proceso correcto para arreglar un bug tiene cuatro pasos ineludibles:
- Pegar error + pasos de reproducción: el mensaje de error completo, el stack trace, y "qué hice para que saltara".
- Que localice la causa raíz: no le dejes modificar nada aún, que explique claramente "por qué falla".
- Darle luz verde para reparar: cuando acierte con la causa raíz, déjale actuar.
- Añadir prueba de regresión: que añada una prueba que reproduzca el bug, para asegurar que no vuelva a ocurrir en el futuro.
El cuarto paso es el que los principiantes más olvidan, pero es el más valioso. La forma genial en que lo plantea la documentación oficial: pide a Claude que "escriba una prueba que falle para reproducir el problema, y luego lo repare". De este modo, tras la reparación la prueba pasará, lo que le pone un "candado" al bug; si en el futuro alguien vuelve a cambiar el código y rompe algo, la prueba saltará de inmediato.
Muchos han sufrido por no hacer esto. Por ejemplo, al arreglar un bug de análisis de fechas, Claude lo reparó rápidamente y, al no ver más errores, se hizo el commit. Dos semanas después, otro colega refactorizó y deshizo el arreglo: el bug resucitó. Como no había pruebas, nadie sabía que esa línea no se podía tocar. Por eso, toda reparación de bug debe llevar su cuarto paso.
Aquí tienes tu plantilla para arreglar bugs:
He encontrado un bug.
Mensaje de error: [Pega el mensaje completo y el stack trace]
Pasos para reproducir: [Qué hice para que saltara, ¿ocurre a veces o siempre?]
Por favor:
1. Primero localiza la causa raíz y explica por qué ocurre el error. No modifiques el código todavía.
2. Dame una propuesta de reparación que resuelva la causa raíz, no te limites a ocultar el error.
3. Tras reparar, añade una prueba de regresión que reproduzca el bug y ejecútala para confirmar que pasa.💡 Resumen en una frase: Reparar bugs requiere cuatro pasos: pegar el error y cómo reproducirlo, buscar la causa raíz, reparar, y por último añadir una prueba de regresión; sin este candado, el bug volverá tarde o temprano.
04 Refactorizar: estado actual -> objetivo -> pequeños pasos -> prueba antes y después
Refactorizar es, de todas, la tarea de mayor riesgo, porque toca "código que no está roto".
Al menos al arreglar un bug hay un indicador claro de que se logró: el error se fue y las pruebas pasan. En la refactorización no lo hay; el objetivo es que "el código sea más limpio, pero el comportamiento no cambie ni una letra". Si el comportamiento cambia, estás introduciendo bugs sigilosamente bajo la excusa de la refactorización, y este es el peor tipo de bug porque nadie probará código "que solo se estaba limpiando".
Analogía: reformar una casa habitada sin que los inquilinos se vayan. Tienes que asegurar que el agua y la luz sigan funcionando; solo estás pintando paredes y arreglando cables. Refactorizar es "reformar con inquilinos": la funcionalidad (la vida de los inquilinos) debe quedar intacta en todo momento.
Por lo tanto, la estrategia segura de refactorización consta de cuatro pasos centrados en "bloquear el comportamiento mediante pruebas":
- Que explique primero la situación actual: asegúrate de que entiende qué hace realmente el código, incluyendo cualquier comportamiento oculto.
- Definir el objetivo de refactorización: ¿Quieres "dividir la función", "usar sintaxis moderna" o "eliminar código duplicado"? Sé específico.
- Cambiar en pequeños pasos: la documentación oficial recomienda explícitamente "refactorizar en incrementos pequeños y testeables". No dejes que borre y reescriba todo de golpe.
- Las pruebas deben pasar antes y después: antes de refactorizar ejecuta las pruebas como línea base, tras refactorizar ejecútalas de nuevo; los resultados deben ser idénticos.
El cuarto paso es la esencia de la refactorización. Si el código no tiene pruebas, el primer paso no es refactorizar, sino añadirlas; úsalas para tomar una foto del "comportamiento actual" y compara la foto tras la refactorización. Esto concuerda con las mejores prácticas oficiales: hay que darle a Claude una forma de verificar su trabajo, si no, que el código "se vea bien" será la única señal, y las refactorizaciones que "se ven bien" son las que más trampas esconden.
De aquí sale una regla de oro estricta: no le pidas a Claude que refactorice directamente código que no está cubierto por pruebas. Imagina que, por rapidez, le pides que refactorice una función de utilidad sin pruebas, y él "optimiza" una rama para casos límite. Esa rama parecía inútil, pero resulta que gestionaba una entrada poco común. Boom, sorpresa en producción. Siempre, añade pruebas antes de refactorizar; será un poco más lento, pero evitará desastres.
Aquí tienes tu plantilla de refactorización:
Quiero refactorizar [nombre de archivo / función].
Objetivo: [Sé específico, p. ej., "dividir en funciones más pequeñas", "actualizar a sintaxis moderna", "eliminar duplicidades"]
Requisitos:
1. Explica primero el comportamiento actual del código, incluyendo casos límite fáciles de ignorar.
2. Si aún no tiene pruebas, primero añade pruebas que cubran el comportamiento actual.
3. Refactoriza en pequeños pasos, manteniendo su comportamiento externo exactamente igual.
4. Ejecuta las pruebas antes y después de la refactorización, y confirma que los resultados son consistentes.💡 Resumen en una frase: La esencia de refactorizar es "el comportamiento no puede cambiar": pide que explique la situación actual, establece el objetivo, avanza con pasos pequeños y bloquea el comportamiento con pruebas antes y después; si no hay pruebas, añádelas primero.
05 Escribir pruebas: céntrate en forzarle a cubrir casos límite
La última categoría: escribir pruebas para el código.
Escribir pruebas es algo que a Claude se le da muy bien: buscará tus archivos de prueba actuales y seguirá el marco y el estilo de aserción que ya usas; se alinea automáticamente, no tienes que enseñarle. Pero hay una trampa importante que debes conocer: si no le indicas lo contrario, por defecto solo probará los "casos normales".
¿Qué significa esto? Por ejemplo, si tienes una función de división, probará "6 dividido por 2 es igual a 3". Es correcto, pero ¿qué pasa si divido por cero? ¿Y si paso un número negativo? ¿Y si paso un null? Estos "casos límite" (edge cases) son donde se esconden los verdaderos bugs y donde las pruebas deberían enfocarse.
Analogía: cuando contratas a alguien para el control de calidad, no le pides solo que haga un "uso normal". Un buen inspector intentará romper las cosas: meterá valores vacíos, muy largos, negativos, caracteres extraños. Los problemas siempre surgen en los bordes, no en el camino principal. El núcleo de redactar pruebas es obligar a Claude a testear esos bordes.
Así que la clave en la plantilla de pruebas es una sola frase: exígele explícitamente que cubra los casos límite. El buen consejo de las mejores prácticas oficiales es ser muy claro sobre "qué función, qué escenario y si hay que usar mock (simulación) o no":
Escribe pruebas para foo.py, cubriendo los casos límite donde el usuario ya ha cerrado sesión. Evita usar mock.
Observa la diferencia entre estas dos formas de pedirlo:
| ❌ Petición ambigua | ✅ Petición precisa |
|---|---|
| "Añade pruebas a esta función" | "Escribe pruebas para la función divide, centrándote en cubrir casos límite: división por 0, números negativos, y entradas no numéricas" |
| Solo prueba la ruta feliz; cobertura engañosa | Cubre las áreas donde de verdad explotaría |
Otro pequeño truco: usa @ para indicarle directamente el archivo objetivo (@src/utils/math.py), así lo leerá entero antes de empezar; es mucho más preciso que decirle con palabras "la función divide en el archivo math". Ya explicamos el uso de la referencia con @, y aquí es muy útil.
Aquí tienes tu plantilla para escribir pruebas:
Escribe pruebas para [nombre de función] en @[ruta del archivo].
Requisitos:
1. Sigue el marco de pruebas y el estilo de aserción existentes en el proyecto.
2. Céntrate en cubrir casos límite: [Enumera los que se te ocurran, p. ej. "entrada vacía, cero, negativos, valores enormes, tipos incorrectos"].
3. Piensa también en otros casos límite que yo no haya mencionado y añádelos a las pruebas.
4. Una vez escritas, ejecútalas, y si alguna falla, repárala hasta que pase.El punto 3 es un truco añadido: haz que busque activamente lagunas. La documentación oficial menciona que Claude puede analizar las rutas de ejecución del código y encontrar casos límite que podrías haber pasado por alto. Siempre deberías incluir esta frase al pedir pruebas; a menudo descubre combinaciones de entradas que ni siquiera te imaginaste, mucho más completo que intentar listarlas tú solo.
💡 Resumen en una frase: Al escribir pruebas, no digas simplemente "escribe pruebas": oblígale de forma explícita a cubrir casos límite (vacíos, cero, negativos, errores de tipo) y pídele que encuentre los que a ti se te escaparon; los casos normales son lo de menos.
06 Manos a la obra: ejecutar un flujo de reparación de bug real
Leer sobre plantillas no basta, tienes que usarlas. Vamos a usar el escenario "Reparar bug" como ejercicio práctico, ya que tiene los cuatro pasos completos; si dominas esto, podrás adaptar fácilmente los otros tres. Aquí te he preparado un pequeño bug intencionado.
Paso 1: Crear un proyecto de prueba con un bug (Mac / Linux)
mkdir bug-demo
cd bug-demo
echo 'def average(numbers):
return sum(numbers) / len(numbers)' > calc.pyUsuarios de Windows: usad mkdir y cd igual, cread calc.py con el Bloc de notas y pegad el código Python de arriba.
Esta función calcula la media y parece correcta, pero si le pasas una lista vacía, explotará por división por cero. Ese es el bug que vamos a arreglar.
Resultado esperado: En la carpeta bug-demo hay un calc.py con la función average.
Paso 2: Iniciar Claude Code
claudeResultado esperado: Pantalla de bienvenida con un campo de entrada en la parte inferior.
Paso 3: Aplicar la plantilla y pegar el error para que repare
En el campo de entrada (aquí ya hemos rellenado la plantilla de la sección 03):
He encontrado un bug.
Mensaje de error: Al llamar a average([]) lanza ZeroDivisionError: division by zero
Pasos para reproducir: Al pasar una lista vacía a la función average en calc.py siempre ocurre.
Por favor:
1. Primero localiza la causa raíz y explica por qué ocurre el error. No modifiques el código todavía.
2. Dame una propuesta de reparación que resuelva la causa raíz, no te limites a ocultar el error.
3. Tras reparar, añade una prueba de regresión que reproduzca el bug y ejecútala para confirmar que pasa.Resultado esperado: Claude te dirá la causa (cuando la lista está vacía, len(numbers) es 0, y divide por 0); luego te propondrá un diff (por ejemplo, retornar 0 o lanzar una excepción más clara si la lista está vacía) y esperará tu aprobación. Una vez que apruebes, creará un archivo de pruebas (como test_calc.py) con una prueba específica para listas vacías.
Paso 4: Aprobar el cambio y observar las pruebas
Acepta el diff ("Yes"). Claude ejecutará la prueba recién creada.
Resultado esperado: Verás resultados similares en la terminal:
test_calc.py::test_average_empty_list PASSED
test_calc.py::test_average_normal PASSEDVer las pruebas pasar = el bug se ha solucionado y tiene un candado. En el futuro, si alguien revierte ese código, la prueba se pondrá en rojo para avisar.
Paso 5: Salir y confirmar el cambio
Sal de Claude (escribe exit o pulsa Ctrl+D) y comprueba:
cat calc.py(En Windows PowerShell usa type calc.py)
Resultado esperado: El archivo calc.py ahora contiene lógica para gestionar listas vacías, y verás un archivo de prueba en el directorio. Coincide con el diff = ciclo completo dominado, ¡enhorabuena!
⚠️ Atención: Si en el paso 3 Claude no escribe una prueba, lo más probable es que hayas omitido el punto 3 de la plantilla. No omitas esa frase: la prueba de regresión es la frontera entre un novato y un experto.
💡 Resumen en una frase: Haz una ejecución manual completa del flujo de reparación de bugs: crea un bug, usa la plantilla para encontrar la causa raíz y repararlo, y verifica la prueba de regresión. Dominar este flujo te preparará para los demás.
07 Resumen
En este artículo hemos agrupado el 80% del trabajo diario en cuatro categorías y te he dado un enfoque fijo y una plantilla copiable para cada una:
| Tarea | Núcleo de la plantilla en una frase | Punto de mayor cuidado |
|---|---|---|
| Explorar código | "Arquitectura general -> Código de X -> Trazar ruta" | Pregunta en tres niveles, los dos primeros en Plan Mode |
| Arreglar bugs | "Pegar error/pasos -> Buscar raíz -> Reparar -> Añadir prueba" | Resuelve la raíz, no ocultes síntomas; nunca omitas la prueba |
| Refactorizar | "Explicar estado -> Objetivo -> Paso a paso -> Pruebas antes y después" | El comportamiento no cambia; añade pruebas si no existen |
| Escribir pruebas | "Escribir pruebas, forzar cobertura vacíos/0/negativos/tipos" | Fuerza explícitamente los casos límite, que él busque los omitidos |
Al terminar deberías poder: Coger cualquier tarea frecuente, sin quedarte en blanco ante el cursor; simplemente sacar la plantilla y rellenarla, sabiendo qué paso pedir a Claude que haga primero y en qué debes fijarte tú. Estas cuatro plantillas son la base de casi todo el trabajo que harás; a medida que te familiarices, verás que incluso tareas complejas son solo combinaciones de estas cuatro rutinas.
Estas cuatro plantillas resisten el desgaste del uso diario: incluso la tarea más llamativa volverá al final a estos patrones.
El próximo artículo es 17 "Imágenes y Multimodal": hasta ahora todo era "teclear comandos", pero algunas cosas son difíciles de explicar con palabras: un pantallazo de error, un diseño UI, un esquema de base de datos. El siguiente artículo te enseñará a alimentar a Claude con imágenes directamente, para que trabaje mirándolas. Piénsalo: ese pantallazo de error confuso, si pudieras lanzárselo sin más, ¿no sería todo más sencillo?