Tutorial de Claude Code: qué es y cómo usarlo bien

Abres tu terminal. Escribes claude. Y de repente tienes a un agente con acceso a tu repositorio, tu historial de git, tus tests y tus ficheros de configuración.

Le pides que arregle un bug.

Lo investiga. Propone un plan. Toca tres archivos. Ejecuta los tests. Y te pregunta si quieres hacer commit.

Ciencia ficción de domingo por la tarde. Salvo que ya funciona. Y funciona bien… si sabes cómo tratarlo.

El problema es que la mayoría de developers lo usan como si fuera un ChatGPT con esteroides. Le sueltan un prompt, esperan que escupa código mágico y luego se sorprenden cuando aquello no encaja con nada. Eso no es programar con un agente. Eso es tirar los dados y rezar.

Este tutorial va de lo otro. De cómo usarlo bien, paso a paso, hasta que hagas tu primer cambio real sobre un repositorio de verdad:

• Qué es Claude Code y qué lo hace diferente de un asistente de autocompletado
• Instalación, coste y primeros pasos para no empezar a ciegas
• El bucle agentic que ejecuta por debajo y por qué importa
• Un walkthrough completo sobre un repo real: tu primer cambio con investigación, modo plan y verificación con tests
• Pros y contras sin incienso ni marketing
• Comparativa honesta con OpenCode, Copilot y Codex

Qué es Claude Code ¶

La herramienta de Anthropic para programar con IA desde la terminal.

Pero esa descripción se queda corta. Según la documentación oficial, es una herramienta de agentic coding que lee tu código, edita ficheros, ejecuta comandos y se integra con tus herramientas de desarrollo. Terminal, IDE (VS Code, JetBrains), escritorio, navegador, móvil.

La palabra clave es agentic.

No completa líneas de código. Intenta resolver tareas enteras. Piensa en la diferencia entre un GPS que te dice “gira a la derecha en 200 metros” y un copiloto que mira el mapa, elige la ruta, te avisa de los radares y además aparca por ti.

Los asistentes de autocompletado son el GPS. Claude Code quiere ser el copiloto.

Un poco de contexto con números. Según la Stack Overflow Developer Survey de 2025, el 84% de los developers ya usan o planean usar herramientas de IA, con un 51% usándolas a diario. Pero el sentimiento positivo ha bajado del 70% en 2023-2024 al 60% en 2025.

Más uso. Menos confianza.

El 66% dice que su mayor frustración es lidiar con soluciones de IA que “casi aciertan, pero no del todo”. Claude Code nace en ese contexto. No es otra caja de texto donde pegas un prompt. Es un agente que vive en tu terminal, entiende tu repositorio y opera sobre él con una autonomía que puede ser tu mejor aliada o tu peor pesadilla.

🔑 Claude Code no es “Copilot pero en terminal”. Es un agente que intenta resolver tareas completas: desde leer el código hasta hacer commit. Esa diferencia lo cambia todo, y es la que justifica seguir un tutorial en vez de improvisar.

Cómo instalar Claude Code y cuánto cuesta ¶

Antes de contarte cómo funciona por dentro, vamos a lo práctico. Instalar, saber cuánto cuesta y dar los primeros pasos sin destrozar nada.

Cuánto cuesta ¶

Claude Code requiere suscripción de pago. El plan gratuito de Claude no incluye acceso.

• Plan Pro: $20/mes. Suficiente para empezar. Acceso a Sonnet y Opus, aunque Opus consume tokens mucho más rápido.
• Plan Max: más capacidad y ventana de contexto ampliada (hasta 1 millón de tokens). Para uso intensivo o equipos.
• API con pago por uso: la Anthropic Console con créditos. Cada token de salida cuesta unas 4 veces más que uno de entrada, así que las respuestas largas salen caras.

Un detalle que pilla a muchos por sorpresa: tu uso en claude.ai y en Claude Code comparte la misma cuota. Si pasas la mañana chateando en el navegador y la tarde programando, todo sale del mismo presupuesto. Si el coste te echa para atrás, hay formas de usar Claude Code con Ollama, OpenRouter y otros backends más baratos sin perder la ergonomía del agente.

Instalación ¶

Ya no necesitas Node.js. El método por npm está obsoleto desde que Anthropic publicó el instalador nativo. Ese instalador detecta tu sistema operativo, coloca el binario en ~/.local/bin/claude y se autoactualiza en segundo plano.

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

# Asegura que el binario esté en tu PATH
export PATH="$HOME/.local/bin:$PATH"

En Windows el comando equivalente es irm https://claude.ai/install.ps1 | iex desde PowerShell. También puedes instalarlo con Homebrew (brew install --cask claude-code), como extensión de VS Code o JetBrains, o usarlo en claude.ai/code sin instalar nada. La experiencia de terminal sigue siendo la más completa.

Comprueba que ha ido bien antes de seguir:

# Confirma que el binario está disponible
claude --version

# Diagnóstico completo: tipo de instalación, auth y settings
claude doctor

Si claude --version te devuelve un número, ya tienes medio camino hecho.

