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 puedas centrarte en escribir y mejorar código.

Estas son algunas de las 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 errores: identifica y resuelve errores, dependencias faltantes 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 que fallen, lanza comandos de linting y mejora la calidad del código.
• Integración con Git: busca en el historial de git, resuelve conflictos de merge, crea commits y genera pull requests sin esfuerzo.

Tanto si trabajas en un proyecto de código abierto como si gestionas bases de código a nivel empresarial, Claude Code te ayuda con automatización inteligente que se adapta a tu estilo de programación y a los requisitos del proyecto. Las últimas novedades incluyen auto mode (menos interrupciones de permisos), plan mode (flujos de trabajo con diseño primero) y Routines (agentes en la nube programados que se ejecutan por disparadores sin necesidad de tener tu equipo encendido).

Estos son algunos perfiles 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 revisión de código 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 los modelos Opus para tareas exigentes. Puedes cambiar de modelo a mitad de 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 presentado Cowork para recibir ayuda con estilo agente en tareas cotidianas con 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.

Vamos a empezar 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 con el que trabajar y una suscripción a Claude (Pro/Max/Teams/Enterprise) o una cuenta de 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á en desuso; es preferible usar el instalador nativo anterior. Si lo instalaste antes 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 la API.

Después 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 está ejecutando Claude Code. Listo. Además, se crea 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 usarse.

Paso 2: prepara el entorno de desarrollo

Para esta demo, usaré la librería de Python de Supabase supabase-py, un cliente de Python de código abierto para interactuar con Supabase, un backend como servicio construido sobre PostgreSQL. Supabase ofrece un conjunto de herramientas que incluyen 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 quieras clonar el repositorio de 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 para ejecutar la librería de Supabase y tu repositorio está preparado para explorar.

Paso 3: identifica áreas en las que contribuir

Una buena forma de contribuir es explorando la pestaña Issues en GitHub. En el repositorio de Supabase, identifiqué un problema en client.py relacionado con la legibilidad del código, la estructura y la falta de comentarios útiles.

Esto es lo que vamos a hacer con Claude Code:

• Refactorizar el código para mejorar la legibilidad, el mantenimiento y la estructura.
• Añadir docstrings y comentarios en línea que aclaren el propósito de los distintos componentes.
• Identificar y corregir errores analizando issues y otros posibles fallos.

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 probarlo.

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 la legibilidad, el mantenimiento y la 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 continuar. 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 los cambios realizados.

Con Claude Code aplicamos las siguientes mejoras a client.py:

• Imports organizados: Claude Code agrupó imports relacionados en secciones lógicas (errores de auth, tipos de API, errores de funciones), renombró imports para mayor claridad y eliminó alias redundantes para ser consistentes.
• Más legibilidad: añadió comentarios por secciones para clasificar imports y eliminó duplicados en la lista __all__ para una organización más limpia.
• Opciones del cliente simplificadas: redujo varias líneas combinando imports similares en una sola instrucción.

Aquí tienes una comparación lado a lado 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 en todo un proyecto. Detecta 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 en client.py, con el siguiente resultado:

• Docstrings claros a nivel de módulo que explican el propósito del archivo.
• Comentarios detallados por secciones que categorizan imports (tipos de errores, 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 lado a lado del código refactorizado y documentado.

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

Una vez añadida la documentación, puedes comprobar si cumple con 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 causas raíz y proponiendo soluciones. Ya sea por imports faltantes, errores en tiempo de ejecución o problemas lógicos, reduce el espacio 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 arreglo: pide posibles soluciones a Claude.
3. Aplica y verifica el arreglo: implementa las sugerencias de Claude y comprueba si se resolvió.

Claude Code realizó lo siguiente para resolver problemas de imports en el archivo client.py:

• Comentarios type ignore: añadió el comentario # type: ignore para suprimir avisos del IDE y del tipado estático ante imports no resueltos.
• Categorización de errores coherente: Claude Code se aseguró de que los imports de errores de autenticación, base de datos, almacenamiento y funciones estuvieran claramente agrupados.
• Legibilidad mantenida: se añadieron comentarios para indicar por qué ciertos imports se ignoraban en vez de eliminarlos.

Aquí tienes una comparación lado a lado del código original y el código 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 probar 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 te 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 específicos durante tu sesión. Automatizan tareas repetitivas como formateo de código, ejecución de tests y comprobaciones de seguridad que Claude podría omitir.

Los hooks usan un sistema evento-acción, donde defines tres cosas:

• Evento: ¿cuándo se dispara el hook?

• Matcher: ¿qué acciones se ven afectadas?

• Comando: ¿qué se ejecuta cuando se dispara el hook?

Por ejemplo, un hook puede activarse después de que Claude escriba un archivo de Python y lanzar 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 volcar salida en la transcripción de Claude o enviarle errores directamente para bloquear operaciones.

Casos de uso comunes de los hooks:

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

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

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

• Documentación: genera documentación de API cuando cambian archivos fuente

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

• Notificaciones: avisa a tu equipo por Slack cuando cambian archivos importantes

• Compliance: impone cabeceras de licencia o estándares de código antes de permitir modificaciones

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

Plugins de Claude Code

Los plugins son extensiones que conectan Claude Code con herramientas, servicios y APIs externos. Mientras que los hooks automatizan comandos locales, los plugins se integran con tu ecosistema de desarrollo más amplio como pipelines CI/CD, herramientas de gestión de proyectos y plataformas de comunicación de equipo.

Un plugin puede incluir varios componentes—subagentes (asistentes Claude especializados), servidores MCP (integraciones estandarizadas) y hooks—en un único paquete que los coordina.

Por ejemplo, un plugin puede analizar cambios de código y crear issues automáticamente en Jira, o conectarse a tu infraestructura interna de testing. Los plugins 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.

Estas son algunas tareas para las que los plugins de Claude Code van muy bien:

• Integración CI/CD: dispara builds, tests y despliegues cuando cambian archivos

• Gestión de proyectos: crea o actualiza issues en Jira, GitHub o Linear

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

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

• Análisis externo: llama a SonarQube, CodeClimate o Snyk para escaneo de código empresarial

• Herramientas a medida: integra sistemas y flujos de trabajo propios de tu empresa

• Extensiones de IDE: añade 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 varias capacidades importantes en 2026 que amplían cómo y dónde puedes usarlo:

• Plan mode: un flujo de trabajo de diseño primero donde 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 deja 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 un cron, un evento de GitHub (como abrir un PR) o una llamada webhook. No necesitas tener tu equipo encendido.
• Integración con IDE: Claude Code tiene extensiones oficiales para VS Code, Cursor y JetBrains, con diffs en línea, checkpoints y soporte multisessión.
• Control remoto y Channels: ejecuta sesiones de Claude Code e interactúa con ellas desde tu 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 del código, añadimos documentación estructurada y resolvimos problemas de imports.

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 dar el siguiente paso, te animo a leer nuestro tutorial de buenas prácticas de 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 guiado por especificaciones con Claude Code.