Compétence CodeTour

Tu crées une CodeTour — une présentation ciblée par persona, étape par étape, d'une base de code qui renvoie directement aux fichiers et numéros de ligne. Les fichiers CodeTour vivent dans .tours/ et fonctionnent avec l'extension VS Code CodeTour.

Deux scripts sont groupés dans scripts/ :

• scripts/validate_tour.py — à exécuter après avoir écrit n'importe quelle tour. Vérifie la validité JSON, l'existence des fichiers/répertoires, les numéros de ligne dans les limites, les correspondances de motifs, les références croisées de nextTour et l'arc narratif. Exécute-le : python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
• scripts/generate_from_docs.py — quand l'utilisateur demande de générer à partir de README/docs, exécute d'abord ce script pour extraire un squelette, puis remplis-le. Exécute-le : python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour

Deux fichiers de référence sont groupés :

• references/codetour-schema.json — le schéma JSON faisant autorité. Lis-le pour vérifier tout nom ou type de champ. Chaque champ que tu utilises doit s'y conformer.
• references/examples.md — 8 vraies tours CodeTour de dépôts en production avec techniques annotées. Lis-le quand tu veux voir comment une fonctionnalité spécifique (commands, selection, view, pattern, isPrimary, série multi-tour) est utilisée en pratique.

Fichiers .tour du monde réel sur GitHub

Ce sont des fichiers .tour de production confirmés. Récupère-en un quand tu as besoin d'un exemple fonctionnel d'un type de step spécifique, d'un champ au niveau de la tour, ou d'une structure narrative — n'écris pas de mémoire quand la vraie chose est à une récupération près.

Trouve-en plus avec la recherche de code GitHub : https://github.com/search?q=path%3A**%2F*.tour+&type=code

Par type de step / technique démontrée

Conseil contenu brut : Utilise raw.githubusercontent.com et supprime /blob/ pour l'accès JSON brut.

Une excellente tour n'est pas juste des fichiers annotés. C'est une narration — une histoire racontée à une personne spécifique sur ce qui importe, pourquoi ça importe, et quoi faire ensuite. Ton objectif est d'écrire la tour que la bonne personne aurait souhaité avoir quand elle a ouvert ce dépôt pour la première fois.

CRITIQUE : Crée uniquement des fichiers JSON .tour. Ne crée, ne modifie ou ne prépare jamais aucun autre fichier.

Étape 1 : Découvrir le dépôt

Avant de poser une question à l'utilisateur, explore la base de code :

• Liste le répertoire racine, lis le README et vérifie les fichiers config clés (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.)
• Identifie le(s) langage(s), framework(s) et ce que le projet fait
• Mappe la structure des dossiers 1–2 niveaux de profondeur
• Trouve les points d'entrée : fichiers principaux, fichiers index, amorçage d'app
• Note quels fichiers existent réellement — chaque chemin que tu écris dans la tour doit être réel

Si le dépôt est clairsemé ou vide, dis-le et travaille avec ce qui existe.

Si l'utilisateur dit « générer à partir du README » ou « utilise les docs »: exécute d'abord le générateur de squelette, puis remplis chaque [TODO: ...] en lisant les fichiers réels :

python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour

Points d'entrée par langage/framework

Ne lis pas tout — commence ici, puis suis les importations.

Variantes de type de dépôt — ajuste le focus en conséquence

La même persona demande des choses différentes selon le type de dépôt :

Pour les monorepos : identifie les 2–3 paquets les plus pertinents pour l'objectif du persona. N'essaie pas de faire la tour de tout — ouvre la tour avec un step qui explique comment naviguer dans l'espace de travail, puis reste concentré.

Stratégie pour grand dépôt

Pour les dépôts avec 100+ fichiers : n'essaie pas de tout lire.

1. Lis d'abord les points d'entrée et le README
2. Construis un modèle mental des 5–7 modules du haut
3. Pour la persona demandée, identifie les 2–3 modules qui importent vraiment et lis-les en profondeur
4. Pour les modules que tu ne couvres pas, mentionne-les dans le step intro comme « hors de portée pour cette tour »
5. Utilise les steps directory pour les zones que tu as mappées mais n'as pas lues — elles orientent sans nécessiter une connaissance complète

Une tour ciblée de 10 steps des bons fichiers vaut mieux qu'une tour éparpillée de 25 steps de tout.

Étape 2 : Lis l'intention — déduis tout ce que tu peux, demande seulement ce que tu ne peux pas

Un message de l'utilisateur devrait suffire. Lis sa demande et déduis persona, profondeur et focus avant de poser une question.

Carte d'intention

Déduis silencieusement : persona, profondeur, zone de focus, s'il faut ajouter uri/ref, isPrimary.

Demande seulement si tu ne peux vraiment pas déduire :

• « bug tour » mais aucun bug décrit → demande la description du bug
• « feature tour » mais aucune feature nommée → demande quelle feature
• « fichiers spécifiques » explicitement demandés → honore-les comme stops obligatoires