Tu primer minuto ¶

Entra en un proyecto real. No en un directorio vacío.

cd tu-proyecto
claude

¿No tienes un proyecto a mano? Clónate el repo de ejemplo que usaremos durante el resto del tutorial. Es una API de frases y chistes de Chiquito de la Calzada, hecha por la comunidad de Web Reactiva con Spec-Driven Development:

git clone https://github.com/webreactiva-devs/chiquito-api-sdd
cd chiquito-api-sdd
npm install
cd ..   # vuelve a la raíz para arrancar claude dentro del proyecto

Con un proyecto delante, empieza preguntando. No pidiendo cambios.

¿Qué hace este proyecto?
¿Qué tecnologías usa?
¿Dónde está el entry point?
¿Cómo están organizados los tests?

Ese es el primer uso sensato. Dejas que el agente demuestre que entiende tu código antes de darle permiso para tocarlo.

Si acierta, ya sabes que tiene buena lectura del repositorio. Si no, corriges antes de que haga ningún daño.

Crea tu CLAUDE.md ¶

Este paso separa a los que usan Claude Code bien de los que se quejan en Reddit.

Un matiz antes de teclear: /init solo tiene sentido cuando ya hay algo de código. El comando lee tu proyecto y genera un CLAUDE.md a partir de lo que encuentra. Si arrancas con la carpeta vacía no tiene nada que mirar.

Así que el orden sano depende de dónde estés:

• Empiezas de cero: primero levantas el esqueleto del proyecto. A mano, si ya tienes claro qué va a llevar (framework, estructura, dependencias), o pidiéndoselo a Claude para que lo monte. Y cuando ya hay algo instalado, entonces sí, /init.
• Ya tienes un proyecto (o has clonado el de ejemplo): /init directo. Tiene material que leer y el CLAUDE.md saldrá con cara y ojos.

Con el repo de Chiquito clonado estás en el segundo caso. Ejecuta /init y personaliza el fichero resultante con tres cosas:

• Comandos de build y test: npm test, npm run build, lo que uses
• Reglas de estilo no obvias: “usamos camelCase”, “rutas en src/routes”
• Restricciones de workflow: “nunca hagas push a main”

# CLAUDE.md

## Comandos
- Build: `npm run build`
- Test: `npm test`
- Dev: `npm run dev`

## Convenciones
- TypeScript estricto, sin `any`
- Validación de entrada con Zod en la capa de rutas
- Commits en español siguiendo conventional commits

## Restricciones
- Toda ruta literal nueva bajo /content/ va antes de /content/:id
- Siempre ejecutar tests antes de proponer commit

Corto. Anthropic advierte que si lo inflas demasiado, Claude acabará ignorando tus instrucciones. Si quieres profundizar en cómo estructurarlo, ya lo cubrimos en los 12 comandos secretos de Claude Code. Y para dominar el sistema de memoria, reglas modulares y la jerarquía de 6 niveles de prioridad, tenemos una guía dedicada a la memoria y configuración de Claude Code.

💡 Si solo te llevas una cosa de esta sección: no le pidas que cambie nada hasta que hayas visto que entiende tu proyecto. Pregunta primero, actúa después.

Cómo funciona por dentro ¶

Un bucle. Sencillo de explicar. Peligroso de dejar sin supervisión.

Reunir contexto → actuar → verificar.

Cuando escribes claude dentro de un proyecto, el agente gana acceso a tu repo, tu terminal, el estado de git y tu CLAUDE.md. Lee ficheros, busca código, ejecuta comandos de shell, navega por la web y opera sobre tu código fuente.

Tres modos de permisos regulan cuánto le dejas hacer:

1. Modo por defecto: confirmación antes de editar o ejecutar. El más seguro para empezar.
2. Plan mode: solo lectura. Investiga, analiza y prepara un plan sin tocar nada. Ideal para entender un codebase nuevo.
3. Auto mode: chequeos de seguridad en segundo plano. Más autonomía, más riesgo.

Anthropic recomienda separar exploración y ejecución para problemas complejos. Traducido: hasta ellos saben que darle las llaves del coche al primer minuto suele acabar regular.

La pieza clave es CLAUDE.md, que ya has configurado en el paso anterior. Cada vez que arrancas una sesión, Claude lo lee y ajusta su comportamiento.

Sin él, opera a ciegas. Con él, arranca sabiendo cómo funciona tu mundo.

Además del ciclo básico, Claude Code soporta subagentes (instancias aisladas para tareas específicas), hooks (eventos que puedes interceptar), skills (paquetes de conocimiento especializado) y servidores MCP (conexión con herramientas externas como GitHub, Slack o bases de datos).

No hace falta que entiendas todo esto el primer día. Pero saber que existe te ayuda a entender por qué Claude Code se siente tan distinto de un simple chatbot. Si te pica la curiosidad técnica, el análisis del código fuente filtrado de Claude Code destapa toda la arquitectura interna.

Para qué sirve de verdad ¶

La lista de marketing dice: escribir tests, arreglar bugs, tocar varios archivos, crear commits y PRs, automatizar tareas repetitivas, montar equipos de agentes, pipelines tipo Unix.

