Cómo funciona Claude Code por dentro: guía técnica completa 2026
Claude Code es el agente de codificación de Anthropic. Muchos lo usan todos los días. Muy pocos saben cómo está construido por dentro.
Esto no es un problema menor. Si un agente decide qué comandos ejecutar en tu máquina, a qué archivos accede, qué te pide permiso y qué no, cómo delega trabajo, qué telemetría envía a Anthropic y cómo maneja tareas largas sin explotar el contexto — entender esa mecánica es la diferencia entre usar la herramienta con fundamento o a ciegas.
En los últimos meses hemos publicado despieces técnicos profundos de cada subsistema de Claude Code. Este artículo los reúne en una única guía: qué hace cada pieza, cómo encajan entre sí y qué lecciones podemos sacar para construir agentes de IA mejor diseñados.
Va dirigido a desarrolladores, arquitectos de agentes y cualquiera que quiera entender por qué Claude Code se siente distinto — y a veces mejor, a veces peor — que otros asistentes de código.
El punto de partida: ¿qué es Claude Code exactamente?
Claude Code es un CLI (interfaz de línea de comandos) instalable con npm install -g @anthropic-ai/claude-code. Corre en tu terminal, lee el código de tu repositorio, edita archivos, ejecuta comandos bash, navega por la web, llama a APIs externas a través de MCP y mantiene memoria de sesión.
Por dentro, no es un programa tradicional: es un loop agéntico donde un modelo (Claude Opus o Claude Sonnet, según el plan) va decidiendo en cada iteración qué herramienta invocar a partir de:
El mensaje del usuario.
El contexto acumulado (archivos leídos, outputs de comandos anteriores, historial).
Un system prompt interno con instrucciones de formato, seguridad y convenciones.
Una lista de herramientas disponibles (leer archivo, escribir archivo, ejecutar bash, grep, delegar a un subagente, etc.).
Cada iteración del loop produce una acción, se ejecuta, su resultado vuelve al modelo, y se decide la siguiente acción hasta que el modelo considera que la tarea está completada.
Sobre ese esqueleto, Anthropic ha construido cinco subsistemas que hacen que Claude Code sea usable en producción y no un experimento frágil: permisos, subagentes, background tasks, telemetría y el propio loop. Vamos uno a uno.
1. El sistema de permisos: cómo decide qué ejecutar
El subsistema más delicado de Claude Code es el de permisos. Un agente con acceso a bash puede hacer daño real: borrar archivos, sobrescribir trabajo, filtrar claves. Sin un modelo de permisos bien pensado, esto es ingobernable.
Claude Code resuelve el problema con seis modos de permiso (default, acceptEdits, plan, auto, dontAsk, bypassPermissions) y un clasificador de machine learning que decide en tiempo real si un comando bash es seguro o necesita confirmación del usuario.
El detalle interesante es que en modo auto — introducido en marzo de 2026 — un clasificador basado en Sonnet 4.6 evalúa cada llamada a bash sin ver el texto que el modelo principal ha escrito antes de la llamada. Solo ve la petición original del usuario y el comando exacto. Anthropic lo diseñó así deliberadamente: impide que el modelo "convenza" al clasificador con texto persuasivo. Es una separación clara entre quién propone y quién autoriza.
Esta arquitectura es lo que permite desbloquear el modo --dangerously-skip-permissions (YOLO mode) para workflows automatizados sin perder todo el control: puedes mezclarlo con reglas de allow/ask/deny en settings.json y el clasificador sigue aplicándose.
Publicamos un despiece completo con los seis modos, las reglas allow/ask/deny, y cómo el clasificador toma decisiones en el sistema de permisos con ML de Claude Code.
2. Subagentes: cómo Claude Code delega en clones de sí mismo
La segunda pieza clave es la de subagentes. Un subagente es un Claude independiente — con su propio system prompt, su propia ventana de contexto y su propio set de herramientas — al que el agente principal puede delegar una tarea.
El patrón es simple pero potente:
El agente principal orquesta.
Cuando topa con una subtarea definida (auditar un módulo, buscar en la codebase, revisar un PR), la pasa a un subagente.
El subagente trabaja aislado. No ensucia el contexto del principal.
Devuelve un resumen corto y el principal continúa.
Un detalle importante: los subagentes no heredan el system prompt completo de Claude Code. Tienen el suyo propio más el entorno básico. Esto los hace más moldeables pero también más quebradizos: si olvidas decirle algo clave en su system prompt, lo va a hacer mal de formas sutiles.
El patrón tiene dos ventajas enormes:
Eficiencia de contexto: en vez de que todo el trabajo se acumule en una sola ventana de 200k tokens, cada subagente arranca limpio. Con tareas largas esto evita la degradación por contexto sucio.
Especialización: puedes configurar subagentes con tools restringidas (ej: un
code-reviewerque solo tengaReadyGrep, sinWriteniBash).
Lo cubrimos en detalle en subagentes: cómo Claude Code delega en clones, incluyendo los siete tipos de agente por defecto y cómo crear los tuyos.
3. Tasks en background: cuando Claude Code "sueña"
Un agente que solo responde de forma síncrona es limitado. Claude Code introdujo un sistema de tasks que permite lanzar trabajo en segundo plano: builds, tests, descargas, procesos largos. El agente principal sigue conversando mientras la tarea corre.
Hay siete tipos de background task en Claude Code, con distintos comportamientos (algunos notifican cuando terminan, otros se monitorizan bajo demanda, otros se pueden matar a mitad). La herramienta ScheduleWakeup permite incluso programar que el agente se despierte a sí mismo en X minutos para volver a revisar algo.
Este sistema es la base técnica de los loops autónomos: decirle al agente "vuelve a revisar esto cada 20 minutos hasta que el build pase" sin ocupar tu terminal ni tu tiempo.
Analizamos los siete tipos, cuándo usar cada uno y los gotchas en Claude Code 'sueña' cuando no lo usas: anatomía del sistema de tasks.
4. Telemetría: qué datos envía Claude Code a Anthropic
Esta es la parte que más incomoda a equipos con preocupaciones de privacidad o requisitos RGPD, y la razón por la que muchas empresas europeas no pueden usar Claude Code como está.
Claude Code tiene tres sistemas de telemetría operando en paralelo:
Telemetría de uso básico: qué comandos se invocan, con qué frecuencia, duración de sesiones.
Telemetría de prompts (opt-out): el contenido de las conversaciones puede usarse para mejorar el producto a menos que lo desactives explícitamente.
Telemetría de crashes y errores: trazas de fallos enviadas a servidores de Anthropic.
El problema no es que exista — casi todo SaaS la tiene — sino que por defecto está activa y los controles granulares no son obvios. Para un equipo que maneja código propietario o datos de clientes bajo NDA, entender exactamente qué sale de la máquina es un requisito de cumplimiento, no un "nice to have".
Tenemos el análisis completo con los endpoints concretos, qué se envía en cada uno y cómo desactivarlos en cómo Claude Code te observa: anatomía de su telemetría. Este artículo es también la razón por la que Levante se construye local-first: los datos de tu código no salen de tu máquina salvo cuando tú decidas, explícitamente, llamar a una API externa.
5. El loop agéntico: el cerebro de todo
Los cuatro sistemas anteriores se montan sobre una pieza central: el loop agéntico, que es lo que ejecuta acción → observación → siguiente acción hasta completar la tarea.
El loop de Claude Code tiene varias sutilezas:
Gestión de tool use: cada tool call tiene un presupuesto de tokens distinto. El modelo tiene que decidir no solo qué tool usar sino cómo comprimir sus argumentos para no quemar contexto.
Compactación: cuando el contexto se acerca al límite, Claude Code comprime automáticamente la conversación para seguir funcionando. Pierde detalle en el proceso — por eso tareas muy largas fallan "raro".
Reintentos: si una tool falla, el loop decide si reintentar, pedir ayuda al usuario o abortar.
Límites de iteración: hay un máximo de pasos por sesión antes de que el loop se detenga preventivamente.
Este es el punto donde más se nota la ingeniería: un agente mal diseñado se queda atascado en bucles infinitos o se confunde con el contexto. Claude Code hace concesiones razonables (compactación agresiva, límites duros) que lo mantienen estable a costa de algo de profundidad en tareas gigantes.
Profundizamos en la mecánica interna — query engine, token budgets, tool execution, compactación — en el cerebro de Claude Code: anatomía del loop agéntico.
Un caso real: cuando Anthropic filtró su propio código
Todo lo anterior describe un sistema bien pensado. Pero ningún stack es perfecto, y Anthropic lo aprendió a las malas.
En un incidente que cubrimos en detalle, Anthropic publicó por error parte de su código fuente en un paquete npm público. Fue una gestión defectuosa del flujo de publicación: se subió un artefacto con fuentes incluidas en vez del bundle minificado y ofuscado.
La lección no es "Anthropic es descuidada" — lo es cualquier equipo grande eventualmente. La lección es que incluso los proveedores de IA más cuidadosos fallan. Si tu empresa depende al 100% de un stack cerrado que no puedes auditar, un descuido del proveedor te puede dejar expuesto sin que te enteres.
Es uno de los argumentos centrales para preferir herramientas open-source auditables — como Levante — cuando el código que manejas es crítico.
Cómo encajan las cinco piezas
Visto desde arriba, el diseño de Claude Code sigue un patrón claro:
Usuario
↓
[Loop agéntico] ← system prompt + context + tools
↓
├─ Permisos (valida cada tool call)
├─ Subagentes (delega tareas aisladas)
├─ Background tasks (trabajo asíncrono)
└─ Telemetría (observabilidad)El loop es el motor. Los permisos son el guardia. Los subagentes son los trabajadores especializados. Los background tasks son el equipo de noche. La telemetría es el observador (que a veces observa demasiado).
Cada decisión de diseño tiene tradeoffs: permisos más estrictos significa más interrupciones. Subagentes más agresivos significa más coste de tokens. Compactación más agresiva significa menos memoria. Anthropic ha calibrado esos tradeoffs para que la herramienta funcione bien en el caso medio — desarrollador individual con codebase de tamaño razonable — pero los casos extremos (equipos grandes, repos enormes, compliance estricto) exponen las costuras.
Qué aprendemos de Claude Code
Después de analizar cada subsistema, estas son las decisiones que nos parecen correctas y las que vemos como deuda:
Lo que acierta:
Separar "quien propone" (modelo) de "quien autoriza" (clasificador) es un patrón de seguridad limpio.
Subagentes con contextos aislados evitan el problema clásico del agente que se pierde en tareas largas.
Compactación automática es pragmática — feo pero necesario con ventanas de contexto finitas.
Background tasks abren la puerta a workflows de verdad asíncronos, no solo REPL glorificado.
Donde duele:
Telemetría activa por defecto no se alinea con requisitos europeos de privacidad / RGPD.
El clasificador de permisos es opaco: no puedes auditar por qué marcó algo como seguro.
La arquitectura cerrada impide customizar loops o sustituir pedazos (ej: cambiar el modelo del clasificador).
Depender de infraestructura Anthropic al 100% genera riesgo de vendor lock-in.
Por qué esto importa: Levante como cowork de IA
Todo este análisis nos lleva a una conclusión práctica: los patrones de Claude Code son excelentes referencias, pero el producto en sí es propietario, cerrado y diseñado para un modelo de distribución (SaaS dependiente de Anthropic) que no funciona para todos los casos.
Por eso construimos Levante: un cowork de IA de escritorio, open-source (Apache 2.0 + Commons Clause), local-first (tu código no sale si tú no quieres) y multi-proveedor (no te atan a un solo modelo). Aplicamos muchos de los patrones que Claude Code popularizó — loop agéntico, subagentes, MCP — pero con el control en tu máquina.
Si además gestionas un equipo y necesitas políticas centralizadas (gestión de MCP, control de costes, AI Gateway con Zero Data Retention europeo), Levante Platform resuelve esa capa empresarial. Y si prefieres usar solo la versión de escritorio gratuita, también es suficiente.
Conclusión
Claude Code es una pieza de ingeniería seria. Sus cinco subsistemas — loop, permisos, subagentes, background tasks y telemetría — están razonablemente bien diseñados y funcionan como stack coherente. Entender cómo encajan te convierte en un usuario más competente y te da ideas para construir tus propios agentes.
Pero entenderlo también te da un criterio más crítico: dónde brilla (seguridad estructurada, delegación), dónde cojea (privacidad, apertura), y cuándo tiene sentido preferir un stack más abierto y controlable.
Si quieres empezar por un subsistema concreto:
Seguridad y permisos: el sistema de permisos con ML.
Arquitectura multi-agente: subagentes y delegación.
Automatización asíncrona: el sistema de tasks.
Privacidad y compliance: anatomía de la telemetría.
Loop interno: el cerebro del loop agéntico.
Caso real de fallo: cuando Anthropic filtró su código.
Cada uno entra al detalle donde este artículo pasa por encima.
Fuentes verificadas
Documentación oficial de subagentes en code.claude.com/docs/en/sub-agents.
Análisis técnico independiente en VILA-Lab/Dive-into-Claude-Code.
Lanzamiento de Claude Managed Agents (beta pública, abril 2026) documentado en comunicados de Anthropic.
Datos verificados el 22 de abril de 2026.
