Qué es Claude Code y cómo usarlo: guía en español

Publicado el 3 de junio de 2026 · Actualizado el 22 de septiembre de 2026 · 14 min de lectura · Por Jorge Fernández Águila · Blog MasterEnClaude

Si has probado GitHub Copilot o ChatGPT para programar, Claude Code es otra categoría: en lugar de completar líneas o responder preguntas, toma un objetivo en lenguaje natural y trabaja de forma autónoma hasta conseguirlo. Esta guía explica cómo funciona, cómo se instala y las cinco piezas que marcan la diferencia entre usarlo «para probar» y usarlo de verdad: CLAUDE.md, hooks, subagentes y skills, MCP y el modo no interactivo.

¿Cómo funciona Claude Code por dentro?

Claude Code es un agente construido sobre los modelos de Anthropic (Claude Sonnet 5 y Opus 5 por defecto). En cada turno, el modelo recibe la conversación más un conjunto de herramientas con las que actúa sobre tu máquina:

• Leer y editar ficheros: abre cualquier fichero del proyecto y cambia exactamente las líneas que hacen falta.
• Bash: ejecuta comandos de terminal (instalar, compilar, lanzar tests), siempre con tu permiso salvo que lo autorices de antemano.
• Búsqueda en el código: localiza funciones, patrones y ficheros sin que tengas que decirle dónde están.
• Web: consulta documentación y páginas en línea.
• Servidores MCP: se conecta a cualquier herramienta externa que registres (GitHub, bases de datos, Slack…).

El agente decide qué herramientas usar y en qué orden, y va corrigiendo su plan con lo que observa. Es un bucle de razonar → actuar → observar que continúa hasta completar la tarea o hasta que te pregunta algo.

Instalación en macOS, Linux y Windows

La forma más habitual sigue siendo el paquete de npm (necesitas Node.js 18 o superior); también existe un instalador nativo que no depende de Node:

# Opción A: con npm
npm install -g @anthropic-ai/claude-code

# Opción B: instalador nativo (macOS y Linux)
curl -fsSL https://claude.ai/install.sh | bash

# Comprueba la instalación
claude --version

Entra en la carpeta de tu proyecto y escribe claude. La primera vez te pedirá iniciar sesión: puedes usar tu cuenta de Claude (los planes Pro y Max incluyen Claude Code) o una clave de API de la consola de Anthropic, con pago por uso. Dentro de la sesión, el comando /init crea un primer CLAUDE.md a partir de lo que ve en tu proyecto.

El fichero CLAUDE.md: instrucciones para tu agente

Cuando Claude Code arranca en un directorio, busca un fichero CLAUDE.md y carga su contenido como contexto persistente. Es el «manual de a bordo» de tu proyecto, versionado junto al código: convenciones, comandos, arquitectura y lo que el agente no debe tocar.

Un buen CLAUDE.md incluye:

# Mi Proyecto — Contexto para Claude Code

## Arquitectura
- Backend: FastAPI (Python 3.11)
- Base de datos: PostgreSQL 15 con SQLAlchemy
- Frontend: React 18 + TypeScript
- Deploy: Railway (backend) + Vercel (frontend)

## Convenciones de código
- Nombres en snake_case (Python) y camelCase (TypeScript)
- Siempre type hints en Python
- Los tests van en /tests con el prefijo test_
- Nunca hacer commits directamente a main

## Comandos frecuentes
- make dev  — levanta el entorno de desarrollo
- make test — ejecuta la suite de tests
- make lint — flake8 + mypy

## Lo que NO debe hacer Claude
- Modificar ficheros de migraciones directamente
- Cambiar variables de entorno en producción
- Instalar dependencias sin preguntar

Con un CLAUDE.md bien escrito puedes arrancar Claude Code en cualquier máquina y el agente entenderá de inmediato las reglas del juego. Hay tres niveles: uno global en ~/.claude/CLAUDE.md (tus preferencias), uno por proyecto (compartido con el equipo) y uno local que no se sube al repositorio.

Hooks: automatización en puntos clave del flujo

Los hooks son comandos que se ejecutan solos en momentos concretos del trabajo del agente: antes de usar una herramienta, después, cuando termina, cuando envías un mensaje… Se configuran en .claude/settings.json del proyecto (o en el global del usuario). Cada hook recibe por la entrada estándar un JSON con el nombre de la herramienta y sus parámetros, y puede bloquear la acción devolviendo el código de salida 2.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -I{} prettier --write {} 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code ha terminado\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

