Tutorial de Claude Code: configuración, refactorización y depuración en la práctica

¿Qué es Claude Code?

Claude Code es una herramienta que funciona directamente en tu terminal, entiende tu base de código y te asiste en tareas de desarrollo mediante comandos en lenguaje natural. Se integra con tu entorno de desarrollo con una configuración mínima, para que te centres en escribir y mejorar código.

Estas son algunas capacidades clave de Claude Code:

• Edición y refactorización: modifica, optimiza y mejora tu base de código con sugerencias impulsadas por IA.
• Corrección de bugs: identifica y resuelve errores, dependencias ausentes y cuellos de botella de rendimiento.
• Comprensión del código: haz preguntas sobre la arquitectura, la lógica y las dependencias de tu código.
• Tests y linting automatizados: ejecuta y corrige tests fallidos, lanza comandos de linting y mejora la calidad del código.
• Integración con Git: busca en el historial, resuelve conflictos de merge, crea commits y genera pull requests sin esfuerzo.

Tanto si trabajas en un proyecto open source como si gestionas bases de código a nivel enterprise, Claude Code te ayuda con automatizaciones inteligentes que se adaptan a tu estilo de programación y a las necesidades del proyecto. Las últimas novedades incluyen auto mode (menos interrupciones por permisos), plan mode (diseño antes de construir) y Routines (agentes en la nube programados que se ejecutan por disparadores sin necesidad de tener tu máquina encendida).

Estos perfiles son ideales para este servicio:

• Desarrolladores de software: mejorar la calidad y el mantenimiento del código.
• Colaboradores de open source: entender y mejorar bases de código desconocidas.
• Ingenieros DevOps: automatizar tareas de code review y linting.

Claude Code ahora usa por defecto Claude Opus 4.7 en los planes Max y Team Premium. Los usuarios Pro empiezan con Sonnet 4.6, pero pueden cambiar a Opus para tareas exigentes. Puedes cambiar de modelo en mitad de la sesión con el comando /model o ajustar la profundidad de razonamiento con el control /effort. También puedes crear agentes de IA independientes con el Claude Agents SDK.

Anthropic también ha lanzado Cowork para recibir ayuda estilo agente con tareas cotidianas de archivos y documentos más allá del código. Está disponible para todas las suscripciones de pago (Pro, Max, Team, Enterprise) en la app de escritorio de Claude.

Si estás comparando Claude Code con el agente de terminal de xAI, nuestra prueba Grok Build vs. Claude Code evalúa ambos en la misma tarea.

Vamos con el proyecto práctico.

Paso 1: configuración de Claude Code

Para empezar con Claude Code necesitas un terminal, un proyecto de código en el que trabajar y, o bien una suscripción a Claude (Pro/Max/Teams/Enterprise), o una cuenta en Claude Console con facturación activa.

Instala Claude Code ejecutando uno de los siguientes comandos en tu terminal, según tu sistema operativo y terminal.

macOS / Linux / WSL: 

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Nota: La instalación mediante npm install -g @anthropic-ai/claude-code sigue existiendo pero está obsoleta; es preferible el proceso nativo indicado arriba. Si lo instalaste con npm, puedes migrar con claude install.

Una vez instalado, ve al directorio de tu proyecto e inicia Claude ejecutando:

cd your-project-directory
claude

Para la autenticación, se te preguntará si quieres usar Claude Code con una suscripción de pago o con facturación por uso de API.

A continuación recibirás un enlace de inicio de sesión con un código de verificación que tendrás que introducir en el terminal donde se ejecuta Claude Code. Con eso, listo: se creará automáticamente un espacio de trabajo dedicado "Claude Code" para el seguimiento del uso y la gestión de costes.

Ahora Claude Code está listo para usar.

Paso 2: prepara el entorno de desarrollo

Para esta demo usaré la librería de Python de Supabase supabase-py, un cliente de Python open source para interactuar con Supabase, un backend-as-a-service creado sobre PostgreSQL. Supabase ofrece un conjunto de herramientas como autenticación, suscripciones en tiempo real, almacenamiento y APIs autogeneradas.

Empecemos clonando el repositorio y preparando el entorno de desarrollo.

1. Abre tu terminal, navega al directorio donde quieres clonar el repositorio Supabase-py (p. ej., cd Desktop) y ejecuta:

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. Crea un entorno virtual e instala las dependencias necesarias ejecutando estos comandos uno a uno en tu terminal:

python3 -m venv env
source env/bin/activate  # En Windows, usa ./env/Scripts/activate
pip install -e .

Tu entorno de Python ya está listo con todas las dependencias necesarias para ejecutar la librería de Supabase, y el repositorio está preparado para explorar.

Paso 3: identifica áreas donde contribuir

