Claude Code desde cero: tutorial en español para instalarlo y usarlo bien

Claude Code es el agente de programación de Anthropic: lee tu proyecto, edita archivos, ejecuta comandos y trabaja con git a partir de lo que le pides en lenguaje normal. Se instala con un solo comando en macOS, Linux o Windows y necesita un plan de pago de Claude (desde 17 dólares al mes) o una cuenta de la API. Este tutorial te lleva de la instalación a los subagentes, los hooks y MCP, con los datos de la documentación oficial a 8 de octubre de 2026 (versión 2.1.294).

Un detalle antes de empezar: esta revista se ha construido con Claude Code. Algunos ejemplos de esta guía salen de ese trabajo y lo indicamos cuando es así.

Qué es Claude Code y dónde funciona

Anthropic lo define como «una herramienta de codificación agéntica que lee tu base de código, edita archivos, ejecuta comandos y se integra con tus herramientas de desarrollo». No le pegas código como en un chat: trabaja dentro de tu carpeta, decide qué archivos mirar y comprueba lo que hace. Es un agente de IA en sentido estricto.

Funciona en la terminal (la versión completa), como extensión de VS Code y de Cursor, como plugin de JetBrains (con la CLI instalada aparte), en la pestaña Code de la app de escritorio de Claude y en la web, en claude.ai/code, donde lanza tareas en la nube. Todas leen la misma configuración del proyecto. Este tutorial se centra en la terminal, porque es donde están todas las opciones.

Qué necesitas y cuánto cuesta

Requisitos de la página de instalación: macOS 13 o posterior, Windows 10 1809 o posterior, Ubuntu 20.04, Debian 10 o Alpine 3.19, al menos 4 GB de RAM y conexión a internet. Funciona en los países donde Anthropic da servicio, España incluida.

Y una cuenta que lo incluya. Precios de claude.com/pricing y del centro de ayuda, en dólares y sin impuestos, a 8 de octubre de 2026:

El pago anual de Pro son 200 dólares por adelantado. Los multiplicadores de Max se miden por sesión de 5 horas, y todos los planes de pago tienen además un límite semanal. En los planes de suscripción, Claude Code comparte cupo con el chat: si gastas mucho en la terminal, te queda menos para conversar. Cuando llegas al límite, esperas a que se renueve, subes de plan o activas créditos de uso.

Si vas por API, Opus 5.5 cuesta 4 dólares por millón de tokens de entrada y 20 por millón de salida, y Sonnet 5.5, 2 y 10. Para hacerte una idea, la propia Anthropic publica que en empresas el gasto medio ronda los 13 dólares por desarrollador y día de uso, y que el 90 % de los usuarios se queda por debajo de 30. Tienes el cálculo detallado en cuánto cuesta usar la IA por API.

Nuestro criterio: Pro basta para aprender y para proyectos personales. Si te quedas sin cupo varios días por semana, el siguiente paso es Max 5x. La API compensa sobre todo para automatizaciones y uso irregular.

Cómo se instala Claude Code

El método recomendado es el instalador nativo, que se actualiza solo en segundo plano. Abre una terminal y ejecuta el comando de tu sistema.

En macOS, Linux o WSL:

curl -fsSL https://claude.ai/install.sh | bash

En Windows con PowerShell (el indicador empieza por PS C:\):

irm https://claude.ai/install.ps1 | iex

En Windows con CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

También hay Homebrew (brew install --cask claude-code), WinGet (winget install Anthropic.ClaudeCode), apt, dnf, apk y npm (con Node.js 22 o posterior, y nunca con sudo). Esos métodos no se actualizan solos.

En Windows conviene instalar antes Git para Windows: Claude Code usa su Bash para ejecutar comandos. Sin él, tira de PowerShell.

Comprueba que ha ido bien abriendo una terminal nueva:

claude --version
claude doctor

El primero imprime algo como 2.1.294 (Claude Code). El segundo revisa la instalación y los archivos de configuración sin abrir sesión, y te dice qué arreglar si algo falla.

