CubeLabs

1. El bucle agéntico y las herramientas

Claude Code es un asistente agéntico que corre en tu terminal. A diferencia de un autocompletado inline que solo ve el archivo abierto, Claude Code ve todo tu proyecto: ficheros, git, comandos y configuraciones. Cuando le das una tarea, trabaja en tres fases que se mezclan continuamente: reunir contexto, actuar y verificar resultados.

Ese ciclo se llama bucle agéntico (agentic loop). Claude decide qué necesita en cada paso encadenando decenas de acciones y corrigiendo el rumbo sobre la marcha. Tú eres parte del bucle: puedes interrumpir en cualquier momento para redirigirlo.

Los modelos

Claude Code usa los modelos de Anthropic para razonar. Sonnet maneja bien la mayoría de tareas de código; Opus aporta razonamiento más fuerte para decisiones arquitectónicas complejas. Cambia de modelo durante la sesión con /model o al arrancar con claude --model <nombre>.

Las herramientas (tools)

Las herramientas son lo que hace agéntico a Claude Code. Sin ellas solo respondería texto; con ellas actúa: lee, edita, ejecuta y consulta. Cada uso de herramienta devuelve información que alimenta la siguiente decisión. Las herramientas integradas caen en cinco categorías:

Por ejemplo, si dices "arregla los tests que fallan", Claude podría: ejecutar la suite para ver qué falla, leer la salida del error, buscar los ficheros fuente, leerlos, editarlos y volver a ejecutar los tests para verificar. Eso es el bucle agéntico en acción.

2. Instalación en 5 minutos

Instalar Claude Code es un comando. La instalación nativa es la recomendada: se actualiza sola en segundo plano. La instalación por npm está deprecada, no la uses.

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

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

claude --version

El comando imprime un número de versión seguido de (Claude Code). También puedes instalar con gestores de paquetes de Linux: apt (Debian/Ubuntu), dnf (Fedora/RHEL) o apk (Alpine).

3. Autenticación y primera sesión

Claude Code requiere una cuenta. Arranca una sesión interactiva con el comando claude y, en el primer uso, te pedirá iniciar sesión en el navegador:

cd /ruta/a/tu/proyecto
claude

Verás el prompt de Claude Code con la versión, el modelo actual y el directorio de trabajo. Escribe /help para ver los comandos disponibles o /resume para continuar una conversación anterior.

Tipos de cuenta soportados

Si tienes la variable ANTHROPIC_API_KEY definida, Claude Code se salta el prompt de login y solo te pide aprobar el uso de la clave. Para cambiar de cuenta o reautenticarte, escribe /login dentro de la sesión. Las credenciales se guardan y no tendrás que volver a iniciar sesión.

4. El agente en acción: preguntar, editar y usar git

Empieza preguntando sobre tu propio proyecto. Claude Code lee tus ficheros según los necesita — no tienes que añadir contexto manualmente.

¿qué hace este proyecto?
¿qué tecnologías usa?
¿dónde está el punto de entrada principal?
explícame la estructura de carpetas

Primer cambio de código

Pide una tarea concreta: "añade una función hello world al archivo principal". Claude localiza el archivo y te muestra el cambio; en tu primera sesión te preguntará antes de cada modificación. Después, el modo auto se convierte en el modo de permisos inicial en los planes Pro, Max y Team: un clasificador revisa las acciones en segundo plano y Claude edita la mayoría de archivos y ejecuta la mayoría de comandos sin preguntarte.

Git conversacional

Las operaciones de git se vuelven lenguaje natural:

¿qué archivos he cambiado?
haz commit de mis cambios con un mensaje descriptivo
crea una rama llamada feature/quickstart
enséñame los últimos 5 commits
ayúdame a resolver conflictos de merge

Refactor, tests y documentación

• Refactorizar: "refactoriza el módulo de autenticación para usar async/await en vez de callbacks"
• Escribir tests: "escribe tests unitarios para las funciones de la calculadora"
• Actualizar docs: "actualiza el README con las instrucciones de instalación"
• Code review: "revisa mis cambios y sugiere mejoras"

Interrumpir y dirigir

