Cinco capas dentro de Claude Code: Memoria, Habilidades, Ganchos, Subagentes y complementos.
Claude Code visto como un entorno de ejecución de agentes: memoria CLAUDE.md, Habilidades bajo demanda, Ganchos deterministas, Subagentes aislados y complementos que integran todo para un equipo.
Fuentes: **Claude Code’s 5-Layer Agent Development Kit: The Architecture Most Engineers Are Missing**
Muchos ingenieros consideran a Claude Code como un asistente de programación muy capaz: abren una terminal, le asignan una tarea, lo dejan leer archivos y ejecutar comandos, y observan cómo avanza el trabajo. Esa descripción es precisa pero incompleta. La documentación de Anthropic lo presenta como una herramienta de programación basada en agentes que opera dentro de la terminal, comprende un conjunto de códigos, realiza tareas rutinarias y accede a sistemas externos mediante mecanismos como MCP. Al leerla con atención, se percibe que el producto es menos un modelo envuelto en una shell de línea de comandos y más un entorno de ejecución para agentes estructurados con varias superficies de control distintas.
Dichas superficies incluyen un archivo CLAUDE.md que permanece en la memoria, Habilidades reutilizables, Ganchos deterministas, Subagentes a los que se delega el trabajo, Plugins que pueden instalarse y enlaces MCP a sistemas externos. Por lo tanto, la pregunta útil cambia: preguntar qué puede generar Claude Code es menos importante que preguntarse cómo se puede dar forma a su comportamiento, restringirlo, especializarlo y compartirlo dentro de un equipo.
Una pila en cinco capas
Un modelo base puede escribir código, explicar archivos y responder preguntas. Por sí solo deja varias cuestiones sin resolver: recordar un proyecto entre sesiones, reutilizar la experiencia en tareas, aplicar restricciones a nivel de infraestructura, limitar lo que se delega y garantizar un comportamiento consistente en el equipo. Esas preocupaciones están fuera del prompt, y el diseño de Claude Code refleja cada vez más eso. La documentación describe los archivos de instrucciones persistentes, las Habilidades ampliables, los subagentes personalizados, los ganchos, los alcances de configuración, los complementos y la conectividad MCP como mecanismos separados. Juntos no constituyen un conjunto aleatorio de funciones; forman capas que hacen que el comportamiento del agente sea más fiable, reutilizable y manejable:
- CLAUDE.md es la capa de memoria y políticas.
- Habilidades son la capa de conocimiento, que proporciona experticia según sea necesario.
Los patrones MCP y agent-team rodean toda la estructura como los sistemas que la conectan con el mundo exterior.
Este enfoque explica un patrón común en los proyectos de agentes fallidos: rara vez el modelo era el punto débil. Faltaba alguna capa. Un equipo depende exclusivamente de las instrucciones proporcionadas sin contar con memoria persistente del proyecto. Otro cuenta con instrucciones detalladas, pero carece de controles deterministas para el uso de herramientas riesgosas. Un tercero sobrecarga a un agente generalista cuando el trabajo debería dividirse entre especialistas. La mayoría de los fallos de los agentes son de naturaleza arquitectónica, no relacionados con las instrucciones dadas. Cada capa se analiza a continuación, comenzando por la base.
Por qué una perspectiva arquitectónica supera a una lista de funcionalidades
Considerar a Claude Code como una lista de características plantea la pregunta sobre lo que puede hacer. Pero verlo desde una perspectiva arquitectónica permite plantearse mejor: ¿qué capas expone para controlar cómo se da forma, restringe, delega y comparte el comportamiento del agente? Una vez que cambia la forma de plantearse, resulta más fácil comprender la estructura del sistema, así como diagnosticar los problemas que surgen en la práctica.
La documentación permite extraer dos conclusiones. Primero, ninguno de estos mecanismos se encuentra dentro del modelo; están distribuidos alrededor de él, en archivos, manejadores de eventos, ámbitos de configuración y formatos de empaquetado. Segundo, cada uno de ellos aborda un tipo diferente de fallo: la memoria soluciona el olvido, las habilidades manejan el comportamiento genérico, los ganchos resuelven la falta de fiabilidad, los subagentes lidian con contextos saturados y los complementos evitan tener que repetir manualmente una configuración adecuada.
Capa uno: CLAUDE.md como memoria
La base es CLAUDE.md. La documentación lo describe como el lugar donde se almacenan instrucciones permanentes sobre cómo trabajar en un proyecto, mientras que una función de memoria automática separada guarda las notas que Claude escribe para sí mismo tras correcciones repetidas y preferencias personales.
Esta separación es importante. CLAUDE.md no sirve como papel en blanco para prompts temporales. Los equipos guardan aquí contexto a largo plazo: estándares de codificación, decisiones arquitectónicas anteriores, bibliotecas preferidas, listas de verificación para revisiones y límites del flujo de trabajo, cualquier cosa que deba estar a la vista antes del primer mensaje de una sesión.
La forma en que se carga es la parte técnica interesante. No se trata de un único archivo leído únicamente desde el directorio actual. Claude recorre el árbol de directorios desde el directorio de trabajo y carga cada archivo CLAUDE.md y CLAUDE.local.md que encuentra. Los archivos se concatenan para formar el contexto en lugar de sobrescribirse mutuamente, y las instrucciones que se encuentran más cerca del directorio de inicio se leen posteriormente.
Eso lo convierte en un sistema de memoria con alcance definido, y no en un simple archivo de configuración. Un archivo de nivel superior puede contener reglas aplicables a todo el repositorio, como convenciones de nomenclatura, expectativas de pruebas o límites arquitectónicos, mientras que un archivo más profundo en la estructura puede restringir el comportamiento de un subsistema específico. Imagine un monorepo: el archivo raíz indica cómo se nombran las pruebas y dónde se encuentran los límites de los servicios, mientras que un archivo dentro del directorio de pagos agrega las reglas más estrictas que solo son aplicables allí. Quien inicie una sesión en ese directorio recibirá ambas configuraciones, siendo las indicaciones más específicas las que se leerán por último.
Las importaciones añaden capacidad de composición. La sintaxis @path/to/import permite a los equipos dividir grandes conjuntos de instrucciones en módulos más pequeños y reutilizables, de modo que un archivo Markdown no se convierta en un desorden incontrolable. Launch expande los archivos importados dentro del contexto, y una importación puede a su vez importar otras, hasta cinco niveles de profundidad. En la práctica, CLAUDE.md funciona más como una memoria de proyecto componible que como un plantilla estática de instrucciones.
La memoria automática y la memoria declarativa tienen funciones diferentes. Ambas se cargan al inicio de cada conversación, pero CLAUDE.md contiene lo que los usuarios escribieron intencionalmente, mientras que la memoria automática almacena las notas acumuladas por Claude en un directorio local de la máquina, indexadas a través de MEMORY.md. Solo las primeras 200 líneas o 25 KB de ese índice se cargan al comenzar la sesión. En contraste, los archivos CLAUDE.md se cargan en su totalidad, independientemente de su longitud, aunque Anthropic observa que los archivos más cortos son seguidos de mejor manera. Una es controlada y declarativa; la otra es adaptativa y emergente.
Un modelo mental mejor que “pegar el contexto una vez para que Claude recuerde el estilo” es un estatuto operativo para el agente. Anthropic incluso especifica ubicaciones en toda la organización para los archivos CLAUDE.md gestionados de forma centralizada en los principales sistemas operativos de escritorio, lo que indica que esta capa está destinada a políticas operativas duraderas y no solo a gustos personales. Esto evita que los equipos tengan que reexplicar las mismas restricciones en cada sesión y proporciona al agente una base estable antes de comenzar cualquier tarea específica.
Una consecuencia práctica de las reglas de carga es que CLAUDE.md requiere un cuidado editorial. Dado que cada archivo descubierto se carga en su totalidad, esto genera sobrecarga en cada sesión; además, la recomendación de Anthropic de priorizar archivos más cortos es una razón para eliminar regularmente contenido innecesario. Las proceduras que ya no caben en el archivo son las primeras en ser eliminadas, lo cual conduce directamente al siguiente nivel.
Nivel dos: Habilidades como conocimiento bajo demanda
Mientras que CLAUDE.md representa la memoria y las políticas persistentes, las Habilidades ofrecen conocimientos modulares que se activan cuando son necesarios. Según la documentación, al escribir instrucciones en un archivo SKILL.md es como Claude adquiere una nueva capacidad. Una orden con barra diagonal llama explícitamente a una habilidad, o bien Claude puede activarla por sí mismo cuando decide que la tarea es adecuada.
El aspecto arquitectónico clave es el momento oportuno. El “cuerpo” de una habilidad no constituye una memoria permanente del proyecto. Solo entra en el contexto cuando es necesario, por lo que se pueden adjuntar procedimientos reutilizables, listas de verificación y guías del dominio sin sobrecargar cada sesión.
Muchos ingenieros tratan la personalización como una única instrucción extensa: introducen todo en el contexto persistente con la esperanza de que el modelo determine qué es importante. Las habilidades representan una opción más estructurada. Anthropic recomienda crearlas cuando se copian repetidamente las mismas instrucciones, o cuando una sección de CLAUDE.md pasa de ser un hecho a convertirse en un procedimiento. CLAUDE.md debe contener reglas duraderas del proyecto; las habilidades, en cambio, deben albergar conocimientos operativos reutilizables. Esto mantiene el contexto siempre cargado de forma ligera y transforma los flujos de trabajo complejos en módulos que Claude puede utilizar cuando sea apropiado.
Las habilidades tampoco son simplemente comandos personalizados con un nombre diferente. Los archivos antiguos .claude/commands/.md y las definiciones más recientes .claude/skills//SKILL.md se comportan de manera similar al ser invocados, pero las habilidades añaden un nivel adicional de control. Permiten contar con un directorio que alberga archivos de soporte, determinan si el usuario, Claude o ambos pueden activarlas, admiten inyección dinámica de contexto e incluso pueden ejecutarse dentro de un subagente. Por eso es adecuado el término “capa de conocimiento”: una habilidad es la unidad a través de la cual la experiencia, los procedimientos y el contexto de las tareas se vuelven componibles dentro del entorno de ejecución.
Considere una habilidad como un paquete sellado de conocimientos para un tipo específico de tarea. Su descripción indica su propósito, la comparación en tiempo de ejecución determina si se ajusta a la solicitud actual, y las instrucciones que contiene solo se cargan cuando son útiles. La documentación señala que las habilidades agrupadas como /debug, /loop y /simplify se basan en prompts, no en una lógica fija, lo cual es una pista importante sobre su diseño. El comportamiento se vuelve modular al no codificar todo de forma rígida en el producto principal, lo cual representa un patrón mucho más escalable que depender de un único prompt base para abarcar todos los flujos de trabajo.
Considere un equipo que utiliza un método estándar para depurar pruebas inestables, revisar migraciones SQL o redactar notas de lanzamiento. La memoria persistente es demasiado general para estos casos, y las instrucciones puntuales resultan demasiado repetitivas. El equipo crea un paquete con el procedimiento una sola vez, guarda el material de referencia junto a él y Claude lo carga únicamente cuando la tarea lo requiere. El contenido de referencia extenso dentro de una habilidad cuesta casi nada hasta que se utiliza, por lo que este enfoque es más ordenado y también resulta más económico de ejecutar.
Por lo tanto, las habilidades recompensan el hábito de detectar la repetición. Cada vez que se escribe la misma explicación por tercera vez, o cuando un párrafo en CLAUDE.md comienza a parecerse a un procedimiento numerado, probablemente se trate de una habilidad lista para ser extraída. Este proceso lleva unos minutos, pero se compensa cada vez que la tarea se repite.
En conjunto, CLAUDE.md proporciona al agente reglas básicas estables, mientras que las Habilidades le brindan conocimientos especializados reutilizables y dirigidos, sin aumentar el tamaño de la ventana de contexto principal. La capa siguiente es la que hace que ese comportamiento sea más seguro.
Tercera capa: Ganchos como medidas de seguridad
Los ganchos convierten el comportamiento del agente en algo aplicable mediante normas. La documentación oficial los describe como automatización basada en eventos: una orden se ejecuta antes o después de una acción determinada en Claude Code, activada por el propio evento. Los ganchos guían y catalogan los usos típicos: formatear automáticamente el código tras las ediciones, rechazar modificaciones en archivos protegidos, restaurar el contexto una vez que la conversación ha sido compactada, auditar los cambios en la configuración, actualizar el estado del entorno cuando cambian los archivos y aprobar previamente ciertas solicitudes de permisos.
Eso es un trabajo diferente al de dar instrucciones. Una instrucción puede sugerir un comportamiento; un gancho puede interceptarlo o transformarlo de manera determinista. Por esa razón, los ganchos deben considerarse más bien como una capa de protección, y no simplemente como una comodidad para la automatización.
Un ejemplo concreto proviene de la guía de costos: un gancho PreToolUse captura las órdenes de Bash, reconoce las ejecuciones de pruebas y las reescribe, de modo que la salida que recibe Claude contiene únicamente los fallos y no toda la información generada. Mecánicamente, el gancho recibe un payload en JSON que describe la llamada pendiente, examina la orden y responde con otro JSON que modifica la entrada del herramienta. En todo esto, la IA no decide mejor; es la infraestructura la que determina qué puede ver o hacer el modelo en ese momento del flujo de trabajo.
El contraste con las reglas a nivel de prompt merece ser destacado. Las medidas de control suaves suelen ser demasiado débiles para entornos de producción. Supongamos que el código generado debe reformatearse siempre, que los archivos sensibles nunca deben modificarse, o que las llamadas a herramientas destructivas requieren una revisión más estricta. Depender únicamente de las instrucciones escritas es frágil, mientras que los ganchos trasladan el control fuera de la discreción del modelo e imponen reglas de flujo de trabajo a nivel de evento.
También es importante señalar que los ganchos se encuentran al lado de la gestión de contexto, y no dentro de ella. La documentación de solución de problemas enumera “ganchos que no se activan” como un problema de configuración independiente, y recomienda utilizar /doctor para diagnosticar problemas con los ganchos, los servidores MCP y el uso del contexto. Ambos detalles demuestran que los ganchos pertenecen al entorno de ejecución: un comportamiento controlado por la configuración que debe integrarse correctamente en el tiempo de ejecución de la sesión, y no texto que Claude lea.
También existe el aspecto relacionado con los costos. La guía de costos de Anthropic recomienda trasladar el procesamiento a los hooks y habilidades, ya que estos pueden preprocesar entradas grandes antes de que el modelo las vea. Su ejemplo es filtrar un enorme registro de pruebas para conservar solo los fallos, reduciendo lo que podrían ser decenas de miles de tokens a una carga mucho más pequeña. Así, los hooks contribuyen tanto a la eficiencia como a la seguridad: disminuyen el desperdicio de tokens, mantienen el contexto más limpio y evitan que el modelo realice tareas de filtrado predecibles, algo que la lógica determinista de shell hace de manera más económica y fiable.
Es útil imaginar una situación antes y después. Antes de los ganchos, un equipo escribe “siempre ejecute el formateador” en las instrucciones y espera que funcione. Después de los ganchos, el formateador se ejecuta en cada edición, independientemente de que el modelo lo recuerde o no, y un archivo protegido simplemente no puede ser modificado. El agente sigue razonando libremente sobre qué construir; los ganchos deciden qué se permite hacer dentro de ese razonamiento.
La mayoría de los equipos subestiman primero esta capa. La memoria ayuda al agente a recordar y las habilidades le permiten especializarse, pero los ganchos convierten expectativas operativas repetidas en políticas. Se encuentran justo donde el razonamiento basado en modelos se encuentra con el comportamiento impuesto por el sistema, que es donde ocurren muchos fallos en producción. Sin ellos, la calidad depende excesivamente de las instrucciones proporcionadas.
Capa cuatro: Subagentes para la delegación
Mientras que los ganchos se encargan del control, los subagentes se ocupan de la delegación. La documentación los describe como asistentes de IA especializados que manejan tipos específicos de tareas dentro de su propia ventana de contexto y devuelven únicamente el resultado.
La lógica es sencilla. Una de las formas más rápidas de deteriorar una sesión es permitir que las tareas secundarias contaminen la conversación principal con registros, resultados de búsquedas o razonamientos exploratorios que nunca se volverán a utilizar. En lugar de forzar a un agente generalista a manejar todo en un único hilo, el agente principal asigna una tarea secundaria a un trabajador especializado que opera de forma independiente y envía un resumen. Las ventajas incluyen:
- La exploración y la implementación permanecen fuera de la conversación principal, preservando el contexto.
- El acceso limitado a herramientas impone restricciones.
- Las configuraciones pueden reutilizarse en diferentes proyectos.
- Los prompts enfocados especializan el comportamiento.
Llamar a un subagente “prompt con nombre” es subestimarlo. En realidad, se trata de una unidad de trabajo autónoma que incluye una descripción, un prompt del sistema, un modelo seleccionado, un conjunto de herramientas permitidas, configuraciones de memoria y un límite de tiempo de ejecución.
Los ejemplos integrados muestran la finalidad de cada uno. Explore está optimizado para búsquedas de solo lectura y análisis de bases de código, Plan sirve para flujos de trabajo de planificación, y el agente de uso general se encarga de tareas complejas de múltiples pasos que combinan razonamiento y acción. La documentación indica además que los subagentes integrados heredan los permisos de la conversación principal, además de restricciones adicionales en las herramientas, por lo que la delegación está limitada por diseño.
Otra limitación: los subagentes no realizan recursión. Anthropic indica que un subagente no puede generar otros subagentes, y es así como Claude evita el anidamiento infinito mientras sigue recopilando el contexto necesario. Sin un límite claro, la delegación puede derivar en estructuras de agentes descontroladas que son costosas, difíciles de monitorear y complicadas de analizar. El modelo se mantiene simple: el agente principal asigna las tareas, el subagente las realiza de forma aislada y el resultado vuelve hacia arriba.
Desde el punto de vista práctico, los subagentes se pueden configurar en varios niveles. Se pueden crear de forma interactiva con el comando /agents, almacenarse por usuario en ~/.claude/agents/, almacenarse por proyecto en .claude/agents/, pasarse por la línea de comandos para una sesión o incluirse dentro de plugins. Cada uno es un archivo Markdown con frontmatter en YAML, pero el comportamiento que define es amplio: la elección del modelo, el acceso a herramientas, el comportamiento de la memoria, los ganchos y las habilidades pueden asignarse todos a ese trabajador delegado. Se trata de perfiles de ejecución empaquetados, no de etiquetas de rol.
Por esta razón, los subagentes se encuentran entre las capas más importantes. CLAUDE.md establece al agente principal dentro de las reglas del proyecto, el suministro de habilidades brinda expertise modular y los ganchos aplican las políticas en tiempo de ejecución, pero los subagentes evitan que todo se convierta en una conversación sobrecargada con demasiadas responsabilidades. El aislamiento es la ventaja silenciosa: un subagente puede leer docenas de archivos, realizar búsquedas y seguir caminos sin salida sin que ninguna de esas actividades llegue al hilo principal, el cual solo recibe la conclusión. Establecen límites claros alrededor del trabajo secundario, permiten que los equipos se especialicen en sus flujos de trabajo y mantienen el contexto principal más limpio y duradero. Con la delegación en marcha, el problema restante es organizativo: cómo empaquetar todo esto para un equipo.
Elegir dónde pertenece cada regla
Con cinco capas disponibles, la ubicación de las reglas se convierte en una decisión de diseño. Una prueba útil es preguntarse cómo debería comportarse la regla: si siempre debe estar disponible, colóquela en CLAUDE.md; si se trata de un procedimiento necesario solo ocasionalmente, conviértala en una habilidad; si debe aplicarse sin importar lo que decida el modelo, entonces es un gancho. Si el trabajo es ruidoso, autónomo o adecuado para un modelo más económico, entréguelo a un subagente. Si todo el conjunto necesita ser transferido, empáquelo como un plugin. Las reglas colocadas en la capa incorrecta tienden a fallar de formas habituales: una política escrita en prosa es ignorada, un procedimiento largo almacenado en memoria ocupa todo el espacio restante, y una configuración ingeniosa guardada en una sola computadora portátil nunca llega al equipo.
Capa cinco: Plugins para distribución
Supongamos que un equipo ya cuenta con su archivo de memoria, sus habilidades, sus complementos y sus subagentes. El problema ya no es el comportamiento local, sino la distribución. ¿Cómo puede esa configuración trasladarse entre repositorios, máquinas y compañeros de equipo sin tener que reconstruirla manualmente cada vez?
Anthropic ofrece varios mecanismos para empaquetar y reutilizar comportamientos en diferentes contextos: subagentes a nivel de usuario y de proyecto, habilidades compartidas, configuraciones de complementos, despliegue de CLAUDE.md en toda la organización, y complementos que incluyen inteligencia de código u otras capacidades. Claude Code no está diseñado únicamente para una sola persona; cada vez está más orientado a que los equipos estandaricen y distribuyan el comportamiento del agente.
La señal oficial más clara es el modelo de complementos y configuraciones. La documentación de las configuraciones describe secciones dedicadas a la configuración de los complementos, listas de permisos y autorizaciones como codeIntelligence.*, además de configuraciones locales del proyecto y configuraciones heredadas del usuario. También señala que los argumentos de la CLI, como las banderas append-system-prompt y allowed-tools, no se transmiten a los complementos, lo que confirma que estos son unidades de distribución independientes con su propia superficie de comportamiento, y no extensiones pasivas de la sesión principal. Por lo tanto, los complementos sirven más bien para encapsular el comportamiento de un agente para que pueda instalarse, reutilizarse y gestionarse a gran escala.
Ese mismo patrón se observa en otros lugares. Los subagentes permiten la instalación a nivel de usuario, a nivel de proyecto, solo para sesiones y definida por complementos. Las habilidades siguen un diseño modular que permite que los conocimientos reutilizables existan fuera de la capa de memoria siempre cargada. La arquitectura no se limita a determinar si el agente puede hacer algo; cada vez más pregunta cómo esa capacidad puede ser empaquetada y compartida, lo cual es la característica distintiva de una plataforma en lugar de un asistente para un único usuario.
La gobernanza también forma parte de ello. Un paquete compartido puede contener subagentes verificados, permisos de herramientas estrictamente limitados, ganchos estándar o flujos de trabajo propios de una organización, de modo que los equipos distribuyen políticas y no solo conveniencias. Las rutas empresariales para archivos CLAUDE.md gestionados de forma centralizada demuestran que la estandarización se planificó desde el principio. El mismo diseño en capas que acelera el trabajo de un ingeniero puede convertirse en un modelo operativo para todo el equipo, en el que la memoria, la experiencia, los controles y la delegación se comparten en lugar de reconstruirse.
¿Qué sucede cuando falta una capa?
Visto en su conjunto, el stack ofrece una lista de verificación práctica para diagnosticar una configuración de agentes poco fiable. El síntoma suele indicar la capa que falta.
- El agente sigue haciendo las mismas preguntas o ignora el estilo de la casa. Falta memoria. Las reglas duraderas deben estar en CLAUDE.md, organizadas por directorio y divididas en importaciones, ya que de lo contrario el archivo crece demasiado.
- Cada sesión comienza con un procedimiento largo pegado. El conocimiento queda atrapado en los prompts. Se deben trasladar las partes repetibles a habilidades para que se carguen solo cuando la tarea lo requiera.
- Las acciones riesgosas dependen de que el modelo recuerde ser cuidadoso. Las medidas de seguridad son solo sugerencias. Los hooks permiten que el formato, la protección de archivos y la reescritura de comandos se realicen independientemente de lo que decida el modelo.
- La conversación principal se llena de registros y callejones sin salida. Falta delegación. Los subagentes con herramientas limitadas se encargan del trabajo secundario ruidoso y devuelven un resumen.
Lo común en todos estos casos es que ninguna de estas soluciones consiste simplemente en una frase mejor redactada en una instrucción. Se trata de cambios estructurales, y por eso son efectivos bajo cargas de trabajo reales. Tratar a Claude Code como un kit de desarrollo para agentes que, por casualidad, se entrega dentro de una terminal hace que esos cambios sean más fáciles de observar, más fáciles de discutir con el equipo y más fáciles de implementar de forma deliberada, capa por capa.
Lecturas relacionadas
- Un Harness de Producción para Claude Code: Seis capas desde Slack hasta el MR fusionado — Cómo un harness de seis capas convierte los tickets de Slack en código fusionado: captura de eventos, bucles de agente con control de acceso, estado duradero, capacidad de autoreparación, observabilidad y control por parte del operador.
- Usando Codex en VS Code: Alcance, puntos de recuperación y soluciones para los cuellos de botella habituales — Una guía práctica para utilizar la extensión Codex en VS Code: instalación, inicio de sesión, una primera tarea de agente delimitada, uso en la nube frente a la CLI, configuración compartida, y soluciones para problemas en WSL, aprobaciones y autenticación remota.