Primer uso: de la primera pregunta al primer commit

Entra en la carpeta de un proyecto y arranca:

cd ~/proyectos/mi-web
claude

La primera vez se abre el navegador para iniciar sesión con tu cuenta de Claude o de la consola. Después ya no lo pide.

No empieces pidiendo cambios. Pregunta primero: no tiene riesgo y te enseña cómo entiende tu código:

¿Qué hace este proyecto y cómo está organizado?
¿Dónde se gestiona el inicio de sesión? Explícame el flujo.

Para referirte a un archivo concreto, escribe @ y su ruta: @src/auth/login.ts. Claude lo lee antes de contestar. También puedes pegar capturas de pantalla o pasarle un log por tubería: cat error.log | claude -p "explica este error".

Luego, un cambio pequeño y verificable:

En @src/utils/fechas.ts, la función formatearFecha falla con fechas
nulas. Escribe un test que lo reproduzca, arréglala y ejecuta los tests.

Y por último, git, que Claude Code maneja de forma conversacional:

Enséñame qué ha cambiado y haz un commit con un mensaje descriptivo.

Para que conteste siempre en español, añade "language": "spanish" a tu ~/.claude/settings.json. Si le escribes en español ya lo hace; el ajuste lo fija y traduce también los títulos de las sesiones.

Los modos de permisos: qué puede hacer sin preguntarte

Es lo más importante del tutorial: Claude Code puede borrar, instalar y publicar. Los modos de permisos vigentes son seis:

Algunos matices que no caben en la tabla. acceptEdits aprueba también comandos de archivos como mkdir, mv o cp, siempre dentro del proyecto. En plan, Claude investiga y propone, pero no edita nada hasta que apruebas el plan. En dontAsk, todo lo que no hayas aprobado de antemano se deniega sin preguntar. Y en auto, el clasificador es un segundo modelo que revisa cada acción antes de que se ejecute.

Desde la versión 2.1.283, el modo de arranque en la terminal y en VS Code es auto. En él, ese clasificador bloquea por defecto cosas como descargar y ejecutar código (curl | bash), los despliegues a producción, los git push --force o borrar archivos que ya existían. La propia documentación avisa de que reduce las preguntas «pero no garantiza la seguridad».

Se cambia de modo con Shift+Tab durante la sesión. Desde auto, el ciclo va a Manual, luego a acceptEdits, luego a plan y vuelve. Para arrancar en uno concreto:

claude --permission-mode plan

Encima de los modos van las reglas. Este ejemplo, sacado de la documentación, deja pasar el lint y los tests sin preguntar y le prohíbe leer tus archivos .env:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

Las reglas deny se aplican en todos los modos, incluido bypassPermissions. Van en ~/.claude/settings.json (para ti en todos los proyectos), en .claude/settings.json (para todo el equipo) o en .claude/settings.local.json (para ti en ese proyecto). Si un secreto se te escapa de todas formas, en qué hacer si se filtra una clave de API tienes los pasos.

CLAUDE.md: las instrucciones que lee en cada sesión

CLAUDE.md es un archivo Markdown que Claude Code carga al empezar cada sesión. Sirve para lo que tendrías que repetirle siempre: cómo se compila y se prueba el proyecto, las convenciones, lo que no debe tocar. Hay tres niveles. ~/.claude/CLAUDE.md guarda tus preferencias para todos tus proyectos. CLAUDE.md (o .claude/CLAUDE.md) en la raíz del proyecto lleva las reglas del proyecto y se comparte por git. Y CLAUDE.local.md es para lo tuyo en ese proyecto: añádelo a .gitignore.

El comando /init analiza tu código y genera uno inicial. Luego hay que podarlo: la documentación recomienda menos de 200 líneas por archivo, porque los largos «consumen más contexto y reducen la adherencia». La prueba que propone Anthropic para cada línea es preguntarte si quitarla haría que Claude se equivocara. Si no, fuera.

