Context Engineering: La Nueva Ingeniería de Software (y Qué Pasa Cuando No la Haces)

Cambias de Claude a GPT y deja de funcionar

Pasa así, casi siempre.

Llevas tres meses con un agente IA en producción. Funciona razonablemente. Sale un modelo nuevo que parece mejor y más barato y decides probar la migración. Cambias el endpoint, ajustas un par de parámetros, y de pronto el agente responde distinto. Algunas cosas mejor, otras peor. Las respuestas que antes citaban fuentes ahora se las inventan. El tono se descalibra. Los casos límite que tenías bajo control vuelven a fallar.

El primer impulso es culpar al modelo nuevo. "No es tan bueno como el anterior." En realidad, casi nunca es eso. Lo que ha ocurrido es que tu agente estaba apoyándose en idiosincrasias del modelo viejo — su forma particular de interpretar instrucciones ambiguas, su tendencia a hacer ciertas asunciones por defecto — y el modelo nuevo, igual de capaz, las interpreta diferente. Cambiar de modelo no debería romper tu agente. Si lo rompe, es señal de que tu contexto estaba mal diseñado.

Esto es lo que hoy separa los proyectos de IA que aguantan de los que mueren al primer cambio de proveedor: la diferencia no la hace el modelo, la hace el contexto que el modelo recibe en cada llamada. Y el contexto no se escribe — se diseña. A esa disciplina la estamos empezando a llamar context engineering, y es la nueva capa donde se decide la calidad de la IA en producción.

Prompt engineering no es context engineering

Durante un par de años, la conversación sobre IA aplicada estuvo dominada por el prompt engineering: optimizar la frase exacta que se le manda al modelo. "Eres un experto en…", "piensa paso a paso", "responde solo en formato JSON". Eso fue útil cuando los proyectos eran simples y el contexto era una sola caja de texto. Hoy, en agentes que operan sobre sistemas reales, el prompt es solo una de las piezas que recibe el modelo, y rara vez la más importante.

El cambio de marco es este: el modelo no razona sobre tu prompt. Razona sobre todo lo que ve en cada llamada. Y lo que ve no es una frase — es un paquete compuesto por seis capas, cada una con su función, su coste y sus tradeoffs.

Diseñar bien ese paquete es lo que llamamos context engineering. Y la diferencia entre un equipo que lo hace y uno que solo "prompt-ea" es lo que separa un agente que aguanta meses en producción de uno que se rompe al primer giro.

Las seis capas del contexto

Cualquier llamada que un agente hace a un modelo está compuesta, explícita o implícitamente, por seis tipos de información:

1. System prompt. La identidad y las reglas del agente. "Eres un agente comercial que opera sobre HubSpot. Nunca cierras deals sin aprobación humana. Siempre citas la fuente de cada dato que aportas." Va al principio del prompt y no cambia entre llamadas. Es la capa más blindada — el modelo le da más peso que al resto.

2. Memoria de largo plazo. Hechos que el agente debe recordar entre sesiones, entre proyectos o entre usuarios. "Este cliente prefiere reuniones los martes a las 10. La última conversación cerró con un pendiente de envío de propuesta." No es contexto general; es contexto persistente sobre entidades concretas.

3. RAG (retrieval-augmented generation). Fragmentos de documentos recuperados según la pregunta actual. Cambia en cada llamada porque depende de qué se pregunta. Es la capa que conecta el modelo con conocimiento que no cabe en el system prompt.

4. Tools y sus respuestas. Las acciones disponibles para el agente (cada una con su contrato) y los resultados de las que ya ejecutó en la sesión actual. Si el agente acaba de consultar el CRM, el resultado de esa consulta está en el contexto cuando decide qué hacer a continuación.

5. Historial de conversación. Lo que se ha dicho hasta ahora en la sesión. Crece con cada turno. Es la capa más fácil de descontrolar — y la que más cara sale cuando se descontrola.

6. User prompt. La instrucción concreta del turno actual. La frase que dispara la siguiente respuesta. Suele ser la más pequeña en tokens y, paradójicamente, la única en la que se centra el "prompt engineering" tradicional.

Cada capa tiene su tamaño, su frecuencia de actualización, su coste por token y su impacto en el comportamiento del modelo. Diseñar bien el agente es decidir qué información vive en cada una y por qué.

Decisión 1: qué va al system prompt y qué va a RAG

Es la decisión más frecuente y la peor entendida. La regla simplificada:

• System prompt = lo que es estable, blindado y pequeño. Identidad del agente, reglas inviolables, formato esperado, lista cerrada de tools.
• RAG = lo que cambia, es grande o depende de la pregunta. Documentación operativa, catálogos, contratos, casos pasados.

