Claude Code: guía completa en español, de cero a un flujo de trabajo serio

Claude Code es el agente de programación de Anthropic: lo abres en una carpeta, le pides algo en lenguaje normal y él lee el código, edita ficheros, ejecuta comandos y comprueba el resultado, pidiéndote permiso según el modo que elijas. Para usarlo necesitas un plan de pago de Claude (desde 20 $ al mes) o una cuenta de API, y se instala con un solo comando en Windows, Mac o Linux.

En esta guía tienes la instalación actual, tu primera sesión paso a paso, los modos de permisos, los comandos que de verdad usamos y cómo pasar de «probarlo» a trabajar con él a diario. Lo contamos desde nuestro caso: en GamzyHost lo usamos todos los días como motor de Jarvis, un asistente propio que vive en una VPS con Windows Server 2022.

Qué es Claude Code y en qué se diferencia del chat#

En el chat de Claude tú haces de manos: copias el error, pegas el código, copias la respuesta y la llevas a tu editor. En Claude Code el modelo tiene herramientas. Puede abrir cualquier fichero de la carpeta, buscar en todo el proyecto, editar, lanzar los tests y leer lo que devuelven. Tú dices qué quieres y revisas.

La diferencia práctica es el bucle. Un agente no responde una vez: lee, decide, actúa, mira qué ha pasado y vuelve a empezar hasta que lo da por bueno o necesita preguntarte.

Desliza para ver la figura completa

Claude Code no es solo la terminal. La documentación oficial lo ofrece también como extensión de VS Code, plugin de JetBrains, app de escritorio y en el navegador (claude.ai/code). Todas usan el mismo motor, así que tus CLAUDE.md, ajustes y servidores MCP valen en todas. Esta guía se centra en la terminal, que es lo que usamos y la superficie más completa.

Qué necesitas y cuánto cuesta#

Requisitos oficiales, comprobados el 16 de octubre de 2026:

• Sistema: macOS 13 o posterior, Windows 10 1809+ o Windows Server 2019+, Ubuntu 20.04+, Debian 10+ o Alpine 3.19+.
• Máquina: 4 GB de RAM o más, procesador x64 o ARM64, conexión a internet.
• Terminal: Bash, Zsh, PowerShell o CMD.
• Cuenta: Pro, Max, Team, Enterprise o una cuenta de Console (API). El plan gratuito de claude.ai no incluye Claude Code.

Nuestro criterio: empieza con Pro. Si en una semana normal te topas con el límite casi a diario y te corta el trabajo, sube a Max 5x. Max 20x tiene sentido cuando hay sesiones largas en paralelo o un agente trabajando solo muchas horas, como nuestro Jarvis. Los precios cambian y hay matices (impuestos, precio en la app móvil): los detallamos en la guía de precios de Claude.

Instalar Claude Code en Windows, Mac y Linux#

El método recomendado hoy es el instalador nativo. No necesitas Node.js y se actualiza solo en segundo plano. El paquete de npm sigue existiendo, pero la documentación lo deja como opción avanzada.

Windows (lo que usamos)#

1. Abre PowerShell (el prompt empieza por PS C:\). No hace falta ser administrador.
2. Ejecuta:

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

3. El instalador no muestra progreso mientras descarga. Cuando acabe, abre una terminal nueva y comprueba:

claude --version

En nuestra VPS devuelve 2.1.283 (Claude Code) y el ejecutable queda en C:\Users\<usuario>\.local\bin\claude.exe. Si te dice que claude no se reconoce, esa carpeta no está en el PATH: abre otra terminal o revisa la guía oficial de problemas de instalación.

Si usas CMD en vez de PowerShell, el comando es otro:

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

También hay winget install Anthropic.ClaudeCode, pero esa vía no se actualiza sola.

Mac y Linux (no probado por nosotros)#

No lo hemos instalado en Mac ni en Linux. Según la documentación oficial, en macOS, Linux y WSL el comando es:

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

En Mac también existe brew install --cask claude-code (canal estable, sin actualización automática; se actualiza con brew upgrade claude-code). En Debian, Ubuntu, Fedora, RHEL y Alpine hay repositorios firmados para apt, dnf y apk.

Comprobar y actualizar#

Tu primera sesión, paso a paso#

1. Entra en la carpeta del proyecto y arranca:

cd mi-proyecto
claude

La primera vez te pide elegir el tema de colores y después el método de acceso. Con una suscripción (Pro, Max, Team o Enterprise), elige la primera opción y termina el inicio de sesión en el navegador.

Desliza para ver la captura completa

2. Pídele que te explique el proyecto antes de tocar nada. Por ejemplo: «Explícame qué hace este proyecto, cómo se arranca y dónde están los tests». Así ves cómo lee y si entiende la estructura.