Si tu repositorio ya tiene un AGENTS.md (el formato abierto que leen Codex, Cursor, Copilot y otros), Claude Code lo lee directamente desde la versión 2.1.277 cuando no hay CLAUDE.md. Si tienes los dos, una línea con @AGENTS.md dentro de tu CLAUDE.md lo importa y te evita mantener dos copias.

Además, Claude Code tiene memoria automática: guarda notas sobre tus correcciones y preferencias en ~/.claude/projects/<proyecto>/memory/ y carga el índice en cada sesión. Se revisa y se desactiva con /memory.

Un CLAUDE.md real: el de esta revista

El CLAUDE.md con el que trabajamos en Metix tiene unas 70 líneas. Esta es su estructura, con fragmentos casi literales (solo hemos quitado datos internos):

# Metix: lo que hay que saber antes de tocar nada

| Archivo | Qué contiene |
|---|---|
| `docs/SEO.md` | El mapa de palabras clave: qué artículo es dueño de qué búsqueda |
| `docs/DECISIONES.md` | Registro con fecha de lo que se decidió y por qué |

## Reglas que no se saltan
1. Desplegar a producción se pide, no se decide.
2. Nada de texto con pinta de IA. [...] `tools/revisar-articulos.mjs`
   corta el build si encuentra lo prohibido.
3. Ningún artículo sin su `clave` en el mapa de `docs/SEO.md`.
7. Git: al cerrar cada bloque de trabajo, commit explicando el porqué.
   Nunca `--force`. Antes de un cambio arriesgado, commit.

## Estado (actualizar al cerrar cada sesión de trabajo)

Tres decisiones de ese archivo que puedes copiar. El archivo no explica el proyecto: apunta a los documentos que lo explican, así que no crece sin control. Las reglas que importan de verdad no se quedan en el texto: las comprueba un script en cada build (el que prohíbe los guiones largos, por ejemplo), y Claude puede saltarse una instrucción, pero no un build que falla. Y la sección de estado se actualiza al acabar, para que la sesión siguiente sepa dónde se quedó la anterior.

Los comandos con barra que vas a usar

Escribe / en la sesión y verás la lista completa (referencia oficial). Estos son los que más se usan, en el orden en que suelen aparecer en una tarea.

Al llegar a un proyecto, /init genera un CLAUDE.md inicial analizando el código. Antes de un cambio grande, /plan entra en modo plan, y /plan arregla el login empieza ya con la tarea. /model y /effort cambian el modelo y cuánto razona.

Para el contexto tienes tres: /clear abre una conversación nueva con el contexto vacío, /compact resume la conversación para liberar espacio y /context enseña qué está llenando la ventana. Si algo sale mal, /rewind vuelve atrás la conversación, el código o ambos.

Antes de dar un cambio por bueno, /diff enseña los cambios del árbol de trabajo, y /code-review y /security-review revisan el diff buscando errores o fallos de seguridad. Y para el resto: /mcp y /hooks gestionan servidores MCP y hooks, /usage dice cuánto llevas gastado del plan o de la API, y /resume recupera una conversación anterior.

Y tres teclas: Esc para Claude en seco sin perder el contexto, Esc dos veces abre el menú de /rewind, y Shift+Tab cambia de modo de permisos.

Qué modelo usa y cómo cambiarlo

El modelo por defecto, con suscripción o con API, es Claude Opus 5.5 con esfuerzo medio. Con /model cambias entre los alias opus (Opus 5.5), sonnet (Sonnet 5.5, más barato por token), haiku (Haiku 5.5, para tareas simples) y fable (Fable 5.1, el más capaz, que en Pro se paga aparte con créditos de uso). Con /effort ajustas cuánto razona, de low a max: más esfuerzo es más lento y gasta más cupo. Detalles en la configuración de modelos.

Subagentes: trabajo aparte sin llenar tu contexto

Un subagente es otra instancia de Claude con su propia ventana de contexto, sus instrucciones y sus herramientas. Sirve para que una búsqueda que lee decenas de archivos no llene tu conversación: investiga y te devuelve un resumen. Claude Code trae varios de serie (Explore, de solo lectura, y Plan, entre otros) y los usa por su cuenta.