El error clásico es meter en el system prompt cosas que deberían vivir en RAG. "Aquí tienes toda la política de devoluciones, todos los productos, todos los procedimientos." En el momento que esa política tiene 30 páginas, no entra. Y aunque entrara, sería un derroche: si solo el 2% de las consultas tocan la política de devoluciones, estás pagando por enviar 30 páginas en cada llamada.

El error inverso también existe: meter en RAG cosas que deberían vivir en el system prompt. "Tu identidad como agente está en este documento que se recupera por similitud." Eso es frágil — el día que un fragmento más relevante desplace la identidad, el agente se descontrola.

Una pauta operativa que aplicamos: si la información se usa en cada llamada, va al system prompt; si se usa de vez en cuando, va a RAG; si es enorme y se usa de vez en cuando, va a tool calling sobre un sistema externo.

Decisión 2: cuánto historial conservar (y cuánto cuesta no decidir)

El historial es la capa que más fácilmente se rompe en producción. Cada turno añade tokens al prompt, y el coste crece linealmente. En una conversación de 20 turnos con respuestas de 800 tokens cada una, el historial pesa más de 16K tokens — solo en historial, antes de meter RAG, tools y system prompt.

Hay tres estrategias y conviene elegir una explícitamente:

Conservar todo. Simple, caro, falla cuando la conversación supera la ventana del modelo. Solo viable en agentes con sesiones cortas y poco tráfico.

Resumir con periodicidad. Cada N turnos, el propio modelo (o uno más barato) resume los turnos anteriores en un párrafo y los originales se descartan. Reduce coste, pero pierde matices. Funciona bien cuando lo que importa son los hechos, no las formulaciones exactas.

Memoria estructurada. En lugar de conservar el texto del historial, el agente extrae los hechos relevantes y los guarda en una memoria estructurada. Lo que se pasa al modelo en cada turno no es la transcripción sino los hechos sintetizados. Más complejo de montar, pero radicalmente más barato en operación.

La decisión incorrecta — la que vemos más a menudo — es no decidir. Conservarlo todo "por si acaso" y descubrir tres meses después que la factura del LLM se ha duplicado por el peso del historial en cada llamada. La elección de qué hacer con el historial es una decisión arquitectónica, no un detalle de implementación.

Decisión 3: cuándo una tool sustituye a RAG

RAG es un buen martillo, pero no todos los datos son clavos. Hay preguntas que la búsqueda vectorial responde mal por diseño y donde la respuesta correcta no es ajustar el chunking — es no usar RAG.

Tres ejemplos donde tool calling gana a RAG:

• "¿Cuántos contratos firmamos el mes pasado?" — Tool de SQL sobre la base de datos del CRM, no recuperación de fragmentos.
• "¿Cuál es el saldo actual de la cuenta?" — Tool que llama a la API del ERP, no documento estático que podría estar desactualizado.
• "¿Cuál es la disponibilidad de este recurso?" — Tool que consulta el calendario, no fragmento sobre políticas de disponibilidad.

La regla: si la respuesta puede cambiar entre el momento del indexado y el momento de la consulta, no es trabajo de RAG. Es trabajo de tool calling sobre la fuente viva.

La forma correcta de diseñar un agente híbrido es decidir, para cada clase de pregunta, qué herramienta usar — y exponer ambas (RAG y la tool específica) al modelo con descripciones claras para que el modelo elija. "Si la pregunta es sobre cifras concretas o estado actual, usa la tool. Si es sobre conocimiento documental, usa RAG." El modelo aplica la regla, y el agente responde con la fuente correcta.

Decisión 4: memoria de largo plazo (y cuándo no la necesitas)

La memoria persistente es la capa más sobrevalorada. Casi todos los proyectos creen que la necesitan; la mayoría no la necesitan en absoluto. Antes de montarla, vale la pena hacerse tres preguntas:

1. ¿Hay multiplicidad real de usuarios o contextos? Si el agente opera en un solo proyecto con un solo conjunto de datos, la memoria "del agente" puede ser simplemente archivos en el repositorio del proyecto. No hace falta vector store.

2. ¿Qué se quiere recordar exactamente? Si la respuesta es vaga ("todo lo importante"), no hay diseño todavía. Si la respuesta es concreta ("las preferencias de comunicación de cada cliente individual"), entonces sí hay un caso de uso.

3. ¿Cuándo se consulta lo recordado? Si solo en momentos predecibles (al inicio de una conversación con un usuario conocido), es memoria de slot estructurado. Si en cualquier momento por similitud semántica, es memoria vectorial.

