code-tour

Code Tour

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

Une bonne tournée 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 une visite guidée du code, un parcours d'onboarding, une revue d'architecture ou une revue de PR
• l'utilisateur dit « expliquez comment X fonctionne » et veut un artefact guidé réutilisable
• l'utilisateur souhaite un chemin d'apprentissage 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 :

• onboarding d'un nouveau mainteneur
• tour d'architecture pour un service ou un package
• revue de PR guidée, ancrée sur les fichiers modifiés
• tour RCA montrant le chemin de l'échec
• tour de revue de sécurité sur les limites de confiance et les contrôles clés

Quand NE PAS l'utiliser

Au lieu de code-tour	Utilisez
Une explication ponctuelle dans le chat suffit	Répondez directement
L'utilisateur veut des docs en prose, pas un artefact .tour	documentation-lookup ou modification 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 un onboarding large 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 la tournée est centrée sur une PR

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

2. Inférer le lecteur

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

Forme de la demande	Persona	Profondeur suggérée
« onboarding », « nouveau membre »	new-joiner	9-13 étapes
« petit tour », « prise de température »	vibecoder	5-8 étapes
« architecture »	architect	14-18 étapes
« visite de cette PR »	pr-reviewer	7-11 étapes
« pourquoi ça a cassé »	rca-investigator	7-11 étapes
« revue de sécurité »	security-reviewer	7-11 étapes
« expliquez comment cette fonctionnalité fonctionne »	feature-explainer	7-11 étapes
« déboguerez ce chemin »	bug-fixer	7-11 étapes

3. Lire et vérifier les ancres

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

• confirmez que le fichier existe
• confirmez que les numéros de ligne sont dans l'intervalle
• si vous utilisez une sélection, vérifiez le bloc exact
• si le fichier est volatil, préférez une ancre basée sur un motif

Ne devinez jamais les numéros de ligne.

4. Écrire le .tour

Écrire 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 sur un fichier ou un dossier réel
• le ref pointe sur une branche ou un commit qui contient réellement tous les fichiers référencés par la tournée (voir ci-dessous)
• la tournée raconte une histoire cohérente plutôt que de lister des fichiers

Le champ ref

ref lie la tournée à une branche ou à un commit Git. Il 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'est pas dans cette révision, l'étape ne s'ouvre pas — le lecteur voit « L'éditeur n'a pas pu être ouvert car le fichier n'a pas été trouvé » même si le fichier est présent. La tournée et ses commentaires s'affichent toujours, donc la vraie cause est facile à manquer.

Choisissez ref selon le type de tournée :

Type de tournée	Définissez ref à
Tour de PR	la branche de la PR — jamais la branche de base
Onboarding / 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 depuis le disque

Le cas de la PR est le piège courant : une PR ajoute souvent de nouveaux fichiers, et les nouveaux fichiers n'existent pas encore sur la branche de base. Pointez ref sur la base (ex. develop) et chaque étape sur un nouveau fichier ne s'ouvrira pas.

Avant de terminer, confirmez que le fichier de chaque étape existe réellement dans la ref que vous avez choisie.

Types d'étapes

Contenu

À utiliser avec parcimonie, généralement seulement pour une étape de conclusion :

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

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

Dossier

À utiliser pour orienter le lecteur vers un module :

{ "directory": "src/services", "title": "Couche Service", "description": "La logique d'orchestration centrale se trouve 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 ici en premier." }

Sélection

À utiliser quand un bloc de code compte plus que le fichier entier :

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

Motif

À utiliser 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

À utiliser pour les PR, les issues ou les docs quand c'est utile :

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

Règle d'écriture : SMIG

Chaque description doit répondre à :

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

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

Structure narrative

Utilisez cet arc sauf si la tâche nécessite clairement autre chose :

1. orientation
2. cartographie des modules
3. chemin d'exécution principal
4. cas limite ou piège
5. conclusion / prochaine action

La tournée 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 paiements.",
  "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 connecte les middlewares avant que toute route ne soit atteinte."
    },
    {
      "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 principales ancres en place."
    }
  ]
}

Anti-patrons

Anti-patron	Correction
Simple liste 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
Ancres devinées	Vérifiez d'abord chaque fichier et chaque ligne
Trop d'étapes pour un petit tour	Taillez de manière agressive
Première étape uniquement de contenu	Ancrez la première étape sur un fichier ou dossier réel
Mauvais persona	Écrivez pour le lecteur réel, pas pour un ingénieur générique

Meilleures pratiques

• gardez le nombre d'étapes proportionnel à la taille du dépôt et à la profondeur du persona
• utilisez des étapes de dossier 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 visiter
• concluez par ce que le lecteur peut maintenant faire, pas par un récapitulatif

Compétences associées

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