Análisis técnico del contexto en IA generativa y agéntica: el contexto no es longitud de prompt sino capas diferenciadas por vida útil y nivel de confianza. Cubre la distinción entre datos de referencia y directivas, el riesgo de inyección de prompts desde material recuperado, por qué la recuperación debe degradarse sin bloquear, y la disciplina de contexto en análisis de datos. Documenta cómo DevSpeak inyecta cuatro capas de contexto —grounding de proyecto, instrucciones de cuenta, contexto de workspace y memoria del usuario— en la Etapa 2 de traducción y la Etapa 3 de refinamiento.
El contexto no es un prompt más largo
Un agente que ignora tu instrucción normalmente no está confundido. Está obedeciendo otra cosa que también pusiste en el prompt, y nunca decidiste cuál de las dos debía ganar.
El contexto es un conjunto de capas, no un campo
La palabra "contexto" carga con demasiado. En la mayoría de las discusiones significa el texto que pegaste encima de la pregunta. En un sistema que ejecuta la misma operación diez mil veces para usuarios distintos, se separa en al menos cuatro cosas que no se comportan igual:
Preferencias a nivel de cuenta. Cómo escribe este usuario, siempre. Terminología que prefiere, convenciones que mantiene. Cambia poco, aplica a cada petición, y es la instrucción permanente del propio usuario al sistema.
Grounding a nivel de proyecto. Los sistemas nombrados, el vocabulario interno, las restricciones arquitectónicas de un cuerpo de trabajo. Estable durante semanas, acotado a un subconjunto de peticiones, y escrito en buena parte por alguien distinto de quien está escribiendo ahora.
Contexto de tarea, a nivel de petición. Lo que se pide, ahora, con estos adjuntos. Vive una sola llamada.
Material recuperado. Lo que un conector, un índice de búsqueda o un almacén vectorial devolvió hace unos cientos de milisegundos. No lo escribió nadie de la conversación, no está verificado y —esto es lo importante— no es de fiar.
Estas cuatro tienen vidas útiles distintas, dueños distintos y niveles de confianza distintos. Un diseño que las concatena en una sola cadena ha descartado todas esas distinciones antes de que el modelo vea un solo token.
Datos de referencia y directivas no son la misma entrada
Este es el fallo que enseña la lección más rápido. Un usuario crea un proyecto y escribe una instrucción a nivel de proyecto: _escribe en español_. Razonable. Después lanza una petición que especifica un formato de salida "API Design".
Si la instrucción del proyecto se inyecta como texto plano junto a los parámetros de la petición, el modelo tiene dos imperativos y ningún orden. A veces produce un diseño de API en español. A veces produce algo que está en español y ya no es un diseño de API. El comportamiento no es determinista porque el prompt nunca dijo qué instrucción era estructural y cuál estilística.
La solución es el encuadre, no el filtrado. El material recuperado y el acotado a un proyecto tienen que entrar al prompt claramente delimitados y etiquetados explícitamente como datos de referencia: algo en lo que apoyar la terminología, los sistemas nombrados y las restricciones, sin ninguna autoridad sobre el formato de salida ni sobre la estructura de documento requerida.
Esa última cláusula es todo lo que sostiene la estructura. Sin ella la capa es una directiva; con ella la capa es evidencia. Los mismos bytes, otra semántica.
Esto se generaliza más allá de un producto. Cualquier agente que lea una página web, un archivo de un repositorio o una fila de una base de datos está ingiriendo texto escrito por alguien que no es el principal. Si ese texto puede emitir instrucciones, tienes una superficie de inyección de prompts, y la mitigación es arquitectónica: el contenido recuperado se delimita, se etiqueta como inerte y se le niega explícitamente autoridad sobre los parámetros estructurales de la operación.
La memoria del usuario exige aplicar el mismo principio con más rigor: una preferencia almacenada es un dato sobre el usuario, y nada de lo que se escriba en ella debería poder cambiar cómo se lee el resto de la petición.
La recuperación es un presupuesto de latencia, no un problema de búsqueda
La literatura sobre RAG trata casi siempre de relevancia. En producción la restricción más dura es el tiempo.
Ensamblar contexto significa llamadas de red: una consulta de documentación, una búsqueda en un repositorio, una consulta web. Cada una puede ser lenta y cada una puede colgarse. Tres decisiones determinan si la función es usable:
Cada fetch se resuelve de forma independiente. Un conector que falla no puede bloquear la petición. Ejecútalos en paralelo, toma lo que resuelva, descarta lo que rechace. Una respuesta parcialmente fundamentada es mejor que un timeout.
La recuperación falla en abierto. Un ID de proyecto desconocido, una cuenta sin derecho, un error de recuperación: todos degradan a una generación sin grounding en lugar de a una respuesta de error. El contexto es un enriquecimiento. Un sistema que devuelve 500 porque falló su capa opcional ha clasificado mal ese enriquecimiento como dependencia.
Algunos llamadores no pueden permitirse la red. Si el presupuesto de tiempo de una operación no tolera una recuperación lenta, omite la recuperación en vivo y fundaméntala en material que ya está almacenado. Recuperar contexto que la llamada no tendrá tiempo de usar solo hace que incumpla su propio plazo.
La sutileza está en la caché. La salida de un conector varía con la entrada, así que la clave de caché tiene que incluir la consulta; si no, la segunda petición de un proyecto recibe grounding recuperado para otra distinta. Cualquier flag que cambie qué fuentes se consultan también pertenece a la clave. Una clave que omita el interruptor de búsqueda web servirá alegremente un bloque cacheado con resultados web a una petición que la desactivó explícitamente.
La misma disciplina aparece en el trabajo con datos
Quien haya pedido a un modelo que interprete el resultado de una consulta ha chocado con esto desde el otro lado. Los números son correctos y la interpretación es errónea, porque al modelo se le dio una tabla y no los tres hechos que hacen que la tabla signifique algo: a qué están filtradas las filas, en qué unidades está la columna y qué representa un nulo.
Una columna de ingresos que excluye silenciosamente los reembolsos no son datos incorrectos. Son datos cuyo contexto vive en una transformación que el modelo nunca vio. El modelo producirá un resumen seguro, fluido e incorrecto: el peor modo de fallo posible, porque nada en la salida señala el hueco.
La ingeniería de contexto en el trabajo analítico es la misma disciplina con otro nombre: declara los filtros, declara las unidades, declara la semántica de los nulos y marca lo que es derivado. Cada una de esas cosas es una restricción que el autor tiene en la cabeza y el artefacto no transporta, que es [el mismo modo de fallo que hunde las especificaciones técnicas](/blog/why-technical-specs-fail).
Cómo DevSpeak inyecta contexto en las Etapas 2 y 3
El pipeline de DevSpeak tiene tres etapas. La Etapa 1 —optimización léxica— queda deliberadamente fuera de todo esto. Trabaja solo con el texto de entrada y su calibración de tono: no intervienen proyectos, instrucciones ni memoria. Pulir la gramática de alguien no debería depender de qué repositorio tenga conectado. El trabajo interesante está en las Etapas 2 y 3.
Etapa 2 — POST /api/v1/translate — ensambla cuatro capas de contexto independientes alrededor de la petición:
`` { "input": "we need users to be able to undo a delete", "audience": "SRE", "context": "Backend", "format": "Technical Spec", "tone": 75, "contextProjectId": "proj_a1b2c3", "customInstructions": "Prefer OpenTelemetry over vendor SDKs.", "webSearch": false, }jsonc
`
contextProjectId resuelve un Context Project —sus instrucciones, sus activos ingeridos y sus conectores habilitados— en un único bloque de grounding. Los Context Projects están disponibles desde el plan VIBECODER, con un techo de 3 proyectos y 25 activos cada uno en ese nivel, y 25 proyectos y 100 activos cada uno en DEVELOPER. customInstructions superpone las preferencias de cuenta, resolviéndose desde el perfil almacenado cuando el campo no viene, de modo que los clientes de CLI y MCP quedan a la par de la aplicación web. workspaceContext añade una tercera capa: lo que el cliente que llama ya tiene delante —la estructura del workspace que envía una extensión del editor—, separada del bloque de grounding del proyecto. La memoria del usuario añade una cuarta capa; la memoria está disponible desde el plan VIBECODER, con un tope de 10 tarjetas en ese nivel.
Las cuatro están subordinadas a una regla: el formato de salida que eliges es vinculante, y nada —ni las instrucciones personalizadas, ni el contexto de workspace, ni la memoria, ni la propia entrada— cambia el tipo de documento.
Etapa 3 — POST /api/v1/refine — reensambla las mismas cuatro capas alrededor de un objetivo distinto. La Etapa 2 transforma una entrada; la Etapa 3 revisa una salida.
`jsonc
{
"previousOutput": "## Soft Delete Specification\n\n### Overview…",
"feedback": "Add a rollback section and drop the migration notes.",
"originalInput": "we need users to be able to undo a delete",
"audience": "SRE",
"context": "Backend",
"format": "Technical Spec",
"tone": 75,
"contextProjectId": "proj_a1b2c3",
}
``
Aquí hay un detalle fácil de equivocar. La Etapa 2 indexa su recuperación de contexto sobre el texto de entrada; la Etapa 3 lo hace sobre el feedback, no sobre la salida previa. El feedback es aquello sobre lo que el usuario quiere saber más, así que es la consulta de recuperación correcta: un documento previo de 50.000 caracteres devolvería grounding relevante para las partes que nadie pidió cambiar.
El refinamiento consume una cuota por periodo. Está disponible desde el plan VIBECODER, con 25 refinamientos por periodo en ese nivel y 100 en DEVELOPER. Solo el endpoint de traducción mide además a los clientes externos con clave de API: GRATIS y VIBECODER tienen 50 solicitudes a la API al mes con el modelo predeterminado y DEVELOPER y superiores no tienen límite; el refinamiento solo requiere un plan que incluya refinamiento.
Lo que vale la pena conservar
Casi nada de esto trata de la calidad de la recuperación. Trata de decidir, antes de que ningún texto llegue al modelo, qué capa puede sobrescribir a cuál, y después codificar esa decisión en la estructura del prompt en lugar de confiar en que el modelo lo infiera.
El contexto que llega etiquetado, presupuestado y jerarquizado produce un comportamiento predecible. El contexto que llega concatenado produce un sistema que funciona en la demo y deriva en producción, y esa deriva es casi imposible de atribuir porque, cuando llega al modelo, cada capa se parece a todas las demás.