Eso como catálogo está bien.

Pero en la práctica, Claude Code brilla en cinco escenarios:

1. Entender repositorios ajenos o grandes. Le dices “explícame cómo funciona el sistema de notificaciones” y te devuelve un análisis detallado tras leer decenas de ficheros. Esto solo, sin escribir una línea, ya justifica la herramienta.

2. Planificar cambios de varios archivos. Le pides un plan antes de tocar nada. Te dice qué ficheros va a modificar, qué enfoque va a seguir y qué trade-offs hay. Tú revisas y corriges antes de que escriba una sola línea.

3. Implementar y verificar. Una vez aprobado el plan, ejecuta los cambios, lanza los tests y te muestra si algo se rompe. El ciclo de feedback es rápido porque todo pasa en la misma sesión.

4. Automatizar trabajo ingrato. Tests de regresión, lint, conflictos de merge, notas de release… Todo eso que nadie quiere hacer y que Claude Code ejecuta sin quejarse.

5. Actuar como pegamento. Git, CI/CD, GitHub Actions, servidores MCP. Orquesta flujos más complejos conectando herramientas que ya usas.

Según los benchmarks de Anthropic, Claude Opus 4.8 alcanza un 88,6% en SWE-bench Verified, uno de los registros más altos para un agente de código a junio de 2026. La generación anterior (Opus 4.6) rondaba el 80,8%, así que el salto en pocos meses ha sido notable.

Pero los benchmarks son benchmarks. Lo que importa es el uso real, y a eso vamos en cuanto entendamos cómo trabaja la gente que más provecho le saca.

⚠️ Claude Code no está pensado para “escribir más rápido”. Su valor real está en reducir la fricción cognitiva en tareas complejas: entender sistemas, planificar cambios y verificar resultados.

Cómo lo usa la gente real ¶

Aquí se pone interesante. El patrón más repetido en blogs de developers serios no es “le pido cosas y ya”. Es un flujo muy estructurado.

El método de Boris Tane: investigar antes de tocar ¶

Boris Tane lleva más de 9 meses usando Claude Code como herramienta principal y su flujo tiene una regla de oro: nunca dejar que Claude escriba código hasta haber aprobado un plan por escrito.

Su proceso tiene tres fases:

1. Research: le pide a Claude que lea una parte del codebase “en profundidad” y que escriba sus hallazgos en un fichero research.md. No un resumen verbal en el chat. Un documento que Boris pueda revisar.

2. Plan: una vez validada la investigación, le pide un plan.md con el enfoque, snippets de código, ficheros afectados y trade-offs. Y aquí viene lo bueno: Boris abre ese plan en su editor y añade notas en línea dentro del propio documento. Corrige supuestos, rechaza enfoques, aporta contexto de negocio. Luego le devuelve el fichero a Claude para que lo actualice.

3. Implementación: solo cuando el plan está aprobado (tras 1 a 6 ciclos de anotación), deja que Claude escriba código.

Un detalle revelador: Boris siempre añade la instrucción “don’t implement yet” al final de cada petición de planificación. Sin ese freno, Claude salta a programar en cuanto cree que el plan es “suficiente”. No lo es hasta que tú lo digas. Boris compartió muchos más trucos en una sesión en directo — los recopilamos en los trucos de Claude Code directamente de su creador.

Dave Van Veen: sesiones paralelas y worktrees ¶

Dave Van Veen sigue un enfoque similar pero añade una capa de paralelismo. Ejecuta 2 o 3 sesiones de Claude Code en tmux sobre features independientes, y usa worktrees de git para que cada sesión tenga su propia copia del código.

Varias IAs trabajando a la vez mientras tú haces de adulto responsable. Hay algo poético en eso.

Jane Street: diseño interactivo sin Figma ¶

Un caso que se sale del molde habitual. Un diseñador de Jane Street cuenta que usa Claude Code más que Figma para prototipar. Arranca editor, build, servidor y Claude desde una descripción del problema, itera hasta tener algo casi real y luego lo envía al entorno de desarrollo.

No es un uso de autocompletado. Es Claude como medio de construcción interactiva.

💡 El patrón que se repite entre los usuarios más efectivos es siempre el mismo: investigar → planificar → anotar → implementar. Nunca al revés. Y eso es justo lo que vas a hacer ahora mismo, con las manos en el teclado.

Tu primer cambio real con Claude Code, paso a paso ¶

Suficiente teoría. Vamos a hacer un cambio de verdad sobre el repo que clonaste antes, y vas a ver cómo trabaja Claude Code en cada fase: la investigación, el modo plan y la verificación con tests.

El proyecto es la API de Chiquito de la Calzada de la comunidad de Web Reactiva. No es un juguete: está en TypeScript con Express, valida la entrada con Zod, tiene una suite de tests con Jest y Supertest, y está organizada por capas (rutas, servicios, datos y modelos). Además se construyó con Spec-Driven Development, así que el flujo de “planificar antes de tocar” le sienta como un guante.

