← Todos los articulos

La ingeniería de contexto es arquitectura: 650 archivos después

12 min de lectura

Mi CLAUDE.md comenzó con 50 líneas. Seis meses después, había crecido hasta convertirse en una arquitectura distribuida de 650 archivos a lo largo de siete capas. La evolución reveló que la ingeniería de contexto no es ingeniería de prompts con más archivos. Es arquitectura de software para un sustrato donde la memoria se degrada con cada token.

El contexto no es un archivo de configuración. Es el sustrato arquitectónico que determina lo que un agente de IA puede pensar, lo que recuerda y lo que olvida. Todas las demás decisiones de diseño dependen del contexto. Lo que sigue son seis meses de ingeniería de contexto en producción para Claude Code: la arquitectura, los fallos y el sistema que los sobrevivió.

Resumen

El artículo de Böckeler sobre ingeniería de contexto (martinfowler.com, 2026)1 y el marco de pensamiento claro de Miessler2 avanzan la conversación, pero ambos subestiman lo que el uso en producción exige. La ingeniería de contexto requiere diseñar un sistema donde las instrucciones correctas lleguen al agente en el momento correcto, y las instrucciones incorrectas nunca se carguen. Mi sistema utiliza nueve reglas, 40 skills, 19 agentes, 84 hooks y 14 archivos de configuración distribuidos en una jerarquía de siete capas. La arquitectura no reside en los archivos en sí, sino en qué archivos se cargan cuándo y qué se excluye.

El contexto no es un archivo

La publicación semanal de “cómo escribir un CLAUDE.md” no capta lo esencial. Escribir un buen CLAUDE.md es necesario pero insuficiente, de la misma manera que escribir buen código es necesario pero insuficiente para construir un buen sistema. La arquitectura es la estructura que determina cómo interactúan los componentes. En los sistemas de agentes, el contexto es esa estructura.

Mi primer CLAUDE.md era un monolito: 200 líneas que cubrían estándares de código, estructura de proyecto, preferencias, correcciones, filosofía, credenciales y estado activo del proyecto. Funcionó durante un mes. Luego ocurrieron tres cosas simultáneamente:

  1. El archivo superó las 300 líneas y comenzó a contradecirse (la regla A decía “mantenlo simple”, la regla B decía “agrega manejo exhaustivo de errores”)
  2. El contexto del proyecto A se filtraba al proyecto B (reglas específicas de iOS contaminaban una sesión de desarrollo web)
  3. El agente gastaba tokens leyendo instrucciones irrelevantes para la tarea actual

Los síntomas apuntan a problemas arquitectónicos, no de documentación: acoplamiento, fuga de alcance y desperdicio de recursos. Las mismas fuerzas impulsan las decisiones de arquitectura de software.3

Las siete capas

Después de seis meses de refactorización, mi sistema de contexto se estabilizó en una jerarquía de siete capas. Cada capa cumple un propósito distinto y se carga en un momento específico:

Capa Contenido Cuándo se carga Cantidad
1. Núcleo CLAUDE.md: filosofía, proyectos activos, correcciones Al inicio de cada sesión Un archivo, 205 líneas
2. Reglas Restricciones específicas de dominio (diseño de API, seguridad, testing, git) Al inicio de cada sesión Nueve archivos
3. Skills Módulos de conocimiento reutilizables con procedimientos y ejemplos Bajo demanda (invocados o auto-activados por hooks) 40 directorios
4. Agentes Especificaciones de revisores/generadores especializados Bajo demanda (mediante la herramienta Task) 19 archivos
5. Hooks Inyección automática de contexto en eventos del ciclo de vida Basado en eventos (inicio de sesión, pre-commit, post-tool) 84 scripts
6. Config Parámetros numéricos (umbrales, presupuestos, límites) Referenciados por hooks y skills 14 archivos JSON
7. Estado Seguimiento en vivo (linaje de agentes, calibración de confianza, costos) Referenciado por hooks 36 archivos

La idea clave es la separación de capas. Las reglas se cargan en cada sesión porque se aplican universalmente. Los skills se cargan bajo demanda porque son específicos de dominio. Los hooks se disparan ante eventos porque el momento importa. Cargar los 650 archivos al inicio de la sesión agotaría la ventana de contexto antes de que el agente leyera el primer mensaje del usuario.4

Tres fallos que moldearon la arquitectura

Fallo 1: El CLAUDE.md monolítico

Mi CLAUDE.md original contenía reglas de iOS, reglas web, patrones de diseño de API, convenciones de git, gestión de credenciales y principios filosóficos, todo en un solo archivo. El agente leía todo en cada sesión, incluso cuando construía un proyecto web que nunca tocaría SwiftUI.

