Voy a ser honesto contigo: Claude Code me ha cambiado la forma de trabajar. Y no lo digo en modo evangelista de turno que repite lo que lee en X. Lo digo porque llevo meses usándolo todos los días y hay cosas que antes me llevaban una hora que ahora resuelvo en cinco minutos. Literalmente.
Pero cuando empecé con esto, me costó. La documentación oficial es buena pero está repartida en mil sitios, los tutoriales de YouTube se quedan obsoletos cada dos semanas porque Anthropic no para de sacar actualizaciones y, al final, acabas juntando piezas de aquí y de allá hasta que algo funciona.
Así que esta guía es lo que yo habría querido leer el primer día. Sin florituras, sin repetir lo obvio, con los comandos exactos y las cosas que de verdad importan. Si ya programas, en 10 minutos estás funcionando. Si no programas pero quieres entender qué es esto de la IA que programa, también te va a servir.
Qué vas as ver en esta entrada
Qué es Claude Code y por qué debería importarte
Claude Code es el agente de programación de Anthropic. Vive en tu terminal. No es un chatbot bonito, no es una extensión de IDE que te autocompleta líneas, no es Copilot. Es un agente que se mete en tu proyecto, lee tus archivos, entiende la estructura, edita código, ejecuta comandos y gestiona git. Todo con lenguaje natural.
La diferencia con otras herramientas es que no trabaja con trozos aislados de código. Trabaja con tu proyecto entero. Le dices «hay un bug en el login, arréglalo» y va, busca los archivos, entiende las dependencias, propone los cambios y los aplica. Sin que copies nada, sin que pegues nada.
Salió como research preview en febrero de 2025 y se hizo generally available en mayo de ese mismo año, junto con Claude 4. Desde entonces se ha convertido en una de las herramientas de desarrollo con IA más usadas. Y Anthropic no para: cada semana hay funcionalidades nuevas. A veces da hasta pereza actualizarse porque cuando te enteras de un feature ya han sacado tres más.
Lo que necesitas antes de empezar con Claude Code
Los requisitos son bastante bajos, la verdad:
- Sistema operativo: macOS 13.0 (Ventura) o superior, Ubuntu 20.04+ / Debian 10+, o Windows 10 (versión 1809+). Básicamente, si tu ordenador tiene menos de 5 años, vas bien.
- RAM: 4GB mínimo, 8GB recomendado si tus proyectos son grandes.
- Conexión a internet: sí o sí. Toda la IA corre en los servidores de Anthropic. Tu máquina solo ejecuta el cliente de terminal y envía peticiones.
- Cuenta de pago de Anthropic: el plan gratuito NO incluye Claude Code. Oficialmente, Claude Pro a 20$/mes lo incluye, pero en la práctica los límites son tan bajos que para uso real te quedas corto en pocas horas. Si vas a usarlo en serio, lo honesto es decirte que necesitas Claude Max desde 100$/mes (5x) o 200$/mes (20x). Anthropic ha estado testeando quitar Claude Code del plan Pro y todo apunta a que en algún momento lo harán oficial. La alternativa es pagar por API en la Anthropic Console, que sale rentable si lo usas poco.
No necesitas GPU. No necesitas Node.js si usas el instalador nativo (que es el que te recomiendo). No necesitas nada exótico.
Instalación de Claude Code: un comando y listo
A día de hoy, el método recomendado por Anthropic es el instalador nativo. Sin dependencias, se actualiza solo en segundo plano y funciona en macOS, Linux y Windows. Es el que ellos testean internamente, así que es el más fiable.
macOS y Linux
Abre la terminal y copia esto:
curl -fsSL https://claude.ai/install.sh | bash
Ya está. En serio. El instalador baja el binario, lo pone en tu PATH y configura las actualizaciones automáticas. No hay paso dos.
Windows
Aquí hay un detalle importante que mucha gente se salta y luego se pregunta por qué no funciona: si quieres la instalación nativa de Windows, necesitas tener Git for Windows instalado, porque Claude Code usa Git Bash internamente para ejecutar comandos. Bájalo de git-scm.com/download/win, instálalo con las opciones por defecto y reinicia la terminal. Después, abre PowerShell y ejecuta:
irm https://claude.ai/install.ps1 | iex
Si estás en CMD en lugar de PowerShell, el comando es distinto:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
¿Cómo sabes en cuál estás? Mira el prompt: en PowerShell empieza por PS C:\, en CMD solo C:\. Si te equivocas y mezclas comandos, te va a salir un error claro avisando.
Otra opción nativa de Windows es WinGet, que viene preinstalado en Windows moderno:
winget install Anthropic.ClaudeCode
Funciona, pero ojo: como Homebrew, no se auto-actualiza. Tendrás que hacer winget upgrade Anthropic.ClaudeCode de vez en cuando. Si prefieres trabajar en WSL, no hace falta Git for Windows: instalas y ejecutas Claude Code dentro del terminal de WSL como si fuera Linux.
Si prefieres npm (ya no es lo recomendado)
El método npm sigue funcionando pero ya no es lo que Anthropic recomienda. Lo mantienen por retrocompatibilidad. Si aun así lo quieres:
npm install -g @anthropic-ai/claude-code
Necesitas Node.js 18+ y no tienes actualizaciones automáticas. Si ya lo tenías instalado con npm, Anthropic recomienda migrar al instalador nativo. Tu configuración existente se conserva.
Homebrew (macOS)
brew install --cask claude-code
Funciona perfecto, pero tampoco se auto-actualiza. Tendrás que hacer brew upgrade claude-code cuando quieras la última versión. Hay una variante claude-code@latest si quieres recibir las versiones nuevas en cuanto salen.
Comprobar que todo va bien
claude --version
Si ves un número de versión, estás dentro. Si algo falla:
claude doctor
Este comando es una joya escondida. Escanea tu entorno, detecta problemas de configuración y te dice exactamente qué arreglar. Úsalo siempre que algo no cuadre.
Conectar tu cuenta
La primera vez que escribas claude en tu terminal, se abre el navegador para que hagas login con tu cuenta de Anthropic. Le das a autorizar, vuelves a la terminal y el token se guarda en local. No tienes que repetir esto.
Si estás en un servidor sin navegador o en un pipeline de CI/CD, puedes usar una API key:
export ANTHROPIC_API_KEY=sk-tu-clave-aqui
Métela en tu .bashrc o .zshrc para que sea permanente y no tengas que escribirla cada vez.
Tu primera sesión real
Ve a la carpeta de cualquier proyecto que tengas y lanza Claude Code:
cd ~/proyectos/mi-app claude
Eso es todo. Claude Code lee la estructura de tu proyecto y está listo. Ahora puedes hablarle como le hablarías a un compañero:
- «Explícame qué hace este proyecto»
- «Busca los archivos relacionados con la autenticación»
- «Añade un endpoint para crear usuarios con validación de email»
- «El formulario de contacto no envía, arréglalo»
Claude no solo responde con texto. Lee archivos, los modifica, ejecuta comandos, corre tests. Cuando le pides algo, lo hace. Y te pide confirmación antes de aplicar cambios, que eso también se agradece.
Dos atajos que conviene saber desde el primer día: claude –continue retoma la sesión más reciente desde el directorio actual, y claude –resume te deja elegir de una lista qué sesión quieres recuperar. Así no pierdes contexto si cierras la terminal sin querer.
CLAUDE.md: el archivo que nadie configura y todos deberían
De todos los consejos de esta guía, este es el más importante y el que menos gente aplica. El archivo CLAUDE.md es la memoria de tu proyecto. Es donde le explicas a Claude Code cómo trabajas, qué stack usas, qué convenciones sigues y qué cosas no quieres que haga.
Para generarlo automáticamente:
/init
Eso crea un CLAUDE.md base analizando tu proyecto. Pero lo bueno viene cuando lo personalizas. Un CLAUDE.md bien hecho incluye cosas como:
- Tu stack: lenguaje, framework, base de datos, versión de Node o Python que usas.
- Convenciones de código: cómo nombras variables, cómo estructuras las carpetas, qué patrones sigues.
- Comandos clave: cómo correr tests, cómo levantar el entorno de desarrollo, cómo hacer deploy.
- Lo que no quieres: «nunca uses lodash», «no toques los archivos de migración», «no generes CSS inline».
Sin CLAUDE.md, Claude hace lo que puede y normalmente lo clava bastante bien. Pero con un buen CLAUDE.md, los resultados son de otro nivel. Es la diferencia entre un asistente genérico y uno que conoce tu proyecto como si lo hubiera escrito él.
Un truco que me cambió la vida: cada vez que Claude hace algo que no me gusta, en vez de corregirle en el chat, actualizo el CLAUDE.md. Así corriges el contexto, no la conversación. Y no vuelve a pasar.
Los slash commands que vas a usar a diario
Dentro de una sesión de Claude Code, escribes / y te sale una lista de comandos. No necesitas memorizarlos todos, pero estos son los que yo uso constantemente:
- /plan: el modo planificación. Claude analiza el problema, traza un plan paso a paso y te lo enseña antes de tocar nada. Para cualquier cambio que no sea trivial, úsalo. Me ha ahorrado horas de debugging. También puedes activarlo pulsando Shift+Tab dentro de una sesión, que va ciclando entre modo normal, auto-accept y plan mode.
- /compact: comprime el contexto de la conversación para liberar espacio en la ventana de contexto. Úsalo cuando lleves muchos turnos. Puedes decirle qué conservar: /compact conserva los patrones de error del último test. La compactación es prácticamente instantánea.
- /clear: borra todo el contexto. Ideal cuando cambias de tarea completamente.
- /fast: modo rápido. Mismo modelo, pero con configuraciones optimizadas para velocidad. Perfecto para iteraciones rápidas y debugging interactivo. Ojo: cuando lo activas a mitad de sesión, todo el contexto previo se factura a tarifas de Fast Mode, así que apágalo cuando ya no lo necesites.
- /btw: este es relativamente nuevo y es una maravilla. Te permite hacer una pregunta rápida sin que se añada al historial de la conversación. Imagina que estás en medio de un refactoring y necesitas consultar algo: escribes /btw cómo funciona X y te responde en un overlay temporal. Tu tarea principal sigue corriendo, tu contexto sigue limpio. Es lo contrario de un subagente: /btw ve toda tu conversación pero no tiene acceso a herramientas. Un subagente tiene todas las herramientas pero empieza con contexto vacío.
- /init: genera el CLAUDE.md del proyecto.
- /context: muestra info sobre el contexto actual, skills cargados y consumo de tokens.
- /diff: muestra los cambios que Claude ha hecho en los archivos. Combínalo con /rewind si algo no te convence: revisas los cambios y decides si te los quedas o los deshaces.
- /rewind: la red de seguridad. Revierte la conversación y los cambios en archivos a un punto anterior. Claude crea checkpoints automáticos mientras trabajas. Atajo rápido: pulsa Esc dos veces y se abre el menú de rewind, donde puedes elegir si revertir solo el código, solo la conversación, o ambos.
Skills: convierte Claude Code en TU herramienta
Aquí es donde Claude Code pasa de ser una herramienta potente a ser algo verdaderamente personalizado. Y aquí es donde la mayoría de la gente se queda corta.
Una skill es un conjunto de instrucciones empaquetadas en un archivo SKILL.md que Claude puede invocar automáticamente cuando detecta que es relevante, o que tú puedes invocar manualmente con un slash command. Antes, skills y commands eran cosas separadas. En 2026, se unificaron en un mismo sistema: todo lo que hay en .claude/skills/ y en .claude/commands/ funciona igual, aunque Anthropic recomienda usar skills para cosas nuevas porque tienen más opciones.
Cómo crear una skill
Creas una carpeta dentro de ~/.claude/skills/ (global, disponible en todos tus proyectos) o .claude/skills/ (solo para un proyecto concreto). Dentro, un archivo SKILL.md con dos partes:
- Frontmatter YAML con el nombre y la descripción (es lo que Claude lee al arrancar para saber qué skills tiene disponibles).
- Instrucciones en markdown con las reglas, pasos y ejemplos que Claude debe seguir.
Un ejemplo real:
--- name: review-seguridad description: Revisa código buscando vulnerabilidades de seguridad, inyecciones SQL, XSS y problemas de autenticación. --- Cuando revises código: 1. Busca inputs de usuario sin sanitizar 2. Revisa consultas SQL por inyecciones 3. Comprueba que los endpoints tienen auth 4. Busca secrets hardcodeados 5. Genera un informe con severidad y solución
Ahora puedes escribir /review-seguridad en cualquier sesión y Claude ejecuta ese workflow exacto. Pero lo interesante es que también puede invocarlo solo si detecta que estás trabajando en algo relacionado con seguridad.
Opciones avanzadas del frontmatter
El frontmatter tiene campos que te dan bastante control:
- disable-model-invocation: true: solo tú puedes invocar la skill. Útil para skills con efectos secundarios como /deploy o /enviar-a-produccion. No quieres que Claude decida por su cuenta que es buen momento para desplegar.
- allowed-tools: restringe qué herramientas puede usar Claude cuando ejecuta esa skill. Puedes darle solo lectura (Read, Grep, Glob) para una skill de revisión, o acceso completo para una de desarrollo.
- model: puedes forzar un modelo específico. Usar Sonnet para tareas rápidas y Opus para las complejas, por ejemplo.
- context: fork: ejecuta la skill en un subagente con su propio contexto aislado.
Las skills también soportan archivos complementarios: scripts, templates, datos de referencia. Claude los lee bajo demanda, así que no consumen tokens hasta que realmente los necesita.
Subagentes: delegar tareas a agentes especializados
Si las skills son instrucciones, los subagentes son trabajadores especializados. Y esta es una de las funcionalidades más potentes de Claude Code, con diferencia.
Cuando Claude usa el comando Task durante una sesión, está creando un subagente general para ayudarle con algo. Pero tú puedes crear los tuyos propios: agentes con un prompt específico, herramientas restringidas y que se lanzan cuando los necesitas.
Cómo crear un subagente
Tienes dos formas. La rápida: dentro de una sesión escribe /agents, selecciona «Create new agent», elige si es personal (en ~/.claude/agents/) o de proyecto (en .claude/agents/) y deja que Claude te ayude a generarlo.
La manual: creas un archivo .md en la carpeta correspondiente con frontmatter YAML y el prompt del sistema:
--- name: api-tester description: Testea endpoints REST y valida schemas tools: [Bash, Read, WebFetch] model: sonnet memory: user --- Eres un agente especializado en testing de APIs. Cuando te invoquen: 1. Lee el spec de la API 2. Testea cada endpoint contra el servidor de dev 3. Compara respuestas con el schema esperado 4. Reporta fallos con request, expected y actual
Fíjate en los detalles importantes:
- tools define qué puede hacer el agente. Un agente de review solo necesita Read, Grep, Glob. Uno de desarrollo necesita Read, Write, Edit, Bash. Principio de mínimo privilegio: si no necesita escribir, no le des permiso para escribir.
- model te permite asignar un modelo más barato (Sonnet) para tareas simples y reservar Opus para las complejas. O usa model: inherit para que herede el modelo de tu sesión.
- memory (con valor user, project o local) le da al subagente un directorio persistente donde acumula conocimiento entre sesiones. Patrones del codebase, decisiones arquitectónicas, errores recurrentes. Es como una memoria a largo plazo para ese agente específico. Anthropic recomienda project como valor por defecto, para que el conocimiento se pueda compartir vía git con tu equipo.
Orquestación: varios agentes trabajando juntos
Claude Code puede ejecutar hasta 10 subagentes en paralelo. Esto abre la puerta a pipelines bastante serios. Un ejemplo real:
- Un agente pm-spec lee los requisitos y genera una especificación estructurada con criterios de aceptación.
- Un agente architect-review valida la spec contra las restricciones de la plataforma.
- Un agente implementor escribe el código siguiendo la spec aprobada.
- Un agente test-runner ejecuta los tests y reporta resultados.
Cada uno con sus herramientas, su modelo y su contexto aislado. Los subagentes que defines en .claude/agents/ se pueden commitear en tu repositorio para que todo el equipo los comparta.
Truco práctico: cuando un subagente está tardando demasiado, pulsa Ctrl+B y se va a background. La conversación principal sigue corriendo y los resultados aparecen cuando termine. Para ver qué hay corriendo en background: /tasks.
Dónde más puedes usar Claude Code
La terminal es el core, pero hay mucho más:
- Extensión de VS Code y plugin de JetBrains: se conectan al mismo binario CLI que ya instalaste. La integración con VS Code muestra los diffs en el visor nativo del editor.
- Claude Cowork: la app de escritorio de Anthropic con interfaz gráfica, pensada para usuarios menos técnicos. Disponible para Mac y Windows. Acceso a un shell en sandbox y a las carpetas que tú elijas, para que el modelo pueda leer, escribir y ejecutar tareas con una UI más amigable.
- GitHub Actions y GitLab CI/CD: para automatizar revisiones de código, generación de tests y demás en tu pipeline.
- Channels (research preview): te permiten conectar Claude Code con Telegram, Discord o iMessage. Puedes enviar mensajes a un bot y que lleguen a tu sesión activa. Útil para monitorizar tareas largas o lanzar cosas rápidas desde el móvil. La sesión tiene que estar corriendo en tu máquina.
- Servidores MCP (Model Context Protocol): conectan Claude Code con herramientas externas como bases de datos, Slack, Asana, Playwright para testing, GitHub para gestión de PRs… Es lo que convierte a Claude Code de un asistente de código a un agente de desarrollo completo.
Cuánto cuesta todo esto
Claude Code como binario es gratis. Lo que pagas es el acceso a los modelos. A día de hoy:
- Claude Pro: 20$/mes (17$/mes si pagas anual). Oficialmente incluye Claude Code, pero con límites muy ajustados. Para algo más que probarlo te vas a quedar corto.
- Claude Max: 100$/mes (5x) o 200$/mes (20x, con muchos más límites). Es el plan realista si vas a usar Claude Code de verdad en tu día a día.
- API (Anthropic Console): pagas por tokens. Las tarifas actuales por millón de tokens son: Haiku 4.5 a 1$/5$, Sonnet 4.6 a 3$/15$, y Opus 4.6 y Opus 4.7 a 5$/25$. El coste real de una sesión depende mucho de qué hagas: una conversación corta puede costar céntimos, una sesión larga con muchas lecturas de archivos y subagentes puede irse a varios dólares. Si lo usas poco, la API te puede salir más barata que la suscripción.
- Teams y Enterprise: hay planes para equipos. Las tarifas y los planes que incluyen Claude Code cambian con cierta frecuencia, así que mejor consulta la página oficial de planes en el momento que lo necesites.
Lo que aprendí después de meses de uso diario
Cierro con las cosas que me hubiese gustado que alguien me dijera el primer día:
- El CLAUDE.md es más importante que cualquier prompt. Si Claude hace algo raro, no pierdas tiempo corrigiéndole en el chat. Actualiza el CLAUDE.md. Arregla el contexto, no la conversación.
- Usa /plan (o Shift+Tab) siempre que el cambio toque más de un archivo. La tentación de dejar que Claude ejecute directamente es grande, pero el modo planificación te ahorra horas de limpiar desastres.
- Compacta antes de que sea tarde. La regla es: si el contexto supera el 80%, haz /compact. Si no lo haces tú, Claude lo hará automáticamente, pero es mejor que le digas tú qué conservar.
- Crea skills para todo lo que hagas más de dos veces. Una /review, un /deploy-staging, un /generate-tests. Tu yo del futuro te lo va a agradecer.
- Usa /btw sin miedo. Cada pregunta rápida que haces en el chat principal infla el contexto. Con /btw haces la consulta, recibes la respuesta en un overlay y tu historial queda limpio. En sesiones largas se nota en el consumo de tokens.
- Dale subagentes a las tareas repetitivas. Si revisas PRs todos los días, haz un subagente para eso con tools de solo lectura. Si siempre ejecutas los mismos tests, haz un subagente con Bash. Lo que automatices bien una vez, no lo vuelves a hacer mal.
- Claude Code gestiona git de forma nativa. Pídele que cree ramas, haga commits con mensajes descriptivos y abra PRs. Es más consistente que hacerlo a mano cuando llevas 12 horas delante de la pantalla.
- Si la cosa se tuerce, doble Esc. Se abre el menú de /rewind y eliges si revertir solo el código, solo la conversación o las dos cosas. Más rápido que pelearte con git stash para experimentos pequeños.
Y un consejo extra que no es técnico: no intentes aprenderlo todo de golpe. Empieza con lo básico (instalar, /plan, CLAUDE.md), úsalo una semana en un proyecto real, y luego ve añadiendo skills y subagentes cuando sientas que los necesitas. La herramienta crece contigo.
Nos vemos en la terminal.
Por cierto, sobre la filtración del código de Claude Code
Hace poco se filtró el código fuente completo de Claude Code, y aunque no fue un evento del que se hablara demasiado fuera de los círculos técnicos, da una visión muy interesante de cómo está construida la herramienta por dentro: cómo gestiona el contexto, cómo orquesta los subagentes, qué decisiones de diseño tomaron en Anthropic. Escribí un análisis bastante detallado en mi blog personal contando lo que me pareció más relevante.