code-tour

Code Tour

Crea archivos CodeTour .tour para recorridos guiados por la base de código que se abren directamente a archivos y rangos de líneas reales. Los tours viven en .tours/ y están pensados para el formato CodeTour, no para notas Markdown ad hoc.

Un buen tour es una narrativa para un lector específico:

• qué está viendo
• por qué es importante
• qué camino debe seguir a continuación

Solo crea archivos .tour JSON. No modifiques el código fuente como parte de esta habilidad.

Cuándo Usarlo

Usa esta habilidad cuando:

• el usuario solicite un code tour, tour de onboarding, recorrido de arquitectura o tour de PR
• el usuario diga "explica cómo funciona X" y quiera un artefacto guiado reutilizable
• el usuario quiera una ruta de incorporación para un nuevo ingeniero o revisor
• la tarea se beneficie más de una secuencia guiada que de un resumen plano

Ejemplos:

• onboarding de un nuevo mantenedor
• tour de arquitectura de un servicio o paquete
• recorrido guiado de revisión de PR anclado a los archivos modificados
• tour de RCA que muestre la ruta de fallo
• tour de revisión de seguridad sobre límites de confianza y controles clave

Cuándo NO Usarlo

En lugar de code-tour	Usa
Una explicación puntual en el chat es suficiente	responde directamente
El usuario quiere documentación en prosa, no un artefacto .tour	documentation-lookup o edición de docs del repo
La tarea es implementación o refactorización	haz el trabajo de implementación
La tarea es onboarding amplio de la base de código sin un artefacto tour	codebase-onboarding

Flujo de Trabajo

1. Descubrir

Explora el repositorio antes de escribir nada:

• README y puntos de entrada de paquetes/aplicaciones
• estructura de carpetas
• archivos de configuración relevantes
• los archivos modificados si el tour está centrado en un PR

No empieces a escribir pasos antes de entender la forma del código.

2. Inferir al lector

Decide el perfil y la profundidad a partir de la solicitud.

Forma de la solicitud	Perfil	Profundidad sugerida
"onboarding", "nuevo miembro"	new-joiner	9-13 pasos
"tour rápido", "vistazo general"	vibecoder	5-8 pasos
"arquitectura"	architect	14-18 pasos
"tour de este PR"	pr-reviewer	7-11 pasos
"por qué falló esto"	rca-investigator	7-11 pasos
"revisión de seguridad"	security-reviewer	7-11 pasos
"explica cómo funciona esta funcionalidad"	feature-explainer	7-11 pasos
"depura esta ruta"	bug-fixer	7-11 pasos

3. Leer y verificar anclajes

Cada ruta de archivo y anclaje de línea debe ser real:

• confirma que el archivo existe
• confirma que los números de línea están dentro del rango
• si usas una selección, verifica el bloque exacto
• si el archivo es volátil, prefiere un anclaje por patrón

Nunca adivines números de línea.

4. Escribir el .tour

Escribe en:

.tours/<perfil>-<enfoque>.tour

Mantén la ruta determinista y legible.

5. Validar

Antes de finalizar:

• cada ruta referenciada existe
• cada línea o selección es válida
• el primer paso está anclado a un archivo o directorio real
• ref apunta a una rama o commit que realmente tiene todos los archivos que referencia el tour (ver más abajo)
• el tour cuenta una historia coherente, no solo lista archivos

El Campo ref

ref vincula el tour a una rama o commit de git. Importa más de lo que parece: cuando ref no es la rama que el lector tiene checkout, CodeTour abre el archivo de cada paso desde esa revisión en git, no desde los archivos en disco. Si un archivo no está en esa revisión, el paso no se abrirá — el lector verá "No se pudo abrir el editor porque no se encontró el archivo" aunque el archivo esté justo ahí. El tour y sus comentarios aún se muestran, así que la causa real es fácil de pasar por alto.

Elige ref según el tipo de tour:

