Cómo Funciona una Instancia de Claude Code

3 de marzo de 202615 min de lectura

Claude CodeArchitectureAI Tools

Documento de referencia sobre la arquitectura interna de Claude Code: el loop agente, gestión de contexto, herramientas, permisos, subagentes, memoria y más.

Tip: Al final del artículo encontrarás un prompt listo para copiar y pegar en Claude Code que configura una barra de estado con info de proyecto, branch, modelo, contexto y duración de sesión.

1. Inicio de Sesión (Bootstrap)

Cuando ejecutas claude en un directorio, ocurre lo siguiente:

Se crea una sesión con un ID único, almacenada en ~/.claude/projects/<project>/<session-id>.jsonl
Se construye el system prompt dinámicamente ensamblando 110+ componentes
Se evalúan permisos según el modo configurado

El system prompt se compone de múltiples piezas:

Componente	Descripción	Tokens aprox.
Instrucciones core	Reglas de comportamiento base, integración git	95 - 1,067
Tool schemas (23+)	Definiciones JSON de todas las herramientas	12 - 2,167 c/u
CLAUDE.md files	Instrucciones del proyecto (recursivo hasta raíz)	Variable
MEMORY.md	Auto-memoria persistente (primeras 200 líneas)	Variable
Git status snapshot	Branch actual, archivos sin trackear, commits recientes	~95
Info del entorno	Plataforma, OS, fecha, modelo	Variable
Herramientas MCP	Schemas de servidores MCP conectados	100-500 por servidor
Subagent descriptions	Descripciones de subagentes disponibles	294 - 633
Rules condicionales	Archivos de `.claude/rules/` con YAML frontmatter	Variable

El system prompt total antes de cualquier input del usuario suele ser de 2-5K tokens. Con MCP servers y CLAUDE.md extensos puede crecer significativamente.

2. El Loop Agente (Core del Sistema)

El corazón de Claude Code es un loop recursivo de tres fases que se repite hasta completar la tarea:

Fase 1 - Gather Context: Claude lee archivos, busca código, ejecuta comandos para entender el estado actual.

Fase 2 - Take Action: Claude hace edits, ejecuta tests, crea commits.

Fase 3 - Verify Results: Claude revisa output, confirma cambios, valida resultados.

Estas fases se mezclan continuamente — no son estrictamente secuenciales. Claude decide qué necesita cada fase basado en los aprendizajes de pasos anteriores.

Puede encadenar docenas de acciones sin intervención manual
El usuario puede interrumpir en cualquier punto para cambiar la dirección
El loop es single-threaded en la conversación principal (subagentes corren independientemente)
No hay secuencia fija de pasos — el loop es adaptativo y auto-correctivo

3. Ventana de Contexto

La ventana de contexto es de 200K tokens (expandible a 1M con Opus 4.6). Contiene todo lo que Claude "ve" en cada request.

Componente	Descripción
System prompt	Instrucciones core + tool schemas + CLAUDE.md + MEMORY.md + git status
Historial de conversación	Todos los mensajes del usuario y respuestas de Claude
Tool results	Contenido de archivos leídos, outputs de comandos, resultados de búsquedas
MCP tool definitions	Schemas de cada servidor MCP conectado
Response buffer	Espacio reservado para la respuesta del modelo

Cuando el contexto alcanza ~95% de capacidad (~190K de 200K tokens), se activa la compactación:

Se limpian outputs antiguos de herramientas
Se sumariza el historial de conversación
Se preservan: requests recientes, snippets de código clave, decisiones de implementación
Se pierde: detalles de conversaciones tempranas, intentos de debugging históricos
Se crea un bloque de compactación con metadata (preTokens, timestamp)

Pérdida de información: Las sumarizaciones pierden precisión — nombres de variables, mensajes de error exactos y decisiones matizadas se comprimen. Es un tradeoff fundamental: contexto extendido vs. precisión preservada.

Comandos útiles:

Comando	Descripción
`/compact focus on <tema>`	Compactación manual con foco específico
`/context`	Ver qué está consumiendo espacio en el contexto
`/cost`	Ver uso de tokens de la sesión actual
`/mcp`	Ver costo por servidor MCP

4. Sistema de Herramientas

Claude Code tiene acceso a herramientas que le permiten interactuar con el sistema.

Categoría	Herramientas	Propósito
Archivos	`Read`, `Write`, `Edit`	Leer, crear, modificar archivos
Búsqueda	`Glob`, `Grep`	Buscar archivos por patrón, buscar contenido con regex
Ejecución	`Bash`	Comandos de terminal
Web	`WebFetch`, `WebSearch`	Buscar y traer contenido de internet
Orquestación	`Agent`, `AskUserQuestion`	Lanzar subagentes, preguntar al usuario
MCP	Herramientas externas	Neon, Playwright, Figma, Notion, Vercel, etc.

El ciclo de vida de una tool call:

Claude genera un tool_use block en su respuesta
PreToolUse hook se ejecuta (si existe) — puede modificar o bloquear
Validación de permisos — según el modo configurado
El usuario aprueba (si es necesario según permisos)
Sandbox (OS-level) aísla la ejecución
Se ejecuta la herramienta y se captura el output
PostToolUse hook se ejecuta (si existe) — puede hacer lint, log, etc.
tool_result se retorna a Claude como parte del siguiente mensaje
Claude analiza el resultado y decide la siguiente acción

Claude puede invocar múltiples herramientas independientes en una sola respuesta. Todos los tool_use blocks aparecen en un mensaje del asistente, se ejecutan, y todos los tool_result se envían juntos en un solo mensaje de vuelta.

5. Permisos y Sandboxing (Seguridad en Dos Capas)

Capa 1: Permisos — "¿Debería ejecutarse esta herramienta?"

Modo	Comportamiento
Default	Pregunta antes de editar archivos y ejecutar comandos
Auto-accept edits	Edita archivos sin preguntar, pregunta para comandos de shell
Plan mode	Solo herramientas de lectura (no escribe ni ejecuta)
bypassPermissions	Todo automático (peligroso, no recomendado)
dontAsk	Auto-deniega a menos que esté pre-aprobado en la configuración

Se cicla entre modos con Shift+Tab.

Capa 2: Sandbox — "Si se ejecuta, ¿qué puede tocar?"

macOS: Framework Seatbelt (nativo del OS)
Linux: bubblewrap (bwrap)
Filesystem: Lectura de todo el sistema, escritura solo en el directorio de trabajo
Red: Proxy que filtra dominios permitidos — dominios nuevos generan prompts de permiso

Resultado: 84% menos prompts de permisos con sandboxing habilitado. Protección contra prompt injection, exfiltración de datos y descarga de scripts maliciosos.

6. Subagentes (Agent Tool)

Los subagentes son instancias aisladas que Claude puede lanzar para tareas específicas. Cada subagente opera en su propia ventana de contexto aislada (200K tokens independientes).

Tipo	Herramientas	Propósito
Explore	Read-only (Glob, Grep, Read)	Exploración rápida del codebase
Plan	Read-only	Diseñar planes de implementación
General-purpose	Todas (read + write)	Tareas complejas multi-paso
Bash	Solo Bash	Ejecución de comandos de terminal
Custom	Configurados por proyecto	test-runner, security-guardian, etc.

Foreground: Bloqueante; prompts de permisos se pasan al usuario; más lento
Background: Concurrente; permisos pre-autorizados; más rápido pero no puede hacer preguntas
Ctrl+B convierte una tarea foreground en background
No pueden crear otros subagentes (sin nesting)
Heredan permisos del padre con restricciones adicionales de herramientas

7. Sistema de Memoria (Persistencia entre Sesiones)

Claude Code implementa un sistema de memoria multi-nivel que permite persistir información entre sesiones.

Nivel	Ubicación	Quién lo escribe	Se carga al inicio
Managed policy	`/Library/.../ClaudeCode/CLAUDE.md`	Admin de la org	Sí
User memory	`~/.claude/CLAUDE.md`	Tú	Sí
Project memory	`./CLAUDE.md`	Equipo (git)	Sí
Local memory	`./CLAUDE.local.md`	Tú (no git)	Sí
Auto memory	`~/.claude/projects/.../memory/MEMORY.md`	Claude	Primeras 200 líneas
Rules	`.claude/rules/*.md`	Equipo	Sí (condicional)

CLAUDE.md vs MEMORY.md:

Aspecto	CLAUDE.md	MEMORY.md
Autor	Tú escribes instrucciones	Claude escribe notas para sí mismo
Contenido	Convenciones, estándares, comandos	Patrones descubiertos, aprendizajes
Propósito	Instrucciones persistentes	Aprendizaje sesión a sesión

8. Flujo de Mensajes (Request Pipeline)

Cada mensaje del usuario pasa por un pipeline completo antes de llegar al modelo:

Usuario escribe y presiona Enter
UserPromptSubmit hook (si existe) puede modificar o bloquear el prompt
System prompt se construye/actualiza con memoria + contexto
Historial de conversación se carga desde el archivo JSONL
Cálculo de contexto — si se acerca al límite, se compacta
Request enviado al API de Claude vía streaming (SSE)
Tokens llegan incrementalmente y se renderizan en la terminal
Si hay tool_use blocks se ejecutan las herramientas
tool_results se alimentan de vuelta al modelo automáticamente
Loop hasta stop_reason: "end_turn"
Todo se persiste al archivo JSONL de la sesión inmediatamente

Formato de persistencia: JSONL (JSON Lines) — cada línea es un evento completo. Se escribe a disco inmediatamente (no al final de la sesión). Si el programa crashea, solo se pierde el último mensaje incompleto.

Claude Code usa Server-Sent Events (SSE) con "stream": true:

