Recetas de Claude Code

Receta: depurar una prueba fallida

Una prueba fallida es una señal reproducible: indica exactamente lo que el código prometía y lo que realmente hizo. Claude Code convierte esa señal en una corrección siguiendo un ciclo de cuatro pasos: Reproducir, Aislar, Corregir, Confirmar.

Reproducir significa ejecutar el comando de prueba para que Claude vea el mensaje de error exacto en contexto. Aislar significa reducir la causa a una sola función, una sola afirmación o una sola suposición incorrecta. Corregir significa cambiar únicamente el código que causó el fallo. Confirmar significa volver a ejecutar la prueba y leer un resultado verde antes de cerrar la tarea.

La disciplina clave es: no le pidas a Claude que corrija nada antes de que haya leído el error. Pega la salida completa de la prueba (el stack trace, es decir, la cadena de llamadas a funciones que condujo al fallo) en tu prompt. Sin él, Claude adivina.

1. Ejecuta tu suite de pruebas y copia la salida del fallo.
2. Abre Claude Code y pega la salida con un objetivo claro.
3. Deja que Claude lea los archivos fuente relevantes y proponga una corrección.
4. Aplica la corrección, vuelve a ejecutar las pruebas y confirma el verde antes de continuar.

Receta: refactorizar con seguridad

Refactorizar significa cambiar la estructura interna del código sin modificar lo que hace desde el exterior. El peligro es una ruptura silenciosa: mueves cosas de lugar y una funcionalidad deja de funcionar sin que nadie lo note. El antídoto es un candado de tests, una suite de pruebas automatizadas que verifica el comportamiento antes de tocar una sola línea de lógica.

La receta tiene tres pasos en un orden estricto:

1. Escribe o genera los tests primero. Pide a Claude Code que lea tu archivo y produzca tests que cubran el comportamiento actual. Haz commit de esos tests. Son tu red de seguridad.
2. Ejecuta los tests en modo vigilancia. Usa /terminal dentro de Claude Code o tu propio shell para mantener el ejecutor de tests activo. Cada vez que Claude modifica un archivo, el ejecutor vuelve a correr y se pone en rojo en cuanto algo falla.
3. Pide a Claude Code que refactorice, una preocupación a la vez. Los cambios pequeños y enfocados facilitan rastrear los fallos. Si un test se pone en rojo, Claude Code puede leer la salida del fallo y corregirlo antes de continuar.

Claude Code lee la salida de los tests automáticamente cuando la pegas o la rediriges a la conversación. Ese ciclo de retroalimentación, escribir el test, refactorizar, leer el fallo, corregir, es lo que hace que el refactoring asistido por IA sea fiable en lugar de imprudente.

Receta: construir una funcionalidad escribiendo primero la prueba

El desarrollo guiado por pruebas (TDD) es un flujo de trabajo en el que se escribe una prueba que falla antes de escribir el código que la hace pasar. El ciclo tiene tres pasos: rojo (la prueba falla), verde (el código pasa la prueba), refactorización (limpiar sin romper la prueba). Claude Code encaja de forma natural porque se puede describir la intención en lenguaje cotidiano y dejar que genere tanto la prueba como la implementación en el orden correcto.

Para empezar, dale a Claude Code una descripción clara de la funcionalidad e indícale explícitamente que escriba la prueba primero. La frase clave es: "escribe una prueba que falle, luego hazla pasar." Sin esa instrucción, Claude suele saltar directamente a la implementación.

Una vez que Claude produce el archivo de prueba, ejecútalo de inmediato. Confirma que está en rojo (fallando) antes de pedirle a Claude que escriba la implementación. Este único punto de control evita el error más común en TDD: escribir una prueba que en realidad nunca estaba comprobando nada.

• Rojo: Claude escribe la prueba, la ejecutas y falla.
• Verde: Claude escribe el código mínimo para que la prueba pase.
• Refactorización: Pide a Claude que elimine duplicados o mejore los nombres, luego vuelve a ejecutar.
• Repetición: Agrega la siguiente prueba para el siguiente comportamiento.

Receta: revisar una pull request

