¿Qué debe contener la documentación de onboarding para que un agente de IA llegue con ella hasta el primer cambio fusionado (merge)?

Pregunta abierta

La documentación de onboarding de un proyecto debe guiar a una persona nueva desde una máquina vacía hasta su primer cambio fusionado. El capítulo sobre documentación del libro «Software Engineering at Google» recomienda para ello un documento «Hello World» que no dé nada por supuesto, y señala la incorporación al equipo como el mejor momento para escribir un tutorial así; Diátaxis lo clasifica como un tutorial orientado al aprendizaje. Ambos enfoques están pensados para personas. Sin embargo, cada vez más a menudo es también un agente quien recorre ese mismo itinerario, y tropieza en otros puntos: un paso del tipo «inicia sesión en el navegador», un «pregunta en el canal», un comando que espera una entrada de teclado, un diagrama sin versión en texto, una regla que todos conocen y nadie ha escrito. En concreto, siguen abiertas estas cuestiones:

• ¿Qué pasos de los itinerarios de onboarding habituales fallan con más frecuencia para los agentes, y es posible agrupar los fallos en pocas clases (entrada interactiva, permisos que faltan, conocimiento implícito, dependencia de una persona)?
• ¿Basta con una lista de comandos no interactivos con su salida esperada, o los agentes necesitan además una lista explícita de prohibiciones (no desplegar, no borrar nada, no escribir a nadie) y una indicación de qué significa «terminado»?
• ¿Cómo se mantiene sincronizada una variante del itinerario para agentes con la variante para personas: un solo documento con secciones marcadas, dos documentos, o un único itinerario que sirva para ambos porque cada paso es, de todos modos, un comando verificable?
• ¿Existen observaciones o registros sobre con qué frecuencia un agente recorre un itinerario de onboarding hasta el merge sin intervención humana, y sobre qué causó los abandonos?
• ¿Deberían los obstáculos que encuentra un agente volver a la documentación como primeras contribuciones, igual que ocurre con las personas, y quién revisa esos cambios?

Qué contiene una respuesta útil

El tipo de proyecto y de entorno del agente (herramientas, permisos, si una persona responde preguntas); el itinerario o su estructura; la lista de pasos en los que hubo problemas, con su clase de fallo; qué añadido ayudó y si empeoró la variante para personas; y, si hay recuentos, el número de ejecuciones y de abandonos. Los informes de experiencia de proyectos concretos son bienvenidos, siempre que se identifiquen como tales.