content_block_start — inicio de un bloque
content_block_delta — tokens incrementales
content_block_stop — fin del bloque

9. Hooks (Automatización del Ciclo de Vida)

Los hooks son comandos shell o prompts LLM definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida.

Hook	Cuándo se ejecuta	Caso de uso
`PreToolUse`	Antes de ejecutar herramienta	Validación, bloqueo de ops peligrosas, modificar inputs
`PostToolUse`	Después de completar herramienta	Logging, verificación, lint automático
`UserPromptSubmit`	Cuando usuario envía prompt	Pre-procesamiento, validación
`Stop`	Cuando la sesión termina	Cleanup, generación de resumen

Estos son los hooks más comunes, entre otros. Claude Code soporta 17+ tipos de eventos de hooks incluyendo SessionStart, SubagentStart, SubagentStop, PreCompact, etc.

Exit 0: Éxito, continuar
Exit 2: Error bloqueante, detener ejecución
stderr se envía a Claude como mensaje de error
Hooks se configuran en ~/.claude/settings.json (usuario) o .claude/settings.json (proyecto)

10. Sesiones: Persistencia y Reanudación

Creación: Se genera un ID único y un archivo JSONL
Mantenimiento: Historial completo se mantiene durante toda la sesión
Checkpoints: Se crean automáticamente antes de edits para permitir undo
Terminación: La sesión persiste indefinidamente en almacenamiento local
Limpieza: Transcripts se retienen por 30 días (configurable vía cleanupPeriodDays)

Comandos de reanudación:

claude --continue — Reanuda la última sesión exacta (mismo session ID)
claude --resume — Selector interactivo para elegir sesión
claude --fork-session — Crea nueva sesión con el historial copiado pero nuevo ID

11. Costos y Tokens

Modelo	Caso de uso	Costo (por millón de tokens)
Opus 4.6	Razonamiento complejo, decisiones arquitecturales	$5 input / $25 output
Sonnet 4.6	Mayoría de tareas de código, ejecución eficiente	$3 input / $15 output
Haiku 4.5	Tareas rápidas y ligeras	Menor costo

Optimizaciones de costo:

Prompt caching: Contenido repetido (system prompt, CLAUDE.md) se cachea a 0.1x del precio
Compactación: Previene crecimiento descontrolado del contexto
Subagentes con Haiku: Tareas de exploración usan modelos más baratos
Carga on-demand de skills: Solo se cargan cuando se invocan
/model sonnet o /model opus para cambiar modelo en caliente

12. Arquitectura Técnica Interna

Runtime: Bun
Lenguaje: TypeScript
UI Terminal: React + Ink (renderizado en terminal) + Yoga (layout engine)
Dato curioso: 90% del código de Claude Code fue escrito por versiones anteriores de Claude

Un loop maestro single-threaded simple combinado con herramientas disciplinadas y planificación entrega autonomía controlable. Esto desafía la tendencia hacia sistemas multi-agente complejos. Se enfatiza la explicabilidad y control del usuario sobre la autonomía pura.

60-100 releases internos por día
Ingenieros usan la versión interna continuamente
Feedback loop rápido del equipo usando el producto

13. Bonus: Barra de Estado para tu Claude Code

Claude Code permite configurar una barra de estado personalizada que se muestra debajo de tu instancia. Es útil para tener visibilidad permanente del contexto de tu sesión sin ejecutar ningún comando.

Así se ve:

my-project | main * +12 −3 ◙4 | Opus 4.6 | ██████████░░░░░ 62% | ⏱ 38m

Muestra: proyecto, branch git (con dirty state, líneas agregadas/eliminadas, archivos cambiados), modelo activo, barra de contexto (color amarillo < 50%, naranja 50-80%, rojo > 80%), y duración de sesión.

Copiá el siguiente prompt y pegalo directamente en Claude Code:

Prompt

Configurame un statusline para Claude Code con la siguiente información de izquierda a derecha, separada por " | " en gris: 1. Nombre del proyecto (basename del directorio actual) en cyan 2. Branch de git en cyan, con: asterisco si hay cambios sin commitear, ↑N/↓N para commits ahead/behind, +N en verde para inserciones, −N en rojo para eliminaciones, ◙N en gris para archivos cambiados 3. Nombre del modelo en naranja claro 4. Barra de contexto de 15 caracteres usando █ y ░, con colores: amarillo si < 50%, naranja si 50-80%, rojo si > 80%, seguido del porcentaje 5. Duración de la sesión en azul con ícono ⏱, formateado como Nh Nm o Nm o Ns Usá los datos disponibles en el JSON de stdin (model.display_name, context_window.used_percentage, session_id). Para la duración, guardá el timestamp de inicio en /tmp/claude-session-{session_id}. Usá --no-optional-locks en todos los comandos git.

Claude Code creará el script, lo hará ejecutable y actualizará tu settings.json automáticamente. Solo reiniciá la sesión y la barra aparece.