Aprender una base de código desconocida en un día: un protocolo de exploración con un mapa escrito

Objetivo

Llegar, en el plazo de un día laboral, al punto en que se pueda hacer un cambio pequeño con seguridad: el código compila, las pruebas se ejecutan, se entiende la ruta principal, y todo lo aprendido queda por escrito para la siguiente persona que lo lea (o la siguiente sesión de un agente).

Requisitos previos

Una copia de trabajo del código, el README y la guía de contribución, una cadena de herramientas funcional, y un archivo de mapa abierto desde el inicio (MAP.md o una nota) con los encabezados usados a continuación.

Pasos

1. Primera hora: compilar y ejecutar la suite de pruebas exactamente como indica la documentación. Registrar cada desviación necesaria para que funcione; esas son las primeras entradas bajo «preguntas abiertas».
2. Leer el historial antes que el código. git shortlog -sn (la documentación describe shortlog como un resumen de la salida de git log) muestra quién ha escrito más; git log --stat -20 muestra qué archivos cambian juntos; git log --follow -- <path> sobre un archivo sospechoso muestra su historial a través de los renombrados. Anotar los tres directorios que cambian con más frecuencia.
3. Dibujar la estructura de directorios hasta dos niveles y escribir una línea por directorio sobre lo que parece contener. Marcar las conjeturas con «?».
4. Encontrar los puntos de entrada: main, rutas HTTP, subcomandos de CLI, trabajos programados. Enumerarlos con archivo y línea.
5. Elegir una solicitud o un comando representativo y seguirlo de principio a fin, anotando en el mapa cada salto (función, archivo, línea). Detenerse cuando los datos llegan al almacenamiento o salen del proceso.
6. Identificar el modelo de datos: el esquema, los tipos centrales, y qué invariantes verifica el código (restricciones de unicidad, validación, aserciones). Escribir los invariantes en palabras.
7. Leer las pruebas de la ruta seguida; expresan el comportamiento esperado con más claridad que el código.
8. Hacer un cambio trivial (una línea de registro, una prueba que afirma algo ya cierto), ejecutar las pruebas, revertir. Esto demuestra que el ciclo funciona.
9. Última hora: reescribir el mapa para alguien que no ha visto el código, conservando las marcas «?» y la lista de preguntas abiertas. Registrar el hash del commit que describe el mapa.

Resultado esperado

Un mapa de una página con los puntos de entrada, una ruta trazada, el modelo de datos y los invariantes, las peculiaridades de la compilación y una lista de preguntas abiertas, fechado y vinculado a un commit.

Límites y base de verificación

Este es un protocolo propuesto; no se afirma ningún tiempo ni tasa de éxito. Los monorepos grandes necesitan una decisión de alcance antes del paso 3. El código generado, las dependencias empaquetadas (vendored) y el despacho dinámico hacen que la ruta trazada quede incompleta; el mapa debe indicar dónde se perdió el rastro.