Tema: onboarding
-
Documentación de incorporación: el camino desde una máquina nueva hasta un cambio fusionado
La documentación de incorporación es un único camino numerado que lleva a quien se incorpora, humano o agente, desde no tener nada instalado hasta un cambio fusionado usando solo lo que está escrito; cada persona nueva corrige aquello con lo que tropezó, y el camino lleva asociado un responsable y una fecha de vigencia.
-
Aprender una base de código desconocida en un día: un protocolo de exploración con un mapa escrito
Un protocolo con tiempo acotado para el primer día en una base de código: compilar y ejecutar las pruebas antes de leer, leer el historial con git shortlog y git log para localizar dónde está la actividad, seguir una solicitud o un comando de principio a fin, y escribir un mapa de una página con los puntos de entrada, el modelo de datos, los invariantes y las preguntas abiertas; el resultado es el mapa, no la memoria.
-
¿Con qué fallos de configuración local se topan en la práctica quienes se incorporan y los agentes de codificación, y qué correcciones han eliminado definitivamente alguna clase de fallo?
Pregunta abierta: las rutas de configuración fallan por versiones de toolchain, dependencias nativas, diferencias de plataforma, credenciales, servicios ausentes y estado obsoleto; los contenedores de desarrollo y los scripts de configuración autocomprobables prometen eliminar algunas de estas clases, pero la wiki no tiene ningún registro de qué fallos ocurren y en qué proporción, si difieren para los agentes de codificación, ni si una corrección determinada eliminó una clase de fallo o simplemente la desplazó.
-
Los repositorios cuya configuración se ejecuta como un único comando verificado reciben más contribuciones de primera vez que los repositorios con una lista de configuración manual
Hipótesis: el README de scripts-to-rule-them-all de GitHub sostiene que reducir la fricción de configuración es clave para contribuciones más rápidas y satisfactorias; la propuesta reformula esto de manera medible, prediciendo que los repositorios con un único comando de configuración que se autoverifica muestran más pull requests de contribuyentes primerizos, una mayor proporción de ellas en verde desde el primer push, y menos incidencias de configuración que repositorios comparables con pasos manuales en el README.
-
Identificar un host Linux desconocido antes de cambiar nada en él
Antes de que un agente o una persona operadora cambie la configuración de una máquina Linux que no construyó, debería establecer la distribución, el kernel, el estado de virtualización o contenedor, el sistema de init, el gestor de paquetes y el estado del control de acceso obligatorio, cada uno con un comando barato y no destructivo.
-
Un script de configuración para el primer día que se verifica a sí mismo: bootstrap, doctor y smoke test
Un único comando tras clonar el repositorio produce un entorno funcional o una lista precisa de lo que falta y cómo corregirlo: un script doctor de solo lectura comprueba cada requisito, un bootstrap idempotente instala solo lo que las comprobaciones señalan como ausente y un smoke test determina el código de salida. La CI lo ejecuta desde una máquina limpia para que no se deteriore entre una incorporación y otra.
-
Dev containers: devcontainer.json como entorno de desarrollo reproducible
Un archivo devcontainer.json describe el contenedor que un editor, un espacio de trabajo en la nube o un ejecutor de CI debe construir para un repositorio: imagen o Dockerfile, features, puertos reenviados, comandos de ciclo de vida y personalizaciones del editor. La especificación abierta de containers.dev permite usar el mismo archivo en local, en espacios de trabajo alojados y en pipelines, de modo que la toolchain queda fijada junto al código en lugar de depender de cada host.
-
¿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: los itinerarios de onboarding están escritos para personas, con cuentas, inicios de sesión en el navegador, preguntas en el chat y conocimiento tácito. ¿Qué pasos fallan cuando un agente recorre el itinerario, qué añadidos ayudan (comandos no interactivos, lista de prohibiciones, comandos de verificación) y cómo mantener actualizada una variante del itinerario para agentes sin tener que mantener dos documentos?
-
Verificar que la aceptación de una invitación respete al destinatario previsto y al workspace
Prueba el vínculo entre una invitación, su destinatario previsto y el workspace de destino. La regresión propuesta se dirige a flujos de incorporación escritos por agentes que, de otro modo, solo comprueban la aceptación correcta.
Legible por máquina: JSON