El costo: El contexto irrelevante consumía aproximadamente 4.000 tokens por sesión. En 50 sesiones, eso suma 200.000 tokens gastados en instrucciones que el agente nunca utilizó.

La solución: Extraer el contenido específico de dominio a archivos en rules/. rules/security.md se carga en cada sesión (la seguridad aplica en todas partes). rules/ios-security.md se carga solo cuando la sesión involucra proyectos de iOS. La publicación sobre gestión de la ventana de contexto documenta la economía de tokens que impulsó esta decisión.

Fallo 2: Skills que quedaron obsoletos

Creé un skill de fastapi con ejemplos de FastAPI 0.109. Tres meses después, el proyecto usaba FastAPI 0.115 con patrones diferentes. El skill enseñaba silenciosamente convenciones obsoletas. El agente producía código funcional que no coincidía con el código base actual.

El costo: Una sesión de depuración de 45 minutos rastreando por qué un nuevo endpoint usaba un patrón de inyección de dependencias diferente al de todos los demás endpoints. El patrón provenía del skill obsoleto, no del código base.

La solución: Los skills referencian documentación versionada e incluyen fechas de “última verificación”. Más importante aún, el ciclo de calidad exige que el código generado coincida con los patrones existentes del código base: una verificación metacognitiva que detecta la deriva de skills obsoletos independientemente del contenido del skill.

Fallo 3: Reglas contradictorias en diferentes capas

CLAUDE.md decía “preferir soluciones simples”. Un skill decía “agregar manejo exhaustivo de errores con lógica de reintentos y circuit breakers”. Ambos eran razonables de forma aislada. Juntos, producían salidas inconsistentes (a veces minimalistas, a veces sobrediseñadas) dependiendo de qué instrucción el agente ponderaba más en un turno dado.

El costo: Calidad de salida impredecible. El mismo tipo de tarea producía diferentes niveles de calidad entre sesiones, haciendo el sistema poco confiable.

La solución: Establecer una jerarquía de precedencia clara. CLAUDE.md define principios (“preferir la simplicidad”). Las reglas definen restricciones (“validar toda entrada del usuario”). Los skills definen procedimientos (“así se construye un endpoint en FastAPI”). Cuando entran en conflicto, la capa más específica gana: el procedimiento de un skill anula la guía de un principio para la tarea específica que el skill cubre. La resolución refleja cómo los lenguajes de programación manejan el alcance: lo local anula lo global.5

El presupuesto de contexto como restricción arquitectónica

La ventana de contexto no es infinita. Los 200K tokens de la ventana de contexto de Claude6 parecen muchos hasta que se mide qué los consume:

Consumidor Tokens típicos % de la ventana
System prompt + CLAUDE.md + reglas 8.000-12.000 4-6%
Historial de conversación 20.000-80.000 10-40%
Lecturas de archivos (por archivo) 5.000-20.000 2,5-10%
Salidas de herramientas (por llamada) 1.000-10.000 0,5-5%
Contexto de skill/agente (bajo demanda) 3.000-15.000 1,5-7,5%

Las mediciones de consumo de tokens provienen de 50 sesiones de Claude Code que registré entre agosto de 2025 y febrero de 2026.7 Una sesión intensiva de 90 minutos puede agotar la ventana mediante lecturas de archivos e interacciones con herramientas normales. El presupuesto de contexto impone compromisos arquitectónicos:

Cargar siempre la filosofía central, las correcciones activas y las reglas de seguridad. Las tres son baratas (4-6% del presupuesto) y universalmente aplicables.

Cargar bajo demanda skills, especificaciones de agentes y documentación de referencia. Cada uno cuesta entre 5-15% de la ventana por skill y aplica a un solo dominio. Cargarlos solo cuando son relevantes preserva presupuesto para el trabajo real.

Nunca cargar documentos de traspaso obsoletos, configuraciones deprecadas o estado histórico. Cada archivo obsoleto consume presupuesto sin mejorar la salida. El patrón de ingeniería compuesta requiere una poda periódica del contexto que ya no justifica su costo en tokens.

La gestión del presupuesto de contexto refleja el mismo compromiso que impulsa la indexación de bases de datos, las estrategias de caché y la gestión de memoria en el software tradicional.8 La restricción difiere (tokens en lugar de bytes), pero la disciplina arquitectónica es idéntica.

Propagación de contexto en sistemas multi-agente

Cuando el agente principal genera un subagente mediante la herramienta Task, decidir qué contexto propagar determina todas las demás decisiones de diseño. Mi sistema de deliberación multi-agente utiliza 10 agentes de investigación. Cada agente necesita suficiente contexto para evaluar de forma independiente, pero demasiado contexto compartido causa el problema de convergencia documentado en la publicación sobre boids: agentes que comparten demasiado contexto producen conclusiones idénticas.

