Como usar Claude Code: guia practica 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 guia 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 sesion con tu cuenta Anthropic. Despues 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 mas usamos en el dia a dia. Ordenados de mas basico a mas avanzado.

1. Debuggear un error

El flujo mas 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 codigo

> 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: validacion, 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 documentacion

> 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 guia completa de worktrees.

Configura tu proyecto con CLAUDE.md

El archivo CLAUDE.md en la raiz de tu proyecto es como un briefing para Claude Code. Define reglas, convenciones y contexto que se cargan automaticamente en cada sesion.

# 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 guia completa de CLAUDE.md para mas detalles.

Comandos esenciales

Referencia rapida de los comandos mas 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 mas.

# 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 mas de 100 servidores MCP disponibles. Lee nuestra guia de MCP para configurar los mas utiles.

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 aprobacion automatica: con el flag --dangerously-skip-permissions aprueba todo automaticamente. Solo para entornos de CI/CD aislados
• Permisos granulares: en settings.json puedes permitir comandos especificos (npm test, git status) y bloquear otros

Tips de productividad avanzados

1. Usa prompts largos y especificos. 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 modulo 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 codigo simultaneamente.

4. Usa /compact en sesiones largas. Despues 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 despues de acciones de Claude Code. Ejemplo: ejecutar el linter despues de cada edicion.

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 codigo" no da informacion suficiente. Especifica 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 rapido puede ahorrarte horas de debugging.

Sesiones demasiado largas sin /compact. Despues de ~30 minutos de conversacion continua, la calidad baja porque el contexto se satura. Usa /compact o inicia una sesion nueva.

No tener CLAUDE.md. Sin contexto del proyecto, Claude Code tiene que adivinar tus convenciones. Invierte 5 minutos en crear un CLAUDE.md basico 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. Despues, 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 documentacion, analizar rendimiento y trabajar con bases de datos.

Claude Code es mejor que GitHub Copilot?

Son herramientas complementarias. Copilot autocompleta codigo 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 mas potente. Para autocompletado rapido dentro del editor, Copilot es mas 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 mas detalles, lee sobre Claude Code gratis y sus limites.

Puedo usar Claude Code sin saber programar?

Claude Code esta disenado para desarrolladores, pero puedes usarlo para tareas basicas como modificar archivos de configuracion, generar scripts sencillos o gestionar repositorios git. El requisito minimo es saber usar la terminal y entender que estas pidiendo. Para aprender los fundamentos, empieza con nuestra guia para principiantes.