El repositorio de partida ¶

La API expone cinco endpoints de lectura: un chiste al azar, una frase al azar, el listado completo de contenido, una búsqueda por palabra clave y el detalle de un elemento por su identificador. La lógica vive en una capa de servicios; las rutas solo orquestan y validan. Y un detalle que vas a necesitar: la búsqueda (/content/search) está declarada antes que el detalle por identificador (/content/:id), porque si no, la ruta dinámica se tragaría la palabra “search”.

El objetivo de tu cambio: añadir GET /api/content/stats, un endpoint que devuelva cuántos chistes y cuántas frases hay. Parece trivial. Tiene la misma trampa que la búsqueda. Y esa trampa es justo la que vamos a cazar antes de escribir una línea.

Paso 1: pregunta, y que escriba lo que aprende ¶

Arrancas dentro del repo y, antes de pedir cambios, dejas que el agente demuestre que entiende el terreno. Y le pides que vuelque sus hallazgos en un fichero, no en el chat: el chat se lo lleva el viento, un documento lo puedes revisar.

No cambies nada todavía. Lee el proyecto en profundidad: qué
endpoints expone, cómo se reparten las capas y cómo están montados
los tests. Escribe tus hallazgos en docs/research.md.

Claude recorre las rutas, los servicios y los tests, y crea docs/research.md con el mapa del proyecto. Si patina aquí, lo descubres ahora, antes de darle permiso para escribir. Barato. Lo que te interesa comprobar en ese documento es que haya entendido tres cosas: la arquitectura por capas, que la validación va con Zod en las rutas y —la joya— que el orden de las rutas importa, porque /content/:id captura cualquier segmento que venga detrás.

Si el agente menciona por su cuenta esa última observación, vas por buen camino. Pero que lo escriba no garantiza que lo respete. Para eso está el siguiente paso.

Paso 2: planifica en modo plan ¶

Aquí entra la pieza que mejor distingue a Claude Code de un chatbot: el modo plan. Es un modo de solo lectura. El agente puede leer ficheros y razonar sobre la arquitectura, pero no puede tocar nada: ni editar, ni ejecutar comandos, ni hacer commits. Investiga y te presenta un plan para que lo apruebes antes de que cambie una sola línea.

Claude Code tiene tres modos de permisos y se cambia entre ellos con Shift+Tab, que los va rotando. El modo activo aparece en la barra de estado:

1. Modo por defecto: te pide confirmación antes de cada edición o comando. El más seguro para empezar.
2. Auto-aceptar ediciones: aplica los cambios sin preguntar, para tareas repetitivas en las que confías.
3. Modo plan: solo lectura. Planifica sin tocar. El que vas a usar ahora.

Pulsa Shift+Tab hasta ver ⏸ plan mode on (o escribe el comando /plan, que hace lo mismo). Con el modo plan activo, le pides el trabajo:

Quiero añadir un endpoint GET /api/content/stats que devuelva el
total de contenido y el desglose por tipo (chistes y frases).
Planifica el cambio.

Claude investiga y, al terminar, te presenta el plan y te frena para que decidas. La respuesta tiene esta pinta:

⏸ plan mode on

Plan para añadir GET /api/content/stats

1. ContentService: nuevo método getContentStats() que cuenta
   los elementos por tipo y devuelve { total, jokes, catchphrases }.
2. contentRoutes: nueva ruta GET /content/stats declarada ANTES
   de /content/:id, para que el validador de UUID no intercepte
   "stats" y responda 400.
3. Tests: caso de integración que comprueba el 200 y que
   total === jokes + catchphrases.

╭───────────────────────────────────────────────╮
│  ¿Quieres continuar?                            │
│ ❯ 1. Sí, y auto-aceptar las ediciones           │
│   2. Sí, pero revisar cada edición a mano        │
│   3. No, seguir planificando                     │
╰───────────────────────────────────────────────╯

Tres caminos: ejecutar el plan (con o sin revisar cada cambio) o seguir afinándolo. Fíjate en que el agente ha llevado al plan la trampa del orden de rutas. Si no lo hubiera hecho, este es el momento de elegir “seguir planificando” y exigírselo, porque del plan al código no hay vuelta atrás fácil.

Y aquí va el truco que usan Boris Tane y compañía: en vez de aprobar a ojo, le pides que guarde el plan en un fichero para revisarlo con calma:

Antes de implementar, guarda el plan en docs/plan.md. Quiero
revisarlo y dejarte notas dentro del propio fichero.

Ese guardado escribe en disco, así que el agente sale del modo plan para hacerlo (un modo de solo lectura no puede crear ficheros). No pasa nada: el plan queda en docs/plan.md y la implementación no arranca hasta que tú lo digas.

Abres docs/plan.md en tu editor, anotas tus correcciones en línea (convenciones del equipo, contexto que el agente no tiene, ese matiz que solo conoces porque ya te diste el golpe) y se lo devuelves para que lo actualice. Ese ida y vuelta es el corazón del método.

