English

Verifica cada afirmación contra el código

El README dice una cosa. El código hace otra. Confía en el código. Cada repo al que te vas a incorporar viene con una historia sobre sí mismo — un README, un diagrama de arquitectura, una página de wiki — y cada una de esas historias era cierta el día en que se escribió. El código siguió moviéndose; la historia no. Si tus notas de onboarding se construyen a partir de la historia, heredan su desactualización.

Por qué los README se desactualizan

La documentación y el código viven en el mismo repo pero cambian con calendarios distintos. Un refactor mueve la lógica de negocio fuera de services/ hacia un módulo nuevo; el pull request toca 40 archivos y cero párrafos de texto. Nadie mintió — el doc simplemente no estaba en el diff. Ese es todo el modo de falla: los docs se vuelven obsoletos en silencio, porque nada se rompe cuando eso pasa. El movimiento docs-as-code existe precisamente para combatir esto — pasar los docs por el mismo control de versiones y code review que el código — pero incluso los docs revisados quedan atrás, porque un revisor revisa el doc que cambió, no los docs que deberían haber cambiado.

Así que trata cada afirmación escrita sobre una base de código — "el auth vive en el gateway", "todas las escrituras pasan por la cola" — como una hipótesis, no como un hecho. Las hipótesis son baratas de probar cuando puedes leer el código fuente.

Traza una request real de punta a punta

No intentes verificar todo a la vez. Elige una request real — un login, un checkout, una búsqueda — y síguela desde el punto de entrada, pasando por la lógica de negocio, hasta el almacén de datos y de vuelta:

1. Encuentra el punto de entrada. Tabla de rutas, controller, registro de handlers, parser de argumentos del CLI — donde sea que el mundo exterior toque el código por primera vez.
2. Sigue la cadena de llamadas hacia abajo. Usa Go to Definition y Find All References de tu editor en lugar de adivinar por los nombres de archivos; los nombres se desactualizan igual que los docs.
3. Detente en el almacén de datos. La consulta, la tabla, la ruta de escritura. Ya viste dónde vive realmente el estado.
4. Vuelve a subir y anota la forma de la respuesta.

Ese único trazado ancla todo lo demás. Una vez que conoces un camino verdadero a través del sistema, toda otra afirmación puede contrastarse con él: ¿el diagrama coincide con los módulos que acabas de recorrer? ¿"La capa de servicio es dueña de la validación" coincide con lo que viste en el paso 2? Un camino verificado vale más que diez inferidos.

Reglas prácticas

El patrón de la tabla: cuanto más cerca está una afirmación de algo que la máquina ejecuta o verifica, menos puede desactualizarse.

Trucos avanzados

• Traza la historia, no solo la estructura. git log -L :funcName:path/to/file muestra la evolución de una función a través de los commits — ves cuándo se movió la lógica y adónde fue, que suele ser el momento exacto en que el README dejó de ser cierto.
• Usa la navegación de código también en el host. La navegación integrada de GitHub soporta jump-to-definition y find-all-references dentro de un repo, así que puedes hacer un trazado ligero durante el code review sin clonar.
• En sistemas distribuidos, traza literalmente. Un trace distribuido registra el camino real de una request a través de los servicios — es la versión en runtime de este tip, y verifica afirmaciones que ninguna lectura estática puede verificar (qué servicio llama realmente a cuál).
• Escribe tus notas como rutas, no como prosa. "Login: routes.py:42 → auth/service.py:check() → tabla users" sobrevive a los refactors mejor que los párrafos, porque una ruta rota se ve visiblemente rota.

Recursos

• Docs as Code — guía de Write the Docs
• Navegación de código en VS Code — Go to Definition, Find All References
• Navegar código en GitHub — jump to definition y referencias
• git log -L — trazar un rango de líneas o una función a través de la historia
• Traces — OpenTelemetry: el camino de una request a través de tu aplicación