Contexto para agentes de código: qué documentar y cómo probarlo

El 6 de abril de 2026, Meta explicó cómo convirtió parte del conocimiento tácito de sus ingenieros en un mapa para agentes de programación. El caso importa más allá de Meta porque plantea una pregunta que cualquier equipo puede comprobar: cuando un asistente recibe instrucciones sobre un repositorio, ¿está obteniendo una brújula útil o una carga de texto que lo vuelve más caro y menos preciso? La respuesta no se deduce del número de documentos. Exige distinguir qué contexto falta, limitar dónde se aplica y comparar resultados con y sin él.

El sistema descrito en la fuente primaria de Meta Engineering cubría un pipeline interno distribuido entre cuatro repositorios, tres lenguajes y más de 4.100 archivos. Incorporar un campo de datos podía afectar registros de configuración, enrutamiento, composición de grafos, validación y generación de código. Un agente encontraba funciones y producía cambios que compilaban, pero no conocía relaciones que para los mantenedores eran obvias. Ese es el problema exacto que el mapa intentaba resolver: no enseñar sintaxis, sino hacer visible información operacional que el código por sí solo no expresaba.

Primero, identificar el conocimiento que realmente falta

Meta no pidió a un modelo que escribiera una enciclopedia del repositorio. Repartió el análisis entre más de 50 tareas especializadas —exploración, análisis de módulos, redacción, crítica, corrección y pruebas de prompts— y produjo 59 archivos de contexto. Cada archivo quedó en unas 25 a 35 líneas, alrededor de 1.000 tokens, con comandos rápidos, archivos clave, patrones poco evidentes y referencias a otras zonas del sistema. También creó un índice de dependencias entre repositorios y programó actualizaciones periódicas.

La unidad útil no es, por tanto, el resumen general, sino la decisión que un agente no podría inferir con seguridad. Puede ser una compatibilidad de serialización que impide borrar un valor obsoleto, dos nombres distintos para la misma operación o un campo temporal que cambia de identidad más adelante. Meta dice haber recuperado más de 50 patrones de ese tipo. Son ejemplos de conocimiento negativo: explican qué camino plausible no debe seguirse y por qué.

Un archivo de contexto mantenible puede registrar cada regla con seis piezas: alcance, motivo, archivos afectados, comprobación ejecutable, responsable y fecha o versión de la última verificación. «No borres este valor» es una prohibición frágil. «No lo borres porque los mensajes guardados aún lo serializan; ejecuta esta prueba de compatibilidad; afecta a estos dos módulos» ofrece evidencia y una salida verificable. Si la restricción puede expresarse como una prueba, un tipo o un validador, esa protección determinista debe acompañar a la explicación: el texto orienta, pero no sustituye al control.

Una brújula tiene que seleccionar, no inundar

La concisión no es una virtud estética. Cada instrucción compite por atención con el problema, el código y los resultados de las herramientas. Una guía global debería limitarse a convenciones realmente transversales; las instrucciones específicas deben vivir cerca del módulo al que afectan y cargarse solo cuando la tarea entra en ese ámbito. Separar navegación, reglas estables y estado temporal también facilita detectar qué ha caducado. Una ruta de entrada puede cambiar mañana; una razón arquitectónica quizá dure años.

Otra experiencia de Meta sobre clasificación de activos con IA formula el mismo principio en un contexto distinto: más contexto no es automáticamente mejor. Su propuesta consiste en preparar un informe de evidencias compacto, conservar tanto señales favorables como contradictorias y registrar su procedencia. También separa las etiquetas revisadas por personas de las recomendaciones generadas. Trasladado al código, esto significa que una instrucción no debería borrar la incertidumbre: debe indicar de dónde procede, qué contradicciones existen y qué decisión sigue requiriendo aprobación humana.

Ese diseño protege contra dos fallos. El primero es la autoridad accidental: una frase generada acaba tratándose como política del proyecto. El segundo es la obsolescencia: un archivo correcto el día de su creación sigue cargándose meses después, aunque las rutas o invariantes hayan cambiado. Verificar que los archivos citados existen evita enlaces internos rotos, pero no demuestra que la regla continúe siendo verdadera. Para eso hacen falta responsables, versiones, señales de deriva y una revisión cuando cambien las dependencias.

Medir eficiencia no equivale a medir corrección

Meta informa de una prueba preliminar con seis tareas en la que el contexto redujo aproximadamente un 40% las llamadas a herramientas y los tokens por tarea. También dice que evaluó más de 55 prompts, que el conjunto central alcanzó una tasa de paso del 100% y que la crítica elevó una puntuación interna de 3,65 a 4,20 sobre 5. Son datos del fabricante sobre su propio sistema. No constituyen un benchmark externo, y seis tareas no permiten concluir que la técnica mejore cualquier repositorio. Sobre todo, gastar menos tokens muestra eficiencia; no prueba por sí mismo que el cambio final sea correcto.