Puedes crear los tuyos como archivos Markdown en .claude/agents/ (del proyecto) o ~/.claude/agents/ (tuyos). Siguiendo el formato de la documentación:

---
name: revisor-seguridad
description: Revisa el código buscando fallos de seguridad. Úsalo después de cambios en autenticación o en la API.
tools: Read, Grep, Glob
model: opus
---
Eres un revisor de seguridad. Busca inyecciones, fallos de
autorización y secretos en el código. Indica archivo y línea
de cada problema y propón el arreglo.

Al no tener Edit ni Bash en tools, este revisor no puede cambiar nada: solo leer. Claude lo llama solo cuando la descripción encaja, o se lo pides tú: «usa el subagente revisor-seguridad con los cambios de hoy».

Hooks: lo que tiene que pasar siempre

Un hook es un comando de terminal que Claude Code ejecuta en un momento fijo: antes de usar una herramienta (PreToolUse), después (PostToolUse), al terminar de responder (Stop), al empezar la sesión (SessionStart)… La diferencia con CLAUDE.md es clave: una instrucción es una sugerencia que el modelo puede olvidar; un hook se ejecuta siempre.

Este ejemplo de la guía oficial de hooks pasa Prettier a cada archivo que Claude edita. Va en .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Para bloquear una acción, el hook termina con exit 2. La guía trae un script que así impide editar .env o la carpeta .git/; Claude recibe el motivo y busca otro camino. Y no hace falta escribirlos a mano: pídeselo a Claude («escribe un hook que pase eslint después de cada edición»).

MCP: conectar Claude Code con tus herramientas

MCP es el protocolo abierto con el que Claude Code habla con servicios externos: Notion, Sentry, GitHub, tu base de datos. Si no lo conoces, empieza por MCP explicado. En Claude Code se añaden servidores con un comando:

# Servidor remoto (el método recomendado)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Compartido con todo el equipo: se guarda en .mcp.json
claude mcp add --transport http --scope project sentry https://mcp.sentry.dev/mcp

El ámbito por defecto es local (solo tú, en ese proyecto). Con --scope project se guarda en .mcp.json para todo el equipo, y con --scope user lo tienes en todos tus proyectos. Dentro de la sesión, /mcp muestra el estado de cada servidor y gestiona los inicios de sesión.

Conecta solo servidores de los que te fíes (los que traen contenido externo te exponen a inyección de instrucciones), da a las bases de datos un usuario de solo lectura y no subas claves dentro de .mcp.json: GitGuardian contó más de 24.000 secretos expuestos en configuraciones MCP públicas.

Errores habituales al empezar

• command not found: claude después de instalar. La carpeta del instalador no está en el PATH. Abre una terminal nueva; si sigue, la guía de problemas de instalación tiene el arreglo por sistema. En Windows, si ves 'irm' is not recognized, estás en CMD y no en PowerShell.
• Quedarte sin cupo a mitad de tarea. Los límites van por ventanas de 5 horas más un tope semanal. /usage te dice cuánto llevas.
• La sesión cajón de sastre. Mezclar tareas sin relación llena el contexto de ruido. /clear entre tareas.
• Fiarte de que «ya está». Pide siempre la prueba: la salida de los tests, el comando que ejecutó, una captura. Si no se puede verificar, no se publica.
• Usar /rewind como si fuera git. Los puntos de control solo guardan lo que Claude edita con sus herramientas, no lo que cambia un comando de Bash. Haz commit.

Por dónde seguir

Con esto ya puedes trabajar. Para el método completo (cómo plantear tareas, revisar diffs, cuándo usar un agente y cuándo no) sigue con la guía para programar con IA. Si dudas entre Claude Code y otras opciones, tienes la comparativa de Claude Code, Cursor, Codex y Copilot. Y para no perder el control del proyecto cuando el agente escribe la mayor parte, los hábitos para programar con IA.