Claude Code: Guía Definitiva para Desarrolladores (2026)

Claude Code es la herramienta de Anthropic que convierte tu terminal en un agente autónomo de programación. A diferencia de un chatbot, puede leer tu codebase completo, editar archivos, ejecutar comandos y hacer commits en Git — todo desde la línea de comandos, sin cambiar de herramienta.

En esta guía encontrarás todo lo que necesitas para empezar y dominar Claude Code: instalación, workflow, slash commands, hooks avanzados, integración con MCP y comparativa honesta con Cursor y GitHub Copilot.

Qué es Claude Code

Claude Code es un agente de programación basado en IA desarrollado por Anthropic que opera directamente desde la terminal. No es un chatbot ni un plugin para editores — es un proceso autónomo que puede leer, modificar y ejecutar código en tu proyecto sin intervención constante.

Cuando le das una instrucción, sigue un bucle de tres fases que se repite hasta completar la tarea:

1. Recopilar contexto: lee los archivos relevantes, revisa el historial de Git, busca patrones en el código.
2. Tomar acción: edita archivos, ejecuta comandos, corre tests.
3. Verificar resultados: comprueba que los cambios funcionan y corrige si algo falla.

Si le dices «arregla los tests que están fallando», Claude Code ejecuta la suite de tests, lee los errores, localiza los archivos involucrados, aplica el fix y vuelve a correr los tests para confirmar que funciona. Sin que muevas un dedo.

La arquitectura es sencilla: hay un modelo de lenguaje (Claude Sonnet o Opus) que razona, y hay un conjunto de herramientas que le permiten actuar sobre el sistema de archivos, la terminal y Git.

Cómo instalar Claude Code

Requisitos previos

• Node.js 18 o superior (o macOS/Linux/WSL)
• Cuenta en Anthropic con plan Pro, Max, Teams o acceso a la API
• Conexión a internet

Nota para Windows: Claude Code requiere WSL (Windows Subsystem for Linux). No hay soporte nativo para PowerShell.

Instalación

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | sh

# O vía npm (sigue siendo compatible)
npm install -g @anthropic-ai/claude-code

Autenticación

La primera vez que ejecutas claude, abre el navegador para iniciar sesión con tu cuenta de Anthropic. El token se guarda localmente.

Si usas la API directamente (pago por uso):

export ANTHROPIC_API_KEY=sk-ant-xxxxx

Primer uso

cd mi-proyecto
claude

Claude Code cargará el contexto del directorio y quedará listo para recibir instrucciones.

Cómo usar Claude Code — workflow completo

Modo interactivo vs one-shot

Claude Code tiene dos modos de operación:

• Modo interactivo: ejecutas claude y tienes una sesión conversacional. Puedes hacer follow-up, pedir correcciones, y mantener contexto entre mensajes.
• One-shot: ejecutas claude -p "tu instrucción" para una tarea puntual sin sesión interactiva. Útil para scripts y automatizaciones.

Slash commands esenciales

El archivo CLAUDE.md: instrucciones persistentes

El archivo CLAUDE.md en la raíz del proyecto contiene instrucciones que Claude Code lee al inicio de cada sesión. Úsalo para definir convenciones del proyecto, stack tecnológico, reglas de estilo y contexto que no quieres repetir cada vez.

# CLAUDE.md

## Stack
- Backend: Python 3.12 + FastAPI
- DB: PostgreSQL 16 + SQLAlchemy 2.0
- Tests: pytest

## Convenciones
- Nombres de funciones en snake_case
- Sin comentarios obvios — solo si el WHY no es evidente
- Siempre correr tests antes de proponer un commit

## Comandos útiles
- Tests: `pytest -x -v`
- Lint: `ruff check src/`

Permisos y modos de ejecución

Por defecto, Claude Code te pide confirmación antes de editar archivos o ejecutar comandos. Puedes cambiar este comportamiento:

• Shift+Tab: alterna entre modo manual (confirmar todo), auto-edits (edita sin pedir, confirma ejecución) y solo lectura.
• Archivo .claude/settings.json: configura permisos granulares por comando o herramienta.

Claude Code tips y trucos avanzados

Optimizar costes con model switching

Usa /model para cambiar de modelo según la complejidad de la tarea:

