English

Archivos .tour: recorridos de código por persona

Un árbol de archivos es un mapa. Un code tour es una ruta GPS a través de tu código. Suelta a un desarrollador nuevo en un repo desconocido y un listado de directorios le dice qué existe, no por dónde empezar. Un archivo .tour lo resuelve: un recorrido en JSON versionado en el repo, con pasos anclados a archivos y líneas reales, que se reproduce parada por parada dentro del editor.

Qué es realmente un archivo .tour

CodeTour es una extensión gratuita y open source de Microsoft para VS Code. Un tour es un archivo JSON con un title y un arreglo steps; cada paso apunta a un file (ruta relativa al workspace) más una line, y lleva una description en markdown — una nota sobre por qué importa ese punto. La extensión descubre tours en un directorio .tours, .vscode/tours o .github/tours (los subdirectorios funcionan), o en un único archivo .tour en la raíz del repo.

// .tours/backend-request-path.tour
{
  "title": "1 - Backend: life of a request",
  "description": "For new backend devs — follow one request end to end.",
  "steps": [
    {
      "file": "src/api/router.py",
      "line": 42,
      "description": "Every request enters here. Note the auth middleware on line 42 — it runs before any handler."
    },
    {
      "file": "src/services/orders.py",
      "line": 118,
      "description": "Business logic lives in services, never in handlers. This is the pattern to copy."
    }
  ]
}

La reproducción ocurre en el editor: cada paso abre el archivo, salta a la línea y muestra la nota como una burbuja de comentario. Tampoco escribes el JSON a mano — ejecuta CodeTour: Record Tour, haz clic en la barra de comentarios de la línea que quieres, escribe la nota y los pasos se agregan en orden.

Un tour por persona

El consejo que hace que los tours escalen: no escribas un gran tour de todo. Escribe una ruta por audiencia.

CodeTour lo soporta directamente: numera los títulos (1 - Backend, 2 - Frontend) y los enlaza con Siguiente/Anterior, marca uno como isPrimary para que quien abre el repo por primera vez reciba la ruta por defecto, y usa una cláusula when para mostrar un tour solo cuando se cumpla su condición.

Mantén los anclajes honestos

Los números de línea se desplazan cuando el código cambia — un tour que apunta a la línea equivocada es peor que ningún tour. CodeTour te da tres herramientas:

• Fija a un ref de git. Cada tour tiene un ref opcional (branch, tag o commit). Fijado a un tag o commit, el tour abre el código exactamente como se grabó y nunca se desincroniza; sin fijar, sigue el working tree y editas los pasos a medida que el código se mueve.
• Anclajes por patrón. Un paso puede usar un pattern (regex) en lugar de una line fija, de modo que el anclaje sigue al código que describe.
• Verifica en el review. Trata .tours/ como si fueran tests: cuando un PR mueve un archivo que un tour referencia, actualizar el tour es parte del diff.

Jugadas avanzadas

• Content steps no necesitan archivo — paradas de puro markdown (título más texto) para pantallas de introducción y resumen dentro de un tour.
• Directory steps anclan a una carpeta en lugar de una línea — útil para "todo lo que está bajo src/services/ sigue esta forma".
• Exporta con contenido embebido — un tour exportado empaqueta el contenido de los archivos que referencia, así se reproduce sin clonar el repo (o compártelo como GitHub Gist vía GistPad).
• Los pasos pueden ejecutar comandos — la propiedad commands de un paso dispara comandos de VS Code al navegar, así un tour puede abrir una terminal o correr la suite de tests en la parada correcta.
• Alimenta los tours a tu agente de IA. Un archivo .tour es JSON plano con anclajes archivo:línea y razonamiento humano — exactamente el contexto de "dónde mirar y por qué" que a los agentes de código les falta en un repo nuevo. Apunta al agente a .tours/ antes de una tarea igual que orientarías a alguien recién contratado.

Recursos

• CodeTour — repositorio en GitHub y documentación completa
• Grabar tours
• Versionar tours con un ref de git
• Ubicaciones y formato de los archivos de tour
• Exportar tours para reproducirlos sin el repo
• CodeTour en el VS Code Marketplace

Read this article in English