Como usar Claude Code: guía práctica paso a paso

Si ya sabes que es Claude Code y lo tienes instalado, este tutorial te ensena como usarlo de verdad. No conceptos abstractos: 10 flujos de trabajo concretos que puedes aplicar hoy.

Antes de empezar

Necesitas tres cosas:

1. Node.js 18+ instalado (node --version para verificar)
2. Claude Code instalado: npm install -g @anthropic-ai/claude-code
3. Cuenta Anthropic con plan Max (100 USD/mes) o API con creditos

Si no lo tienes instalado, sigue nuestra guía de instalacion paso a paso.

# Verificar instalacion
claude --version

# Iniciar Claude Code en tu proyecto
cd mi-proyecto
claude

La primera vez, Claude Code te pedira autenticacion. Se abre una ventana del navegador donde inicias sesión con tu cuenta Anthropic. Después de autenticar, el CLI queda vinculado a tu cuenta.

Tu primer uso de Claude Code

Abre tu terminal en la carpeta de cualquier proyecto y escribe claude. Veras un prompt interactivo donde puedes escribir en lenguaje natural.

Empieza con algo simple:

# Pedirle que explore tu proyecto
> Explicame la estructura de este proyecto

# Pedirle un cambio concreto
> Anade un endpoint GET /api/health que devuelva {"status": "ok"}

# Pedirle que arregle un error
> El test test_user_login falla con "AssertionError". Arreglalo.

Claude Code leera los archivos relevantes, propondra cambios y te pedira confirmacion antes de modificar nada. Puedes aprobar, rechazar o pedir ajustes.

10 flujos de trabajo reales

Estos son los flujos que más usamos en el día a día. Ordenados de más básico a más avanzado.

1. Debuggear un error

El flujo más comun. Pegas el error y dejas que Claude Code investigue.

> Este error aparece en produccion:
> TypeError: Cannot read properties of undefined (reading 'email')
> en UserProfile.tsx:42
> Investigalo y arreglalo.

Claude Code leera el archivo, rastreara donde se usa la variable, identificara el caso edge y propondra un fix. Normalmente tarda 30-60 segundos.

2. Refactorizar código

> El archivo utils/helpers.ts tiene 800 lineas. Dividelo en
> modulos logicos separados manteniendo los exports.

Claude Code analizara las dependencias internas, creara los nuevos archivos y actualizara todos los imports en el proyecto.

3. Escribir tests

> Escribe tests unitarios para el servicio auth/login.ts.
> Usa vitest. Cubre los casos: login correcto, password
> incorrecto, usuario no existe, cuenta bloqueada.

4. Crear un endpoint API

> Crea un endpoint POST /api/v1/invoices que reciba
> {client_id, items[], due_date}. Valida los datos,
> calcula el total y guarda en la tabla invoices.
> Usa el patron que ya usamos en /api/v1/orders.

Al decir "usa el patron que ya usamos", Claude Code buscara el endpoint existente y replicara la estructura: validación, middleware, respuesta de error.

5. Git workflow completo

> Revisa los cambios que he hecho, crea un commit con
> mensaje descriptivo y abre un PR con titulo y descripcion.

Claude Code ejecuta git diff, analiza los cambios, redacta un mensaje de commit semantico y usa gh pr create para abrir el PR. Todo en un paso.

6. Migrar de una libreria a otra

> Migra todos los componentes de moment.js a date-fns.
> Actualiza las importaciones, adapta los formatos
> y verifica que los tests sigan pasando.

7. Generar documentación

> Genera documentacion JSDoc para todas las funciones
> publicas del directorio src/services/. No documentes
> funciones privadas ni helpers internos.

8. Analizar rendimiento

> La pagina /dashboard tarda 4 segundos en cargar.
> Analiza los componentes React, identifica re-renders
> innecesarios y propone optimizaciones concretas.

9. Trabajar con bases de datos

> Crea una migracion SQL que anade la tabla audit_logs
> con columnas: id, user_id, action, entity_type,
> entity_id, metadata (jsonb), created_at.
> Incluye indices para user_id y created_at.

10. Desarrollo paralelo con worktrees

> Crea un worktree en rama feature/new-dashboard y
> trabaja ahi sin tocar mi rama actual. Implementa
> el nuevo layout del dashboard con sidebar colapsable.

Para profundizar en este flujo, lee nuestra guía completa de worktrees.

Configura tu proyecto con CLAUDE.md

El archivo CLAUDE.md en la raíz de tu proyecto es como un briefing para Claude Code. Define reglas, convenciones y contexto que se cargan automaticamente en cada sesión.

# CLAUDE.md ejemplo
## Stack
- Backend: FastAPI + Python 3.11
- Frontend: Next.js 14 + TypeScript
- DB: Supabase PostgreSQL con RLS

## Reglas
- Tests obligatorios para funciones publicas
- Commits en conventional commits (feat:, fix:, refactor:)
- Espanol en comentarios, ingles en codigo

## Patrones
- Servicios en src/services/, un archivo por dominio
- Endpoints en src/routes/, agrupados por recurso
- Validacion con Pydantic models

Con un buen CLAUDE.md, no necesitas repetir convenciones en cada prompt. Claude Code las aplica automaticamente. Lee la guía completa de CLAUDE.md para más detalles.

Comandos esenciales

