Claude Code: Instalación, Configuración y Mejores Prácticas para Desarrollo con IA (Guía 2026)

Claude Code es la herramienta de terminal de Anthropic que lleva la inteligencia de Claude directamente a tu flujo de desarrollo. No es un chat, no es una IDE — es un agente de codificación en tu terminal que lee, entiende, edita y ejecuta código en tu proyecto.

En esta guía te enseño a instalarlo, configurarlo al máximo y aplicarle las mejores prácticas para que sea un multiplicador de productividad real, no un juguete.

1. ¿Qué es Claude Code?

Claude Code es un CLI agentic coding tool. A diferencia de Copilot (que autocompleta líneas) o ChatGPT (que genera bloques que copias y pegas), Claude Code:

🔍 Lee tu codebase completa — entiende el contexto del proyecto
✏️ Edita archivos directamente — no copias y pegas, él escribe
🖥️ Ejecuta comandos — tests, linting, builds, git
🔧 Debuggea — lee errores, propone y aplica fixes
📦 Gestiona dependencias — instala paquetes, actualiza configs

💡 La diferencia clave: Claude Code es un agente autónomo. Le dices "agrega autenticación JWT a mi API" y él solo explora tu proyecto, crea los archivos, modifica los existentes, instala dependencias y ejecuta los tests. Tú solo revisas el resultado.

2. Instalación

Requisitos previos

Node.js 18 o superior
npm o yarn
Git instalado y configurado
Una API Key de Anthropic (desde console.anthropic.com)

Instalación global

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

# Verificar
claude --version

Configurar la API Key

# Opción 1: Variable de entorno (recomendado)
export ANTHROPIC_API_KEY=sk-ant-api03-tu-clave-aqui

# Agregar a ~/.bashrc o ~/.zshrc para que persista
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-tu-clave-aqui' >> ~/.bashrc
source ~/.bashrc

También puedes usar OpenRouter, Amazon Bedrock o Google Vertex AI como proveedor — Claude Code soporta múltiples backends.

3. Configuración Avanzada

Archivo de configuración global (~/.claude.json)

{
  "model": "claude-sonnet-4-20250514",
  "maxThinkingTokens": 4000,
  "permissions": {
    "allowRead": true,
    "allowWrite": true,
    "allowExecute": true,
    "allowBash": true,
    "denyCommands": ["rm -rf", "git push --force", "sudo"]
  },
  "theme": "dark",
  "editor": "code"
}

Configuración por proyecto (.claude/settings.json)

{
  "contextLines": 200,
  "maxFilesToRead": 50,
  "allowedTools": ["Read", "Write", "Edit", "Bash", "Grep"],
  "instructions": "Usa TypeScript estricto. No uses any. Documenta funciones con JSDoc."
}

Variables de entorno útiles

# Modelo a usar
export CLAUDE_MODEL=claude-sonnet-4-20250514

# Máximo de tokens de pensamiento (razonamiento extendido)
export CLAUDE_MAX_THINKING_TOKENS=4000

# Directorio de trabajo
export CLAUDE_WORKDIR=/ruta/a/tu/proyecto

4. Uso Diario — Comandos Esenciales

Iniciar sesión en un proyecto

cd mi-proyecto
claude

# O directamente con un prompt
claude "Explícame la estructura de este proyecto"

Modos de trabajo

# Modo normal — Claude Code decide qué hacer
claude

# Modo pregunta — solo responde, no edita
claude --question "¿Qué hace el middleware de auth?"

# Modo plan — planifica sin ejecutar
claude --plan "Quiero migrar de Express a Fastify"

# Con un prompt directo
claude -p "Agrega rate limiting a todas las rutas GET"

Flags avanzadas

# Permitir todas las acciones sin pedir confirmación
claude --dangerously-skip-permissions

# Usar un modelo específico
claude --model claude-opus-4-20250514

# Salida en formato JSON (para scripts)
claude --output-json

5. Casos de Uso Reales

🧹 Refactorización Masiva