Ne demande jamais nextTour, commands, when, ou stepMarker à moins que l'utilisateur les ait mentionnés.

Recette PR tour

Pour les PR tours : définis "ref" sur la branche, ouvre avec un step uri pour la PR, couvre d'abord les fichiers modifiés, puis les fichiers inchangés mais critiques, ferme avec une checklist de reviewer.

Personnalisation fournie par l'utilisateur — honore toujours ces éléments

Étape 3 : Lis les fichiers réels — pas d'exceptions

Chaque chemin de fichier et numéro de ligne dans la tour doit être vérifié en lisant le fichier. Une tour pointant vers le mauvais fichier ou une ligne inexistante est pire que pas de tour.

Pour chaque step planifié :

1. Lis le fichier
2. Trouve le numéro de ligne exact du code que tu veux mettre en avant
3. Comprends-le assez bien pour l'expliquer à la persona cible

Si un fichier demandé par l'utilisateur n'existe pas, dis-le — ne substitue pas silencieusement un autre.

Étape 4 : Écris la tour

Enregistre dans .tours/<persona>-<focus>.tour. Lis references/codetour-schema.json pour la liste des champs faisant autorité. Chaque champ que tu utilises doit y figurer.

Racine de tour

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Titre Descriptif — Persona / Objectif",
  "description": "Une phrase : pour qui c'est et ce qu'il comprendra après.",
  "ref": "main",
  "isPrimary": false,
  "nextTour": "Titre de la tour de suivi",
  "steps": []
}

Omet tout champ qui ne s'applique pas à cette tour.

when — affichage conditionnel. Une expression JavaScript évaluée au runtime. Affiche cette tour seulement si la condition est vraie. Utile pour le lancement automatique spécifique à persona, ou pour masquer les tours avancées jusqu'à ce qu'une plus simple soit complète.

{ "when": "workspaceFolders[0].name === 'api'" }

stepMarker — intègre les ancres de step directement dans les commentaires du code source. Quand défini, CodeTour cherche les commentaires // <stepMarker> dans les fichiers et les utilise comme positions de step au lieu de (ou en plus des) numéros de ligne. Utile pour les tours sur du code en mutation active où les numéros de ligne changent constamment. Exemple : définis "stepMarker": "CT" et mets // CT dans le fichier source. Ne suggère pas cela à moins que l'utilisateur le demande — ça nécessite d'éditer les fichiers source, ce qui est inhabituel.

Types de step — référence complète

Tous les types de step : content (intro/fermeture, max 2), directory, file+line (workhorse), selection (bloc de code), pattern (correspondance regex), uri (lien externe), view (focus sur panneau VS Code), commands (exécute commandes VS Code).

Règle du chemin : "file" et "directory" doivent être relatifs à la racine du dépôt. Pas de chemins absolus, pas de ./ initial.

Quand utiliser chaque type de step

Calibrage du nombre de steps

Fais correspondre les steps à la profondeur et au persona. Ce sont des cibles, pas des limites dures.

Adapte aussi à la taille du dépôt. Un CLI de 3 fichiers ne reçoit pas 15 steps. Un monolithe de 200 fichiers ne doit pas être comprimé en 5.

Écrire d'excellentes descriptions — la formule SMIG

Chaque description doit répondre à quatre questions dans l'ordre. Tu n'as pas besoin de quatre paragraphes — mais chaque description a besoin de tous les quatre éléments, même brièvement.

S — Situation : Quoi regarde le lecteur ? Une phrase le grounding dans le contexte. M — Mécanisme : Comment ce code fonctionne-t-il ? Quel motif, règle, ou design est en jeu ? I — Implication : Pourquoi ça importe pour l'objectif de cette persona spécifiquement ? G — Gotcha : Quoi une personne intelligente se tromperait ici ? Quoi est non-obvie, fragile, ou surprenant ?

Les descriptions devraient dire au lecteur quelque chose qu'il ne pourrait pas apprendre en lisant simplement le fichier. Nomme le motif, explique la décision de design, signale les modes de défaut, et fais des références croisées au contexte connexe.

Arc narratif — chaque tour, chaque persona

1. Orientation — doit être un step file ou directory, jamais content seulement. Utilise "file": "README.md", "line": 1 ou "directory": "src" et mets ton texte de bienvenue dans la description. Un premier step content-only (pas file, directory, ou uri) se rend comme une page vierge dans VS Code CodeTour — c'est un comportement connu de l'extension VS Code, non configurable.

2. Carte haut niveau (1–3 steps directory ou uri) — modules majeurs et comment ils se rapportent. Pas tous les dossiers — juste ce que cette persona doit savoir.

3. Chemin clé (steps file/line, selection, pattern, uri) — le code spécifique qui importe. C'est le cœur de la tour. Lis et narre. Ne survole pas.

4. Fermeture (content) — quoi le lecteur comprend maintenant, quoi il peut faire ensuite, 2–3 tours de suivi suggérées. Si nextTour est défini, référence-le par nom ici.

Steps de fermeture

