La medición que tumbó una creencia extendida
Un estudio de febrero de 2026 se planteó justo la pregunta que todo el mundo da por evidente: ¿ayuda a un coding agent un fichero de contexto a nivel de repo?
La metodología es cuidadosa. Dos conjuntos de tareas: uno propio, con 138 tareas de doce repos recientes y poco conocidos — a propósito nada populares, para que la memoria del modelono ayudase —, más un conjunto establecido de 300 tareas. Cuatro agents, cuatro modelos. Y dos tipos de fichero de contexto: generado por máquina y escrito a mano por un desarrollador.
| Fichero de contexto | Tasa de éxito | Coste |
|---|---|---|
| Generado por máquina | −0,5 % y −2 % | +20 % y +23 % |
| Escrito por un desarrollador | mejor que el generado con los cuatro agents; salvo una excepción, mejora | hasta +19 % |
El número de pasos subió en todas las configuraciones, entre dos y cuatro de media. Y sobre la navegación tampoco hay efecto: el fichero de contexto no redujo de forma apreciable en cuántos pasos llega el agent a los ficheros relevantes.
La conclusión de los autores, literalmente: «los tours de repositorio — pese a ser populares y estar recomendados por los proveedores de modelos — no ayudan.»
Y hay un resultado parcial que es más revelador que todo lo demás. Cuando se quitó la documentación del repo, los ficheros de contexto generados por máquina mejoraron el rendimiento un 2,7 % de media — y salieron mejor parados que la documentación escrita por el desarrollador.
O sea, el fichero es útil cuando no hay otra documentación. Si no, solo duplica.
Esto no contradice la otra medición
Conviene aclararlo ya, porque a primera vista los dos resultados parecen chocar.
Otro experimento, este pareado, encontró que el fichero de instrucciones de proyecto reduce un 20 % el consumo de tokens y el tiempo de ejecución. Aquella medición usaba los ficheros que ya existían en los repos, escritos por desarrolladores.
La medición de ahora, en cambio, muestra que el fichero generado por máquina empeora y encarece.
Las dos juntas dejan una lección: lo que cuenta no es que el fichero exista, sino quién lo escribió y qué hay dentro. El tour del repo generado es el peor caso — largo, deducible del código de todos modos, y presente en el contexto en cada ejecución. Lo desarrolla el post las instrucciones de proyecto , con los números.
Qué cuesta esto en dinero
Calculémoslo para un equipo. Supongamos que lanzáis 300 tareas de agent al mes, con un coste base de medio dólar por tarea.
Coste base: 300 × 0,50 = 150 dólares / mes
Con fichero generado (+23 %): 150 × 1,23 = 184,50 dólares / mes
Sobrecoste: 34,50 dólares / mes
Cambio en la tasa de éxito: −2 puntos porcentuales
Soluciones perdidas: 300 × 0,02 = 6 tareas / mes
(Cálculo propio a partir de las proporciones publicadas.)
Treinta y cinco dólares de más al mes y seis tareas resueltas menos. No es una catástrofe — pero lleva el signo contrario a aquello por lo que montaste todo esto.
La documentación mala es peor que ninguna
Es la afirmación más importante del post, y la respalda un experimento.
Un estudio de 2024 entregó las mismas 164 funciones en cinco variantes: sin documentación; con la documentación original; con documentación sacada de otra función, que no venía a cuento; con los nombres de variable reescritos; y con documentación parcial.
De ahí salieron dos resultados:
- La documentación errónea perjudica gravemente. Con comentarios aleatorios y fuera de lugar, la tasa de éxito cayó al 22,1 % en el modelo más flojo y al 68,1 % en el más potente. Estadísticamente significativo.
- La documentación ausente apenas cuenta. Entre la variante comentada y la variante base sin comentarios no hubo diferencia significativa.
A esto se suma otra medición, sobre una tarea completamente distinta: allí quitar los comentarios mejoró la tasa de acierto de los modelos.
Dos mediciones independientes, la misma dirección. La documentación que no vas a mantener no es un pasivo neutro, sino un riesgo activo. Quien cree que documentar sale gratis, calcula mal.
El comentario obsoleto es más peligroso cuando es reciente
Esta es la conclusión que más choca con la expectativa instintiva.
Según un estudio sobre 32 proyectos de Apache, los cambios en los que el código y el comentario se separan llevan a un commit que provoca fallos 1,52 veces más a menudo en el plazo de una semana, y 1,14 veces más a menudo en el de dos semanas.
Y aquí viene lo importante: el efecto es máximo justo después de la separación, y disminuye con el tiempo.
El comentario obsoleto no es peligroso por ser viejo. Es peligroso mientras todavía haya alguien que se lo crea. Después el equipo aprende a ignorarlo — solo que el modelo no lo aprende.
Qué meter y qué no
La recomendación del fabricante y la medición de arriba llegan al mismo sitio. Esta tabla se puede usar tal cual:
| Sí | No |
|---|---|
| Comandos que no puede adivinar | Cualquier cosa que entienda leyendo el código |
| Reglas de estilo distintas de las de serie | Convenciones estándar del lenguaje |
| Instrucciones de test, el ejecutor preferido | Descripción detallada de la API — enlázala |
| Etiqueta del repo: nombres de rama, convención de PR | Información que cambia a menudo |
| Decisiones de arquitectura propias del proyecto | Explicaciones largas, material didáctico |
| Rarezas del entorno, variables obligatorias | Descripción fichero a fichero del código |
| Trampas no evidentes | Consejos obvios |
La columna de la derecha es, en esencia, lo que la medición llama «tour del repo» — y de lo que demostró que no sirve.
La pregunta de autocontrol para cada línea: «Si borrara esto, ¿se equivocaría por ello?» Si no, bórralo.
Lo que no se queda obsoleto: el registro de decisiones
Hay un tipo de documentación que por definición no envejece: el registro de decisiones de arquitectura.
La lógica es sencilla. Una entrada recoge una decisión en un momento concreto, junto con su contexto y las alternativas que se sopesaron. Si la decisión cambia más adelante, no la reescribes: escribes una entrada nueva que sustituye a la vieja.
Así consigues documentación cuya actualización no es una obligación, sino una línea nueva. Y así sigue siendo cierta: la entrada antigua es exacta aunque la decisión ya no valga, porque recoge qué pensábamos entonces y por qué.
(Límite honesto: no hemos encontrado ninguna medición sobre la utilidad del registro de decisiones. Lo que hay es una comparación de plantillas en un experimento con 33 estudiantes — allí sí hubo diferencia significativa entre las dos plantillas examinadas, pero de esa muestra no se puede sacar una conclusión industrial.)
Lo que puede quedar obsoleto, hazlo ejecutable
Este es el mecanismo más práctico del post.
El ejemplo escrito en la documentación sigue siendo cierto si se ejecuta. La biblioteca estándar de Python tiene una herramienta para esto: extrae del texto de documentación los ejemplos interactivos, los ejecuta y los compara con la salida esperada que está escrita. En otros lenguajes hay algo parecido, donde los ejemplos de la documentación corren como parte de la batería de tests.
Esta es la única forma en la que la documentación que se queda obsoleta aparece como un test en rojo en vez de pudrirse en silencio.
La misma lógica se puede extender: si una explicación habla de algún comportamiento, que ese comportamiento tenga un test — y que el nombre del test sea la explicación. De escribir tests habla con más detalle el post la red de seguridad de los tests , con las mediciones.
La receta
1. NO GENERES UN TOUR DEL REPO.
Efecto medido: -0,5 y -2 puntos de tasa de éxito,
+20-23 % de coste, +2-4 pasos por tarea.
2. LO QUE ENTIENDA DEL CÓDIGO, NO LO ESCRIBAS.
Pregunta por cada línea: "si la borro, ¿se equivocaría?"
3. LO QUE PUEDA QUEDAR OBSOLETO, HAZLO EJECUTABLE.
Ejemplo en la documentación -> test que se ejecuta.
Explicación de comportamiento -> test con nombre claro.
4. REGISTRA LAS DECISIONES, NO EL ESTADO.
Registro de decisiones: contexto, alternativas, decisión, fecha.
Al cambiar, entrada NUEVA, no reescritura.
5. EL COMENTARIO OBSOLETO BÓRRALO, NO LO DEJES AHÍ.
Medida, la documentación errónea es peor que ninguna.
6. CUANDO SE SEPAREN, ARRÉGLALO ENTONCES.
La propensión a provocar fallos es máxima justo
después de la separación, no meses más tarde.
Una cifra que falta
Por honestidad: lo hemos buscado y no hemos encontrado ninguna medición sobre qué porcentaje de la documentación generada por máquina es errónea u obsoleta.
Lo que hay es la medición del efecto — que la documentación errónea empeora la comprensión. Sobre la frecuencia no hay datos publicados. Quien cite una cifra así, probablemente la estima.
Malentendidos típicos
- «El agent necesita documentación para entender el repo.» Según la medición, el tour del repo no ayuda, y sobre la navegación tampoco tiene efecto.
- «Genero un resumen, así al menos hay algo.» Dos puntos porcentuales peor de tasa de éxito y un 23 % más de coste. Nada habría sido mejor.
- «El comentario obsoleto se vuelve peligroso con el tiempo.» Al revés: la propensión a provocar fallos es máxima justo después de la separación.
- «La documentación ausente es una desventaja seria.» En el experimento controlado, la documentación ausente no provocó un empeoramiento significativo. La errónea sí.
- «Documentar sale gratis.» La documentación mala es un riesgo activo, y el fichero de contexto se hace pagar en cada ejecución.
Lo que conviene llevarse
La marca de la buena documentación en 2026 no es cuánto cubre, sino qué le pasa cuando el código cambia. Lo que es ejecutable avisa: el test se pone en rojo. Lo que recoge una decisión no envejece. Lo que es un tour del repo, según la medición, mejor ni escribirlo — el modelo va a leer el código igualmente, solo que ahora además pagas por ello.
Cómo se orienta el agent en el código en lugar de en la documentación lo recorre el post entender código heredado , hilo a hilo.