🔑 La fase de plan no es papeleo. Es donde inyectas el contexto que el agente no tiene y donde cazas los bugs antes de que existan. Un plan.md revisado vale más que diez “venga, impleméntalo” a ciegas.

Paso 3: que implemente el plan aprobado ¶

Aquí se abren dos caminos, y dependen de lo que hicieras en el paso anterior.

Si guardaste el plan en docs/plan.md.
Guardarlo ya te sacó del modo plan. Tiene su lógica: el modo plan es de solo lectura, y escribir un fichero es, al fin y al cabo, escribir. Así que al pedirle el guardado saliste de ese modo. Ahora tienes que decirle de forma explícita que implemente, señalándole el fichero:

Implementa el plan de docs/plan.md. Ejecuta los tests al terminar
y dime si algo se rompe.

Si no lo guardaste.
Cuando Claude te enseñó el plan en el menú de antes, basta con elegir “Sí” para que salga del modo plan y se ponga manos a la obra con el plan que acabáis de acordar. No hay que pedirle nada más: sigue su curso.

En cualquiera de los dos casos, ¿qué obtienes? Un cambio pequeño y quirúrgico repartido en tres sitios: un método nuevo en la capa de servicios que cuenta el contenido por tipo, una ruta nueva colocada antes de /content/:id (tal y como exigía el plan, con su comentario explicando por qué), y un test de integración que comprueba el 200 y que el total cuadra con la suma de chistes y frases. Ni una línea de más, ni un refactor que nadie pidió.

Lo importante no es el código que escupe, sino que respeta lo que acordasteis: la ruta en su sitio, la validación en su capa y un test que acompaña al cambio.

Paso 4: verifica que no has roto nada ¶

La regla de oro: nunca te fíes de su palabra. Ejecuta los tests tú.

npm test

El repo arrancaba con 58 tests en verde. Después del cambio salen 59, incluido el nuevo de stats, y todo lo demás sigue pasando. Esa es la otra mitad de la ecuación: no basta con que lo nuevo funcione, lo viejo no puede romperse.

¿Y la trampa? Si hubieras dejado que la ruta /content/stats cayera después de /content/:id (lo que habría hecho sin tu nota en el plan), una petición a /api/content/stats no llegaría nunca al handler nuevo: la ruta dinámica trataría “stats” como un identificador, el validador de Zod lo rechazaría por no ser un UUID y la API respondería un 400 en un endpoint que “está implementado”. El tipo de bug que te come una tarde entera. Lo cazaste en el plan, no en producción. Eso es usar Claude Code bien.

🛡️ El cambio fue pequeño, pero el flujo es idéntico para uno enorme: pregunta, investiga en un fichero, planifica en modo plan, anota, implementa, verifica. La diferencia entre un agente útil y un generador de deuda técnica está en quién manda. Y mandas tú.

La plantilla del flujo, lista para reutilizar ¶

Ya has hecho el recorrido completo con un ejemplo. Ahora quédate con la plantilla genérica, la que aplicas a cualquier cambio que tenga sustancia.

Para cualquier cambio que toque varios archivos o partes del sistema que no dominas:

Lee el módulo X en profundidad y escribe tus hallazgos en
docs/research.md. No propongas cambios todavía.

Una vez revisada la investigación, entras en modo plan (Shift+Tab) y pides la estrategia:

Planifica el cambio para [tarea]. Cuando tengas el plan, guárdalo
en docs/plan.md para que lo revise antes de implementar nada.

Y solo cuando el plan está aprobado, implementas con verificación obligatoria:

Implementa el plan de docs/plan.md. Ejecuta los tests después de
cada cambio significativo y dime si algo se rompe.

La documentación de Anthropic dice que darle al agente una forma de verificar su trabajo es la palanca de mayor impacto. Sin criterio de éxito, el bicho improvisa. Por eso el patrón “test que falla primero, implementación después” funciona tan bien:

Escribe un test que falle para el caso del usuario sin permisos.
Después, implementa la lógica para que pase y ejecuta toda la suite.

Si quieres ir más allá con Agent Teams, orquestación de múltiples agentes y sesiones paralelas, ya lo cubrimos en Agent Teams en Claude Code.

Cómo cambiar de modelo con /model ¶

No todas las tareas merecen el mismo motor. Y como Opus consume tokens mucho más rápido que Sonnet, elegir bien el modelo es media batalla del presupuesto.

El comando /model cambia el modelo en mitad de la sesión, sin reiniciar nada. Lo escribes en el prompt, eliges de la lista y el cambio se aplica de inmediato a partir del siguiente mensaje.

/model

La estrategia que mejor relación calidad-coste da:

• Opus para pensar: la fase de investigación y de plan es donde el razonamiento importa. Aquí Opus marca la diferencia detectando trampas como la del orden de rutas.
• Sonnet para ejecutar: una vez el plan está cerrado, implementar es trabajo más mecánico. Sonnet lo hace bien y te deja la ventana de contexto y la cuota para rato.

Cambiar de Opus a Sonnet entre la fase de plan y la de implementación es uno de los ajustes que más estiran una suscripción Pro sin que se note en la calidad del resultado.