Tipo de tour	Establece ref a
Tour de PR	la rama del PR — nunca la rama base
Onboarding / arquitectura	la rama en la que estará el lector (a menudo main), o déjalo fuera
No estás seguro	deja ref fuera, para que CodeTour lea los archivos directamente del disco

El caso del PR es la trampa común: un PR normalmente añade archivos nuevos, y los archivos nuevos no existen todavía en la rama base. Apunta ref a la base (por ejemplo develop) y cada paso en un archivo nuevo no se abrirá.

Antes de finalizar, confirma que el archivo de cada paso realmente existe en el ref que elegiste.

Tipos de Paso

Contenido

Úsalo con moderación, normalmente solo para un paso de cierre:

{ "title": "Próximos Pasos", "description": "Ahora puedes rastrear la ruta de la solicitud de extremo a extremo." }

No hagas que el primer paso sea solo de contenido.

Directorio

Úsalo para orientar al lector hacia un módulo:

{ "directory": "src/services", "title": "Capa de Servicios", "description": "La lógica de orquestación central reside aquí." }

Archivo + línea

Este es el tipo de paso por defecto:

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Puerta de Autenticación", "description": "Toda solicitud protegida pasa primero por aquí." }

Selección

Úsalo cuando un bloque de código importe más que el archivo completo:

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Pipeline de Solicitudes",
  "description": "Este bloque conecta validación, autenticación y ejecución descendente."
}

Patrón

Úsalo cuando las líneas exactas puedan cambiar:

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Punto de Entrada de la Aplicación" }

URI

Úsalo para PRs, issues o documentación cuando sea útil:

{ "uri": "https://github.com/org/repo/pull/456", "title": "El PR" }

Regla de Escritura: SMIG

Cada descripción debe responder a:

• Situación: qué está viendo el lector
• Mecanismo: cómo funciona
• Implicación: por qué es importante para este perfil
• Gotcha: qué podría pasar por alto un lector inteligente

Mantén las descripciones compactas, específicas y basadas en el código real.

Forma Narrativa

Usa este arco a menos que la tarea requiera claramente algo diferente:

1. orientación
2. mapa del módulo
3. ruta de ejecución principal
4. caso límite o gotcha
5. cierre / siguiente acción

El tour debe sentirse como un camino, no como un inventario.

Ejemplo

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Tour del Servicio API",
  "description": "Recorrido de la ruta de solicitud para el servicio de pagos.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Raíz del Código Fuente",
      "description": "Todo el código en tiempo de ejecución del servicio comienza aquí."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Punto de Entrada",
      "description": "El servidor arranca aquí y conecta el middleware antes de que se alcance cualquier ruta."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Rutas de Pagos",
      "description": "Toda solicitud de pagos entra por este enrutador antes de llegar a la lógica del servicio."
    },
    {
      "title": "Próximos Pasos",
      "description": "Ahora puedes seguir cualquier solicitud de pago de extremo a extremo con los anclajes principales establecidos."
    }
  ]
}

Anti-patrones

Anti-patrón	Corrección
Listado plano de archivos	Cuenta una historia con dependencias entre pasos
Descripciones genéricas	Nombra la ruta o patrón de código concreto
Anclajes adivinados	Verifica primero cada archivo y línea
Demasiados pasos para un tour rápido	Recorta agresivamente
El primer paso es solo de contenido	Ancla el primer paso a un archivo o directorio real
Desajuste de perfil	Escribe para el lector real, no para un ingeniero genérico

Buenas Prácticas

• mantén el número de pasos proporcional al tamaño del repo y la profundidad del perfil
• usa pasos de directorio para orientación, pasos de archivo para contenido sustancial
• para tours de PR, cubre primero los archivos modificados
• para monorepos, delimita a los paquetes relevantes en lugar de recorrer todo
• cierra con lo que el lector puede hacer ahora, no con un resumen

Habilidades Relacionadas

• codebase-onboarding
• coding-standards
• council
• formato oficial aguas arriba: microsoft/codetour