code-tour

Code Tour

Crea archivos CodeTour .tour para recorridos guiados de la base de código que se abren directamente en archivos reales y rangos de líneas. Los tours residen 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 código fuente como parte de esta habilidad.

Cuándo Usar

Usa esta habilidad cuando:

• el usuario pida un tour de código, 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 aprendizaje para un nuevo ingeniero o revisor
• la tarea sea mejor servida por una secuencia guiada que por un resumen plano

Ejemplos:

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

Cuándo NO Usar

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 documentación en el repo
La tarea es implementación o refactorización	Haz el trabajo de implementación
La tarea es un onboarding amplio sin un artefacto de 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á enfocado en un PR

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

2. Inferir al lector

Decide la persona y la profundidad a partir de la solicitud.

Forma de la solicitud	Persona	Profundidad sugerida
"onboarding", "nuevo integrante"	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 basado en patrón

Nunca adivines números de línea.

4. Escribir el .tour

Escribe en:

.tours/<persona>-<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
• el ref apunta a una rama o commit que realmente contenga todos los archivos que el tour referencia (ver más abajo)
• el tour cuenta una historia coherente en lugar de listar archivos

El Campo ref

ref vincula el tour a una rama o commit de git. Es más importante 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á "The editor could not be opened because the file was not found" aunque el archivo esté justo ahí. El tour y sus comentarios siguen mostrándose, por lo que la causa real es fácil de pasar por alto.

Elige ref según el tipo de tour:

Tipo de tour	Asigna 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 vacío
No estás seguro	deja ref vacío, 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 aún no existen en la rama base. Apunta ref a la base (p. ej. develop) y cada paso sobre un archivo nuevo fallará al abrirse.

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 seguir 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 principal vive 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": "Cada solicitud protegida pasa aquí primero." }

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 Solicitud",
  "description": "Este bloque conecta validación, autenticación y ejecución downstream."
}

Patrón

Úsalo cuando las líneas exactas puedan variar:

{ "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:

• Situación: qué está viendo el lector
• Mecanismo: cómo funciona
• Implicación: por qué es importante para esta persona
• 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 movimiento

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 middleware antes de que se alcance cualquier ruta."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Rutas de Pagos",
      "description": "Cada solicitud de pagos entra a través de 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 en su lugar."
    }
  ]
}

Anti-Patrones

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

Mejores Prácticas

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

Habilidades Relacionadas

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