code-tour

Code Tour

Créez des fichiers CodeTour .tour pour des parcours guidés de codebase qui s'ouvrent directement sur des fichiers et des plages de lignes réels. Les tours vivent dans .tours/ et sont destinés au format CodeTour, pas à des notes Markdown ad hoc.

Un bon tour est un récit pour un lecteur spécifique :

• ce qu'il regarde
• pourquoi c'est important
• quel chemin il doit suivre ensuite

Créez uniquement des fichiers .tour JSON. Ne modifiez pas le code source dans le cadre de cette compétence.

Quand l'utiliser

Utilisez cette compétence quand :

• l'utilisateur demande un code tour, un tour d'intégration, un parcours d'architecture ou un tour de PR
• l'utilisateur dit "explique comment X fonctionne" et souhaite un artefact guidé réutilisable
• l'utilisateur veut un chemin de montée en compétence pour un nouveau développeur ou un relecteur
• la tâche est mieux servie par une séquence guidée qu'un résumé plat

Exemples :

• intégration d'un nouveau mainteneur
• tour d'architecture pour un service ou un package
• parcours de revue de PR ancré aux fichiers modifiés
• tour RCA montrant le chemin de l'échec
• tour de revue de sécurité des frontières de confiance et des contrôles clés

Quand NE PAS l'utiliser

Au lieu de code-tour	Utilisez
Une explication unique dans le chat suffit	Répondez directement
L'utilisateur veut des docs en prose, pas un artefact .tour	documentation-lookup ou édition de docs du dépôt
La tâche est de l'implémentation ou du refactoring	Faites le travail d'implémentation
La tâche est une intégration large de codebase sans artefact de tour	codebase-onboarding

Workflow

1. Découvrir

Explorez le dépôt avant d'écrire quoi que ce soit :

• README et points d'entrée des packages/applications
• structure des dossiers
• fichiers de configuration pertinents
• les fichiers modifiés si le tour est axé sur une PR

Ne commencez pas à rédiger des étapes avant d'avoir compris la forme du code.

2. Inférer le lecteur

Décidez de la persona et de la profondeur à partir de la demande.

Forme de la demande	Persona	Profondeur suggérée
"intégration", "nouvel arrivant"	new-joiner	9-13 étapes
"tour rapide", "vibe check"	vibecoder	5-8 étapes
"architecture"	architect	14-18 étapes
"parcours de cette PR"	pr-reviewer	7-11 étapes
"pourquoi cela a cassé"	rca-investigator	7-11 étapes
"revue de sécurité"	security-reviewer	7-11 étapes
"expliquez le fonctionnement de cette fonctionnalité"	feature-explainer	7-11 étapes
"déboguez ce chemin"	bug-fixer	7-11 étapes

3. Lire et vérifier les ancrages

Chaque chemin de fichier et ancrage de ligne doit être réel :

• confirmez que le fichier existe
• confirmez que les numéros de ligne sont dans la plage
• si vous utilisez une sélection, vérifiez le bloc exact
• si le fichier est volatil, préférez un ancrage par motif

Ne devinez jamais les numéros de ligne.

4. Écrire le .tour

Écrivez dans :

.tours/<persona>-<focus>.tour

Gardez le chemin déterministe et lisible.

5. Valider

Avant de terminer :

• chaque chemin référencé existe
• chaque ligne ou sélection est valide
• la première étape est ancrée à un fichier ou un répertoire réel
• le ref pointe vers une branche ou un commit qui contient effectivement tous les fichiers référencés par le tour (voir ci-dessous)
• le tour raconte une histoire cohérente plutôt que de lister des fichiers

Le champ ref

ref lie le tour à une branche ou un commit Git. C'est plus important qu'il n'y paraît : quand ref n'est pas la branche que le lecteur a extraite, CodeTour ouvre le fichier de chaque étape depuis cette révision dans git, pas depuis les fichiers sur le disque. Si un fichier n'existe pas dans cette révision, l'étape ne s'ouvrira pas — le lecteur verra "L'éditeur n'a pas pu être ouvert car le fichier est introuvable" même si le fichier est bien là. Le tour et ses commentaires s'affichent quand même, ce qui rend la cause réelle difficile à repérer.