Una gran forma de contribuir es revisando la pestaña Issues en GitHub. En el repositorio de Supabase, identifiqué un issue en client.py relacionado con la legibilidad, la estructura y la falta de comentarios útiles.

Esto es lo que vamos a hacer con Claude Code:

• Refactorizaremos el código para mejorar legibilidad, mantenimiento y estructura.
• Añadiremos docstrings y comentarios en línea para clarificar el propósito de los distintos componentes.
• Identificaremos y corregiremos bugs analizando issues y otros posibles errores.

Paso 4: experimenta con Claude Code

Como ya estamos en la carpeta supabase-py, navega al directorio supabase que contiene el archivo client.py y ejecuta Claude Code:

cd supabase
claude

Claude Code ahora tiene acceso a todos los archivos y carpetas dentro de supabase-py. Vamos a probar.

Refactorización de código

Como parte de la mejora del SDK de Supabase para Python, vamos a refactorizar el archivo client.py para mejorar legibilidad, mantenibilidad y organización. Simplemente escribe el siguiente prompt en la línea de comandos:

Prompt: Refactoriza el código del archivo client.py ubicado en la carpeta Supabase.

Claude pedirá confirmación antes de proceder. Pulsa Enter para aprobar los cambios. Al terminar, Claude Code actualizará el archivo, mostrará las modificaciones en el terminal y te dará un resumen de lo realizado.

Con Claude Code aplicamos estas mejoras a client.py:

• Importaciones organizadas:  Claude Code agrupó importaciones relacionadas en secciones lógicas (errores de auth, tipos de API, errores de funciones), renombró importaciones para dar claridad y eliminó alias redundantes para mantener coherencia.
• Mayor legibilidad: añadió comentarios por secciones para clasificar importaciones y eliminó duplicados en la lista __all__ para una organización más limpia.
• Opciones del cliente simplificadas: redujo varias líneas combinando importaciones similares en una sola sentencia.

Aquí tienes una comparación en paralelo del código original y el refactorizado.

Documentación del código

Además de refactorizar, Claude Code puede generar, actualizar y estandarizar la documentación de código en todo un proyecto. Identifica secciones sin documentar, genera docstrings o comentarios estructurados y comprueba el cumplimiento de los estándares de documentación del proyecto.

Usamos Claude Code para mejorar la documentación de client.py, obteniendo:

• Docstrings claros a nivel de módulo explicando el propósito del archivo.
• Comentarios detallados por secciones que categorizan importaciones (tipos de error, implementaciones de cliente, servicios de almacenamiento).
• Comentarios en línea para describir tipos de errores, funciones del cliente y componentes importantes.

Aquí tienes una comparación en paralelo del código refactorizado y el documentado.

Prompt: Documenta el código de client.py añadiendo comentarios para mejorar la comprensión.

Una vez añadida la documentación, puedes verificar si cumple los estándares de tu proyecto pidiéndoselo a Claude:

Prompt: Comprueba si la documentación sigue los estándares de nuestro proyecto.

Corrección de errores

Depurar puede llevar tiempo, pero Claude Code acorta el ciclo analizando mensajes de error, identificando las causas raíz y proponiendo soluciones. Ya sea por importaciones ausentes, errores en tiempo de ejecución o problemas lógicos, reduce el área de búsqueda y sugiere correcciones concretas.

Así puedes usar Claude Code para depurar:

1. Identifica el problema: comparte el mensaje de error con Claude.
2. Obtén recomendaciones de solución: pide posibles arreglos a Claude.
3. Aplica y verifica la solución: implementa las sugerencias de Claude y comprueba si el problema se resuelve.

Claude Code tomó estas medidas para resolver problemas de importación en client.py:

• Comentarios type ignore: añadió el comentario # type: ignore para suprimir avisos del IDE y del chequeo de tipos por importaciones no resueltas.
• Categorización coherente de errores: Claude Code se aseguró de que las importaciones de errores de autenticación, base de datos, almacenamiento y funciones estén claramente agrupadas.
• Legibilidad mantenida: se añadieron comentarios para indicar por qué se ignoraban ciertas importaciones en lugar de eliminarlas.

Aquí tienes una comparación en paralelo del código original y el corregido.

Prompt: Veo algunos errores, como "Import gotrue.errors" no se pudo resolver. Ayúdame a corregir todos los errores en client.py.

Comandos de Claude Code

Aquí tienes algunos comandos para que pruebes con Claude.

Si quieres profundizar, te recomiendo nuestra guía de comandos slash de Claude Code.

Funciones avanzadas de Claude Code

Cuando domines lo básico de refactorización y depuración, podrás ampliar las capacidades de Claude Code personalizando su comportamiento. Hooks y plugins permiten automatizar tareas repetitivas e integrar sistemas externos.

Hooks de Claude Code

