Arquitectura Context-First

La Arquitectura Context-First es un patrón estructural que trata al contexto como el artefacto de ingeniería principal en un flujo de trabajo agéntico. En lugar de depender de prompts ad-hoc y documentación dispersa, los equipos construyen un Context Index: una colección estructurada y versionada de especificaciones, estándares, ejemplos y registros históricos que los agentes consumen antes de generar cualquier código.

La idea central detrás de este patrón es que la calidad de los resultados del agente está limitada por la calidad del contexto. Un modelo capaz con un contexto deficiente produce resultados deficientes. Un modelo menos capaz con un contexto bien estructurado lo supera consistentemente. La Context Engineering es la disciplina de diseñar, mantener y entregar contexto para maximizar la efectividad del agente.

Los equipos que adoptan agentes de IA se enfrentan a un patrón de degradación predecible:

• Calidad de resultados inconsistente. La misma tarea asignada al mismo agente produce resultados diferentes en días distintos porque el contexto se proporciona de manera diferente cada vez: se mencionan archivos distintos, fraseo diferente o suposiciones que se dejan implícitas.
• Documentación dispersa. El conocimiento del proyecto reside en archivos README, páginas de wiki, hilos de Slack, comentarios de código y en la cabeza de los ingenieros. No existe una fuente única que agregue lo que un agente necesita para realizar su trabajo correctamente.
• Alucinaciones por brechas de contexto. Cuando los agentes carecen de información sobre restricciones de arquitectura, convenciones de nomenclatura o contratos de API, llenan el vacío con suposiciones plausibles pero incorrectas. Estos errores sutiles pasan la revisión inicial y aparecen como errores más tarde.
• Amnesia de sesión. Las sesiones de los agentes son efímeras. El conocimiento proporcionado en una sesión no se traslada a la siguiente. Los ingenieros pierden tiempo volviendo a suministrar el mismo contexto repetidamente.
• Fallas de escalabilidad. Lo que funciona para un desarrollador que chatea con un agente se rompe cuando un equipo ejecuta múltiples agentes en paralelo. Sin una fuente de contexto compartida, los agentes producen implementaciones en conflicto.

Construya un Context Index como la única fuente de verdad de la cual todos los agentes se alimentan. El Context Index es una estructura de directorios dentro del repositorio que organiza el contexto en categorías bien definidas. Para cada unidad de trabajo, ensamble un Context Packet (un subconjunto curado del Context Index limitado a una tarea específica) que el agente recibe junto con su Live Spec.

El rol de Context Architect es el propietario del Context Index. Esta persona (o rol combinado) es responsable de auditar, estructurar, mantener y evolucionar el contexto a lo largo del tiempo. El contexto se trata como código: se versiona, se revisa en pull requests, se prueba para detectar obsolescencia y se mide su efectividad.

Los cinco componentes de un Context Index son:

1. Colección de Live Spec — Contratos de comportamiento, criterios de aceptación y mapas de tareas para el trabajo actual y planificado
2. Constitución del Sistema — Reglas para todo el proyecto que se aplican a cada tarea: estándares de codificación, restricciones de framework, políticas de seguridad, convenciones de nomenclatura
3. Contexto de la Base de Código — Definiciones de tipos, contratos de API, registros de decisiones de arquitectura, mapas de dependencias
4. Contexto Histórico — Decisiones pasadas, enfoques obsoletos, trampas conocidas, registros de migración
5. Golden Samples — Implementaciones ejemplares que demuestran la calidad, estructura y estilo esperados