En este ejemplo, cada vez que Claude edita o crea un fichero, el hook lee la ruta del JSON y pasa Prettier; y cuando el agente termina, el Mac muestra una notificación. Los hooks son la forma de imponer reglas que no dependen de que el modelo «se acuerde»: formateo, linters, pruebas obligatorias o vetos a comandos peligrosos.

Subagentes y skills: Claude Code orquestando Claude Code

Claude Code puede delegar partes de una tarea en subagentes: instancias con su propio contexto, sus propias herramientas y unas instrucciones fijas. Se definen como ficheros Markdown en .claude/agents/ y el agente principal los invoca cuando la descripción encaja con lo que tiene entre manos:

---
name: revisor-seguridad
description: Revisa código en busca de vulnerabilidades. Úsalo antes de cada commit.
tools: Read, Grep, Bash
---
Eres un revisor de seguridad. Busca inyección SQL, secretos en el código
y validación de entrada insuficiente. Devuelve una lista con fichero y línea.

Las skills y los comandos personalizados funcionan de forma parecida: un fichero Markdown en .claude/skills/ o .claude/commands/ con un procedimiento (por ejemplo, «cómo desplegamos en producción») que se invoca escribiendo /nombre. Es la manera de convertir el conocimiento del equipo en algo que el agente ejecuta igual cada vez.

Y cuando quieres paralelizar de verdad, puedes lanzar varias sesiones no interactivas desde un script:

import subprocess, concurrent.futures

def revisar(modulo):
    r = subprocess.run(
        ["claude", "-p", f"Revisa {modulo} y lista posibles bugs de seguridad"],
        capture_output=True, text=True, cwd="/mi-proyecto")
    return modulo, r.stdout

with concurrent.futures.ThreadPoolExecutor(max_workers=2) as ex:
    for modulo, informe in ex.map(revisar, ["src/auth.py", "src/payments.py"]):
        print(f"--- {modulo} ---\n{informe}")

Integración con MCP: Claude Code con superpoderes

Claude Code soporta de forma nativa el Model Context Protocol (MCP). Registrando servidores MCP le das acceso a sistemas externos: tu base de datos en modo lectura, la API de GitHub para gestionar issues, Slack para avisar de avances, o cualquier herramienta que use tu equipo.

# Registrar un servidor MCP (GitHub, por ejemplo)
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Ver los servidores configurados
claude mcp list

# Usarlo en una tarea
claude "Lista los últimos 5 issues abiertos del repo y propón un plan de priorización"

Para entender MCP en profundidad, lee el artículo dedicado: ¿Qué es MCP (Model Context Protocol)? Guía en español.

Modo no interactivo y automatización en CI/CD

Con el flag -p (o --print) Claude Code ejecuta una tarea y devuelve el resultado sin abrir la sesión interactiva, así que puedes usarlo en scripts, cron y pipelines. Lo que le pases por la entrada estándar forma parte del contexto:

# Revisar los cambios de una rama
git diff main...HEAD | claude -p "Revisa este diff y devuelve una lista de posibles bugs"

# Generar un changelog con los commits de la semana
git log --since="1 week ago" --oneline | claude -p "Escribe un CHANGELOG.md con estos commits"

# Salida en JSON para encadenar con otras herramientas
claude -p "Resume los TODO del proyecto" --output-format json

Para GitHub hay una integración oficial (la acción de Claude Code) que responde a menciones en issues y pull requests; se instala desde la propia sesión con /install-github-app.

Cuándo usar Claude Code y cuándo la interfaz web de Claude

• Usa claude.ai (web): para conversaciones generales, preguntas puntuales, redacción y análisis de documentos.
• Usa Claude Code: cuando necesitas que el agente actúe sobre tu código o tu sistema: refactorizar módulos, escribir tests, ejecutar comandos o automatizar un flujo que toca ficheros y terminal.

La combinación más potente es usar la API de Claude en tus propias aplicaciones y Claude Code en tu proceso de desarrollo. Así tienes IA tanto en el producto que construyes como en la forma de construirlo.

Primeros pasos recomendados

1. Instala Claude Code y arráncalo en tu proyecto más importante.
2. Escribe /init y completa el CLAUDE.md con tus convenciones y tus comandos.
3. Prueba una tarea real: «añade tests unitarios para el módulo X» o «refactoriza esta función para que sea más legible».
4. Configura un hook (el de notificación al terminar se agradece en tareas largas).
5. Conecta un servidor MCP a la herramienta que más uses.

Preguntas frecuentes sobre Claude Code