No necesitas esperar a que termine un turno para corregir el rumbo. Pulsa Esc para detener a Claude inmediatamente, o escribe una corrección y pulsa Enter para enviarla sin parar la herramienta en ejecución — Claude la lee al terminar la acción actual y ajusta su siguiente paso.

5. Permisos, modos y checkpoints

Claude Code tiene dos mecanismos de seguridad: checkpoints para deshacer cambios de archivos y modos de permisos para controlar qué puede hacer sin preguntarte.

Checkpoints: deshacer es gratis

Antes de editar un archivo, Claude Code hace una instantánea del contenido. Si algo sale mal, pulsa Esc dos veces para retroceder a un estado anterior, o pídele que deshaga. Los checkpoints son independientes de git y siguen disponibles al reanudar una conversación. Solo cubren cambios de archivo: las acciones sobre sistemas remotos (bases de datos, APIs, despliegues) no se pueden deshacer con checkpoints.

Modos de permisos

Pulsa Shift+Tab para ciclar entre los modos de permisos de la sesión actual:

También puedes permitir comandos concretos en .claude/settings.json para que Claude no pregunte cada vez — útil para comandos de confianza como npm test o git status. La configuración se puede escalar desde políticas de organización hasta preferencias personales.

{
  "permissions": {
    "allow": [
      "npm test",
      "git status",
      "git log"
    ]
  }
}

6. Memoria persistente: CLAUDE.md y auto memory

Cada sesión de Claude Code empieza con una ventana de contexto fresca: no recuerda la conversación anterior. Dos mecanismos llevan conocimiento entre sesiones:

Dónde vive cada CLAUDE.md

Cómo escribir instrucciones efectivas

• Tamaño: apunta a menos de 200 líneas por archivo; más contexto reduce la adherencia.
• Especificidad: "usa indentación de 2 espacios" en vez de "formatea el código bien".
• Importa otros archivos con la sintaxis @ruta/al/archivo: @README o @package.json se expanden en contexto al arrancar.
• AGENTS.md: Claude Code lee CLAUDE.md, no AGENTS.md. Si tu repo ya usa AGENTS.md, crea un CLAUDE.md que lo importe con @AGENTS.md para no duplicar.

Ejecuta /init para que Claude analice tu codebase y genere un CLAUDE.md inicial con comandos de build, instrucciones de test y convenciones del proyecto. Para confirmar que un archivo de memoria se cargó, ejecuta /context y mira la sección Memory files.

7. Sesiones: resume, fork y worktrees

Claude Code guarda tu conversación localmente mientras trabajas: cada mensaje, uso de herramienta y resultado se escribe en un archivo JSONL de texto plano bajo ~/.claude/projects/. Eso permite reanudar, bifurcar y rebobinar sesiones.

Las sesiones son independientes

Cada sesión nueva empieza con una ventana de contexto fresca, sin historial de sesiones anteriores. Claude puede persistir aprendizajes con auto memory y tú añades instrucciones persistentes en CLAUDE.md. Las sesiones están ligadas al directorio actual: si cambias de rama, Claude ve los archivos de la nueva rama pero conserva la conversación.

Reanudar y bifurcar

claude --continue    # reabre la última sesión con el mismo ID
claude --resume      # elige sesión del selector interactivo
claude --fork-session # copia el historial a un ID nuevo, sin tocar el original

Dentro de la sesión también puedes usar /resume para abrir el selector y /branch para bifurcar. El selector muestra por defecto las sesiones del worktree actual, con atajos de teclado para ampliar a otros worktrees o proyectos.

Sesiones paralelas con git worktrees

Como las sesiones están ligadas a directorios, puedes ejecutar varias sesiones en paralelo usando git worktrees, que crean directorios separados para ramas individuales. Es la forma recomendada de trabajar en varias ramas a la vez sin colisiones.

git worktree add ../proyecto-feature feature/quickstart
cd ../proyecto-feature
claude

Gestiona el contexto

El contexto se llena con el historial, contenidos de archivos, salidas de comandos y memoria. Claude compacta automáticamente: primero limpia salidas de herramientas antiguas y luego resume la conversación si hace falta. Ejecuta /context para ver qué consume espacio, y /compact para resumir manualmente con un foco: /compact focus on the API changes.