Cómo limpiar la ventana de contexto ¶

La ventana de contexto es el espacio de trabajo del agente, y se llena. Cuando se satura, la calidad cae: el modelo “olvida” decisiones tempranas y empieza a contradecirse. Tres comandos te dejan gobernarla, y conviene saber qué hace cada uno porque no son intercambiables.

/context te enseña qué está ocupando tu ventana ahora mismo: el system prompt, las herramientas, los servidores MCP, tu CLAUDE.md y el historial de la conversación. Es el primer comando que deberías mirar cuando notes que el agente va más torpe de lo normal.

/context

/clear borra la conversación y empieza de cero. Lo usas cuando saltas a una tarea que no tiene nada que ver con la anterior. No conserva nada del hilo previo, así que asegúrate de que ya tienes guardado en ficheros (research, plan) lo que necesites recuperar.

/clear

/compact resume el historial conservando lo esencial y libera espacio sin perder el hilo de la tarea en curso. Es el término medio: ni arrastras toda la conversación ni la tiras entera. Eso sí, ten cuidado, porque tras compactar puede perder matices de decisiones anteriores; si la tarea es delicada, mejor /clear y volver a cargar el contexto desde tus ficheros.

/compact

⚠️ Corta sesiones con /clear entre tareas no relacionadas y vigila la ventana con /context. La gestión del contexto no es una manía de gente quisquillosa: es lo que mantiene al agente afilado conforme avanza la sesión.

Lo que hace bien ¶

Vamos con los pros que se repiten entre la documentación y los usuarios reales.

Entiende tareas amplias mejor que los asistentes inline.
La combinación de lectura del repo, shell, git y verificación hace que sea útil en cambios multiarchivo, debugging con contexto, exploración de sistemas y ejecución guiada por plan. Anthropic insiste en que mejora mucho cuando puede verificar por sí mismo con tests, salidas esperadas o screenshots — para esto último, conectar Claude Code a un navegador real vía dev-browser cierra el bucle de verificación visual sobre la UI que el agente acaba de tocar.

Ergonomía de terminal.
La quickstart empieza con cd proyecto && claude, y la documentación sugiere comenzar haciendo preguntas sobre el codebase antes de pedir cambios. Para developers que viven en la terminal, esto es natural. En varios hilos recientes de Hacker News aparece la preferencia por agentes CLI porque resultan más directos y más propensos a hacer lo que se pidió que algunas integraciones de IDE.

Disciplina mediante artefactos persistentes.
CLAUDE.md, planes en markdown, worktrees, subagentes separados y tareas con criterios de verificación convierten al agente en algo gobernable. No perfecto, claro. Pero gobernable, como acabas de ver con el plan guardado en docs/plan.md.

Ecosistema de extensibilidad.
Skills, plugins, hooks, Agent SDK… Si tu agente necesita saber cómo trabaja tu proyecto con Remotion, con Django o con cualquier tecnología específica, le instalas una skill y trabaja como si hubiera leído la documentación. Si quieres explorar el ecosistema, tenemos una guía completa de skills para agentes de IA y un repaso de las 10 mejores skills aplicadas a metodologías.

En la VS Code Marketplace, Claude Code ya supera a Codex de OpenAI en instalaciones (5,2 millones frente a 4,9 millones) y en valoración (4,0 frente a 3,4 sobre 5), según datos de Visual Studio Magazine de febrero de 2026.

Lo que hace mal ¶

Ahora la parte que no sale en el folleto.

El contexto se llena y la calidad cae ¶

La ventana de contexto tiene un límite (200.000 tokens, ampliable a 1 millón en ciertos planes). Todo lo que Claude necesita para funcionar compite por ese espacio: el system prompt, las herramientas, los servidores MCP, tu CLAUDE.md, los ficheros que lee y el historial de la conversación.

La documentación oficial dice que el rendimiento cae cuando el contexto se llena y recomienda usar /clear, compacción y subagentes para mantenerlo bajo control. No es una queja de usuarios exigentes. Está en la guía oficial.

Hay reportes concretos de pérdida de contexto tras compacción. Un post técnico de febrero de 2026 describe cómo, después de compactar, Claude “olvidó” decisiones de media hora antes y empezó a producir código duplicado y patrones contradictorios. No ocurre siempre, pero es un fallo real y documentado.

Si quieres entender cómo gestionar esto, ya escribimos sobre cómo ahorrar tokens en Claude Code.

El consumo de tokens es voraz ¶

Un análisis de usuario en Reddit, con metodología detallada, estimó unas 16.063 tokens de sobrecarga en un directorio vacío y unas 23.000 en un proyecto real. La mayor parte viene de herramientas, skills y MCP cargados al inicio. Es un dato comunitario, no una cifra oficial, pero encaja con la insistencia de Anthropic en gestionar el contexto.

Además, Opus consume mucho más que Sonnet por interacción. Una sesión intensa con Opus puede agotar tu ventana en 15 minutos. Con Sonnet, la misma sesión dura bastante más. Si quieres entender el fenómeno cultural detrás del consumo descontrolado de tokens, tenemos un artículo sobre qué es el tokenmaxxing y cómo usar tokens con criterio.