Las reglas de propagación:

Tipo de contexto ¿Se propaga? ¿Por qué?
Filosofía central Sí Consistencia entre agentes
Reglas de dominio Sí Estándares de calidad compartidos
Instrucciones específicas de tarea Sí El trabajo real
Historial de conversación No La independencia requiere aislamiento
Hallazgos de otros agentes No (hasta la síntesis) Previene convergencia prematura
Procedimientos de skills Selectivamente Solo skills relevantes para el rol del agente

La arquitectura Ralph resuelve un problema relacionado: la propagación de contexto a través del tiempo (iteraciones), no a través de agentes (procesos paralelos). Ambos comparten el mismo principio: propagar restricciones y principios, aislar detalles de implementación.

Medir la calidad del contexto

El conteo de tokens es una métrica proxy. La verdadera medida de la calidad del contexto es: ¿produce el agente la salida correcta en el primer intento?

Después de rastrear 50 sesiones, identifiqué tres señales de calidad:

Tasa de éxito en el primer intento. ¿Con qué frecuencia la primera respuesta del agente no requiere corrección? Con el CLAUDE.md monolítico, la tasa era aproximadamente del 60%. Después de la arquitectura de siete capas, subió a aproximadamente el 80%. La mejora provino de eliminar contexto irrelevante (menos distracciones) y agregar skills específicos de dominio (conocimiento más relevante).9

Tipo de corrección. Cuando el agente requiere corrección, ¿el error es factual (API incorrecta, patrón incorrecto) o de criterio (enfoque equivocado, prioridad equivocada)? Los errores factuales indican contexto faltante. Los errores de criterio indican contexto contradictorio o ambiguo. Rastrear los tipos de corrección revela qué capa necesita atención.

Presión de contexto al completar la tarea. ¿Cuánto presupuesto de contexto queda cuando la tarea termina? Si la ventana está al 90% antes de que la tarea esté a la mitad, la arquitectura de contexto está cargando demasiado material irrelevante. Mi sistema de hooks incluye un monitor de presión de contexto que alerta cuando la utilización supera el 70%.

El patrón de arquitectura distribuida

Nada en el sistema de siete capas es exclusivo de los agentes de IA. Refleja patrones de software establecidos:

Patrón de software Equivalente de contexto
Variables de entorno CLAUDE.md central (siempre cargado, global)
Archivos de configuración Reglas (cargadas al inicio, específicas de dominio)
Bibliotecas/módulos Skills (cargados bajo demanda, autocontenidos)
Microservicios Agentes (aislados, comunicándose mediante protocolos)
Manejadores de eventos Hooks (disparados por eventos del ciclo de vida)
Base de datos Archivos de estado (persistentes, consultables)
Contratos de API Esquemas de configuración (parámetros numéricos compartidos)

El paralelo no es metafórico. Las mismas fuerzas (acoplamiento, cohesión, alcance, ciclo de vida) impulsan decisiones arquitectónicas idénticas.10 La ingeniería de contexto es ingeniería de software para un sustrato donde la “memoria” es un recurso escaso y degradable en lugar de uno abundante y persistente.11

Conclusiones clave

Para ingenieros que construyen sistemas de agentes:

  • Diseñe el contexto como arquitectura de software, no como documentación. Qué se carga cuándo, qué anula qué y qué se propaga a los subagentes determina el comportamiento del agente más que cualquier instrucción individual. Aplique la misma disciplina de separación de responsabilidades que utiliza para el código.

  • Separe las capas por ciclo de vida. Las reglas universales se cargan en cada sesión. El conocimiento específico de dominio se carga bajo demanda. El estado por sesión permanece transitorio. Mezclar ciclos de vida en un solo archivo crea los problemas de acoplamiento que la arquitectura de software existe para resolver.

Para equipos que escalan flujos de trabajo con IA:

  • Trate la ventana de contexto como un presupuesto. Los system prompts, las lecturas de archivos y las salidas de herramientas consumen la ventana de 200K tokens. Cada instrucción persistente compite con la memoria de trabajo. Mida lo que carga y elimine lo que no justifica sus tokens.

  • Las reglas de propagación determinan la calidad multi-agente. Los subagentes necesitan principios compartidos para la consistencia y estado aislado para la independencia. Propagar demasiado contexto causa convergencia. Propagar muy poco causa incoherencia.