Los hooks de Claude Code son disparadores automatizados que ejecutan comandos de shell cuando ocurren eventos concretos durante tu sesión con Claude Code. Automatizan tareas repetitivas como formateo de código, ejecución de tests y comprobaciones de seguridad que Claude podría omitir.

Los hooks siguen un sistema evento-acción en el que defines tres cosas:

• El evento: ¿cuándo se dispara el hook?

• El matcher: ¿qué acciones se ven afectadas?

• El comando: ¿qué se ejecuta cuando el hook se activa?

Por ejemplo, un hook puede dispararse después de que Claude escriba un archivo de Python y ejecutar automáticamente black para formatear el código. Los hooks reciben contexto en JSON sobre lo ocurrido, lo que permite decisiones inteligentes según tipos o rutas de archivo. Pueden escribir en la transcripción de Claude o enviar errores directamente a Claude para bloquear operaciones.

Casos de uso comunes de hooks:

• Formateo de código: ejecutar linters y formatters automáticamente tras escribir código

• Testing: lanzar suites de tests tras modificaciones para detectar errores pronto

• Seguridad: bloquear cambios en archivos sensibles como configs de producción o claves de API

• Documentación: generar documentación de API automáticamente cuando cambian los fuentes

• Automatización con Git: crear commits inteligentes y validar políticas de protección de ramas

• Notificaciones: avisar a tu equipo por Slack cuando cambien archivos importantes

• Cumplimiento: hacer cumplir cabeceras de licencia o estándares de código antes de permitir cambios

Configura hooks con el comando /hooks en Claude Code o edita directamente ~/.claude/settings.json.

Plugins de Claude Code

Los plugins son extensiones que conectan Claude Code con herramientas, servicios y APIs externas. Mientras que los hooks automatizan comandos locales de shell, los plugins se integran con tu ecosistema de desarrollo (pipelines CI/CD, herramientas de gestión de proyectos y plataformas de comunicación de equipo).

Un plugin puede agrupar varios componentes —subagentes (asistentes de Claude especializados), servidores MCP (integraciones estandarizadas) y hooks— en un solo paquete que los orquesta en conjunto.

Un plugin podría analizar cambios de código y crear issues automáticamente en Jira, o conectarse a tu infraestructura interna de testing. Responden a los mismos eventos que los hooks, pero envían datos a servicios externos y procesan respuestas para influir en el flujo de trabajo de Claude.

Algunas tareas para las que destacan los plugins de Claude Code:

• Integración CI/CD: disparar builds, tests y despliegues al cambiar archivos

• Gestión de proyectos: crear o actualizar issues en Jira, GitHub o Linear

• Comunicación del equipo: publicar actualizaciones en Slack o Teams cuando haya cambios

• Revisión de código: crear pull requests automáticamente y gestionar reviews en GitHub/GitLab

• Análisis externo: llamar a SonarQube, CodeClimate o Snyk para escaneos de código a nivel enterprise

• Herramientas personalizadas: integrarse con sistemas y flujos propietarios de tu empresa

• Extensiones para IDE: añadir comandos personalizados y ayudas de navegación

Instala plugins desde un registro o créalos internamente para tu organización, y configura a qué eventos responden. Juntos, hooks y plugins crean una plataforma extensible que adapta Claude Code a tu infraestructura.

Otras funciones avanzadas

Claude Code ha incorporado en 2026 varias capacidades importantes que amplían cómo y dónde puedes usarlo:

• Plan mode: un flujo de trabajo que empieza por el diseño, en el que Claude crea un plan de implementación detallado antes de escribir código. Lo uso para cualquier tarea no trivial.
• Auto mode: un clasificador de permisos que permite a Claude trabajar con menos interrupciones, útil para tareas largas en las que no quieres aprobar cada escritura de archivo.
• Routines: agentes en la nube programados que se ejecutan con cron, un evento de GitHub (como PR abierto) o una llamada webhook. Tu máquina no necesita estar encendida.
• Integración con IDE: Claude Code tiene extensiones oficiales para VS Code, Cursor y los IDE de JetBrains con diffs en línea, checkpoints y soporte multisesión.
• Control remoto y Channels: ejecuta sesiones de Claude Code e interactúa con ellas desde el móvil u otros dispositivos.

Conclusiones

En este tutorial, usé Claude Code para refactorizar, documentar y depurar un archivo del SDK de Supabase para Python. Mejoramos la legibilidad, añadimos documentación estructurada y resolvimos problemas de importación.

Claude Code evoluciona activamente con funciones como plan mode, auto mode y Routines, así que merece la pena experimentar en tus propios proyectos para ver cómo encaja en tu flujo de trabajo.

Para seguir, te animo a leer nuestro tutorial de buenas prácticas con Claude Code, donde aprenderás a sacarle partido a la ventana de contexto de Claude. Si quieres crear un proyecto desde cero, te recomiendo nuestro tutorial sobre desarrollo dirigido por especificaciones con Claude Code.