• Claude Sonnet: tareas de mediana complejidad, refactorizaciones, fixes de bugs. Más rápido y barato.
• Claude Opus: diseño de arquitectura, análisis complejo, decisiones críticas. Más potente pero más lento y caro.

Una estrategia común: empezar con Sonnet y cambiar a Opus solo cuando la tarea lo requiera.

Git workflow con Claude Code

# Pedir a Claude Code que implemente una feature completa
claude -p "Implementa autenticación JWT en src/auth/. 
Usa python-jose para los tokens. Añade tests en tests/test_auth.py. 
Haz commit con un mensaje descriptivo cuando esté listo."

# Revisar un PR
claude -p "Revisa el diff de este PR y dame feedback sobre seguridad y calidad"

Multi-file editing patterns

Claude Code brilla cuando los cambios afectan múltiples archivos. Instrucciones que funcionan bien:

• «Renombra la función process_data a transform_records en todos los archivos donde aparezca»
• «Migra todos los endpoints de Flask a FastAPI manteniendo la misma API»
• «Añade logging a todas las funciones del módulo src/payments/»

Debugging con Claude Code

# Pasar el error directamente
claude -p "$(npm run build 2>&1)"

# O en sesión interactiva
claude
> Corre los tests y analiza los errores: $(pytest -x 2>&1 | tail -50)

Claude Code Hooks: automatiza tu workflow

Los hooks permiten ejecutar comandos automáticamente en respuesta a acciones de Claude Code. Se configuran en .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{"type": "command", "command": "npm run lint:fix"}]
      }
    ],
    "Stop": [
      {
        "hooks": [{"type": "command", "command": "npm run test:changed"}]
      }
    ]
  }
}

Casos de uso habituales para hooks:

• Formatear código automáticamente después de cada edición
• Correr tests de los archivos modificados al terminar
• Enviar notificación cuando Claude Code completa una tarea larga

Integración con MCP (Model Context Protocol)

El Model Context Protocol (MCP) permite extender Claude Code conectándolo a servicios externos: bases de datos, APIs, sistemas de documentación, herramientas de monitoreo.

Para añadir un MCP server al proyecto:

# Añadir server de GitHub
claude mcp add github-server -s user -- npx @modelcontextprotocol/server-github

# Añadir server de PostgreSQL
claude mcp add postgres -s project -- node /path/to/postgres-mcp --connection-string $DATABASE_URL

Una vez configurado, Claude Code puede interactuar con esos servicios directamente desde la conversación sin herramientas adicionales.

Claude Code vs Cursor vs GitHub Copilot

La mayoría de desarrolladores en 2026 no eligen uno — los combinan. Cursor o Copilot para el trabajo en el editor, Claude Code para tareas que requieren autonomía y múltiples archivos.

→ Comparativa detallada: Claude Code vs Cursor AI

Cuánto cuesta Claude Code

Para uso casual o probar antes de suscribirse, la API por uso es la opción más económica (~$0.05 por sesión corta). Para uso intensivo diario, el plan Max $100 es más rentable.

Preguntas frecuentes

¿Claude Code es gratuito?

No. Requiere al menos el plan Pro de Anthropic ($20/mes) o acceso a la API. No existe tier gratuito para el agente de terminal.

¿Cómo hacer que Claude Code acepte todo automáticamente?

Usa el modo auto-edits: pulsa Shift+Tab hasta seleccionarlo, o configura "autoAcceptEdits": true en .claude/settings.json. También puedes usar el flag --dangerously-skip-permissions en entornos CI donde confías totalmente en el código.

¿Funciona Claude Code en Windows?

Sí, pero requiere WSL2 (Windows Subsystem for Linux). No hay soporte nativo para PowerShell o cmd.

¿Es seguro darle acceso al terminal a Claude Code?

Claude Code tiene un sistema de permisos que pide confirmación antes de ejecutar comandos destructivos. Puedes configurar exactamente qué comandos puede ejecutar sin pedir permiso desde .claude/settings.json. Para entornos críticos, usa el modo de solo lectura o configura los permisos con granularidad.

¿Qué modelo usa Claude Code por defecto?

En 2026, el modelo por defecto es Claude Sonnet 4.6. Puedes cambiar a Opus con /model dentro de una sesión.

¿Claude Code funciona offline?

No. Claude Code requiere conexión a internet para comunicarse con la API de Anthropic. No hay modo offline.