Referencia rápida de los comandos más usados dentro de Claude Code:

Para la lista completa, consulta nuestra referencia de comandos.

Conecta herramientas externas con MCP

MCP (Model Context Protocol) permite a Claude Code conectarse con servicios externos: GitHub, Slack, bases de datos, APIs y más.

# Ejemplo: conectar con GitHub
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Ejemplo: conectar con Supabase
claude mcp add supabase -- npx -y @supabase/mcp-server

# Despues puedes hacer cosas como:
> Crea un issue en GitHub con el bug que acabamos de encontrar
> Ejecuta esta query SQL en la base de datos de staging

Hay más de 100 servidores MCP disponibles. Lee nuestra guía de MCP para configurar los más útiles.

Gestiona permisos y seguridad

Claude Code pide confirmacion antes de ejecutar acciones potencialmente destructivas. Puedes configurar el nivel de autonomia:

• Modo seguro (default): pide confirmacion para escribir archivos, ejecutar comandos y operaciones git
• Modo aprobación automática: con el flag --dangerously-skip-permissions aprueba todo automaticamente. Solo para entornos de CI/CD aislados
• Permisos granulares: en settings.json puedes permitir comandos específicos (npm test, git status) y bloquear otros

Tips de productividad avanzados

1. Usa prompts largos y específicos. Claude Code trabaja mejor con contexto completo. En lugar de "arregla el bug", da el error exacto, el comportamiento esperado y donde crees que esta el problema.

2. Trabaja en una cosa a la vez. Cada prompt deberia tener un objetivo claro. "Arregla el bug Y refactoriza el módulo Y actualiza los tests" es tres tareas. Hazlas por separado.

3. Aprovecha los subagents. Para tareas grandes, Claude Code puede lanzar agentes paralelos que trabajan en diferentes partes del código simultaneamente.

4. Usa /compact en sesiones largas. Después de completar una tarea, comprime el contexto antes de empezar la siguiente. Mantiene la calidad de las respuestas.

5. Crea hooks para automatizar. Los hooks ejecutan comandos automaticamente antes o después de acciones de Claude Code. Ejemplo: ejecutar el linter después de cada edición.

6. Usa el modo plan para tareas grandes. Antes de implementar, pide un plan. Revisalo, ajustalo y luego ejecuta. Evita retrabajo.

7. Monta un CLAUDE.md solido. Un buen CLAUDE.md con las convenciones de tu proyecto ahorra repeticion y mejora la consistencia del output.

Errores comunes y como evitarlos

Prompts vagos. "Mejora el código" no da información suficiente. Específica que mejorar: rendimiento, legibilidad, tipos, cobertura de tests.

No revisar los cambios. Claude Code es potente pero no infalible. Siempre revisa el diff antes de aceptar. Un git diff rápido puede ahorrarte horas de debugging.

Sesiones demasiado largas sin /compact. Después de ~30 minutos de conversación continua, la calidad baja porque el contexto se satura. Usa /compact o inicia una sesión nueva.

No tener CLAUDE.md. Sin contexto del proyecto, Claude Code tiene que adivinar tus convenciones. Invierte 5 minutos en crear un CLAUDE.md básico y el retorno es inmediato.

Pedir demasiado en un prompt. Un prompt con 5 tareas diferentes produce peores resultados que 5 prompts enfocados. Divide y venceras.

Ignorar las preguntas de Claude Code. A veces Claude Code pide clarificacion: "Quieres que use vitest o jest?" Responde en lugar de ignorar. La clarificacion mejora el resultado.

Preguntas frecuentes

Como usar Claude Code por primera vez?

Instala con npm install -g @anthropic-ai/claude-code, navega a tu proyecto en la terminal y ejecuta claude. La primera vez te pedira autenticacion via navegador. Después, escribe lo que necesitas en lenguaje natural y Claude Code se encarga del resto.

Que puedo hacer con Claude Code?

Practicamente cualquier tarea de desarrollo: leer y escribir archivos, ejecutar comandos, hacer commits y PRs, conectarse a APIs via MCP, debuggear errores, refactorizar, escribir tests, generar documentación, analizar rendimiento y trabajar con bases de datos.

Claude Code es mejor que GitHub Copilot?

Son herramientas complementarias. Copilot autocompleta código dentro del editor (inline, linea a linea). Claude Code es un agente autonomo en la terminal que puede modificar multiples archivos, ejecutar tests, hacer git push y conectarse a servicios externos. Para tareas complejas que involucran multiples archivos, Claude Code es significativamente más potente. Para autocompletado rápido dentro del editor, Copilot es más comodo. Puedes usar ambos. Lee nuestra comparativa completa.

Cuanto cuesta usar Claude Code?

Claude Code requiere un plan Anthropic Max (100 USD/mes) que incluye uso ilimitado, o pago por uso via API donde pagas por tokens consumidos. No hay plan gratuito permanente. Para más detalles, lee sobre Claude Code gratis y sus límites.

Puedo usar Claude Code sin saber programar?

Claude Code esta disenado para desarrolladores, pero puedes usarlo para tareas básicas como modificar archivos de configuración, generar scripts sencillos o gestionar repositorios git. El requisito mínimo es saber usar la terminal y entender que estas pidiendo. Para aprender los fundamentos, empieza con nuestra guía para principiantes.