El fichero, entero
Esto es exactamente lo que descargas: sin resúmenes ni recortes.
Recorridos guiados por el código
Un documento de onboarding envejece en silencio: el código se mueve y el .md
se queda quieto. Un recorrido guiado apunta a ficheros y líneas concretas, así
que cuando deja de encajar, se nota.
El formato es CodeTour: un JSON en
.tours/ que VS Code abre como una serie de pasos, cada uno saltando al sitio
exacto del que se está hablando.
Antes de escribir: para quién
Un recorrido no es un índice, es una historia contada a alguien concreto. La misma base de código produce recorridos distintos según quién entre por la puerta:
| Persona | Lo que necesita | Pasos |
|---|---|---|
| Quien acaba de entrar | Estructura, contexto de negocio, cómo arrancarlo | 9-13 |
| Quien revisa una PR | Qué cambió, qué invariantes están en juego, dónde mirar | 9-13 |
| Quien investiga una incidencia | La cadena causal y dónde están las trazas | 14-18 |
| Quien viene a decidir arquitectura | Fronteras, decisiones y sus porqués, puntos de extensión | 14-18 |
| Quien solo quiere hacerse una idea | Punto de entrada y los tres módulos que importan | 5-8 |
Si la petición no dice para quién, el recorrido de nuevo ingreso es el que más sirve. No preguntes: infiérelo y dilo.
La regla que no se rompe
Cada ruta y cada número de línea se verifican leyendo el fichero. Un recorrido que apunta a la línea equivocada es peor que no tener recorrido: quien lo sigue pierde la confianza en el resto de pasos y en quien lo escribió.
Si un fichero que querías citar no existe, se cae ese paso. No se aproxima.
El fichero
{
"$schema": "https://aka.ms/codetour-schema",
"title": "Autenticación de punta a punta — nuevo ingreso",
"description": "Para quién es y qué entenderá al terminar.",
"ref": "main",
"steps": [
{ "directory": "src/services", "title": "El mapa" },
{ "file": "src/auth.ts", "line": 42, "title": "Dónde se valida el token" }
]
}
Tipos de paso, por orden de utilidad real:
| Tipo | Cuándo |
|---|---|
file + line | El caballo de batalla: el 80% de los pasos |
directory | Orientar sobre un módulo antes de entrar en él |
pattern | Ficheros que se mueven mucho: ancla por regex en vez de por línea |
uri | Enlazar la PR, la incidencia o el ADR que lo explica |
| Solo contenido | Introducción y cierre. Máximo dos en todo el recorrido |
El primer paso nunca es de solo contenido: en VS Code se abre en blanco y el recorrido arranca con la sensación de estar roto.
Cómo se escribe cada paso
Cuatro cosas, en este orden:
- Qué está mirando quien lee.
- Cómo funciona este código.
- Por qué le importa a esta persona en concreto.
- Qué asumiría mal alguien inteligente que llegara aquí solo.
El cuarto punto es el que convierte un recorrido en algo que vale la pena escribir. Lo demás lo puede deducir cualquiera leyendo; la trampa oculta, no.
Arco narrativo
- Orientación — un fichero o un directorio, nunca texto suelto
- El mapa — uno a tres pasos de directorio con los módulos grandes
- El camino principal — pasos de fichero y línea; aquí está el recorrido
- Cierre — qué puede hacer ahora quien ha llegado hasta el final
Lo que arruina un recorrido
| Error | Qué hacer en su lugar |
|---|---|
| Enumerar ficheros: «aquí están los modelos» | Contar una historia: cada paso depende del anterior |
| Descripciones que valdrían para cualquier repo | Nombrar el patrón concreto de este código |
| Adivinar números de línea | No escribir ninguna línea que no hayas leído |
| Estirar un recorrido corto | Cortar pasos de verdad, no rellenar |
| Cerrar con un resumen de lo visto | Cerrar con lo que ahora se puede hacer |
Antes de darlo por bueno
- Todas las rutas son relativas a la raíz, sin
/ni./delante - Todos los ficheros existen
- Todas las líneas se han verificado leyendo
- El primer paso ancla a fichero o directorio
- Como mucho dos pasos de solo contenido
- Si hay
nextTour, coincide exacto con el título del siguiente recorrido
Y una nota de mantenimiento
Un recorrido es documentación con fecha de caducidad, como cualquier otra. La diferencia es que esta la puedes comprobar: si los pasos ya no cuadran con el código, o se actualiza o se borra. Un recorrido desactualizado y bien presentado engaña más que un README viejo, porque parece verificado.