Claude Code es mucho más de lo que piensas

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 paré y me hice una pregunta:

¿cómo funciona realmente Claude Code por dentro?

me puse a leer la documentación, a experimentar, a probar.

y lo que fui descubriendo es esto:

no hace magia. está construido sobre piezas concretas, cada una con un rol claro. y cuando las entiendes, todo lo demás empieza a tener sentido.

→ si siempre repites las mismas instrucciones, lo conviertes en una Skill.

→ si pierde el hilo en una tarea larga, delegas en un SubAgent.

→ si hay pasos manuales que repites, los automatizas 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í.

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 preguntas "¿cómo agrego autenticación a mi app?" y te explica los pasos.

pero tienes que ir al proyecto, modificar el código y probar si funciona.

tú haces el trabajo.

con Claude Code le dices "agrega 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? ¿cómo sabe si algo 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.

si algo falla, vuelve atrás, corrige, y sigue.

el loop tiene 3 fases:

reunir contexto → entiende qué tiene que hacer. lee archivos, analiza el código, explora la estructura del proyecto.

tomar acción → ejecuta los cambios. edita archivos, corre comandos, instala dependencias.

verificar resultados → comprueba que lo que hizo funciona. corre tests, revisa errores, corrige si algo falla.

el loop se adapta a lo que pides.

una pregunta simple puede requerir solo reunir contexto. arreglar un bug puede pasar por las tres fases varias veces.

Claude Code decide qué requiere cada paso en base a lo que aprendió del anterior. y tú también eres parte de ese loop.

puedes interrumpir en cualquier momento para redirigirlo, 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.

Tools: cómo Claude Code actúa en el mundo

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 abrir un archivo o modificarlo?

utiliza tools.

las tools son funciones que Claude Code puede invocar para interactuar con el mundo real.

piénsalo como las apps de un móvil. el teléfono 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 vez que 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.

1Tu pedido
2    ↓
3Claude Code decide qué tool usar
4    ↓
5┌─────────────────────────────────┐
6│  Read · Edit · Write · Bash     │
7│  Grep · Glob · WebFetch · WebSearch │
8└─────────────────────────────────┘
9    ↓
10Sistema ejecuta la tool
11    ↓
12Resultado vuelve a Claude Code
13    ↓
14¿Terminó? → No → usa otra tool
15             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 puedes 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:

→ usa Glob para encontrar el archivo del componente

→ usa Read para leer el código y entender qué está pasando

→ usa Edit para corregir el error

→ usa Bash para correr los tests y verificar que funcionó

todo eso sin que tú intervengas. esa es la diferencia entre un chat y un agente.

Context y Memory: lo que Claude Code recuerda

Claude Code trabaja, ejecuta acciones, obtiene resultados y decide qué hacer después.

pero ¿cómo sabe qué hizo a medida que avanza?

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í dentro.

no solo tu prompt inicial, sino todo lo que va encontrando: archivos que abrió, lo que descubrió en el código, las acciones que ejecutó y sus resultados.

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 verás cómo los SubAgents resuelven esto.

2. se vacía cada vez que abres 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 dices, lo infiere o te pregunta.

Memory resuelve el segundo problema.

es un sistema de archivos markdown donde guardas 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 dices "agrega un endpoint para crear usuarios" y Claude Code te pregunta: ¿qué framework usas? ¿tienes una base de datos configurada? ¿cómo están estructuradas las rutas?"

con Memory: le dices lo mismo y ya sabe que usas 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.

Claude Code tiene 2 sistemas de memoria:

→ CLAUDE.md - archivos markdown que tú escribes con todo lo que Claude Code necesita saber. pueden vivir en distintos niveles:

→ ~/.claude/CLAUDE.md - aplica a todos tus proyectos. ahí van tus preferencias personales: cómo quieres que escriba el código, convenciones que usas siempre. las instrucciones tienen que ser específicas: "usa 2 espacios de indentación" es más claro que "formatea bien el código".

