Claude Code: la guía completa (septiembre de 2026)

Claude Code es el agente de código de Anthropic: lee los archivos de un proyecto, los cambia, ejecuta comandos y comprueba su propio trabajo. Esta guía explica cómo funciona por dentro y cómo se configura, para quien ya lo usa o quiere construir con él. Si buscas si te conviene, empieza por la ficha de Claude Code.

Todo lo que sigue está comprobado contra la documentación oficial el 27 de septiembre de 2026, con la versión 2.1.283. Claude Code cambia cada pocos días: si lees esto meses después, algún comando habrá cambiado de nombre o de sitio. Dentro de la herramienta, /release-notes enseña qué ha cambiado.

Antes de entrar en comandos, una forma sencilla de entenderlo. Imagina que contratas a un ayudante muy rápido para tu negocio. Llega el primer día sin saber nada de tu empresa, trabaja en tu computadora y hace lo que le pides: ordenar archivos, arreglar tu web, preparar un informe. Todo lo que sigue en esta guía son las formas de decirle cómo trabajar, qué puede tocar y cómo comprobar que lo hizo bien.

La documentación lo define con una frase útil: Claude Code es la capa que rodea al modelo, la que le da herramientas y decide qué contexto ve. Esa capa se llama arnés. El modelo —Claude, en la versión que elijas— razona; el arnés le deja actuar sobre tu proyecto. Lo explicamos con calma en qué es el arnés de un agente de código.

El mismo motor está disponible en varios sitios. Tu archivo de instrucciones del proyecto viaja con el repositorio, pero no toda la configuración llega a todas partes: las sesiones en la nube, por ejemplo, no leen los ajustes personales de tu computadora.

Para usarlo hace falta un plan de pago de Claude (Pro, Max, Team o Enterprise), una cuenta de la consola de la API con crédito o un proveedor de nube compatible. El plan gratuito de Claude no lo incluye. Los precios cambian: se consultan en la página oficial.

El instalador recomendado es el nativo, que se actualiza solo. Con Homebrew o WinGet también se instala, pero entonces las actualizaciones son manuales.

La primera vez te pide iniciar sesión en el navegador. Si algo falla, /doctor revisa la instalación y propone arreglos. Y si prefieres no abrir la terminal, la aplicación de escritorio hace lo mismo con ventanas.

Cuando le das una tarea, Claude Code recorre tres fases que se mezclan entre sí: reunir contexto (buscar y leer archivos), actuar (editar, ejecutar comandos) y verificar (pasar las pruebas, mirar el resultado). Después de cada paso decide el siguiente con lo que aprendió, y puede encadenar decenas de acciones.

Tú también estás dentro del bucle: puedes interrumpirle en cualquier momento con Esc, corregir el rumbo o darle más contexto. Si le pides «arregla las pruebas que fallan», lo normal es que ejecute las pruebas, lea el error, busque los archivos implicados, los lea, los edite y vuelva a ejecutar las pruebas para comprobarlo.

De esto sale el consejo más repetido en la documentación: dale una forma de verificar su trabajo. Unas pruebas, un comando que compile, una captura que comparar. Sin eso, el agente puede darte por buena una tarea que no lo está.

Cada sesión empieza con la memoria en blanco. Dos mecanismos llevan el conocimiento de una sesión a otra.

El archivo de instrucciones es un archivo de texto que escribes tú y que Claude lee al empezar: cómo se prueba el proyecto, qué convenciones sigue, qué no se toca. Hay varios niveles y se suman, no se sustituyen. Te lo contamos paso a paso en cómo se escribe un CLAUDE.md.

Tres detalles que conviene saber:

• Corto funciona mejor. La documentación recomienda menos de 200 líneas por archivo: uno largo ocupa contexto y se sigue peor. Si crece, se reparte en .claude/rules/.
• Se pueden importar archivos con @ruta/al/archivo dentro del CLAUDE.md. Así un solo AGENTS.md puede servir a Claude Code y a otras herramientas: el CLAUDE.md lo importa.
• AGENTS.md se lee directamente desde la versión 2.1.277. Si el proyecto tiene AGENTS.md y no tiene CLAUDE.md ni CLAUDE.local.md, Claude Code lee el AGENTS.md; si tiene los dos, lee solo el CLAUDE.md, salvo que lo importe o cambies el ajuste «Project instructions» en /config.

La memoria automática son notas que Claude escribe por su cuenta: tus preferencias, las correcciones que le haces, decisiones del proyecto y dónde encontrar información externa. Se guardan en ~/.claude/projects/<proyecto>/memory/, con un índice, MEMORY.md, del que se cargan al empezar las primeras 200 líneas o 25 KB. Con /memory editas tus archivos de instrucciones y activas o desactivas la memoria automática.

El modo decide qué hace Claude sin preguntarte. Se cambia con Shift+Tab en la terminal o con el selector en la aplicación y en los editores. Desde la versión 2.1.283, el modo automático es el de inicio para las sesiones interactivas en la terminal y en VS Code, cuando está disponible y ningún ajuste lo cambia.

