Configurar Claude Code desde Cero: Guía Práctica para Desarrollo en Terminal

Claude Code
1

Claude Code no es un editor — es un agente de desarrollo que vive en tu terminal. Le dices qué hacer, y él lee tu código, planifica, implementa, ejecuta comandos, corre tests, y commitea. Esta guía te lleva desde la instalación hasta un flujo de trabajo real.

Requisitos Previos

  • Node.js 18+ instalado
  • Cuenta de Anthropic (se puede autenticar con tu cuenta de Claude o con API key)
  • Git configurado en tu máquina
  • Un proyecto existente con repositorio git inicializado

Paso 1: Instalación

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

Verifica la instalación:

claude --version

Navega a tu proyecto:

cd tu-proyecto
claude

La primera vez, Claude Code te pedirá autenticarte. Puedes usar tu cuenta de Anthropic directamente o configurar una API key.

Paso 2: Tu Primer Sesión

Al ejecutar claude, entras en un modo conversacional en la terminal. Prueba algo simple primero:

> Analiza la estructura de este proyecto y dame un resumen de la 
  arquitectura, las dependencias principales, y cualquier problema 
  potencial que notes.

Claude Code va a:

  1. Leer tu estructura de archivos
  2. Analizar package.json, configuraciones, y archivos clave
  3. Darte un resumen organizado del proyecto

Esto es útil para confirmar que Claude Code entiende tu proyecto antes de pedirle cambios.

Paso 3: Crear CLAUDE.md

El archivo CLAUDE.md en la raíz de tu proyecto es la pieza más importante para obtener buenos resultados. Es el equivalente a las Rules de Cursor o las custom instructions de Copilot.

Crea CLAUDE.md:

# Proyecto: API de Gestión de Inventario

## Stack
- Runtime: Node.js 20 con TypeScript
- Framework: Fastify
- ORM: Drizzle con PostgreSQL
- Auth: JWT con refresh tokens
- Testing: Vitest
- Linting: Biome

## Estructura

src/
routes/ → Rutas de Fastify organizadas por recurso
services/ → Lógica de negocio
repositories/ → Acceso a datos con Drizzle
schemas/ → Validación con Zod
middleware/ → Auth, rate limiting, logging
utils/ → Helpers compartidos


## Convenciones
- Repository pattern: routes → services → repositories
- Validación de inputs siempre en la capa de routes con Zod
- Errores tipados con clases custom (AppError, ValidationError, NotFoundError)
- Nombres de variables y funciones en inglés
- Commits en inglés siguiendo Conventional Commits
- Tests junto al archivo que testean (archivo.test.ts)

## Comandos
- `npm run dev` — servidor de desarrollo
- `npm run test` — correr todos los tests
- `npm run test:watch` — tests en modo watch
- `npm run lint` — linting con Biome
- `npm run db:migrate` — correr migraciones
- `npm run db:generate` — generar migraciones desde schema

## Notas Importantes
- La base de datos está en Supabase, no crear migraciones destructivas sin confirmación
- Los endpoints públicos necesitan rate limiting
- Nunca hardcodear secrets, siempre usar variables de entorno

Claude Code lee este archivo automáticamente al iniciar cada sesión.

Paso 4: Flujo de Trabajo para Implementar una Feature

Veamos un flujo completo para agregar funcionalidad:

> Necesito agregar un endpoint para gestionar categorías de productos.
  Cada categoría tiene: id, nombre, descripción (opcional), slug 
  (generado del nombre), y timestamps.
  
  Necesito:
  1. Schema de Drizzle y migración
  2. Repository con CRUD completo
  3. Service con validación de negocio (nombre único, slug único)
  4. Routes: GET /categories, GET /categories/:id, POST /categories, 
     PUT /categories/:id, DELETE /categories/:id
  5. Tests para el service
  
  Sigue los patrones existentes del proyecto.

Claude Code va a:

  1. Leer los archivos existentes para entender los patrones (routes, services, repositories actuales)
  2. Planificar la implementación
  3. Crear cada archivo siguiendo las convenciones del proyecto
  4. Generar la migración de base de datos
  5. Escribir los tests