Choisissez ref selon le type de tour :

Type de tour	Définissez ref sur
Tour de PR	la branche de la PR — jamais la branche de base
Intégration / architecture	la branche sur laquelle le lecteur sera (souvent main), ou omettez-le
Pas sûr	omettez ref, pour que CodeTour lise les fichiers directement du disque

Le cas des PR est le piège courant : une PR ajoute généralement de nouveaux fichiers, et ces fichiers n'existent pas encore sur la branche de base. Pointez ref sur la base (par exemple develop) et chaque étape sur un nouveau fichier échouera à s'ouvrir.

Avant de terminer, confirmez que le fichier de chaque étape existe bien à la ref que vous avez choisie.

Types d'étapes

Contenu

Utilisez avec parcimonie, généralement seulement pour une étape de clôture :

{ "title": "Prochaines étapes", "description": "Vous pouvez maintenant tracer le chemin de la requête de bout en bout." }

Ne faites pas de la première étape une étape de contenu uniquement.

Répertoire

Utilisez pour orienter le lecteur vers un module :

{ "directory": "src/services", "title": "Couche Service", "description": "La logique d'orchestration principale vit ici." }

Fichier + ligne

C'est le type d'étape par défaut :

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Porte d'authentification", "description": "Chaque requête protégée passe d'abord ici." }

Sélection

Utilisez quand un bloc de code est plus important que l'ensemble du fichier :

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Pipeline de requête",
  "description": "Ce bloc câble la validation, l'authentification et l'exécution en aval."
}

Motif

Utilisez quand les lignes exactes peuvent dériver :

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Point d'entrée de l'application" }

URI

Utilisez pour les PR, les issues ou la documentation quand c'est utile :

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

Règle d'écriture : SMIG

Chaque description devrait répondre à :

• Situation : ce que le lecteur regarde
• Mécanisme : comment cela fonctionne
• Implication : pourquoi c'est important pour cette persona
• Gotcha : ce qu'un lecteur avisé pourrait manquer

Gardez les descriptions concises, spécifiques et ancrées dans le code réel.

Structure narrative

Utilisez cet arc sauf si la tâche nécessite clairement quelque chose de différent :

1. orientation
2. carte du module
3. chemin d'exécution principal
4. cas limite ou piège
5. clôture / prochain mouvement

Le tour doit donner l'impression d'un chemin, pas d'un inventaire.

Exemple

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Tour du service API",
  "description": "Parcours du chemin de requête pour le service de paiement.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Racine source",
      "description": "Tout le code d'exécution du service commence ici."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Point d'entrée",
      "description": "Le serveur démarre ici et câble les middlewares avant d'atteindre n'importe quelle route."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Routes de paiement",
      "description": "Chaque requête de paiement entre par ce routeur avant d'atteindre la logique métier."
    },
    {
      "title": "Prochaines étapes",
      "description": "Vous pouvez maintenant suivre n'importe quelle requête de paiement de bout en bout avec les ancres principales en place."
    }
  ]
}

Anti-patrons

Anti-patron	Correctif
Liste plate de fichiers	Racontez une histoire avec des dépendances entre les étapes
Descriptions génériques	Nommez le chemin ou le motif de code concret
Ancrages devinés	Vérifiez d'abord chaque fichier et ligne
Trop d'étapes pour un tour rapide	Coupez agressivement
Première étape uniquement du contenu	Ancrez la première étape à un fichier ou répertoire réel
Mauvais persona	Écrivez pour le lecteur réel, pas pour un développeur générique

Bonnes pratiques

• gardez le nombre d'étapes proportionnel à la taille du dépôt et à la profondeur de la persona
• utilisez des étapes de répertoire pour l'orientation, des étapes de fichier pour le fond
• pour les tours de PR, couvrez d'abord les fichiers modifiés
• pour les monorepos, limitez-vous aux packages pertinents au lieu de tout parcourir
• terminez par ce que le lecteur peut maintenant faire, pas un récapitulatif

Compétences liées

• codebase-onboarding
• coding-standards
• council
• format officiel amont : microsoft/codetour