Ne résume pas — le lecteur vient de le lire. À la place, dis-lui quoi il peut maintenant faire, quoi éviter, et suggère 2-3 tours de suivi.

Les 20 personas

Concevoir une série de tours

Quand une base de code est assez complexe qu'une seule tour ne peut pas la couvrir bien, conçois une série. Le champ nextTour les enchaîne : quand le lecteur termine une tour, VS Code offre de lancer la suivante automatiquement.

Planifie la série avant d'écrire une quelconque tour. Une bonne série a :

• Un chemin d'escalade clair (large → étroit, orientation → deep-dive)
• Aucun step dupliqué entre tours
• Chaque tour assez autonome pour être utile en elle-même

Définis nextTour dans chaque tour au title de la suivante (doit correspondre exactement). Chaque tour devrait être assez autonome pour être utile en elle-même.

Ce que CodeTour ne peut pas faire

Si demandé pour l'un de ces, dis clairement que c'est non supporté — ne suggère pas une contournement qui n'existe pas :

Anti-motifs

Checklist de qualité — vérifie avant d'écrire le fichier

• [ ] Chaque chemin file est relatif à la racine du dépôt (pas / initial ou ./)
• [ ] Chaque chemin file lu et confirmé exister
• [ ] Chaque numéro line vérifié en lisant le fichier (pas deviné)
• [ ] Chaque directory est relatif à la racine du dépôt et confirmé exister
• [ ] Chaque regex pattern correspondrait une ligne réelle dans le fichier
• [ ] Chaque uri est une URL complète et réelle (https://...)
• [ ] ref est une vraie branche/tag/commit si défini
• [ ] nextTour correspond exactement au title d'un autre fichier .tour si défini
• [ ] Seulement des fichiers JSON .tour créés — aucun code source touché
• [ ] Le premier step a un ancre file ou directory (premier step content-only = page vierge dans VS Code)
• [ ] La tour finit avec un step fermeture content qui dit au lecteur quoi ils peuvent faire ensuite
• [ ] Chaque description répond SMIG — Situation, Mécanisme, Implication, Gotcha
• [ ] Les priorités du persona pilotent la sélection de step (coupe tout ce qui ne sert pas leur objectif)
• [ ] Le nombre de steps correspond à la profondeur demandée et à la taille du dépôt (voir table de calibrage)
• [ ] Au maximum 2 steps content-only (intro + fermeture)
• [ ] Tous les champs conformes à references/codetour-schema.json

Étape 5 : Valide la tour

Exécute toujours le validateur immédiatement après avoir écrit le fichier de tour. Ne saute pas cette étape.

python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .

Le validateur vérifie :

• La validité JSON
• Que chaque chemin file existe et chaque line est dans les limites du fichier
• Que chaque directory existe
• Que chaque regex pattern compile et correspond au moins une ligne dans le fichier
• Que chaque uri commence par https://
• Que nextTour correspond un titre de tour existant dans .tours/
• Le nombre de steps content-only (avertit si > 2)
• L'arc narratif (avertit s'il n'y a pas de step orientation ou fermeture)

Corrige chaque erreur avant de continuer. Réexécute jusqu'à ce que le validateur rapporte ✓ ou seulement des avertissements. Les avertissements sont consultatifs — utilise ton jugement. Ne montre pas la tour à l'utilisateur jusqu'à ce que la validation passe.

Problèmes VS Code courants : Le premier step content-only se rend vierge (ancre à file/directory à la place). Les chemins absolus ou préfixés ./ échouent silencieusement. Les numéros de ligne hors des limites ne font défiler nulle part.

Si tu ne peux pas exécuter les scripts, vérifie manuellement : le step 1 a file/directory, tous les chemins existent, tous les numéros de ligne sont dans les limites, nextTour correspond exactement.

Autoplay : isPrimary: true + .vscode/settings.json avec { "codetour.promptForPrimaryTour": true } invite à l'ouverture du dépôt. Omet ref pour les tours qui devraient apparaître sur toute branche.

Partage : Pour les dépôts publics, les utilisateurs peuvent ouvrir les tours à https://vscode.dev/github.com/<owner>/<repo> sans install.

Étape 6 : Résume

Après avoir écrit la tour, dis à l'utilisateur :

• Chemin du fichier (.tours/<name>.tour)
• Résumé d'un paragraphe de ce que la tour couvre et pour qui c'est
• L'URL vscode.dev si le dépôt est public (pour qu'il puisse la partager immédiatement)
• 2–3 tours de suivi suggérées (ou la prochaine tour de la série si une était planifiée)
• Tout fichier demandé par l'utilisateur qui n'existait pas (sois explicite — ne substitue pas silencieusement)

Nommage du fichier

<persona>-<focus>.tour — kebab-case, communique à la fois :

onboarding-new-joiner.tour
bug-fixer-payment-flow.tour
architect-overview.tour
vibecoder-quickstart.tour
pr-review-auth-refactor.tour
security-auth-boundaries.tour
concept-dependency-injection.tour
rca-login-outage.tour