claude -p "Refactoriza todos los controladores para usar async/await en lugar de .then().catch(). Mantén los tests pasando."

🐛 Debugging

claude -p "El endpoint POST /api/users está devolviendo 500 en producción pero no en local. Analiza el código, encuentra la causa probable y arréglalo."

📝 Documentación

claude -p "Genera documentación JSDoc para todas las funciones públicas en src/services/. Sigue el estándar TSDoc."

✅ Tests

claude -p "Escribe tests unitarios con Vitest para el módulo src/auth/. Cubre todos los casos: éxito, error, edge cases."

🚀 Deploy y DevOps

claude -p "Genera un Dockerfile multi-stage optimizado para esta app Node.js y un docker-compose.yml con PostgreSQL y Redis."

6. Mejores Prácticas

✅ Haz esto

Commitea antes de usar Claude Code — trabaja en una rama separada. Si algo sale mal, git reset --hard y listo.
Sé específico en los prompts — "Agrega validación Zod al endpoint POST /api/orders con estos campos: email, items[], total" es 10x mejor que "Agrega validación".
Usa Claude Code en modo pregunta primero — déjalo explorar y entender antes de editar. Así evitas cambios innecesarios.
Configura reglas por proyecto — .claude/settings.json con las convenciones de tu equipo (estilo, patrones, restricciones).
Divide tareas grandes — no le pidas "hazme todo el backend". Pídele: 1) modelo de datos, 2) endpoints CRUD, 3) autenticación, 4) tests. Paso a paso.
Revisa los diffs — Claude Code es muy bueno, pero no perfecto. Siempre revisa con git diff antes de commitear.
Usa .claude/instructions para contexto persistente — estilo de código, reglas de negocio, patrones preferidos.

❌ No hagas esto

❌ No uses --dangerously-skip-permissions sin un commit previo.
❌ No pidas cambios en 50 archivos a la vez — difícil de revisar.
❌ No confíes ciegamente en cambios de seguridad (auth, crypto, permisos). Revísalos manualmente.
❌ No ignores los tests — pídele a Claude Code que corra los tests después de cada cambio.
❌ No compartas tu API key en repositorios públicos — usa variables de entorno o un gestor de secretos.

7. Integración con tu Flujo de Trabajo

Con Git Hooks

# .git/hooks/pre-commit
#!/bin/bash
echo "Ejecutando linting con Claude Code..."
claude -p "Ejecuta eslint en los archivos staged. Si hay errores, arréglalos." --dangerously-skip-permissions

Con GitHub Actions

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - run: claude -p "Revisa este PR. Encuentra bugs, problemas de seguridad y malas prácticas." --output-json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Combinado con n8n

Automatiza flujos con n8n: recibe un webhook de GitHub → ejecuta Claude Code para revisar el PR → publica el resultado como comentario automático.

8. Costos y Modelos

Modelo	Costo (input)	Costo (output)	Ideal para
Claude Haiku	$0.80/M tokens	$4/M tokens	Tareas rápidas, linting, refactors simples
Claude Sonnet 4	$3/M tokens	$15/M tokens	Desarrollo diario, debugging, features
Claude Opus 4	$15/M tokens	$75/M tokens	Arquitectura compleja, migraciones grandes

Dato real: una sesión típica de desarrollo con Sonnet consume ~50K tokens (~$0.50 USD). Un feature completo puede costar $2-5 USD en tokens. Mucho más barato que el tiempo de un desarrollador senior.

9. Conclusión

Claude Code no reemplaza al desarrollador — lo multiplica. Las tareas mecánicas (boilerplate, tests, refactors, documentación) pasan de horas a minutos. El desarrollador se enfoca en arquitectura, decisiones de diseño y revisión.

Para empezar hoy:

Instala: npm install -g @anthropic-ai/claude-code
Configura tu API key
Entra a tu proyecto y escribe: claude "explícame este proyecto"
Deja que te sorprenda

¿Ya usas Claude Code en tu día a día? Cuéntame tu experiencia en los comentarios 👇