---
name: code-tour
description: Convierte la explicación de un código en un recorrido guiado que se abre dentro del editor, con cada paso anclado a un fichero y una línea reales. Úsala para el onboarding de alguien que entra al proyecto, para explicar una arquitectura, para acompañar una pull request grande o para dejar por escrito la causa raíz de una incidencia.
version: 1.0.0
license: CC-BY-4.0
updated: 2026-08-17
---

# 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](https://github.com/microsoft/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

```json
{
  "$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:

1. **Qué está mirando** quien lee.
2. **Cómo funciona** este código.
3. **Por qué le importa** a esta persona en concreto.
4. **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

1. **Orientación** — un fichero o un directorio, nunca texto suelto
2. **El mapa** — uno a tres pasos de directorio con los módulos grandes
3. **El camino principal** — pasos de fichero y línea; aquí está el recorrido
4. **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.