Guía paso a paso de Claude Code: cómo usar el agente programador de Anthropic en tu terminal

Para cualquier equipo de desarrollo o empresa que mantiene aplicaciones web y plataformas digitales, el tiempo dedicado a buscar errores, refactorizar código antiguo y mantener suites de pruebas representa una carga operativa enorme. En este contexto, Claude Code, la herramienta de desarrollo agentic creada por Anthropic, se ha convertido en el estándar de oro de la programación asistida por IA en 2026.

A diferencia de las extensiones tradicionales de autocompletado en el editor, Claude Code es un agente de software autónomo que corre en tu consola. Comprende la arquitectura completa de tu repositorio, navega entre carpetas, ejecuta comandos bash, corre tests, diagnostica fallas y aplica cambios en múltiples archivos a la vez.

En esta guía paso a paso aprenderás cómo instalarlo, cómo configurar sus permisos y cuáles son los patrones de trabajo recomendados para integrarlo en proyectos reales.

1. Requisitos previos y entorno#

Antes de iniciar la instalación asegurate de contar con:

• Node.js: Versión 18 o superior instalada en tu sistema (Linux, macOS o WSL en Windows).
• Control de versiones: Un repositorio de Git inicializado en tu proyecto.
• Acceso a Anthropic: Una clave de API de Anthropic con saldo disponible o una suscripción activa a Claude Pro / Max.

2. Instalación y autenticación inicial#

Paso 1: Instalación global mediante npm#

Abrí tu terminal y ejecutá el comando de instalación oficial:

npm install -g @anthropic-ai/claude-code

Verificá que la herramienta se haya instalado correctamente consultando su versión:

claude --version

Paso 2: Autenticación con tu cuenta#

Navegá hasta la carpeta raíz del proyecto en el que quieras trabajar y ejecutá:

claude

La primera vez que corras el comando, la CLI abrirá automáticamente una ventana en tu navegador predeterminado para iniciar sesión en tu cuenta de Anthropic y vincular el token de acceso. Una vez autorizado, el comando quedará configurado permanentemente en tu entorno local.

3. Cómo funciona la interacción en la terminal#

Cuando iniciás una sesión con claude dentro de tu repositorio, la herramienta indexa la estructura del proyecto y entra en un bucle interactivo de comandos en lenguaje natural.

Análisis inicial del repositorio#

Para comenzar a trabajar en un proyecto nuevo o que no conocés a fondo, podés pedirle una síntesis arquitectónica:

"Explicame cómo está estructurada esta aplicación, cuáles son las rutas principales del backend y qué base de datos utiliza."

Claude Code inspeccionará el archivo package.json, los archivos de configuración y los controladores, devolviéndote un resumen claro de los módulos principales.

4. Casos de uso prácticos paso a paso#

Caso 1: Resolución de un bug complejo#

Imaginá que tu pasarela de pagos rechaza transacciones con tarjetas específicas y arroja un error ambiguo en los registros del servidor. Podés indicarle:

"Revisá el módulo de procesamiento de pagos en src/services/payment.ts. Los usuarios reportan que las respuestas con código 422 de Mercado Pago no capturan el detalle del error en la base de datos. Identificá la causa, corregí el tipado, agregá manejo de excepciones y corré las pruebas unitarias para validar la solución."

Qué hace Claude Code de forma autónoma:

1. Lee payment.ts y los archivos de tipos asociados.
2. Encuentra la función que parsea la respuesta JSON de la API.
3. Modifica el bloque try/catch para registrar el mensaje devuelto por la pasarela.
4. Ejecuta npm test en la terminal para comprobar que ninguna otra prueba se haya roto.
5. Te muestra el diff exacto de las líneas modificadas y te pide confirmación para aplicar el cambio.

Caso 2: Refactorización y modernización de código#

Podés encomendarle migraciones estructurales que a un desarrollador le demandarían días enteros de trabajo manual:

"Refactorizá todos los componentes ubicados en src/components/legacy para que utilicen TypeScript estricto con interfaces explícitas en lugar de tipos any. Asegurate de que el linter pase sin advertencias."

Caso 3: Generación de suites de pruebas automáticas#

"Analizá los endpoints de la API en routes/api.ts y escribí pruebas de integración con Jest y Supertest en tests/api.test.ts cubriendo casos de éxito y de error de autenticación."

5. Mejores prácticas y consejos de seguridad#

• Trabajá siempre en ramas dedicadas (feature branches): Creá una rama nueva en Git (git checkout -b fix/modulo-pagos) antes de pedirle cambios masivos. De esta forma podés revertir cualquier modificación con facilidad.
• Validación interactiva de comandos: Por defecto, Claude Code solicita confirmación antes de ejecutar comandos bash que modifican el sistema de archivos o la red. Mantené activado este control para evitar ejecuciones accidentales.
• Uso de archivos .claudesignore: Si tu proyecto contiene carpetas pesadas con archivos generados (como dist, build o archivos de datos CSV extensos), agregalos a un archivo .claudesignore para no consumir tokens innecesariamente en la indexación.

Servicios de desarrollo y arquitectura con Mark-Co Digital#

Adoptar agentes como Claude Code acelera el desarrollo de software, pero la visión estratégica, la seguridad de la arquitectura y la integración con la lógica de negocio requieren criterio experto.

En Mark-Co Digital diseñamos y mantenemos software a medida para pymes: desarrollamos agentes a medida, auditamos seguridad y rendimiento y construimos plataformas web escalables preparadas para el futuro.

Si querés modernizar el software de tu empresa o integrar agentes de IA en tu equipo de desarrollo, contactá a nuestro equipo técnico.

Fuentes#

• Anthropic - Claude Code Official Product Documentation
• Anthropic Engineering - Best Practices for Claude Code
• Anthropic Institute - Autonomous AI Coding Research & Metrics