Arquitectura de Claude Code

Las tres capas de Claude Code

Claude Code se organiza internamente en una arquitectura de tres capas que separa las responsabilidades del agente en niveles bien diferenciados. Comprender esta estructura proporciona un modelo mental sólido para entender por qué Claude Code se comporta como lo hace y cómo sacarle el máximo partido.

Las tres capas son:

• Core (núcleo): el bucle agéntico principal con el modelo de lenguaje y las herramientas integradas.
• Delegación: subagentes que ejecutan tareas en contextos aislados y devuelven resultados al agente principal.
• Extensión: mecanismos para conectar servicios externos, automatizar flujos y añadir funcionalidades personalizadas.

flowchart TB
    subgraph Extension["Capa de extensión"]
        MCP["MCP - Servicios externos"]
        Hooks["Hooks - Automatización"]
        Skills["Skills - Flujos reutilizables"]
        Plugins["Plugins - Paquetes distribuibles"]
    end

    subgraph Delegation["Capa de delegación"]
        Sub1["Subagente Explore"]
        Sub2["Subagente Plan"]
        Sub3["Subagente Custom"]
    end

    subgraph Core["Capa core"]
        Model["Modelo Claude"]
        Tools["Herramientas integradas"]
        Context["Ventana de contexto"]
    end

    Extension --> Core
    Delegation --> Core
    Sub1 --> Context
    Sub2 --> Context
    Sub3 --> Context

Cada capa añade capacidades sobre la anterior sin sustituirla. La capa core funciona de forma autónoma para la mayoría de tareas de desarrollo. La capa de delegación permite escalar a tareas paralelas o que requieren aislamiento de contexto. La capa de extensión conecta Claude Code con el ecosistema externo.

La arquitectura de tres capas (core, delegación y extensión) permite que Claude Code escale desde tareas sencillas de edición hasta flujos de trabajo complejos con servicios externos y ejecución paralela.

Capa core: el bucle agéntico

La capa core es el corazón de Claude Code. Está compuesta por tres elementos que trabajan en conjunto: el modelo de lenguaje, las herramientas integradas y la ventana de contexto.

El modelo de lenguaje

Claude Code utiliza los modelos de la familia Claude para razonar sobre el código. El modelo analiza el contexto disponible, comprende la intención del usuario y decide qué acciones tomar. No se limita a generar texto: razona sobre el problema y planifica una secuencia de pasos para resolverlo.

Hay varios modelos disponibles con distintos perfiles de rendimiento:

• Sonnet: equilibrio entre velocidad y capacidad de razonamiento. Adecuado para la mayoría de tareas de desarrollo.
• Opus: razonamiento más profundo para decisiones arquitectónicas complejas o problemas que requieren mayor análisis.

El modelo se puede cambiar en cualquier momento durante una sesión con el comando /model, lo que permite ajustar el nivel de razonamiento según la complejidad de la tarea en curso.

Las herramientas integradas

Las herramientas son lo que convierten a Claude Code en un agente. Sin ellas, el modelo solo podría responder con texto. Con ellas, puede actuar sobre el proyecto de forma concreta.

Las herramientas integradas se agrupan en cinco categorías:

| Categoría | Herramientas | Qué permiten hacer | |---|---|---| | Operaciones de archivo | Read, Edit, MultiEdit, Write | Leer, editar, crear y reorganizar archivos | | Búsqueda | Glob, Grep | Buscar archivos por patrón y contenido con expresiones regulares | | Ejecución | Bash | Ejecutar comandos de terminal, builds, tests, Git | | Web | WebSearch, WebFetch | Buscar documentación, consultar páginas web | | Interacción | AskQuestion, TodoWrite | Preguntar al usuario y gestionar listas de tareas |

Cada vez que Claude usa una herramienta, el resultado se incorpora al contexto de la conversación y alimenta la siguiente decisión. Si Claude ejecuta grep para buscar una función y no la encuentra, ajusta su estrategia y prueba con otro patrón de búsqueda. Esta capacidad de iterar basándose en los resultados es lo que distingue a un agente de un simple generador de código.

La ventana de contexto