Una pull request (PR) es una propuesta para fusionar un conjunto de cambios de codigo en un proyecto. Los cambios se presentan como un diff (abreviatura de diferencia): una vista archivo por archivo que muestra las lineas eliminadas en rojo y las lineas agregadas en verde. Leer un diff con atención es como se detectan los bugs y la lógica poco clara antes de llegar a producción.

Claude Code puede leer un diff y actuar como un segundo revisor. Se le indica una rama o una URL de PR, y señala problemas en varias dimensiones:

• Bugs de corrección: errores de lógica, errores por uno, casos límite no manejados.
• Problemas de claridad: nombres de variables que confunden, comentarios faltantes en código no obvio.
• Regresiones: cambios que rompen silenciosamente el comportamiento existente cubierto en otra parte del código.
• Señales de seguridad: secretos codificados, entradas de usuario sin verificar, uso inseguro de dependencias.

La habilidad /code-review dentro de Claude Code orquesta esto automáticamente. Lee los cambios en el área de preparación o el diff de una rama especificada, ejecuta el análisis y devuelve hallazgos estructurados. Se controla la profundidad con un parámetro de esfuerzo: --effort low para un pase rápido, --effort high para una cobertura más amplia que incluye hallazgos inciertos. Se agrega --comment para publicar los hallazgos directamente como comentarios inline en GitHub, o --fix para aplicar correcciones seguras al árbol de trabajo.

Receta: construir una funcionalidad de principio a fin

Una construcción de funcionalidad abarca todo el recorrido, desde una solicitud en lenguaje común hasta un cambio funcional y probado confirmado en su repositorio. Claude Code gestiona cada paso, pero se obtienen mejores resultados cuando se estructura ese recorrido de forma deliberada.

La receta tiene cuatro fases:

1. Alcance. Abra Claude Code en la raíz de su proyecto y describa lo que quiere en una frase clara. Pídele que liste los archivos que va a modificar antes de escribir nada: /plan o simplemente diga "lista los archivos que vas a cambiar y por qué, luego espera mi aprobación."
2. Implementación. Apruebe el plan y deje que Claude Code escriba el código. Observe las llamadas a herramientas en el terminal. Si alguna parece incorrecta, escriba /stop para interrumpir sin perder el contexto.
3. Verificación. Pida a Claude Code que ejecute las pruebas o el linter correspondientes: run the tests for this module and show me the output. Para un cambio de interfaz, use el skill /run o pídele que inicie el servidor de desarrollo y describa qué hay que comprobar.
4. Commit. Una vez que las pruebas pasen, pida a Claude Code que agregue solo los archivos modificados al stage y redacte un mensaje de commit. Revise el diff que muestra antes de confirmar.

Dos hábitos que evitan retrabajos: lea siempre el plan antes de aprobarlo, y ejecute siempre las pruebas dentro de Claude Code en lugar de confiar únicamente en una inspección visual.

Receta: corregir un error de forma sistematica

Ir directo a una corrección sin entender la causa raíz es la forma más rápida de crear dos errores en lugar de uno. El enfoque sistemático obliga a aplicar el principio diagnóstico primero, parche después. Claude Code apoya esta disciplina mediante un conjunto de comandos que leen, rastrean y prueban antes de tocar cualquier código.

El flujo de trabajo tiene cuatro fases. Reproducir: confirmar que el error es real y está aislado. Rastrear: encontrar la línea exacta y el motivo del fallo. Formular una hipótesis: enunciar una causa específica antes de escribir cualquier corrección. Verificar: volver a ejecutar las pruebas después del parche para confirmar que el síntoma desapareció y que no surgió nada nuevo (esto se denomina prueba de regresión).

El skill /systematic-debugging de Claude Code impone este orden. También puede ejecutarse manualmente con prompts sencillos. En cualquier caso, la regla clave es: no acepte un parche que Claude proponga a menos que también explique por qué ocurrió el error.

• Comience con: what is the root cause of this error?, no con fix this error.
• Pida a Claude que muestre la pila de llamadas (la cadena de funciones que condujo al fallo) antes de sugerir un cambio.
• Solicite una reproducción mínima: el fragmento de código más pequeño que todavía desencadena el error.
• Después del parche, ejecute claude --print "run the existing test suite and report any failures" para detectar regresiones.