8. MCP: conecta servicios externos

El Model Context Protocol (MCP) permite a Claude Code usar herramientas más allá de las integradas: buscar en un gestor de issues, consultar una base de datos o controlar un navegador. Estas herramientas vienen de servidores MCP que corren en tu máquina o como servicios alojados.

Conectemos un servidor MCP de principio a fin con el CLI. El ejemplo usa el servidor MCP de la documentación de Claude Code, que no requiere autenticación y es perfecto como primer servidor de prueba:

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

claude mcp list

claude
usa el servidor claude-code-docs para buscar qué hace MCP_TIMEOUT

claude mcp remove claude-code-docs

Scopes de configuración

9. Skills, subagentes y plugins

La capa de extensión de Claude Code te permite personalizar qué sabe, a qué se conecta y cómo automatiza. Estas son las piezas clave:

Skills: conocimiento reutilizable

Una skill es un archivo markdown con conocimiento, workflows o instrucciones. Se invoca con un comando como /deploy, o Claude la carga automáticamente cuando es relevante. Claude ve las descripciones de las skills al inicio de la sesión, pero el contenido completo solo se carga on demand — así no desperdicias contexto.

# .claude/skills/deploy/SKILL.md
---
description: Ejecuta el checklist de despliegue del proyecto
---
1. Ejecuta `npm run build`
2. Verifica que no hay errores de tipos
3. Publica el artefacto con `npm publish`

Subagentes: trabajo aislado

Un subagente ejecuta su propio bucle en una ventana de contexto separada y devuelve solo un resumen. Ideal para tareas de investigación que leen muchos archivos, trabajo paralelo o workers especializados. Las llamadas a herramientas del subagente no ensucian tu contexto principal.

Plugins: empaqueta y comparte

Un plugin agrupa skills, subagentes, hooks y servidores MCP en una unidad instalable. Se comparte entre repositorios o se distribuye vía marketplaces. Cada plugin vive en su propio directorio con un manifiesto .claude-plugin/plugin.json:

mkdir -p my-first-plugin/.claude-plugin my-first-plugin/skills/hello

{
  "name": "my-first-plugin",
  "description": "Un plugin para aprender lo básico",
  "version": "1.0.0",
  "author": { "name": "Tu Nombre" }
}

Las skills de un plugin quedan con namespace (por ejemplo /my-first-plugin:hello), de modo que varios plugins pueden coexistir sin colisionar. Empieza con configuración standalone en .claude/ para iterar rápido y conviértela a plugin cuando quieras compartirla.

10. Headless y CI: claude -p y Agent SDK

El modo no interactivo (headless) ejecuta Claude Code desde scripts y pipelines de CI. Se usa con la bandera -p (o --print):

claude -p "Encuentra y arregla el bug en auth.py" --allowedTools "Read,Edit,Bash"

Claude Code sale con código 0 en éxito y código distinto de cero si el run falla, de modo que tus scripts pueden ramificar según el estado de salida.

Opciones que combinan con -p

Pipe: Claude como herramienta de terminal

El modo no interactivo lee de stdin, así que puedes encadenarlo como cualquier herramienta CLI:

cat build-error.txt | claude -p 'explica de forma concisa la causa raíz de este error de build' > output.txt

Con --output-format json, la respuesta incluye total_cost_usd y desglose de costes por modelo — ideal para scripts que controlan el gasto por invocación. El stdin canalizado tiene un tope de 10MB.

Claude como linter en tu build

Envuelve una llamada no interactiva en un script de package.json para usar Claude como revisor de tu proyecto:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"eres un linter de erratas. por cada errata en este diff, reporta archivo:línea en una línea y el problema en la siguiente. no devuelvas nada más.\""
  }
}

Ejecútalo con npm run lint:claude. Para CI, añade --bare para que no cargue hooks ni configuración del host y el resultado sea reproducible en cualquier máquina. En modo bare, define ANTHROPIC_API_KEY en el entorno (no usa tu login OAuth).