La ventana de contexto es el espacio de memoria de trabajo del agente durante una sesión. Contiene el historial de la conversación, el contenido de los archivos leídos, las salidas de los comandos ejecutados, las instrucciones de CLAUDE.md, las skills cargadas y el prompt del sistema.

A medida que avanza la sesión, el contexto se va llenando. Claude Code gestiona esto de forma automática mediante un mecanismo de compactación: cuando se acerca al límite, elimina primero las salidas de herramientas más antiguas y, si es necesario, genera un resumen de la conversación preservando los elementos clave.

flowchart LR
    A["Instrucciones CLAUDE.md"] --> CTX["Ventana de contexto"]
    B["Historial conversación"] --> CTX
    C["Archivos leídos"] --> CTX
    D["Salidas de comandos"] --> CTX
    E["Skills cargadas"] --> CTX
    CTX --> F["Modelo Claude"]
    F --> G["Siguiente acción"]

El comando /context permite inspeccionar en cualquier momento qué está ocupando espacio en la ventana de contexto, lo que resulta útil para diagnosticar por qué Claude podría estar "olvidando" instrucciones dadas al inicio de una sesión larga.

La ventana de contexto tiene un tamaño limitado. Las instrucciones persistentes deben ir en CLAUDE.md en lugar de depender del historial de conversación, ya que las instrucciones antiguas pueden perderse durante la compactación.

Capa de delegación: subagentes

La capa de delegación permite que el agente principal delegue tareas en subagentes que operan con su propia ventana de contexto aislada. Cada subagente recibe una tarea concreta, trabaja de forma independiente y devuelve un resumen de sus resultados al agente principal.

Por qué delegar en subagentes

La delegación resuelve dos problemas prácticos:

• Aislamiento de contexto: el subagente puede leer decenas de archivos o ejecutar búsquedas extensas sin consumir la ventana de contexto del agente principal. Solo el resumen del resultado vuelve a la conversación principal.
• Ejecución en paralelo: múltiples subagentes pueden trabajar simultáneamente en tareas independientes, reduciendo el tiempo total de ejecución.

Tipos de subagentes integrados

Claude Code incluye tres tipos de subagentes predefinidos:

• Explore: especializado en búsquedas rápidas y exploración del codebase. Útil para encontrar archivos, localizar definiciones de funciones o responder preguntas sobre la estructura del proyecto.
• Plan: orientado a investigación y análisis en profundidad. Trabaja en modo de solo lectura para analizar un problema antes de proponer una solución.
• generalPurpose: subagente de propósito general para tareas complejas que requieren lectura, edición y ejecución de comandos.

Además de estos, es posible definir subagentes custom con instrucciones, herramientas y skills propias. Esto permite crear agentes especializados para tareas recurrentes del equipo, como revisiones de seguridad, generación de documentación o análisis de rendimiento.

Cómo fluye la información

Cuando el agente principal delega una tarea, el subagente recibe un contexto fresco que incluye las instrucciones de CLAUDE.md, el estado de Git y las skills especificadas, pero no hereda el historial de conversación. Esto es deliberado: garantiza que el subagente trabaje con un contexto limpio y enfocado.

flowchart TB
    Main["Agente principal"] -->|Delega tarea| Sub["Subagente"]
    Sub -->|Recibe| Fresh["Contexto fresco: CLAUDE.md + Git + Skills"]
    Sub -->|Trabaja| Work["Lee archivos, ejecuta comandos, analiza resultados"]
    Work -->|Devuelve| Summary["Resumen de resultados"]
    Summary --> Main

Este flujo mantiene la ventana de contexto del agente principal limpia y permite que los subagentes realicen trabajo intensivo (leer cientos de archivos, ejecutar múltiples búsquedas) sin impactar en la conversación principal.

Capa de extensión: MCP, hooks, skills y plugins

La capa de extensión conecta Claude Code con el ecosistema exterior y permite personalizar su comportamiento. Cada mecanismo de extensión se integra en un punto distinto del bucle agéntico.

CLAUDE.md: la memoria del proyecto