→ /tu-proyecto/CLAUDE.md - específico del repositorio. ahí va la arquitectura, las convenciones del equipo, los comandos importantes. cuando arrancas un proyecto nuevo, ejecuta /init y Claude Code lo genera automáticamente. mantenlo en menos de 200 líneas: si crece mucho, Claude Code empieza a ignorar instrucciones. y si lo haces commit al repo, todo el equipo comparte el mismo contexto.

→ .claude/rules/ - reglas modulares que se activan según el tipo de archivo. útil cuando el proyecto crece y no quieres meter todo en un solo archivo.

Auto Memory - la memoria que Claude Code construye solo. a medida que trabajas, toma notas por su cuenta: patrones que detecta, correcciones que le haces, decisiones que tomaron juntos. se guarda en

~/.claude/projects/<proyecto>/memory/ y se carga al inicio de cada sesión.

revisalo seguido: Claude Code puede haber guardado malas prácticas sin que te des cuenta.

tip: puedes ver y editar todo lo que Claude Code recuerda ejecutando /memory.

Hooks y Skills: toma el control

1. Hooks

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 hace algo que no querías, ya está hecho.

¿cómo lo controlas? 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.

tú defines 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:

1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "matcher": "Edit|Write",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "npx prettier --write $file_path"
10          }
11        ]
12      }
13    ]
14  }
15}

este hook corre Prettier automáticamente cada vez que Claude Code edita o crea un archivo.

sin que tú 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

hay otro problema: la consistencia.

le pides la misma tarea dos veces y obtienes resultados distintos. cada vez que abres una conversación nueva, Claude Code empieza sin saber cómo lo hiciste la vez anterior.

¿cómo lo resuelves? con Skills.

una Skill es un archivo markdown donde le explicas 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 pides que documente una API y genera algo, pero cada vez con un formato distinto. a veces con ejemplos, a veces sin ellos.

con Skill: le pides que documente una API y sigue el proceso exacto que tú definiste. siempre con los mismos pasos, el mismo formato, los mismos criterios. cada vez igual.

para crear una Skill, defines una carpeta con esta estructura:

1mi-skill/
2├── SKILL.md          # Instrucciones principales (requerido)
3├── template.md       # Template que Claude completa
4├── examples/
5│   └── sample.md    # Ejemplo del output esperado
6└── scripts/
7    └── validate.sh  # Script que Claude puede ejecutar

el único archivo obligatorio es el SKILL.md. el resto es opcional y lo agregas 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.

1---
2name: api-docs
3description: Documenta endpoints de una API. Úsalo cuando el usuario
4             pida documentar una API o mencione "swagger" o "endpoints"
5---
6
7## Proceso
81. Identifica todos los endpoints
92. Para cada uno: método, path, parámetros, respuesta esperada
103. Incluye un ejemplo de request y response
114. Cierra con una tabla resumen

una vez creada, puedes 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 encaja con lo que pides, la activa solo.

puedes 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.

SubAgents: delega 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.

imagina que le pides 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 resuelves? 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.

1Agente principal
2    ↓
3"revisa el proyecto en busca de problemas de seguridad"
4    ↓
5┌─────────────────────────────┐
6│    SubAgent: security-reviewer    │
7│                             │
8│  Lee archivos del proyecto  │
9│  Analiza el código          │
10│  Detecta vulnerabilidades   │
11│  Genera informe             │
12└─────────────────────────────┘
13    ↓
14Devuelve resumen al agente principal
15    ↓
16Agente 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.

1Agente principal
2    ↓
3Divide el trabajo en tareas independientes
4    ↓
5┌──────────────┐  ┌──────────────┐  ┌──────────────┐
6│  SubAgent 1  │  │  SubAgent 2  │  │  SubAgent 3  │
7│              │  │              │  │              │
8│ Revisa auth  │  │ Revisa base  │  │ Revisa APIs  │
9│              │  │ de datos     │  │ externas     │
10└──────────────┘  └──────────────┘  └──────────────┘
11        ↓                 ↓                 ↓
12        Agente principal recibe los tres resúmenes
13                          ↓
14                Sigue con el loop