3. Genera el CLAUDE.md con /init. Crea un fichero con lo que ha entendido del proyecto, que leerá al empezar cada sesión. Revísalo y corrige lo que esté mal: es tu manual para él.

4. Haz un cambio pequeño y comprobable. «Añade una validación para que el email no pueda estar vacío en el formulario de registro, con su test, y pasa los tests». Pequeño y con una forma clara de saber si ha salido bien.

5. Revisa lo que ha hecho. Pulsa Ctrl+O para ver el detalle de cada herramienta que ha usado. Si algo no te gusta, Esc dos veces con el campo vacío abre el menú para rebobinar código y conversación a un punto anterior.

6. Cierra o limpia. /clear empieza una conversación nueva con el contexto vacío. claude -c en la terminal retoma la última conversación de esa carpeta.

Modos de permisos: el ajuste que más importa#

El modo de permisos decide qué hace Claude sin preguntarte. Es lo primero que conviene entender, porque marca la diferencia entre un agente que te interrumpe cada diez segundos y uno que puede romper algo sin que te enteres.

Se cambia durante la sesión con Shift+Tab (rota entre manual, acceptEdits y plan, más auto si está disponible) o al arrancar con claude --permission-mode plan. La barra de estado siempre te dice en cuál estás.

Un detalle que cambia mucho la experiencia: según la documentación oficial, desde la versión 2.1.283 las sesiones interactivas de terminal y de VS Code arrancan en modo auto en todos los planes. Según la misma documentación, el clasificador bloquea por defecto cosas como despliegues a producción, git push --force, git reset --hard, borrar ficheros que existían antes de la sesión o descargar y ejecutar código con curl | bash. La propia documentación avisa de que reduce las preguntas pero no garantiza la seguridad.

Cómo lo usamos nosotros:

• Código local en una carpeta con copia o con git: auto o acceptEdits. Si algo sale mal, se rebobina.
• Cuando no sé bien qué quiero: plan. Me trae un plan, lo corrijo y solo entonces edita.
• Servidores de producción: aquí no basta el modo. Jarvis tiene su propia capa de aprobación: puede mirar por SSH, pero cualquier cambio en un servidor Linux de producción le llega a Ferran como un vale con botones de aprobar o denegar. Lo contamos en automatizar servidores con IA.
• bypassPermissions: nunca fuera de una máquina desechable.

Encima de los modos puedes poner reglas fijas con /permissions: permitir siempre npm test, preguntar siempre antes de git push, prohibir leer cierta carpeta. Las reglas de denegar se respetan en todos los modos.

CLAUDE.md: el manual que lee cada vez#

Cada sesión empieza con la memoria en blanco. El CLAUDE.md es lo que la llena: instrucciones que Claude Code carga al arrancar. Los de las carpetas superiores a donde lo abres se cargan todos, y los de subcarpetas, cuando trabaja en ellas. La documentación recomienda que cada uno tenga menos de 200 líneas: lo largo gasta contexto y se sigue peor.

Nosotros lo usamos por capas. C:\Proyectos\CLAUDE.md tiene las reglas de todos los proyectos («nada de git push, despliegues ni cambios en servidores sin su vale», «nunca escribas secretos en ficheros ni en notas»). Cada área tiene el suyo (C:\Proyectos\Otros\CLAUDE.md dice qué proyectos hay en ella). Y cada proyecto, el suyo con el stack, los comandos y lo que no se toca. Abras Claude donde lo abras, recibe las tres capas.

Desliza para ver la figura completa

Cómo escribir uno bueno, con ejemplos reales y plantillas para copiar, lo tienes en la guía de CLAUDE.md.

Comandos y atajos que de verdad usamos#

Claude Code tiene decenas de comandos (escribe / para verlos). Estos son los que salen en nuestro día a día:

MCP: conectarlo con tus herramientas#

MCP (Model Context Protocol) es el estándar con el que Claude Code habla con herramientas externas: una base de datos, un navegador, tu panel de hosting. Cada servidor MCP le añade herramientas nuevas.

claude mcp add --transport http mi-servidor https://ejemplo.com/mcp
claude mcp list

En nuestro caso, Jarvis usa cinco: uno de memoria y agenda (su vault de Obsidian), uno con las herramientas del negocio (soporte, correo, cobros), uno propio para GamzyCloud (crear webs, desplegar, ver logs), Playwright para manejar un navegador y uno para el escritorio de Windows. Qué es MCP, cómo funciona por dentro y cómo montar uno, en qué es MCP.

Skills: enseñarle un procedimiento una vez#

Una skill es una carpeta con un SKILL.md: instrucciones para una tarea concreta, con una descripción que le dice a Claude cuándo usarla. Las personales van en ~/.claude/skills/<nombre>/SKILL.md y las del proyecto en .claude/skills/. Mientras no se usan, solo ocupa contexto la descripción, así que puedes tener muchas.