CLAUDE.md es un archivo markdown que se carga automáticamente al inicio de cada sesión. Contiene las convenciones del proyecto, comandos de build, reglas del equipo y cualquier instrucción que Claude deba conocer siempre. Es el equivalente a un "manual del proyecto" que el agente lee antes de empezar a trabajar.

Ejemplo de contenido típico de un CLAUDE.md:

# Convenciones del proyecto

- Usar pnpm como gestor de paquetes
- Ejecutar tests antes de cada commit: pnpm test
- Nombrar las ramas como feature/nombre-descriptivo
- Los componentes React van en src/components/

Skills: flujos de trabajo reutilizables

Las skills son archivos markdown que contienen instrucciones, conocimiento de dominio o flujos de trabajo que Claude puede cargar bajo demanda. A diferencia de CLAUDE.md, que se carga siempre, las skills se activan cuando son relevantes o cuando el usuario las invoca explícitamente con /.

Las skills pueden ser de dos tipos:

• De referencia: proporcionan conocimiento que Claude utiliza durante la sesión, como una guía de estilo de API o la documentación de un esquema de base de datos.
• De acción: definen flujos de trabajo ejecutables que Claude sigue paso a paso, como un checklist de despliegue o un proceso de revisión de código.

MCP: conexión con servicios externos

El Model Context Protocol (MCP) es un protocolo que permite conectar Claude Code con servicios y herramientas externas. A través de servidores MCP, el agente puede consultar bases de datos, interactuar con APIs, publicar en Slack, controlar un navegador o acceder a cualquier servicio que exponga un servidor MCP.

Cada servidor MCP registra sus herramientas en Claude Code, que las incorpora a su repertorio disponible. Esto amplía las capacidades del agente sin necesidad de modificar su código base.

Hooks: automatización determinista

Los hooks son scripts que se ejecutan automáticamente en respuesta a eventos del ciclo de vida del agente, como por ejemplo:

• PreToolUse: se ejecuta antes de que Claude use una herramienta (por ejemplo, para validar que un archivo no está protegido antes de editarlo).
• PostToolUse: se ejecuta después de usar una herramienta (por ejemplo, ejecutar el linter automáticamente tras cada edición).
• SessionStart: se ejecuta al comenzar una sesión.

A diferencia de las skills y los subagentes, los hooks no involucran al modelo de lenguaje. Son scripts deterministas que siempre producen el mismo resultado ante el mismo evento, lo que los hace ideales para automatizaciones predecibles como formateo de código, validaciones o notificaciones.

Plugins: distribución y reutilización

Los plugins son la capa de empaquetado. Un plugin agrupa skills, hooks, subagentes y servidores MCP en una unidad instalable y distribuible. Los plugins permiten compartir configuraciones completas entre proyectos o equipos, y se pueden descubrir e instalar desde marketplaces.

La capa de extensión sigue el principio de composición: CLAUDE.md para contexto permanente, skills para conocimiento bajo demanda, MCP para servicios externos, hooks para automatización determinista y plugins para empaquetar y distribuir todo lo anterior.

Cómo se conectan las capas

Las tres capas trabajan de forma coordinada en cada tarea. Un ejemplo práctico ilustra cómo interactúan:

Supongamos que solicitas "añade un endpoint REST para gestionar perfiles de usuario y asegúrate de que pase los tests":

• Capa core: Claude lee la estructura del proyecto, identifica el framework usado, localiza endpoints existentes como referencia y edita los archivos necesarios para crear el nuevo endpoint.
• Capa de delegación: Claude podría delegar la exploración del esquema de base de datos a un subagente Explore para no llenar la ventana de contexto principal con información de archivos de migración.
• Capa de extensión: un hook PostToolUse ejecuta automáticamente el linter tras cada edición. Un servidor MCP podría proporcionar acceso a la base de datos de desarrollo para verificar el esquema. Las convenciones de CLAUDE.md guían la nomenclatura de rutas y la estructura del controlador.

Este modelo de capas permite que Claude Code sea simple para tareas sencillas (solo necesita la capa core) y escalable para tareas complejas (activa las capas de delegación y extensión según sea necesario).