Los límites pueden ser impredecibles ¶

En Reddit hay quejas recientes de usuarios que describen haber llegado al 60% del uso a las 8:00 de la mañana y al límite a las 8:15 con una sola terminal y un equipo de 3 agentes. Es anecdótico, no estadística pura, pero señala que para usuarios intensivos los límites pesan.

Tiende a pasarse de listo ¶

Sin una fase fuerte de investigación y plan, Claude puede saltar a implementar demasiado rápido o sobre-ingenierizar soluciones. Lo viste con la trampa de la ruta: sin tu nota en el plan, habría dejado un 404 silencioso. Boris Tane y Dave Van Veen insisten en lo mismo desde trincheras diferentes.

Traducido al castellano llano: si no le marcas la pista, te monta una catedral para cambiar una bombilla.

⚠️ La gestión del contexto no es una optimización friki. Es parte central de usar bien Claude Code. Si no la cuidas, la calidad del agente cae en picado conforme avanza la sesión.

Comparativa con OpenCode, Copilot y Codex ¶

Vamos herramienta por herramienta, sin adornar.

Claude Code frente a OpenCode ¶

OpenCode es un agente de código open source con licencia MIT. Su punto diferencial gordo es que soporta más de 75 proveedores de LLM y también modelos locales vía Ollama o LM Studio. Además tiene agentes especializados (Build, Plan, Review, Debug) y carga skills compatibles con el formato de Claude.

La forma simple de verlo:

• Claude Code es más producto cerrado y más coherente. La optimización entre el agente y el modelo Claude es de primer nivel porque los hace la misma empresa.
• OpenCode es más navaja suiza y más hackeable. Si quieres cambiar de modelo, usar local y personalizar hasta el último detalle, tiene más juego.

En Hacker News hay críticas a OpenCode: ritmo de releases alto, testing irregular, consumo de RAM considerable y una TUI que algunos ven recargada. OpenCode ofrece más libertad a cambio de más fricción.

Si quieres una comparativa más profunda con datos de coste, benchmarks y experiencias de developers, tenemos un análisis dedicado en Claude Code vs OpenCode.

Claude Code frente a Copilot ¶

Copilot en 2026 ya no es solo autocompletado. Tiene CLI, coding agent, skills, MCP y un agente en la nube que investiga, planifica y cambia código en una rama dentro de un entorno efímero con GitHub Actions.

Si quieres una comparativa completa con precios y recomendaciones por perfil de las 7 herramientas principales, tenemos la guía de la mejor IA para programar en 2026. La diferencia entre Claude Code y Copilot es de centro de gravedad:

• Copilot está pensado desde GitHub hacia afuera: issues, ramas, PRs, Actions, políticas enterprise. Si tu trabajo vive en backlog de GitHub, Copilot tiene ventaja estructural.
• Claude Code está más centrado en el repo local y en el terminal como puesto de mando. Si tu trabajo vive en shell, repo local y conversación iterativa pegada al código, Claude Code encaja mejor.

En percepción de usuarios, hay comentarios recientes en Hacker News diciendo que Copilot todavía no está al nivel de los productos más agentic cuando se compara con Claude Code y Codex.

Para una comparativa más amplia que incluye también Gemini CLI y Qwen Code, tenemos el artículo de agentes de IA para programación en terminal.

Claude Code frente a Codex ¶

Codex de OpenAI se define como un agente de ingeniería en la nube. Cada tarea se ejecuta en su propio sandbox, precargado con el repositorio. La app de Codex es un “centro de mando para agentes” con hilos por proyecto, worktrees y múltiples agentes paralelos sobre copias aisladas del código.

La diferencia práctica es bastante clara:

• Claude Code se siente como “un agente conmigo en mi shell”. Ida y vuelta constante, conversación pegada al terminal, estado local.
• Codex se siente como “varios trabajadores remotos en sandboxes”. Atacas varias tareas en paralelo sin tocar tu estado local y revisas diffs desde fuera.

Si tu flujo de trabajo requiere paralelismo masivo y revisión asíncrona, Codex tiene una propuesta más natural. Si quieres una conversación cercana y rápida sobre tu árbol de ficheros, Claude Code gana en inmediatez.

Veredicto final ¶

Si lo resumimos sin incienso: Claude Code es una herramienta sólida para developers que quieren un agente de terminal capaz de entender un repositorio, planificar, tocar varios archivos y verificar cambios con autonomía.

Donde más brilla no es en “teclear más rápido”. Es en reducir la fricción cognitiva en tareas que requieren contexto amplio.

Pero usarlo bien implica aceptar tres verdades poco glamurosas, y las acabas de ver en miniatura con la API de Chiquito:

• Hay que gobernar el contexto. Si no, la calidad cae conforme avanza la sesión.
• Hay que forzar verificación. Sin tests ni criterios de éxito, improvisa.
• Hay que separar planificación de ejecución. Cuando la tarea tiene sustancia, dejarle saltar a programar sin plan es una receta para el desastre.

