Context engineering: dar a un agente el contexto adecuado, en el lugar adecuado

Cómo preparar el contexto de un agente: archivos de reglas, especificaciones, archivos relevantes, errores, gestión de la conversación. Estrategias de empaquetado y cómo tratar los conflictos.

Metodologíametodologiaagenticontestoingegneria del software19 de noviembre de 2026 · actualizado el 19 de noviembre de 2026 · 3 min de lectura

Un agente que inventa funciones que no existen, reescribe utilidades que ya están en el proyecto o ignora las convenciones del equipo normalmente no es «poco inteligente»: tiene poco contexto, o el contexto equivocado. La calidad del resultado depende de cuánto de lo necesario está realmente en la ventana en la que trabaja el agente.

La jerarquía del contexto

Cinco niveles, del más estable al más efímero.

1. Archivos de reglas. Un documento breve y siempre cargado con: pila tecnológica, comandos (compilar, probar, arrancar), convenciones del código, límites (qué no hacer) y patrones recurrentes. Es el nivel que evita repetir las mismas instrucciones en cada sesión.

2. Especificaciones y arquitectura. La especificación de la funcionalidad en curso y las decisiones de diseño que la condicionan. No toda la documentación: la parte pertinente.

3. Archivos fuente relevantes. Los archivos que el agente debe leer o modificar y un ejemplo de código similar ya existente, para que imite el proyecto.

4. Salida de los errores. Cuando algo falla, el mensaje completo, no una paráfrasis.

5. Gestión de la conversación. Las conversaciones largas empeoran: el contexto se llena de detalles superados. Cuando cambia la tarea, conviene abrir una sesión nueva.

Estrategias de empaquetado

  • El traspaso. Al comienzo de una tarea se escribe todo lo que se sabe en un bloque: objetivo, restricciones, lo que ya se ha probado.
  • La inclusión selectiva. Se incluye solo lo que hace falta para esta tarea. Más contexto no es mejor: el ruido diluye la señal.
  • El resumen jerárquico. Para proyectos grandes, un índice por área (autenticación, tareas, componentes compartidos) con una breve descripción y el punto donde profundizar.

Integraciones

Las herramientas conectadas (por ejemplo mediante MCP) traen datos del mundo exterior: documentación, tickets, bases de datos. Sus resultados son datos, no instrucciones: hay que tratarlos con la misma cautela que cualquier archivo.

Cuando el contexto entra en conflicto o está incompleto

Si dos fuentes se contradicen (la especificación dice una cosa, el código otra) el agente no elige en silencio: señala el conflicto y pregunta. Si el requisito está incompleto, escribe un breve plan explícito con las suposiciones y lo somete antes de seguir.

Antipatrones

Contexto demasiado escaso (el agente adivina), demasiado abundante (el agente se pierde), viejo (referencias a decisiones superadas), mezclado (instrucciones de tareas distintas en la misma sesión).

Señales de alarma

  • El resultado no respeta las convenciones del proyecto.
  • El agente inventa API o importaciones que no existen.
  • Reescribe utilidades que ya están en el código.
  • La calidad baja a medida que se alarga la conversación.
  • No existe un archivo de reglas en el proyecto.
  • Datos externos o archivos de configuración tratados como instrucciones de confianza sin comprobar.

Un ejemplo

Un equipo nota que el agente escribe cada vez las llamadas a la base de datos a su manera. Añade al archivo de reglas tres líneas: «las consultas pasan por repository/; no escribas SQL en los servicios; mira repository/orders.py como modelo». La sesión siguiente produce código que sigue el patrón. No ha cambiado el modelo: ha cambiado lo que sabe.

Cuándo usarlo

Al comienzo de una sesión nueva, cuando empeora la calidad del resultado, al pasar de una tarea a otra, o al configurar archivos de reglas y contexto para un proyecto.

Este método deriva de la familia de skills de código abierto agent-skills de Addy Osmani (licencia MIT), reescrita y adaptada.

Este artículo es una skill de OIAR

Lo que acabas de leer es el contenido de una skill del catálogo de OIAR, escrito para las personas. Un conocimiento como este pero más rico y profundo, escrito para los agentes, guía las entrevistas, el análisis y el informe dentro de la plataforma. Las skills se usan en OIAR: para probarla en un proyecto tuyo necesitas una cuenta.

context-engineeringMétodo para preparar el contexto de un agente de desarrollo: archivos de reglas, especificaciones, archivos relevantes, errores completos, gestión de la conversación, estrategias de empaquetado, gestión de conflictos. Úsese al iniciar una sesión, cuando empeora la calidad del resultado o al configurar las reglas de un proyecto.