Receta: migrar o actualizar una dependencia

Una dependencia es una biblioteca externa de la que depende su proyecto (por ejemplo, un formateador de fechas o un cliente HTTP). Actualizarla implica cambiar un número de versión, corregir cada ruptura y confirmar que la aplicación sigue funcionando. Claude Code convierte esa tarea de múltiples pasos en una conversación guiada.

La receta tiene cuatro etapas:

1. Planificar: pida a Claude Code que lea la versión actual, consulte el changelog y liste los cambios incompatibles que afectan a su código.
2. Cambiar: déjelo editar package.json (o el manifiesto correspondiente) y ejecutar el comando de instalación.
3. Ejecutar: lance su build y su suite de pruebas para que los errores aparezcan de inmediato.
4. Verificar: revise el diff, confirme que las pruebas pasan y realice una prueba rápida de la funcionalidad afectada.

Dado que Claude Code puede leer archivos, ejecutar comandos de shell e iterar en una sola sesión, detecta errores en cascada (donde corregir un import rompe otro) sin que usted tenga que cambiar entre pestañas de terminal. Haga siempre un commit de su código antes de empezar para tener un punto de retroceso limpio.

Receta: familiarizarse con una base de código desconocida

Cuando abres una base de código que nunca has visto antes, lanzarte directamente a editar es la forma más rápida de romper las cosas. El movimiento profesional es mapear el territorio primero: entender qué existe, dónde están los puntos de entrada y, solo entonces, actuar. Claude Code puede hacer la mayor parte de este trabajo por ti en una sola sesión.

Comienza con un reconocimiento general. Pide a Claude Code que describa la estructura del proyecto, liste los directorios principales e identifique los puntos de entrada (los archivos donde comienza la ejecución, como index.js, main.py o app.ts). Luego pídele que encuentre los archivos de configuración clave: gestores de paquetes (package.json, pyproject.toml), plantillas de entorno (.env.example) y definiciones de CI (.github/workflows/).

Una vez que tienes un mapa mental, lo más valioso que puedes hacer es escribir un archivo CLAUDE.md en la raíz del proyecto. Este archivo de texto plano es leído automáticamente por Claude Code al inicio de cada sesión. Actúa como un briefing permanente: le dice a Claude Code cómo construir el proyecto, qué comandos evitar, qué directorios importan y las convenciones del equipo. Sin él, cada nueva sesión empieza desde cero.

Un buen CLAUDE.md cubre cuatro cosas:

• Comandos de build y ejecución: cómo instalar dependencias e iniciar la aplicación.
• Comando de pruebas: el comando único que ejecuta la suite de pruebas completa.
• Notas de arquitectura: qué carpetas se ocupan de qué responsabilidad (capa API, capa UI, capa de base de datos).
• Reglas de restricción: archivos o patrones que Claude Code nunca debe modificar sin permiso explícito.

Receta: generar y mantener documentación

Una documentación que diverge del código es peor que ninguna documentación: genera confusión. La solución es tratar los docs como un artefacto de compilación, generado y actualizado por Claude Code cada vez que el código cambia. La idea central es el docs-as-code: el README, la referencia de API y los changelogs viven en el repositorio y se regeneran bajo demanda.

Claude Code puede leer toda la base de código en una sola pasada y producir documentación precisa y estructurada. Las opciones clave son --print (modo no interactivo, redirige la salida a un archivo) y --allowedTools "Read,Write" (restringe a Claude a leer el código fuente y escribir docs, nada más). Ajuste siempre el prompt de forma precisa: indique los archivos que se deben leer y el archivo que se debe escribir.

Para la sincronización continua, dos enfoques funcionan bien:

• Git hook: un hook pre-commit ejecuta claude --print e indexa automáticamente el archivo de documentación actualizado, de modo que los docs nunca se confirmen con retraso.
• Paso en CI: un paso de GitHub Actions u otro pipeline regenera los docs en cada fusión a main y abre una pull request si algo cambió.
• Actualización específica: tras editar un módulo concreto, ejecute Claude Code limitado a ese archivo para mantener el costo y la latencia bajos.
• Generación de changelog: pase la salida de git log --oneline directamente en el prompt y pida a Claude que produzca una sección de changelog legible por humanos.