Después de implementar, puedes pedirle que ejecute los tests:

> Corre los tests para verificar que todo funciona

Claude Code ejecuta npm run test (o el comando que definiste en CLAUDE.md), ve los resultados, y si hay fallos, los arregla automáticamente.

Paso 5: Comandos Esenciales

Dentro de una sesión de Claude Code:

  • /compact — resume la conversación actual para liberar espacio en el context window. Esencial para sesiones largas.
  • /clear — limpia el historial de la conversación
  • /cost — muestra cuántos tokens has consumido en la sesión
  • /help — lista todos los comandos disponibles

Permisos: Claude Code te pedirá permiso antes de ejecutar comandos en la terminal o escribir archivos. Puedes configurar permisos más permisivos si confías en lo que está haciendo:

  • Presiona Allow para una acción individual
  • Presiona Allow always para permitir ese tipo de acción en el futuro

Paso 6: MCP (Model Context Protocol)

MCP permite conectar Claude Code a herramientas externas. Configura MCP servers en ~/.claude/claude_desktop_config.json o en .claude/settings.json de tu proyecto:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_URL": "tu-url",
        "SUPABASE_SERVICE_KEY": "tu-key"
      }
    }
  }
}

Con MCP configurado, Claude Code puede consultar tu base de datos directamente, leer schemas actuales, y generar código más preciso.

Algunos MCP servers útiles:

  • Supabase — acceso directo a tu base de datos
  • GitHub — crear issues, PRs, revisar código
  • Filesystem — acceso expandido a archivos fuera del proyecto
  • Brave Search — buscar documentación y soluciones en la web

Paso 7: Flujo de Trabajo de Debugging

Claude Code es excelente para debugging. Flujo práctico:

> El endpoint POST /products está devolviendo 500 cuando envío un 
  producto con precio decimal. Investiga el error, identifica la 
  causa, y corrígelo. Después agrega un test que cubra este caso.

Claude Code va a:

  1. Leer la ruta, el service, y el repository relevantes
  2. Identificar dónde se rompe (probablemente validación de tipos o parsing)
  3. Corregir el bug
  4. Escribir un test que reproduzca el caso
  5. Ejecutar los tests para confirmar que funciona

Paso 8: Hooks para Automatización

Los hooks ejecutan scripts antes o después de acciones de Claude Code. Configura en .claude/settings.json:

{
  "hooks": {
    "afterWrite": {
      "command": "npx biome check --write {{file}}"
    }
  }
}

Esto corre el linter automáticamente después de cada archivo que Claude Code escribe, asegurando que el formato siempre sea correcto.

Otros hooks útiles:

  • afterWrite — lint, format, validación de tipos
  • beforeCommit — correr tests antes de commitear
  • afterCommit — notificaciones, deploy preview

Errores Comunes

No crear CLAUDE.md. Sin contexto, Claude Code genera código genérico. Con un buen CLAUDE.md, genera código que se integra naturalmente con tu proyecto.

Sesiones demasiado largas sin /compact. El context window se llena y la calidad de las respuestas baja. Usa /compact regularmente en sesiones largas.

No dejar que ejecute tests. Claude Code es más efectivo cuando puede iterar: escribir código → correr tests → ver errores → corregir. Si no le das permiso para ejecutar comandos, pierde esta capacidad.

Pedir demasiado en un solo prompt. Para features grandes, divide en pasos. “Primero crea el schema y la migración” → verifica → “Ahora el repository y el service” → verifica → “Ahora las routes y los tests”.

Resultado

Tu flujo de trabajo con Claude Code:

  1. Abres la terminal en tu proyecto
  2. Claude Code lee CLAUDE.md y entiende tu contexto
  3. Le describes la tarea en lenguaje natural
  4. Él planifica, implementa, testea, y commitea
  5. Tú revisas los cambios y ajustas si es necesario

Es como tener un desarrollador junior muy rápido y disponible 24/7 que sigue tus convenciones al pie de la letra — siempre que le des un buen CLAUDE.md.

¿Ya usas Claude Code? Comparte tu CLAUDE.md y tus flujos de trabajo. :backhand_index_pointing_down: