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 ayuda con tareas de desarrollo usando 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 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 ausentes y cuellos de botella de rendimiento.
• Comprensión del código: formula preguntas sobre la arquitectura, la lógica y las dependencias de tu código.
• Tests y linting automáticos: ejecuta y corrige tests fallidos, 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 y a las necesidades del proyecto. Las actualizaciones recientes han añadido auto mode (menos interrupciones por 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 máquina encendida).

Estos son algunos perfiles ideales para este servicio:

• Desarrolladores de software: mejorar la calidad y el mantenimiento del código.
• Colaboradores de open source: comprender y mejorar bases de código desconocidas.
• Ingenieros DevOps: automatizar revisiones de código y tareas de 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 presentado Cowork para ayuda tipo agente con tareas cotidianas de archivos y documentos más allá del código. Está disponible para todos los suscriptores de planes de pago (Pro, Max, Team, Enterprise) en la app de escritorio de Claude.

Vamos a empezar con el proyecto práctico.

Paso 1: configurar Claude Code

Para empezar con Claude Code, necesitas un terminal, un proyecto de código en 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 simplemente 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 vía npm install -g @anthropic-ai/claude-code sigue existiendo pero está obsoleta; mejor usa el proceso nativo indicado arriba. Si lo instalaste antes con npm, puedes migrar con claude install.

Una vez instalado, ve a tu directorio de 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.

A continuación, recibirás un enlace de inicio de sesión que te llevará a un código de verificación que tendrás que introducir en el terminal donde se está ejecutando Claude Code. Y listo, se crea automáticamente un espacio de trabajo dedicado de “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 biblioteca de Python de Supabase supabase-py, un cliente de Python de código abierto para interactuar con Supabase, un backend-as-a-service construido 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 nuestro entorno de desarrollo.

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

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

2. Después, crea un entorno virtual e instala las dependencias necesarias ejecutando estos comandos en tu terminal uno a uno:

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 biblioteca de Supabase y el repositorio está listo para explorarse. 

Paso 3: identifica áreas en las que contribuir

Una gran 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 con sentido para clarificar el propósito de los distintos componentes.
• Identificar y corregir errores analizando los issues y otros posibles fallos.

Paso 4: experimentar 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 la carpeta Supabase-py. Vamos a probarlo.

Refactorización de código

Como parte de la mejora del SDK de Python de Supabase, vamos a refactorizar el archivo client.py para mejorar la legibilidad, el mantenimiento y la organización. Simplemente introduce 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:

• Importaciones organizadas:  Claude Code agrupó importaciones relacionadas en secciones lógicas (errores de auth, tipos de API, errores de funciones), renombró importaciones para mayor claridad y eliminó alias redundantes para mantener la coherencia.
• Mayor legibilidad: se añadieron comentarios por secciones para clasificar importaciones y se eliminó la duplicación en la lista __all__ para una organización más limpia.
• Opciones del cliente simplificadas: también se redujeron 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 del código en todo un proyecto. Puede identificar secciones sin documentar, generar docstrings o comentarios estructurados y comprobar el cumplimiento de los estándares de documentación del proyecto.

Usamos Claude Code para mejorar la documentación en client.py, lo que dio como resultado:

• Docstrings claros a nivel de módulo explicando el propósito del archivo.
• Comentarios detallados por secciones categorizando las importaciones (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 en paralelo 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 verificar que cumpla con los estándares de tu proyecto pidiéndoselo a Claude:

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

Corrección de bugs

Depurar puede llevar mucho tiempo, pero Claude Code acorta el ciclo analizando mensajes de error, identificando causas raíz y proponiendo correcciones. Ya sea por importaciones que faltan, errores de ejecución o problemas lógicos, reduce el espacio de búsqueda y sugiere correcciones específicas.

Así puedes usar Claude Code para depurar:

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

Claude Code realizó los siguientes ajustes para resolver problemas de importación en el archivo client.py: 

• Comentarios type ignore: se añadió el comentario # type: ignore para silenciar avisos del IDE y del comprobador de tipos por importaciones no resueltas.
• Categorización coherente de errores: Claude Code garantizó que las importaciones de errores de autenticación, base de datos, almacenamiento y funciones estuvieran claramente agrupadas.
• Mantenimiento de la legibilidad: se añadieron comentarios para indicar por qué se ignoraron 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 probar con Claude.

También te recomiendo consultar los tutoriales oficiales de Anthropic y nuestra guía de buenas prácticas de Claude Code.

Funciones avanzadas de Claude Code

Cuando te sientas cómodo con lo básico de refactorizar y depurar, puedes 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 automáticos que ejecutan comandos de shell cuando ocurren eventos específicos 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 usan un sistema evento-acción, donde defines tres cosas:

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

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

• El 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 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 enviar salida a la transcripción de Claude o mandar mensajes de error directamente a Claude para bloquear operaciones.

Casos de uso comunes de los hooks:

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

• Testing: ejecutar suites de test tras modificaciones para detectar bugs pronto

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

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

• 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

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

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 los hooks automatizan comandos locales de shell, los plugins se integran con tu ecosistema de desarrollo más amplio, como pipelines de CI/CD, herramientas de gestión de proyectos y plataformas de comunicación de equipo.

Los plugins pueden agrupar varios componentes—subagentes (asistentes de Claude especializados), servidores MCP (integraciones estandarizadas) y hooks—en un único paquete que los orquesta.

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.

Tareas para las que los plugins de Claude Code son ideales:

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

• Gestión de proyecto: crear o actualizar issues en Jira, GitHub o Linear automáticamente

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

• Revisión de código: crear pull requests y gestionar revisiones en GitHub/GitLab

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

• Herramientas a medida: integrarse con sistemas y flujos internos de la empresa

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

Instala plugins desde un registro o constrúyelos 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 de diseño primero en el que Claude crea un plan de implementación detallado antes de escribir código. Yo lo uso para cualquier tarea no trivial.
• Auto mode: un clasificador de permisos que permite a Claude trabajar con menos interrupciones; útil en 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. Tu máquina no tiene que estar encendida.
• 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.

Reflexiones finales

En este tutorial, he usado Claude Code para refactorizar, documentar y depurar un archivo del SDK de Python de Supabase. Mejoramos la legibilidad del código, 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 dar el siguiente paso, te animo a leer nuestro tutorial de buenas prácticas de Claude Code, que te enseña a sacar el máximo 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.