El contrapunto es el estudio primario sobre archivos AGENTS.md, actualizado el 23 de junio de 2026. Sus autores probaron cuatro configuraciones de modelo y agente en 300 tareas de SWE-bench Lite y en CTXBENCH, un conjunto de 138 tareas procedentes de doce repositorios de Python recientes o menos conocidos. Los archivos generados por modelos no produjeron una mejora estadísticamente significativa en la resolución: el promedio varió en torno a -0,5% y -2% según el banco, mientras el coste aumentó aproximadamente un 20% y un 23%. Los archivos escritos por desarrolladores rindieron mejor que los generados, pero su ventaja media sobre no usar archivo tampoco fue estadísticamente concluyente y también elevaron el coste.

El paper observa que los agentes sí seguían las instrucciones: exploraban y probaban más. El problema era que los resúmenes generales no les ayudaban necesariamente a encontrar antes los archivos relevantes. Sus límites también importan. Evalúa repositorios de Python, cuya familiaridad en el preentrenamiento puede reducir el valor del contexto adicional; mide resolución de tareas, no seguridad ni eficiencia del código; y deja abierta la cuestión de cómo generar mejores archivos. Por eso el estudio no refuta el caso de Meta, del mismo modo que el caso de Meta no invalida el estudio.

Cómo reconciliar resultados que parecen opuestos

Las dos fuentes prueban cosas diferentes. Meta estudia conocimiento propietario, disperso y no disponible para el entrenamiento, y mide principalmente exploración en seis tareas. El paper estudia repositorios públicos de Python, añade archivos generales y mide si se resuelven centenares de incidencias. Es posible reducir llamadas en el primer entorno y aumentar pasos sin mejorar aciertos en el segundo. La conclusión honesta no es «el contexto funciona» ni «el contexto estorba», sino «su valor depende de que aporte información no inferible y de que la tarea active justo esa información».

Una evaluación útil debe congelar modelo, agente, presupuesto y herramientas, y repartir tareas representativas entre una condición sin archivo y otra con contexto. El conjunto de prueba no debe ser el mismo que se usó para redactar o afinar las instrucciones. Conviene medir por separado corrección final, regresiones, número de pasos, tokens, latencia y necesidad de intervención humana. También hay que clasificar las tareas: navegación rutinaria, cambios entre repositorios, compatibilidad, seguridad o migraciones. Un promedio puede ocultar que el mapa ayuda mucho en una clase y perjudica al resto.

La práctica de evaluación independiente que Meta describe en su caso de clasificación ofrece otra regla transferible: no optimizar contra el mismo conjunto que decide si el sistema es bueno. Se necesitan referencias congeladas, etiquetas revisadas por personas y puertas de regresión. Cobertura tampoco es corrección. Que 59 archivos alcancen todos los módulos no demuestra que sus afirmaciones sean ciertas, igual que una documentación exhaustiva no garantiza que el agente seleccione la instrucción adecuada.

Un protocolo que deja rastro

El equipo puede empezar por diez o veinte tareas reales que antes obligaron a preguntar a un mantenedor. Para cada una, registra la decisión tácita, su evidencia y una comprobación. Redacta el mínimo contexto capaz de dirigir al agente hacia esa evidencia. Después ejecuta las tareas con el mismo entorno, revisa el cambio sin saber qué condición lo produjo y conserva tanto éxitos como fallos. Si mejora la corrección o reduce coste sin crear regresiones, amplía el experimento. Si solo provoca más exploración, recorta o retira el archivo.

El mantenimiento forma parte del producto. Las rutas se pueden validar automáticamente; las reglas deben tener propietario y caducidad; los cambios relevantes deberían disparar una revisión; y cualquier recomendación generada ha de quedar separada de una política aprobada. Cuando una instrucción sea estable y comprobable, conviene convertirla en test o regla determinista. El agente necesita saber dónde mirar, pero el repositorio debe hacer difícil infringir sus invariantes.

Así se puede leer la próxima afirmación sobre «memoria» o «contexto» para agentes sin aceptar el titular. Hay que preguntar qué conocimiento nuevo aporta, cuándo se recupera, quién lo verificó, contra qué tareas se comparó y qué métrica mejoró. Un mapa de código es valioso cuando convierte una intuición privada en evidencia localizable y una decisión reproducible. Si no puede superar esa prueba, quizá no sea una brújula: quizá solo sea más texto.