El identificador de modelo para las tareas de documentación habituales es claude-sonnet-4-6: rápido y suficientemente preciso para salida estructurada. Reserve claude-opus-4-8 para la documentación a nivel de arquitectura que requiere un razonamiento profundo sobre las decisiones de diseño.

Receta: automatizar una tarea repetitiva

Una tarea repetitiva es cualquier operación que realizas más de dos o tres veces con la misma estructura: renombrar un lote de archivos, convertir un informe a otro formato, obtener datos de una API y darles formato, limpiar registros. Estas son candidatas ideales para la automatización con Claude Code.

El primer paso es identificar el patrón. Pregúntate: ¿qué entradas cambian cada vez y qué permanece fijo? La parte fija se convierte en el script; la parte variable se convierte en un parámetro (una entrada variable que pasas). Claude Code puede escribir, ejecutar y refinar ese script en una sola conversación.

El segundo paso es capturar la receta para no tener que escribirla desde cero nunca más. Claude Code te ofrece dos opciones:

• Un archivo script: un script de Node, Python o shell guardado en tu proyecto que invocas con un solo comando cada vez que lo necesitas.
• Una slash-command (skill): un archivo markdown breve colocado en ~/.claude/skills/ que se convierte en una /tu-comando que puedes activar en cualquier sesión futura.

Una vez que la receta existe, ejecutar la tarea no te cuesta más que un solo comando. Claude Code lee el script, confirma los parámetros y ejecuta, proporcionándote un registro que puedes revisar antes de que se modifique cualquier archivo.

Receta: escribir y ejecutar un script de un solo uso

A veces necesitas un script desechable: un pequeño programa que realiza una tarea concreta en este momento y que nunca volverás a necesitar. Algunos ejemplos son renombrar 200 archivos, analizar un CSV o consultar una API para obtener datos. Escribirlo a mano es lento. Claude Code puede escribirlo y ejecutarlo por ti en una sola operación.

La receta tiene tres pasos. Describes la tarea en lenguaje común, Claude Code genera el script (generalmente un archivo corto de Node.js o Python) y luego lo ejecuta de inmediato. Obtienes el resultado sin abrir ningún editor de texto.

Aspectos clave que debes incluir en tu solicitud para que Claude Code lo haga bien a la primera:

• Entrada: ¿qué datos o archivos debe leer el script? Proporciona un ejemplo real si puedes.
• Salida: ¿cómo debe verse el resultado? ¿Una lista impresa, un archivo nuevo, un número?
• Entorno: ¿Node.js (CommonJS con require) o Python? Si no lo indicas, Claude Code elegirá según lo que esté disponible.
• Eliminación: di "ejecútalo y elimínalo" si no quieres conservar el archivo.

Claude Code escribe el archivo en una ruta temporal, lo ejecuta, te transmite la salida en tiempo real y puede eliminar el archivo automáticamente. Sin archivos residuales, sin limpieza manual.

Receta: explicar código confuso

Cuando abres un archivo desconocido y la lógica es opaca, Claude Code puede recorrértelo línea por línea. La clave es proporcionar suficiente contexto: el archivo, la sección específica y lo que ya sabes (aunque sea "nada").

El camino más rápido es la sintaxis at-mention. En el panel de chat de Claude Code, escribe @nombrearchivo para adjuntar un archivo directamente a tu mensaje. Claude lo explica entonces con visibilidad completa sobre el código fuente real, no sobre un fragmento que quizás hayas recortado.

Para una explicación concreta, acota la solicitud a una función, una clase o incluso una sola expresión. Las solicitudes amplias ("explica todo este repositorio") producen respuestas amplias. Las solicitudes enfocadas producen respuestas accionables.

• Mención @archivo: adjuntar el archivo fuente para que Claude lo lea directamente
• Rango de líneas: preguntar sobre las líneas 42-67 si el resto está claro
• Analogía: agregar "explica con una analogía del mundo real" para lógica abstracta
• Modo glosario: pedir a Claude que defina cada término desconocido que use en la explicación