@santtiagom_: Cuando empecé a usar Claude Co...
Cuando empecé a usar Claude Code, lo trataba como un chat: le pedía algo, respondía y listo.
Funcionaba.
Pero con el tiempo empecé a notar que no le estaba sacando todo el potencial. Repetía los mismos prompts. Ejecutaba los mismos comandos. No tenía claro cómo aprovecharlo al máximo.
Entonces frené y me hice una pregunta:
¿cómo funciona realmente Claude Code?
Me puse a leer la documentación, a experimentar, a probar. Y lo que fui descubriendo es esto:
No hace magia. Está armado sobre piezas concretas, cada una con un rol claro. Y cuando las entendés, todo lo demás empieza a tener sentido.
Si siempre repetís las mismas instrucciones, lo convertís en una Skill.
Si pierde el hilo en una tarea larga, delegás en un SubAgent.
Si hay pasos manuales que repetís, los automatizás con Hooks.
Entender los fundamentos es lo que te permite saber qué usar, cuándo y por qué.
Hoy tengo más de 100 Skills, procesos automatizados que antes me llevaban horas y agentes para hacer code review y estudiar temas que me interesan.
Escribí este artículo para compartirte todo lo que aprendí: cómo funciona el loop agéntico, qué son las tools, la memoria, los hooks y mucho más.
Arranquemos.
Agent Loop: el corazón de Claude Code
Claude Code es un agente. Un sistema al que le das un objetivo y trabaja hasta cumplirlo.
Es diferente a un chat.
En un chat, le preguntás "¿cómo agrego autenticación a mi app?" y te explica los pasos. Pero tenés que ir al proyecto, modificar el código y probar si funciona. Vos hacés el trabajo.
Con Claude Code le decís "agregá autenticación a mi app" y él se encarga. Lee el código, elige la librería, escribe los cambios y te avisa cuando terminó.
Tiene un objetivo: agregar autenticación. Y trabaja hasta cumplirlo.
¿Pero cómo sabe qué hacer después de cada paso? Si agrega un componente, ¿cómo sabe si funcionó? Necesita algo que coordine esas decisiones.
Eso es el loop.
Un ciclo que se repite. Claude Code ejecuta una acción, observa el resultado, decide qué hacer después, y vuelve a empezar. No para hasta cumplir el objetivo.
No ejecuta los pasos una sola vez y listo. Los repite tantas veces como sea necesario. Si algo falla, vuelve atrás, corrige, y sigue.
El loop tiene 3 fases:
El loop se adapta a lo que pedís.
Una pregunta sobre tu proyecto puede requerir solo reunir contexto. Arreglar un error puede pasar por las tres fases repetidamente. Claude Code decide qué requiere cada paso en base a lo que aprendió del anterior. Así logra cumplir los objetivos.
Seguimos con la autenticación. Por ejemplo, solucionar un bug en el boton del login:
```plaintext
Reunir contexto
→ busca el componente del botón de login
→ lee el código, encuentra que al hacer click no pasa nada
Tomar acción
→ agrega la lógica que faltaba
→ actualiza el componente
Verificar resultados
→ corre los tests → pasan
→ listo
```Y vos también sos parte de ese loop. Podés interrumpir en cualquier momento para redirigir a Claude Code, agregar contexto, o pedirle que pruebe otro enfoque.
Este es el corazón de Claude Code. Todo lo que viene después existe para hacer este loop más poderoso.
¿Pero cómo lo hace? ¿Cómo lee archivos, corre comandos, corrige errores? A través de las tools.
Tools: cómo Claude Code actúa en el mundo
Claude Code es un agente construido alrededor de un LLM. Y un LLM, por diseño, solo procesa texto. Recibe texto y genera texto. No tiene acceso a tu sistema de archivos, no puede ejecutar comandos, no sabe qué hay en tu proyecto. Está aislado.
Entonces, ¿cómo hace Claude Code para actuar? ¿Para abrir un archivo o modificarlo?
Utiliza tools.
Las tools son funciones que Claude Code puede invocar para interactuar con el mundo real. Cada tool tiene un nombre, parámetros específicos, y devuelve un resultado que Claude Code usa para decidir el siguiente paso.
Pensalo como las apps de un celular. El teléfono por sí solo no hace nada. Son las apps las que le dan capacidades concretas: sacar fotos, mandar mensajes, navegar. Las tools son lo mismo para Claude Code: cada una le da una capacidad específica para interactuar con tu entorno.
Cada vez que Claude Code usa una tool, le manda al sistema una solicitud con lo que necesita. El sistema la ejecuta y le devuelve el resultado. Claude Code usa ese resultado para decidir qué hacer después. Y así sigue hasta terminar.
Por ejemplo: para leer un archivo, usa la tool Read con el path del archivo. El sistema lo abre y le devuelve el contenido. Claude Code lo lee y decide el próximo paso.
```plaintext
Tu pedido
↓
Claude Code decide qué tool usar
↓
┌─────────────────────────────────────┐
│ Read · Edit · Write · Bash │
│ Grep · Glob · WebFetch · WebSearch │
└─────────────────────────────────────┘
↓
Sistema ejecuta la tool
↓
Resultado vuelve a Claude Code
↓
¿Terminó? → No → usa otra tool
Sí → responde
```Claude Code viene con tools nativas para las operaciones más comunes:
Read / Edit / Write -> leer, modificar y crear archivos. Las más usadas. Cada vez que Claude Code "entiende tu código" o "hace un cambio", está usando estas tres.
Bash -> acceso completo a la terminal. Si podés hacerlo desde la línea de comandos, Claude Code también puede: instalar dependencias, correr tests, hacer commits.
Grep y Glob -> buscar dentro del proyecto. Glob encuentra archivos por nombre o patrón. Grep busca contenido específico dentro de los archivos.
WebFetch y WebSearch -> acceso a internet. Consultar documentación, leer una API, investigar un error que nunca vio antes.
Volviendo al ejemplo del bug en el botón de login. Cuando Claude Code trabaja en eso, usa varias tools en conjunto:
Todo eso sin que vos intervengas. Esa es la diferencia entre un chat y un agente.
Estas tools cubren la mayoría de lo que necesitás en el día a día. Pero tienen un límite: solo pueden interactuar con lo que está en tu máquina. Para conectarse con el mundo externo, existe MCP. Pero eso viene más adelante.
Context y Memory: lo que Claude Code recuerda
Ya vimos el loop y las tools.
Claude Code trabaja, ejecuta acciones, obtiene resultados y decide qué hacer después. Pero ¿cómo sabe qué hizo a medida que va avanzando? ¿Cómo recuerda el paso anterior?
Todo es gracias al contexto.
El contexto es la información que Claude Code tiene disponible en ese momento. Cada vez que ejecuta una acción, el resultado se va acumulando ahí adentro. No solo tu prompt inicial, sino todo lo que va encontrando: los archivos que abrió, lo que descubrió en el código, las acciones que ejecutó y los resultados.
Cuando le pedís que arregle el bug del botón de login, primero lee el archivo, después encuentra el error, después lo corrige, después corre los tests. En cada paso, lo que aprendió en el anterior está en el contexto. Por eso puede tomar mejores decisiones a medida que avanza.
Aplicado al ejemplo del botón de login:
```markdown
"arreglá el bug del botón de login"
↓
┌──────────────────────────────────────────┐
│ Contexto activo │
│ │
│ Pedido: arreglá el bug del botón │
│ Archivo leído: LoginButton.tsx │
│ Descubrió: al hacer click no pasa nada │
│ Acción: agregó la lógica que faltaba │
│ Test corrido: pasó │
│ │
└──────────────────────────────────────────┘
↓
Claude Code decide qué sigue
```Cada pieza de información que entra al contexto alimenta la siguiente decisión. Por eso puede encadenar pasos, corregirse, y terminar la tarea solo.
Ese contexto tiene 2 problemas.
1) Tiene capacidad limitada. Si la sesión es muy larga, el contexto se llena y Claude Code empieza a olvidar lo que pasó antes. Más adelante vas a ver cómo los SubAgents resuelven esto.
2) Se vacía cada vez que abrís una conversación nueva. Claude Code no sabe en qué proyecto estás, cómo trabaja tu equipo, ni qué decisiones ya tomaron. Si no se lo decís, lo infiere o te pregunta.
Memory resuelve el segundo problema.
Es un sistema de archivos markdown donde guardás todo lo que Claude Code necesita saber: tu stack, las convenciones del equipo, cómo están estructurados los proyectos. Claude Code los lee al inicio de cada sesión e inyecta esa información en el contexto antes de que escribas la primera línea.
Sin Memory: le decís "agregá un endpoint para crear usuarios" y Claude Code te pregunta: "¿Qué framework usás? ¿Tenés una base de datos configurada? ¿Cómo están estructuradas las rutas?"
Con Memory: le decís lo mismo y ya sabe que usás Express con Prisma, que las rutas van en /src/routes y que los errores se manejan con un middleware centralizado. Arranca a trabajar sin preguntar.
Así el agente arranca cada conversación sabiendo dónde está parado. Sin que vos le expliques nada.
Claude Code tiene 2 sistemas de memoria:
CLAUDE.md — archivos markdown que vos escribís con todo lo que Claude Code necesita saber. Pueden vivir en distintos niveles:
Auto Memory — la memoria que Claude Code construye solo. A medida que trabajás, toma notas por su cuenta: patrones que detecta, correcciones que le hacés, decisiones que tomaron juntos. Se guarda en ~/.claude/projects/
Es local a tu máquina. No se comparte con el equipo. Revisalo seguido: Claude Code puede haber guardado malas prácticas sin que te des cuenta.
Tip: podés ver y editar todo lo que Claude Code recuerda ejecutando /memory.
Hooks y Skills: tomá el control
1. Hooks
Ya vimos el loop, las tools y el contexto. Claude Code trabaja de forma autónoma. Ejecuta acciones, toma decisiones, sigue adelante.
Pero esa autonomía tiene un lado que no se menciona tanto: Claude Code hace lo que considera correcto en cada paso. Si algo sale mal, o si hace algo que no querías, ya está hecho.
¿Cómo lo controlás? Con hooks.
Un hook es un comando que se ejecuta automáticamente en puntos específicos del ciclo. Antes de que Claude Code use una tool, después de que la usa, cuando termina la sesión. Vos definís qué pasa en cada momento.
La clave es que los hooks son deterministas. No dependen de que Claude Code "recuerde" hacer algo. Se ejecutan siempre, sin excepción.
Los hooks principales son cuatro:
PreToolUse — se ejecuta antes de que Claude Code use una tool. Es el único hook que puede bloquear una acción. Ejemplo: bloquear cualquier comando que intente modificar archivos .env.
PostToolUse — se ejecuta después de que Claude Code usa una tool. Ejemplo: correr Prettier automáticamente cada vez que Claude Code edita un archivo.
Notification — se ejecuta cuando Claude Code necesita tu atención. Ejemplo: recibir una notificación en tu Mac cuando Claude Code terminó una tarea larga.
Stop — se ejecuta cuando Claude Code termina de responder. Ejemplo: hacer un push automático a staging cuando el agente termina.
Se configuran en .claude/settings.json:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $file_path"
}
]
}
]
}
}
```Este hook corre Prettier automáticamente cada vez que Claude Code edita o crea un archivo. Sin que vos se lo pidas. Sin que Claude Code tenga que recordarlo.
Sin Hook: Claude Code edita un archivo, el código queda sin formatear y te das cuenta en el próximo commit.
Con Hook: Claude Code edita un archivo, PostToolUse dispara automáticamente, Prettier formatea el archivo y el código siempre queda limpio.
Los hooks te permiten agregar comportamiento garantizado al ciclo del agente. No sugerencias, no instrucciones que el modelo puede ignorar. Reglas que se ejecutan siempre.
2. Skills
Ya vimos cómo controlar cuándo y cómo actúa Claude Code con hooks. Pero hay otro problema: la consistencia.
Le pedís la misma tarea dos veces y obtenés resultados distintos. Cada vez que abrís una conversación nueva, Claude Code empieza sin saber cómo querés que trabaje.
¿Cómo lo resolvés? Con skills.
Una Skill es un archivo markdown donde le explicás a Claude Code el proceso exacto para una tarea: qué revisar, en qué orden, qué formato usar, qué ignorar. Cada vez que esa tarea aparece, Claude Code sigue esas instrucciones.
Sin Skill: le pedís que documente una API y genera algo, pero cada vez con un formato distinto. A veces con ejemplos, a veces sin ellos. A veces con tabla resumen, a veces no.
Con Skill: le pedís que documente una API y sigue el proceso exacto que le definiste. Siempre con los mismos pasos, el mismo formato, los mismos criterios. Cada vez igual.
Para crear una Skill, definís una carpeta con esta estructura:
```yaml
mi-skill/
├── SKILL.md # Instrucciones principales (requerido)
├── template.md # Template que Claude completa
├── examples/
│ └── sample.md # Ejemplo del output esperado
└── scripts/
└── validate.sh # Script que Claude puede ejecutar
```El único archivo obligatorio es el SKILL.md. El resto es opcional y lo agregás según lo que necesite la tarea.
El SKILL.md tiene 2 partes:
El frontmatter — un bloque YAML con el nombre y la descripción. El nombre es el comando para invocarla manualmente. La descripción es lo que Claude Code lee para decidir cuándo activarla automáticamente.
El body — las instrucciones en markdown. El workflow, los criterios, el formato del output.
```yaml
---
name: api-docs
description: Documentá endpoints de una API. Usá cuando el usuario
pida documentar una API o mencione "swagger" o "endpoints".
---
## Proceso
1. Identificá todos los endpoints
2. Para cada uno: método, path, parámetros, respuesta esperada
3. Incluí un ejemplo de request y response
4. Cerrá con una tabla resumen
```Una vez creada, podés invocarla de dos formas. Escribiendo /api-docs directamente en el chat, o simplemente pidiéndoselo a Claude Code en lenguaje natural. Si la descripción matchea con lo que pedís, la activa solo.
Podés crearlas para cualquier tarea que repitas con un proceso claro detrás: documentación de APIs, changelogs, resúmenes de reuniones, migraciones de código.
Si querés profundizar en patrones avanzados, casos de uso y mejores prácticas, escribí un artículo completo sobre Skills.
SubAgents: delegá cuando el problema crece
Ya vimos que el contexto tiene capacidad limitada. Cuanto más larga es la sesión, más se llena. Y cuando se llena, Claude Code empieza a perder información de lo que pasó antes.
Imaginá que le pedís que revise todo tu proyecto en busca de problemas de seguridad. Lee decenas de archivos, analiza el código, genera un informe detallado. Todo eso llena el contexto rápido. Y mientras hace eso, tu conversación principal queda bloqueada.
¿Cómo lo resolvés? Con SubAgents.
Un SubAgent es una instancia separada de Claude Code que corre con su propio contexto. El agente principal le delega una tarea, el SubAgent la ejecuta de forma independiente, y cuando termina le manda un resumen con los resultados. El contexto del agente principal no se llena con todo el proceso, solo con la conclusión.
```markdown
Agente principal
↓
"revisá el proyecto en busca de problemas de seguridad"
↓
┌─────────────────────────────────────────┐
│ SubAgent: security-reviewer │
│ │
│ Lee archivos del proyecto │
│ Analiza el código │
│ Detecta vulnerabilidades │
│ Genera informe │
│ │
└─────────────────────────────────────────┘
↓
Devuelve resumen al agente principal
↓
Agente principal sigue con el loop
```Y no solo eso. Los SubAgents pueden correr en paralelo. En vez de analizar tres partes del código de forma secuencial, Claude Code puede delegar las tres al mismo tiempo. Lo que antes llevaba minutos, puede tomar segundos.
```markdown
Agente principal
↓
Divide el trabajo en tareas independientes
↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ SubAgent 1 │ │ SubAgent 2 │ │ SubAgent 3 │
│ │ │ │ │ │
│ Revisa │ │ Revisa │ │ Revisa │
│ auth │ │ base de │ │ APIs │
│ │ │ datos │ │ externas │
└──────────────┘ └──────────────┘ └──────────────┘
↓ ↓ ↓
Agente principal recibe los tres resúmenes
↓
Sigue con el loop
```Claude Code tiene 3 SubAgents nativos que usa automáticamente:
También podés crear los tuyos. Los SubAgents se definen en archivos markdown con YAML frontmatter y se guardan en .claude/agents/. Podés crearlos con el comando /agents:
```yaml
---
name: security-reviewer
description: Revisá el código en busca de vulnerabilidades de seguridad.
Usá cuando el usuario pida una revisión de seguridad.
tools: Read, Grep, Glob
---
Sos un experto en seguridad. Analizá el código en busca de:
- Inyecciones SQL
- Exposición de datos sensibles
- Vulnerabilidades de autenticación
Terminá con un resumen de hallazgos ordenados por severidad.
```Fijate que en el frontmatter limitamos las tools a Read, Grep y Glob. Este agente puede analizar pero nunca modificar nada. Cuando necesitás control fino sobre qué puede hacer cada agente, esa restricción de tools es clave.
Una vez creado, Claude Code lo detecta automáticamente por la descripción y lo invoca cuando la tarea matchea. O podés llamarlo explícitamente: "usá el agente security-reviewer para revisar este PR".
¿Cuándo usar SubAgents y cuándo no?
Tiene sentido cuando la tarea es larga y va a generar mucho output, cuando podés dividir el trabajo en partes independientes que corran en paralelo, o cuando necesitás un agente especializado con tools limitadas.
No vale la pena para tareas cortas que no llenan el contexto. Coordinar SubAgents agrega complejidad que no tiene sentido si la tarea la puede resolver el agente principal en dos minutos.
MCP: conectar el agente con el mundo externo
Ya vimos que las tools le dan a Claude Code capacidad de actuar en tu máquina. Pero hay un límite: todo lo que pasa, pasa ahí adentro.
No puede abrir un PR en GitHub, consultar una base de datos en producción, o crear un ticket en Jira. Para hacer eso, antes tenías que salir del agente y hacerlo vos a mano.
¿Cómo lo resolvés? Con MCP.
MCP (Model Context Protocol) es un protocolo abierto que define cómo Claude Code se conecta con servicios externos. Funciona con una arquitectura cliente-servidor: Claude Code es el cliente, y cada servicio externo tiene su propio servidor MCP que expone lo que puede hacer.
Cuando conectás un servidor MCP, Claude Code recibe una lista de tools disponibles con su nombre y descripción. A partir de ahí, las usa exactamente igual que las tools nativas: decide cuál invocar, la ejecuta, y usa el resultado para seguir adelante. La única diferencia es que la acción ocurre en el servicio externo, no en tu máquina.
```markdown
Claude Code
↓
Decide usar una tool del servidor MCP de GitHub
↓
┌─────────────────────────────────┐
│ Servidor MCP de GitHub │
│ │
│ Abre el PR │
│ Asigna reviewers │
│ Devuelve confirmación │
│ │
└─────────────────────────────────┘
↓
Claude Code recibe el resultado y sigue
```Sin MCP: le decís "terminé los cambios, abrí el PR" y Claude Code no puede. Tenés que ir a GitHub, completar el formulario, asignar reviewers y mergearlo vos mismo.
Con MCP: le decís "terminé los cambios, abrí el PR" y Claude Code abre el PR, escribe la descripción, asigna los reviewers y te avisa cuando está listo. Todo sin que salgas del agente.
Algunos servidores MCP que podés conectar hoy:
Tools nativas para tu entorno local. MCP para el mundo externo.
Para cerrar: cómo encaja todo
Claude Code es un agente: un sistema que toma un objetivo y opera en un loop autónomo hasta cumplirlo. Cada pieza que viste en este artículo existe para hacer ese loop más poderoso.
Pero la mejor forma de entenderlo es verlas interactuar juntas.
Caso 1: revisar y mergear un PR
Le pedís a Claude Code: "revisá el PR #42 y si todo está bien, mergealo".
Vos escribiste una línea. Claude Code coordinó cuatro sistemas.
Caso 2: documentar una API y notificar al equipo
Le pedís a Claude Code: "documentá los endpoints nuevos y avisale al equipo".
Cada vez que lo hagás, el resultado va a ser el mismo. Sin variaciones, sin que tengas que explicar nada.
Todo gira alrededor del loop. Memory para arrancar cada sesión informada. Tools para actuar. Hooks para controlar. Skills para estandarizar. SubAgents para escalar. MCP para conectarse con el mundo externo.
Cuando entendés eso, entendés Claude Code. Y no solo Claude Code: Cursor, Copilot, y cualquier agente que uses de acá en adelante operan sobre las mismas bases. Cambian los nombres, cambia la interfaz, pero el loop es el mismo.
La IA avanza rápido. Cada semana hay algo nuevo. Pero las bases no cambian tan seguido. Tenerlas claras es lo que te va a permitir adaptarte más rápido y sacarle más provecho a lo que venga.
No uses Claude Code solo para promptear. Prestá atención a lo que pasa debajo. Ahí es donde están las oportunidades.
Algunos puntos de partida para empezar hoy:
Gracias por haber llegado hasta acá. Espero que lo hayas disfrutado y que lo que aprendiste te sirva en tu día a día.
Santi