Nosotros tenemos 49. Por ejemplo, estado-de-los-nodos explica qué herramienta llamar para revisar los nodos de juegos, qué umbrales preocupan (disco por encima del 85 %, carga de 15 minutos por encima de los núcleos) y cómo resumirlo en dos frases. Cuando Ferran pregunta «¿cómo van los nodos?», Claude carga esa skill sola. También se pueden lanzar a mano con /nombre-de-la-skill. Cómo crear las tuyas: skills de Claude.

Subagentes: para que la sesión principal no se llene#

Un subagente es otro Claude con su propio contexto al que la sesión principal le pasa una tarea. Hace el trabajo y devuelve solo un resumen. Sirve sobre todo para lo que genera mucho ruido: recorrer cien ficheros, leer documentación larga, revisar logs.

Claude Code trae tres de serie: Explore (busca en el código, solo lectura), Plan (investiga en modo plan, solo lectura) y uno de propósito general que puede leer y editar. Los tuyos se definen como ficheros Markdown en .claude/agents/ (del proyecto) o ~/.claude/agents/ (para todos), con un name, una description y, si quieres, las herramientas y el modelo que puede usar:

---
name: revisor
description: Revisa un cambio buscando fallos y riesgos. Úsalo antes de dar algo por terminado.
tools: Read, Glob, Grep
model: sonnet
---

Revisa el cambio que te indiquen. Devuelve solo los fallos reales, con fichero y línea.

Dos cosas a saber. Los subagentes gastan del mismo límite de uso que tu conversación. Y no hace falta pedirlos: si el encargo es grande, Claude los lanza solo; si quieres forzarlo, díselo («investiga esto con un subagente y tráeme solo la conclusión»).

Cómo pedir bien un encargo#

La calidad del resultado depende sobre todo de cómo lo pides. Los encargos que le pasamos a Jarvis siguen esta forma:

Objetivo: qué quieres que exista al acabar (no cómo hacerlo).
Dónde: carpeta o ficheros. Qué no debe tocar.
Contexto: lo que no está en el código (por qué, para quién, qué se probó ya).
Cómo se comprueba: el test, el build o lo que debe verse si ha ido bien.
Límites: sin push, sin desplegar, sin instalar nada, sin tocar producción.
Qué devolver: un resumen corto con lo hecho, lo que no y las dudas.

Las tres líneas que más cambian el resultado:

• Cómo se comprueba. Un agente con una forma de verificar su trabajo (un test, un npm run build, una URL que debe responder) se corrige solo. Sin ella, te dice «listo» y te toca descubrir el fallo a ti.
• Los límites. «No despliegues» escrito en el encargo vale más que confiar en que no lo hará. En nuestro CLAUDE.md global va por defecto para no tener que repetirlo.
• Qué devolver. Si no lo dices, te escribirá un informe largo. Pide formato y longitud.

Si la tarea es grande o ambigua, empieza en modo plan: le das el objetivo, te propone pasos, corriges el plan (es mucho más barato que corregir código) y luego lo aprueba para ejecutar.

Errores que cometimos y cómo evitarlos#

Otras prácticas que seguimos y por qué:

• Todo lo que aprende, a su CLAUDE.md. Cada vez que una sesión descubre algo técnico que costó (un test que falla solo en cierta condición, un comando que no va en esta máquina), lo apunta en una línea en el CLAUDE.md del proyecto. La próxima sesión no lo redescubre.
• En Windows, los .ps1 en ASCII. PowerShell 5.1, el que viene con Windows Server 2022, lee mal las tildes de un script si el fichero no lleva la codificación que espera. Lo dejamos escrito en el CLAUDE.md para que Claude no las ponga.
• Nunca editar lo publicado. El código de Jarvis se cambia en su repositorio y se publica con un script que pasa los tests; la carpeta en producción no se toca a mano. Así, si Claude se equivoca, el fallo se queda en el repositorio y no llega a producción.
• Nada de secretos en ficheros ni en notas. Las claves viven en ficheros de entorno fuera del repositorio, y la regla está en la primera capa de CLAUDE.md.
• Pedir cambios pequeños. Un encargo que toca veinte ficheros es difícil de revisar. Dos de diez se revisan mejor y se deshacen mejor.

Qué hacer ahora#

1. Instala Claude Code con el comando de tu sistema y comprueba claude --version.
2. Ábrelo en un proyecto pequeño que tengas en git, pide que te lo explique y ejecuta /init.
3. Haz un primer encargo con la plantilla de arriba, con una línea de «cómo se comprueba».
4. Escribe tu primer CLAUDE.md en serio con la guía de CLAUDE.md.
5. Cuando repitas un procedimiento por tercera vez, conviértelo en una skill: skills de Claude.
6. Si quieres ir más allá de programar, mira cómo montamos un asistente completo sobre Claude Code en asistente de IA propio y más casos reales en ejemplos de agentes de IA.