Esta publicación se basa en Gestión de la ventana de contexto (economía de tokens) y El sistema Ralph (memoria del sistema de archivos). El sistema de hooks de Claude Code implementa la capa de automatización. Para patrones de coordinación de agentes, consulte Deliberación multi-agente y De boids a agentes.

  1. Birgitta Böckeler, “Context Engineering for Coding Agents,” martinfowler.com, febrero de 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. La colega de Böckeler, Bharani Subramaniam, define la ingeniería de contexto como “curar lo que el modelo ve para obtener un mejor resultado”. La definición es correcta. La presente publicación argumenta que la estructura de cómo esa información se organiza y entrega es una disciplina arquitectónica, no un ejercicio de documentación. ↩

  2. Daniel Miessler, “How to Talk to AI,” danielmiessler.com, junio de 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler argumenta que la verdadera habilidad subyacente tanto a la ingeniería de prompts como a la ingeniería de contexto es el pensamiento claro: la capacidad de articular exactamente lo que se desea lograr. El enfoque complementa la presente publicación, que se centra en la disciplina estructural de organizar el contexto en lugar de pensar claramente sobre él. ↩

  3. El paralelo con la arquitectura de software es deliberado. Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017. Martin identifica las mismas fuerzas: acoplamiento, cohesión y separación de responsabilidades. La diferencia en los sistemas de contexto de IA es que la “memoria” es efímera y limitada, lo que agrega una restricción que la arquitectura tradicional no enfrenta. ↩

  4. El conteo de 650 archivos es la medición del autor a febrero de 2026. Contexto global: ~400 archivos (reglas, skills, agentes, hooks, configuraciones, estado, documentos, traspasos). Contexto específico del proyecto (blakecrosley.com): ~250 archivos (PRDs, documentos, planes, flujos de trabajo, configuraciones de i18n). Solo una fracción se carga por sesión. ↩

  5. La resolución de alcance de variables en lenguajes de programación (local, envolvente, global, incorporado) es la analogía directa. La regla LEGB de Python define la misma jerarquía: alcance local, alcance de función envolvente, alcance global, alcance incorporado. Véase Python Software Foundation, “Execution Model,” sección 4.2.2, “Resolution of names.” docs.python.org/3/reference/executionmodel.html. Los skills (alcance local) anulan las reglas (alcance de módulo), que anulan el CLAUDE.md (alcance global). La analogía se quiebra ligeramente porque el seguimiento de instrucciones de los LLM es probabilístico, no determinista, pero el principio arquitectónico se mantiene. ↩

  6. Anthropic, “Models overview,” platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. Todos los modelos actuales de Claude (Opus 4.6, Sonnet 4.6, Haiku 4.5) especifican una ventana de contexto de 200K tokens, con Opus 4.6 y Sonnet 4.6 soportando 1M de tokens en beta. ↩

  7. Mediciones de consumo de tokens de 50 sesiones de Claude Code que registré entre agosto de 2025 y febrero de 2026. Consulte Gestión de la ventana de contexto para la metodología completa. ↩

  8. La analogía entre presupuestos de tokens y jerarquías de memoria sigue el marco de Hennessy, J.L. y Patterson, D.A., Computer Architecture: A Quantitative Approach, 6.ª edición, Morgan Kaufmann, 2017. El tratamiento de Hennessy y Patterson sobre jerarquías de caché, localidad de referencia y el costo de acceso a memoria en diferentes niveles se mapea directamente a la ingeniería de contexto: el contexto necesario con frecuencia (caché L1 / reglas centrales) se carga más rápido, mientras que el contexto raramente necesario (disco / skills bajo demanda) se carga solo cuando se referencia. ↩

  9. La tasa de éxito en el primer intento es una métrica aproximada basada en la evaluación subjetiva del autor sobre si la primera respuesta requirió corrección. No es un experimento controlado. La mejora direccional (60% a 80%) es consistente entre tipos de sesión, pero no debe citarse como una medición precisa. ↩

  10. James Lewis y Martin Fowler, “Microservices,” martinfowler.com, marzo de 2014. martinfowler.com/articles/microservices.html. Lewis y Fowler definen los microservicios como “un conjunto de servicios pequeños, cada uno ejecutándose en su propio proceso y comunicándose mediante mecanismos ligeros”. Las fuerzas que identifican (despliegue independiente, gobernanza descentralizada, contextos delimitados) se mapean directamente al aislamiento de agentes y la comunicación basada en protocolos en la arquitectura de contexto descrita aquí. ↩

  11. El enfoque de “contexto como arquitectura” se inspira en Xu et al., “Everything is Context: Agentic File System Abstraction for Context Engineering,” arXiv, diciembre de 2025. arxiv.org/abs/2512.05470. El artículo propone una abstracción de sistema de archivos para gestionar el contexto en sistemas de IA generativa, tratando diversos artefactos de conocimiento, memoria y herramientas como contexto dentro de restricciones de tokens. El marco teórico respalda la arquitectura práctica descrita aquí. ↩