El 52% de los developers aún no usan agentes de IA o se limitan a herramientas más simples, según la Stack Overflow Developer Survey de 2025. Pero entre los que sí los usan, el 69% reporta mejoras en su flujo de trabajo y el 70% dice haber reducido tiempo en tareas concretas.

Claude Code no es perfecto. Ningún agente lo es. Pero si aprendes a gobernarlo —y ya has hecho tu primer cambio real—, puede convertirse en el mejor compañero de terminal que hayas tenido.

Y si quieres seguir exprimiéndolo, tenemos una colección completa de recursos en Web Reactiva: desde los 15 plugins más populares hasta el skill-creator para evaluar y crear skills con datos reales, pasando por 60 tips y trucos para sacarle todo el partido.

La pregunta no es si vas a usar un agente de código. La pregunta es si vas a usarlo bien.

Preguntas frecuentes ¶

¿Cómo se instala Claude Code?

Con el instalador nativo de Anthropic, en un solo comando y sin Node.js. En macOS, Linux o WSL ejecutas curl -fsSL https://claude.ai/install.sh | bash; en Windows, irm https://claude.ai/install.ps1 | iex desde PowerShell. El binario queda en ~/.local/bin/claude y se autoactualiza. Comprueba la instalación con claude --version.

¿Por dónde empiezo si nunca he usado un agente de IA?

Entra en un proyecto real con cd proyecto && claude y empieza haciendo preguntas sobre el código, sin pedir cambios. Cuando veas que el agente entiende tu repositorio, crea tu CLAUDE.md con /init y haz tu primer cambio siguiendo el flujo investigar → planificar → implementar → verificar.

¿Necesito saber programar para usar Claude Code?

Sí. Claude Code no es una herramienta de “no-code”. Está pensada para developers que ya saben programar y quieren un agente que les ayude con tareas complejas. Necesitas entender el código que genera para revisarlo, corregirlo y validarlo. Sin esa capacidad, estás a ciegas.

¿Claude Code funciona con lenguajes que no sean JavaScript o Python?

Sí. Funciona con cualquier lenguaje de programación. Al operar desde la terminal y leer ficheros sin intermediarios, no está limitado a un ecosistema concreto. Trabaja con Rust, Go, Java, PHP, Ruby, C# y cualquier otro lenguaje que uses.

¿Es seguro darle acceso a mi repositorio?

Claude Code se ejecuta en tu máquina y habla con la API de Anthropic. Tu código no se almacena en servidores externos más allá de la ventana de contexto de la sesión. El modo por defecto pide confirmación antes de cada acción destructiva, y git es tu red de seguridad.

¿Puedo usar Claude Code sin conexión a internet?

No. Necesita conectarse a la API de Anthropic para funcionar. Sin conexión, no puede procesar ninguna petición.

¿Qué diferencia hay entre Claude Code y usar Claude en claude.ai?

Claude Code tiene acceso directo a tu sistema de ficheros, tu terminal y tus herramientas de desarrollo. Claude en claude.ai es una interfaz de chat genérica. La diferencia es como entre hablar con un mecánico por teléfono y tenerlo en tu garaje con las herramientas en la mano.

¿Qué es CLAUDE.md y por qué es tan importante?

Es un fichero markdown en la raíz de tu proyecto donde defines instrucciones persistentes para el agente: comandos de build, convenciones de código, restricciones y contexto de proyecto. Sin él, Claude descubre todo desde cero en cada sesión. Con él, arranca sabiendo cómo funciona tu proyecto.

¿Por qué debería pedirle un plan antes de implementar?

Porque sin plan el agente salta a programar y tiende a sobre-ingenierizar o a pasar por alto trampas que solo tú conoces. Pedir un plan.md, anotarlo con tus correcciones y devolvérselo te deja inyectar contexto y cazar bugs antes de que existan, como el solapamiento de rutas del ejemplo de este tutorial.

¿Cuándo debería usar Claude Code en lugar de un asistente inline como Copilot?

Cuando la tarea va más allá de completar una línea o una función. Si necesitas entender un módulo, planificar un refactor, tocar varios archivos o automatizar un flujo de trabajo, Claude Code tiene ventaja. Para autocompletado rápido mientras escribes, un asistente inline sigue siendo más cómodo.

Fuentes ¶

• Claude Code - Documentación oficial
• Claude Code - Best practices (Anthropic Engineering)
• Claude Code - Quickstart
• Claude Code - Setup e instalación
• Stack Overflow Developer Survey 2025 - AI
• SWE-bench Verified Leaderboard (llm-stats)
• Boris Tane - How I Use Claude Code
• Dave Van Veen - Agentic Coding
• Jane Street - I Design with Claude Code More Than Figma Now
• Visual Studio Magazine - Claude Code vs Codex in VS Code Marketplace
• BSWEN - Claude Context Loss After Compaction
• Reddit - I Measured Claude Code’s Hidden Token Overhead
• OpenCode - Documentación
• GitHub Blog - Copilot CLI GA
• OpenAI - Introducing Codex
• GitHub - Claude Code Action

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter