Por dentro de Claude Code: 9 lecciones del nuevo artículo de arquitectura a nivel de código

Qué es realmente el artículo

El 14 de abril de 2026, cuatro investigadores — Jiacheng Liu, Xiaohan Zhao, Xinyi Shang y Zhiqiang Shen, con la autoría de correspondencia de Zhiqiang Shen (MBZUAI) — subieron a arXiv un recorrido de 70 páginas por la arquitectura de Claude Code. No tuvieron acceso interno. Trabajaron a partir de la compilación de TypeScript distribuida públicamente (v2.1.88), siguieron el rastro de archivos como query.ts, permissions.ts y tools.ts, y contrastaron su lectura con un agente de código abierto independiente llamado OpenClaw. El resultado es el primer relato completo, a nivel de código fuente, de cómo está cableado de verdad un agente de programación en producción.

Lo hemos leído para que tú no tengas que hacerlo. Las lecciones de abajo son las partes que deberían cambiar tu forma de pensar sobre construir tu propio arnés de agente. El trabajo es de los autores; si algo de esto te sirve, por favor cita el original.

El bucle es diminuto: el arnés lo es todo

Eso que todos los tutoriales llaman «el agente» es, en Claude Code, un ciclo while-true: llamar al modelo, analizar los bloques tool_use que haya devuelto, pasarlos por el sistema de permisos, despacharlos a las herramientas, añadir el resultado, repetir. Ya está. El análisis de la comunidad que cita el artículo estima la porción de lógica de decisión del modelo en torno al 1,6% del código; el otro 98,4% es la infraestructura operativa alrededor del bucle: ensamblado de contexto, permisos, enrutado de herramientas, aislamiento, recuperación. La única función queryLoop() de query.ts se ejecuta tanto si estás en la CLI interactiva, como en la vía sin interfaz claude -p, en el SDK de agentes o en una integración de editor. Sólo cambia el renderizado.

Si te llevas una sola cosa del artículo, que sea esta: el agente no es un modelo con un prompt. Es un arnés determinista dentro del cual se le permite decidir a un modelo. El modelo nunca accede directamente al sistema de archivos, ni ejecuta comandos de shell, ni hace peticiones de red. Su única interfaz con el mundo exterior es el protocolo estructurado tool_use, que el arnés valida antes de ejecutar. Un modelo comprometido o manipulado de forma adversaria no puede saltarse las reglas implementadas en el arnés, porque razonamiento y aplicación viven en rutas de código distintas.

Cinco valores, trece principios

Los autores no describen la arquitectura como una lista de funciones. Identifican cinco valores humanos — autoridad de decisión humana, seguridad, protección y privacidad, ejecución fiable, amplificación de capacidad, adaptabilidad al contexto — y los siguen a través de trece principios de diseño, cada uno de los cuales responde a una pregunta recurrente que cualquier agente de programación en producción tiene que resolver. Unos cuantos de esos principios le sonarán a cualquiera que haya perdido una tarde con un agente desbocado:

• Denegar primero, con escalado humano: las acciones no reconocidas se deniegan o se escalan, nunca se permiten en silencio.
• Defensa en profundidad con mecanismos por capas: varias capas de seguridad independientes, cada una capaz de bloquear por sí sola.
• El contexto como recurso escaso, con gestión progresiva: trata la ventana de contexto como la restricción que manda y gestiónala por etapas.
• Evaluación de riesgo ponderada por reversibilidad: supervisión más ligera para acciones de sólo lectura y reversibles, más pesada para las destructivas.
• Estado duradero de sólo escritura: mutar lo mínimo posible; conservar el rastro de auditoría.
• Juicio del modelo dentro de un arnés determinista: confía en el razonamiento del modelo, pero sólo dentro de barreras que el arnés pueda hacer cumplir.
• Andamiaje mínimo, arnés operativo máximo: invierte en enrutado de herramientas y recuperación, no en grafos de planificación explícitos.

Catalogarlos hace legibles las renuncias. Si tu arnés incorpora principios distintos —«grafos de planificación explícitos» en lugar de «andamiaje mínimo», o «aislamiento en contenedores» en lugar de «evaluación de denegar primero»— obtendrás LangGraph, SWE-Agent o Aider en lugar de Claude Code, y eso es una elección deliberada y no un accidente.

Denegar primero, porque la gente dice que sí el 93% de las veces

El dato empírico más útil del artículo está tomado del propio modelo de amenazas del modo automático de Anthropic: quien usa la herramienta aprueba alrededor del 93% de las peticiones de permiso. Ese número no es una victoria. Significa que la confirmación interactiva no es fiable como único mecanismo de seguridad, porque en cuanto nos acostumbramos, firmamos sin mirar.

La respuesta arquitectónica va por capas. El prefiltrado de denegación total retira las herramientas prohibidas de la vista del modelo en el momento de ensamblar el conjunto de herramientas: el modelo nunca ve herramientas que no puede ejecutar, así que nunca gasta un turno proponiéndolas. Las reglas de denegación mandan sobre las de preguntar, y estas sobre las de permitir, aunque la regla de permitir sea más específica. Un clasificador de aprendizaje automático opcional en modo automático compite con el diálogo del usuario cuando BASH_CLASSIFIER está activo, aprobando al instante las acciones seguras de alta confianza y escalando el resto. Debajo de todo eso hay un sandbox de shell opcional. Los siete modos de permiso documentados en el artículo (plan, default, acceptEdits, auto, dontAsk, bypassPermissions, más el bubble interno usado para el escalado de subagentes) son puntos de un espectro graduado de confianza, no interruptores.

Un detalle sutil que merece destacarse: cuando el clasificador o una regla de denegación bloquea una acción, el sistema trata la denegación como señal de enrutado y no como una parada en seco. El modelo recibe el motivo de la denegación, revisa su enfoque y prueba algo más seguro en la siguiente iteración. La aplicación de permisos da forma a la conducta en lugar de detenerla.

El contexto como canalización de cinco etapas, no como un único mando

Los modelos de contexto largo no eliminan el problema del contexto; lo desplazan. Claude Code ejecuta cinco compactadores distintos antes de cada llamada al modelo, en orden creciente de coste:

1. Reducción de presupuesto: recorta sobre la marcha las salidas de herramientas demasiado grandes y las sustituye por referencias al contenido.
2. Recorte: poda ligera del historial, controlada por HISTORY_SNIP.
3. Microcompactación: compresión de grano fino con una vía opcional consciente de la caché que aplaza las decisiones de frontera hasta después de la respuesta de la API, para poder usar los cache_deleted_input_tokens reales en lugar de estimaciones.
4. Colapso de contexto: una proyección en tiempo de lectura sobre la conversación, de modo que el modelo ve la vista colapsada mientras el historial completo permanece intacto para reanudar.
5. Compactación automática: un resumen generado por el modelo que sólo se dispara cuando todo lo demás ha fallado.

Cada capa aborda un tipo de presión distinto. Las capas baratas se ejecutan antes que las caras. Los CLAUDE.md de carga diferida, los esquemas de herramientas diferidos y los retornos de subagente sólo con resumen son amortiguadores adicionales del coste de contexto alrededor del bucle. Si tu arnés tiene un único mecanismo de resumen automático, tiene el número equivocado.

Cuatro superficies de extensión, no una megaAPI

Servidores MCP, complementos, habilidades y ganchos. Cada uno se enchufa en un punto de inyección distinto y con un coste de contexto distinto.

• MCP es la vía de integración de herramientas externas, con transportes stdio, SSE, HTTP, WebSocket, SDK y específicos de editor.
• Los complementos empaquetan varios tipos de componente en una sola unidad de distribución: comandos, agentes, habilidades, ganchos, servidores MCP y LSP, estilos de salida, canales, ajustes y configuración de usuario.
• Las habilidades son archivos SKILL.md con encabezado YAML; sus instrucciones sólo se inyectan en el contexto cuando se invocan, así que salen baratas mientras están inactivas.
• Los ganchos se disparan en uno de 27 eventos documentados — PreToolUse, PostCompact, SessionStart, FileChanged, SubagentStop y demás — con cuatro tipos de comando persistibles (shell, prompt, http, agente) y una variante de retrollamada en tiempo de ejecución para uso desde el SDK.

La negativa deliberada a publicar una única API de extensión unificada es en sí misma una decisión de diseño. La extensión está estratificada de modo que se favorezcan los mecanismos de bajo coste y los caros (herramientas siempre activas, respuestas MCP grandes) sean opcionales.

Los subagentes son aislamiento, no paralelismo

El error que casi todo el mundo comete con los subagentes es tratarlos como trabajadores de un grupo. El artículo hace explícita la lectura alternativa. Los subagentes de Claude Code crean ventanas de contexto nuevas y aisladas; no comparten el estado de permisos ni la transcripción del padre; devuelven al padre sólo texto de resumen. El aislamiento basado en worktrees permite que un subagente se ejecute en un worktree de git literalmente separado del árbol de trabajo del usuario. El objetivo no es el rendimiento: es acotar el radio de daño de una tarea delegada. Si lo que quisieras fuera paralelismo, lo construirías de otra manera.

Estado de sólo escritura: auditabilidad por encima de capacidad de consulta

Las transcripciones de sesión son archivos JSONL de sólo escritura con parcheado de cadena en tiempo de lectura. Los permisos deliberadamente no se restauran al reanudar: los autores lo señalan como una decisión de seguridad y no como un descuido. Incluso la compactación se implementa, cuando es posible, como una proyección en tiempo de lectura sobre el historial completo y no como una edición destructiva.

La renuncia es real y explícita: consultas estructuradas del tipo «todas las llamadas a herramientas de todas las sesiones que tocaron el archivo X» exigen reconstrucción a posteriori. Los autores conectan este compromiso con la autoridad de decisión humana: se puede auditar porque no se sobrescribe nada.

Tres patrones que aparecen en todas partes

Cuando los autores toman distancia, tres compromisos aparecen en cada subsistema que analizan:

1. Estratificación graduada frente a mecanismos monolíticos. El sistema de permisos tiene siete etapas; la gestión de contexto, cinco compactadores; la extensibilidad, cuatro mecanismos. Cada capa es auditable por separado.
2. Sólo escritura por encima de capacidad de consulta, en todas partes. Registros, transcripciones, memoria, salidas de ganchos.
3. Juicio del modelo dentro de un arnés determinista. El arnés crea las condiciones para que el modelo decida bien y luego se aparta.

Estos tres son buenos puntos de control al revisar tu propio diseño. Si un subsistema es monolítico, muta estado o restringe las opciones del modelo de forma procedimental, probablemente has elegido un punto distinto del espacio de diseño que el que eligió Claude Code. Puede ser la decisión correcta, pero conviene tomarla a propósito.

Seis preguntas abiertas para quien construya el siguiente

La sección final del artículo es la más generosa. Nombra seis direcciones abiertas, cada una con citas suficientes para tener a un equipo de investigación ocupado un trimestre:

• La brecha entre observabilidad y evaluación. Las encuestas del sector muestran que alrededor del 89% de los equipos publica observabilidad pero sólo el 52% hace evaluación fuera de línea, y Bessemer estima que el 78% de los fallos de IA son invisibles. Cerrar esa brecha probablemente exige andamiaje en la capa del arnés (separación generador-evaluador, contratos de sprint, comprobaciones a posteriori) y no mejoras del modelo.
• Persistencia entre sesiones. ¿Qué hay entre las instrucciones estáticas de CLAUDE.md y la transcripción JSONL de cada sesión? Manuales de estrategias autocurados a partir de sesiones pasadas son la siguiente capa natural.
• Evolución de la frontera del arnés en los ejes dónde, cuándo, qué y con quién. Los agentes gestionados virtualizan sesión, arnés y sandbox; los pulsos proactivos al estilo KAIROS cambian cuándo actúa el agente; el trabajo en visión-lenguaje-acción cambia sobre qué actúa; las topologías multiagente cambian con quién.
• Escalado de horizonte: de la sesión al programa científico. Si las mismas primitivas que funcionan para un turno y una sesión siguen funcionando a lo largo de semanas de investigación autónoma.
• Gobernanza. La Ley de IA de la Unión Europea entra plenamente en aplicación en agosto de 2026, y sólo el 13,3% de los sistemas agénticos indexados publica fichas de seguridad específicas del agente.
• La lente evaluativa. La preocupación del propio artículo: la amplificación de capacidad a corto plazo puede erosionar la capacidad humana a largo plazo. Un estudio interno de la propia Anthropic halló una caída del 17% en la comprensión de quienes programan con ayuda de IA. Merece una columna en el panel de diseño.

Estas son las partes de la pila de agentes que más probablemente se vean completamente distintas dentro de 18 meses.

Créditos y fuente

Este artículo es un resumen. El trabajo es de los autores. La referencia completa es:

Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, Zhiqiang Shen. «Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems.» arXiv:2604.14228 [cs.SE], 14 de abril de 2026. Código: github.com/VILA-Lab/Dive-into-Claude-Code. CC BY-NC-SA 4.0. Autor de correspondencia: Zhiqiang Shen (MBZUAI).

Si sólo tienes tiempo para partes del original, ve a la sección 2 (la tabla de valores y principios), la sección 4 (la canalización de compactación) y la sección 11 (las tensiones de diseño transversales). El artículo es la fuente de verdad; esta entrada es sólo una guía de lectura.

Lecturas relacionadas en este sitio: ¿Qué es MCP?, Los mejores servidores MCP en 2026, Cursor frente a Windsurf frente a Claude Code.