Cuando sí hay un caso real, lo que se guarda no es la transcripción de las conversaciones. Son hechos extraídos: "prefiere reuniones por las mañanas", "objeción habitual: precio", "último estado del proyecto: a la espera de validación legal". Esos hechos son los que se recuperan en cada llamada, no las transcripciones.

Una arquitectura de memoria mal diseñada no solo no aporta — degrada el agente, porque mete ruido en el contexto y desplaza fragmentos relevantes.

El contexto como código

Lo que separa un proyecto serio de uno improvisado es cómo se trata cada capa del contexto. La regla que aplicamos: cada capa del contexto se trata como código.

• Versionado en git, con changelog claro.
• Tests automatizados sobre comportamiento esperado (si cambias el system prompt, deben pasar los casos críticos).
• Pipeline de evals continuos sobre un dataset representativo, con alertas si la calidad cae.
• A/B testing entre versiones del system prompt o de la lógica de retrieval.
• Documentación operativa de cada capa, no solo del agente como caja negra.

Esto suena obvio cuando se enuncia. En la práctica es lo que casi ningún proyecto de IA tiene montado. La mayoría operan con un system prompt en un archivo .txt que alguien editó hace dos semanas y nadie sabe qué cambió. Sin versionado, no hay rollback. Sin evals, el equipo se entera de que algo se rompió cuando un usuario se queja. Sin A/B, los cambios de prompt son apuestas.

El cambio de modelo, en este marco, deja de ser un susto y se convierte en un ejercicio gestionado: cambias el modelo, corres los evals, miras qué casos se degradan, ajustas las capas afectadas, vuelves a correr los evals. Es ingeniería normal, no caza al fantasma.

Cómo se ve un equipo que hace context engineering de verdad

No hay un "prompt engineer" sentado al lado. Hay ingenieros — los mismos que trabajan en el backend del producto — que entienden que las capas del contexto son parte de la arquitectura y se diseñan, versionan y prueban como cualquier otro componente.

En proyectos donde aplicamos esto, hay un patrón consistente:

• El system prompt vive en un archivo system_prompt.md en el repo, con historial de cambios.
• La lógica de retrieval (qué se busca, cómo se chunkea, qué filtros se aplican) vive en código testeado, no en una llamada genérica a una librería.
• Las descripciones de tools están versionadas y se modifican con la misma fricción que el código de las propias tools.
• Hay un dataset de evals con casos reales del cliente (incluyendo los que fallaron en producción) que se ejecuta automáticamente sobre cada cambio.
• El presupuesto de tokens por capa está medido. Sabemos que en el agente X, el system prompt consume ~1.200 tokens, el RAG en media ~2.800, los tools y respuestas ~1.500, el historial ~3.500. Esa contabilidad permite decisiones de optimización con datos.

Lo más útil de este patrón: el día que cambia el modelo, el día que se actualiza un sistema integrado, el día que aparece un caso límite nuevo, el equipo sabe en qué capa actuar. No hace ingeniería al tacto; tiene los componentes mapeados.

Cómo lo construimos en producción

En proyectos de IA donde el cliente quiere algo que aguante años, dedicamos las primeras semanas a algo que aún sorprende: no a elegir el modelo ni a montar el agente. A mapear el contexto.

Listamos qué información necesita el modelo para hacer su trabajo. Decidimos, para cada pieza, en qué capa vive. Diseñamos el presupuesto de tokens por capa. Montamos el repositorio del agente con las capas separadas, versionadas y con sus tests. Solo entonces conectamos el modelo, sabiendo qué se le va a pedir y con qué.

El resultado de ese trabajo no se ve en una demo. Se ve seis meses después, cuando el cliente cambia un sistema integrado y el agente sigue funcionando porque la capa afectada era una y estaba mapeada. O cuando aparece un modelo nuevo y la migración es un cambio gestionado, no una odisea.

Detrás de cada uno de estos sistemas hay un equipo de desarrolladores que cree que la ingeniería de IA no es escribir prompts ingeniosos — es diseñar las seis capas que ese prompt ni siquiera ve. La excelencia técnica no se mide por la magia del primer prompt; se mide porque el agente aguanta dos cambios de modelo y tres cambios de proveedor de RAG sin que el negocio se entere.

Producción significa que cambiar una pieza del contexto no rompe el sistema — porque cada pieza es código, no folclore. Esa es la diferencia entre ingeniería de contexto y prompt-eo con suerte.

Si tu agente IA empieza a comportarse raro cuando cambias de modelo o cuando metes datos nuevos, no es el modelo — es que el contexto no está diseñado. Podemos auditar las seis capas, entregarte el mapa de cómo viven hoy y el plan para que dejen de depender de la suerte.