Hay cosas que ningún modo aprueba solo: lo que coincide con una regla que dice «preguntar», las herramientas que necesitan que respondas tú y el borrado de rutas críticas del sistema.

Por encima del modo van las reglas: listas de lo permitido, lo que debe preguntarse y lo prohibido. Se guardan en los archivos de ajustes —~/.claude/settings.json para ti, .claude/settings.json para el proyecto y .claude/settings.local.json para tus ajustes locales del proyecto— y se gestionan con /permissions. Una regla de denegar bloquea en todos los modos, incluso en el que no comprueba nada.

Con esas reglas, Claude ejecuta los scripts del proyecto y hace commits sin preguntar, y el comando git push escrito en esa forma queda bloqueado. Ojo: una regla de comandos no es una barrera de seguridad completa, porque una variante del mismo comando puede no coincidir con el patrón. Para lo que no debe pasar de ninguna manera, se combina con un hook y con el sandbox. Si te cansas de aprobar los mismos comandos de lectura, /fewer-permission-prompts revisa tus sesiones y propone una lista de permisos.

El sandbox va un paso más allá: aísla los comandos a nivel del sistema operativo, de modo que solo tocan las carpetas y los dominios que permitas. Se activa con /sandbox en Mac, Linux y WSL.

Se escriben con / al principio de la línea. /help los lista todos y, al teclear /, aparece un buscador. Algunos son en realidad skills que vienen incluidas, como /loop, /batch o /debug.

Tres comandos que quizá veas en guías antiguas ya no existen: /vim (el modo Vim está ahora en /config), /pr-comments (se le pide directamente a Claude) y /ultraplan (se usa el modo plan).

• Esc interrumpe a Claude o cierra un diálogo. Esc dos veces vacía lo que estás escribiendo o abre el rebobinado.
• Shift+Tab cambia de modo de permiso.
• Ctrl+B manda a segundo plano lo que se está ejecutando. Ctrl+T muestra u oculta la lista de comprobación de Claude y Ctrl+O, la transcripción completa; el trabajo en segundo plano se ve con /tasks.
• Option+P en Mac o Alt+P en Windows y Linux cambia de modelo.
• ! al principio de la línea ejecuta un comando directamente y le pasa el resultado a Claude. @ sugiere rutas de archivo.
• Ctrl+C interrumpe o borra lo escrito, y Ctrl+D cierra la sesión.

La ventana de contexto guarda la conversación, los archivos leídos, lo que devuelven los comandos, las instrucciones y las skills cargadas. Cuando se acerca al límite, Claude Code primero quita salidas viejas de herramientas y después resume la conversación. Lo que pediste y el código importante se conservan; las instrucciones que diste al principio de la charla pueden perderse. Por eso las reglas que deben durar van en el CLAUDE.md, no en la conversación.

Cuatro costumbres ayudan:

• Mira qué ocupa espacio con /context antes de que se llene.
• Compacta con intención: /compact con un foco —«conserva los cambios de la API»— resume mejor que el automático.
• Empieza limpio con /clear cuando cambias de tarea: una conversación larga arrastra decisiones viejas.
• Deja fuera lo que no hace falta: las skills y las herramientas MCP se cargan bajo demanda, y los subagentes trabajan en su propio contexto y solo devuelven un resumen.

Al empezar cada turno, Claude Code crea un punto de control de las ediciones que hace con sus herramientas de archivos. Si algo sale mal, Esc dos veces o /rewind vuelven a un punto anterior de la conversación, del código o de los dos. Los puntos de control son independientes de git y siguen disponibles al retomar una sesión.

Tienen límites: no deshacen lo que cambió un comando de terminal, ni las ediciones de los subagentes, ni nada fuera de tu computadora, como una base de datos o un despliegue. Eso se controla con el modo de permiso y las reglas.

Con /model eliges el modelo; con alias no hace falta recordar versiones: opus para razonar a fondo, sonnet para el trabajo diario, haiku para tareas sencillas y rápidas. opusplan usa Opus mientras planifica y Sonnet para ejecutar. Hay variantes con ventana de contexto de un millón de tokens. En los planes Pro, Max, Team y Enterprise el modelo por defecto es Opus 5.5.

El esfuerzo decide cuánto razona el modelo en cada paso: low, medium, high, xhigh o max, según el modelo. Menos esfuerzo es más rápido y barato en tareas sencillas; más esfuerzo ayuda en las difíciles. Se cambia con /effort o con las flechas en el selector de /model. Opus 5.5 empieza en medium.

Un hook es un comando que Claude Code ejecuta automáticamente en un momento concreto: al empezar la sesión, antes de usar una herramienta, después de editar un archivo, al terminar de responder, antes de compactar el contexto y en una treintena de momentos más. Se configuran en los mismos archivos de ajustes que los permisos, y /hooks enseña los que tienes.