Claude Code tiene 3 SubAgents nativos que usa automáticamente:

→ Explore - un agente rápido de solo lectura especializado en buscar y analizar el proyecto. los resultados quedan en el contexto del SubAgent, no en el tuyo.

→ Plan - se activa en plan mode. antes de presentarte un plan, Claude Code delega la investigación del proyecto a este agente.

→ General-purpose - para tareas complejas que requieren tanto exploración como modificaciones.

también puedes crear los tuyos.

los SubAgents se definen en archivos markdown con YAML frontmatter y se guardan en .claude/agents/.

1---
2name: security-reviewer
3description: Revisa el código en busca de vulnerabilidades de seguridad.
4             Úsalo cuando el usuario pida una revisión de seguridad.
5tools: Read, Grep, Glob
6---
7
8Eres un experto en seguridad. Analiza el código en busca de:
9- Inyecciones SQL
10- Exposición de datos sensibles
11- Vulnerabilidades de autenticación
12
13Termina con un resumen de hallazgos ordenados por severidad.

fíjate que en el frontmatter limitamos las tools a Read, Grep y Glob.

este agente puede analizar pero nunca modificar nada.

cuando necesitas 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 encaja. o puedes llamarlo explícitamente: "usa 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 puedes dividir el trabajo en partes independientes que corran en paralelo, o cuando necesitas 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

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í dentro.

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 tú a mano.

¿cómo lo resuelves? 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 conectas 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. la única diferencia es que la acción ocurre en el servicio externo, no en tu máquina.

1Claude Code
2    ↓
3Decide usar una tool del servidor MCP de GitHub
4    ↓
5┌─────────────────────────────┐
6│   Servidor MCP de GitHub    │
7│                             │
8│   Abre el PR                │
9│   Asigna reviewers          │
10│   Devuelve confirmación     │
11└─────────────────────────────┘
12    ↓
13Claude Code recibe el resultado y sigue

sin MCP: le dices "terminé los cambios, abre el PR" y Claude Code no puede. tienes que ir a GitHub, completar el formulario, asignar reviewers y mergearlo tú mismo.

con MCP: le dices lo mismo 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 puedes conectar hoy:

→ GitHub - PRs, reviews, issues

→ Postgres / Supabase - consultar y modificar bases de datos

→ Slack - mensajes y canales

→ Jira - tickets y proyectos

tools nativas para tu entorno local. MCP para el mundo externo.

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 pides a Claude Code: "revisa el PR #42 y si todo está bien, mergealo".

→ usa MCP de GitHub para leer los archivos modificados y entender los cambios

→ delega el análisis de seguridad a un SubAgent especializado, para no llenar el contexto principal

→ un Hook corre los tests localmente y verifica que todo pase

→ si los tests pasan, usa MCP de GitHub para hacer el merge sin que tú toques la interfaz

tú escribiste una línea. Claude Code coordinó cuatro sistemas.

caso 2: documentar una API y notificar al equipo

le pides a Claude Code: "documenta los endpoints nuevos y avísale al equipo".

→ activa una Skill de documentación que define el formato exacto: qué incluir, cómo estructurarlo, qué ejemplos agregar

→ usa Tools para leer el código y extraer los endpoints

→ un Hook formatea el output antes de guardarlo

→ usa MCP de Slack para mandar el resumen al canal del equipo

cada vez que lo hagas, 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 entiendes eso, entiendes Claude Code.

y no solo Claude Code: Cursor, Copilot, y cualquier agente que uses de aquí 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. presta atención a lo que pasa debajo. ahí es donde están las oportunidades.

algunos puntos de partida para empezar hoy:

→ revisa tu Auto Memory y mejora lo que Claude Code guardó

→ crea un CLAUDE.md para tu proyecto si no tienes uno

→ conecta el MCP de GitHub

→ arma un SubAgent para tareas que llenan el contexto

→ configura un Hook que corra tests después de cada cambio

esto es todo, nos vemos mañana.

Marcus