Su valor está en que no dependen de que Claude se acuerde: el hook se ejecuta pase lo que pase. Sirven para formatear el código después de cada edición, avisarte cuando Claude necesita algo o cargar contexto al empezar. Y un hook de tipo PreToolUse puede bloquear una acción antes de que ocurra: si el comando termina con código de salida 2, la herramienta no se ejecuta.

Ese es el ejemplo de la documentación: cada vez que Claude vaya a ejecutar un rm, antes corre un script tuyo que puede dejarlo pasar o bloquearlo. Lo que no conseguirías con una línea en el CLAUDE.md, lo consigues con un hook.

Una skill es una carpeta con un archivo SKILL.md: instrucciones para una tarea concreta y, si hace falta, scripts o plantillas. Al empezar, Claude ve una descripción breve de las skills que puede usar por su cuenta y lee el resto cuando las necesita; las reservadas para que las invoques tú se cargan al invocarlas. Así, tener muchas cuesta poco contexto. Las invocas tú con /nombre o Claude las usa cuando la descripción encaja con lo que le pides. Van en ~/.claude/skills/ (tuyas, en todos los proyectos), en .claude/skills/ (del proyecto) o dentro de un plugin. /skill-doctor enseña cuánto contexto cuesta cada una y cuáles no usas. Lo explicamos a fondo en skills en Claude Code.

Un subagente es otra instancia de Claude con su propio contexto, su propio conjunto de herramientas y, si quieres, su propio modelo. Trabaja aparte y te devuelve un resumen, así que lo que lee no ocupa tu conversación. Entre los que trae de serie están Explore, que busca y analiza código sin poder editar; Plan, que investiga para el modo plan; y uno de propósito general para tareas de varios pasos.

Los tuyos se definen como archivos Markdown en .claude/agents/ (del proyecto) o ~/.claude/agents/ (tuyos), con una cabecera que dice su nombre, cuándo usarlo, qué herramientas tiene y qué modelo usa. Con isolation: worktree trabajan en una copia aislada del repositorio. Y /subtask lanza un subagente que hereda la conversación entera para una tarea lateral.

Dos recetas que sirven a casi cualquiera, adaptadas de la documentación:

MCP es el protocolo que conecta al agente con servicios externos: tu gestor de tareas, una base de datos, el navegador, Notion o GitHub. Cada servidor MCP añade herramientas. Para no gastar contexto, Claude Code normalmente carga las definiciones de esas herramientas cuando las usa, salvo que la configuración pida cargarlas al inicio.

El alcance decide quién lo ve: local, el predeterminado, solo tú en este proyecto; project, todo el equipo, a través del archivo .mcp.json; y user, tú en todos tus proyectos. Dentro de la sesión, /mcp enseña el estado de cada conexión y permite autenticarse.

Un plugin es una carpeta que agrupa skills, subagentes, hooks y servidores MCP, con un manifiesto que le da nombre y puede indicar la versión. Sirve para instalar de una vez la forma de trabajar de un equipo. Se gestionan con /plugin y se instalan desde catálogos llamados marketplaces; conviene distinguir los de Anthropic de los de terceros antes de instalar nada.

claude -p "tarea" ejecuta una tarea sin abrir la sesión interactiva y devuelve el resultado, en texto o en JSON con --output-format. Es la base para automatizar: revisiones en cada pull request, informes programados o pasos de un despliegue. Para scripts, la documentación recomienda --bare (necesita una clave de API o credenciales de un proveedor compatible, porque no usa el inicio de sesión de tu suscripción), que arranca sin cargar hooks, skills, plugins, MCP ni instrucciones del proyecto, de modo que el resultado no depende de la carpeta. Para construir tus propios agentes con el mismo motor está el Agent SDK, en Python y TypeScript.

En la parte inferior de la sesión se puede mostrar una línea con lo que quieras vigilar: el modelo, cuánto contexto queda, la rama de git o el uso del plan. Con /statusline se describe en español lo que quieres ver —por ejemplo, «el modelo y el porcentaje de contexto con una barra»— y Claude Code genera el script que la dibuja. Quien trabaja muchas horas con el agente la mira constantemente: saber cuánto contexto queda es lo que te dice cuándo abrir una sesión limpia.

Encargos listos para copiar, pensados para tareas normales de un negocio. Cambia lo que va entre corchetes.

• Dale una forma de comprobar su trabajo: pruebas, un comando que compile o una captura con la que comparar.
• Primero explorar, luego planificar, luego programar. El modo plan existe para eso: que Claude entienda y proponga antes de tocar nada.
• Contexto concreto en cada encargo: qué archivo, qué error, qué resultado esperas. «Arregla el login» da peor resultado que el mensaje de error completo y el archivo implicado.
• Configura el entorno una vez: un CLAUDE.md corto, permisos para los comandos de confianza, hooks para lo que no puede fallar.
• Gestiona la sesión: interrumpe pronto si va mal, rebobina en lugar de discutir y abre una sesión nueva al cambiar de tarea.

Si vas a llevar un proyecto grande, sigue con cómo llevar un proyecto grande con Claude Code.