Comment cette compétence fonctionne

Deux modes, routés automatiquement en fonction du sujet (voir tableau de routage) :

Mode A — Dépôt / concept / documentation (le chemin économique) : recherche → clone (si dépôt) → exploration → synthèse → sortie. Les agents parallèles lâches conviennent parfaitement.
Mode B — Produit web en ligne / concurrent / produit de données / algorithme / paysage concurrentiel (la totale) : éclaireur → confirmation → reconnaissance approfondie orchestrée par Workflow → capture par navigateur réel → rétro-ingénierie vers code validé → synthèse. Lisez @references/competitor-teardown.md et suivez-le.

Routage par type de sujet

Sujet	Signal	Mode	Colonne vertébrale
Dépôt GitHub	`github.com`	A	clone + agents Explore
Concept / technologie	pas d'URL	A	agents chercheur
Documentation / site statique	URL, informationnel	A	chercheur + WebFetch
Produit en ligne / app / SaaS / concurrent	URL est un produit ; "concurrent/démontage/vs nous/comment font-ils"	B	navigateur + Workflow + schéma par sujet
Calculateur / estimateur / prédicteur / tarification / classement	une formule/algorithme à déchiffrer	B	grille de sondage en direct → implémentation de référence exécutable → validation
Paysage concurrentiel complet	"trouver tous les autres / tous ceux dans ce domaine"	B	découverte d'espace de noms → démontage de l'ensemble OUI

Critère de départage : si une URL est à la fois un produit ET a de la documentation, par défaut B — la passe d'éclaireur est économique et rétrograde vers A s'il n'y a rien à démonter.

Règles d'exécution

Le bon outil pour l'échelle : Mode A = appels Task/Agent parallèles. Mode B = l'outil Workflow (pipelines, schémas de sortie structurée, reprise) dès qu'il y a 3+ sujets ou un travail en plusieurs phases.
Étayer, puis confirmer : Le mode B effectue une passe d'éclaireur économique + une porte de confirmation (périmètre + limites de reconnaissance + navigateur) avant le plongeon coûteux — sauf si l'utilisateur a déjà dit "je veux tout / vas-y à fond / everything".
Rétro-ingénierie vers du code exécutable et validé pour tout calculateur/algorithme ; comparer à la vérité terrain faisant autorité, pas aux propres affirmations du concurrent.
Riche en visuels : chaque concept majeur obtient un schéma ou un tableau.
Double sortie : afficher le résumé exécutif + l'index des fichiers dans la conversation ; sauvegarder l'ensemble complet des documents dans ~/.claude/explanations/<date>_<slug>/.
Résilient : les recherches lourdes en mode B s'exécutent en tant que Workflow en arrière-plan ; persister les artefacts de manière incrémentielle ; reprendre (resumeFromRunId) en cas de coupure.
Nettoyage : proposer de supprimer les dépôts clonés / fichiers sauvegardés une fois terminé.

Limites de la reconnaissance en mode B (critique — à lire avant tout sondage en direct)

La reconnaissance concurrentielle est légale et normale sur les surfaces PUBLIQUES. Règles complètes dans @references/competitor-teardown.md. Les invariants :

AUTORISÉ : pages/actifs publics, OpenAPI//docs public, bundles JS publics, une grille modeste et polie (~15–40, faible taux) de requêtes normales de niveau utilisateur vers des points de terminaison publics pour dériver une formule, empreinte des en-têtes, WHOIS/DNS.
JAMAIS : contourner CAPTCHA/défis anti-bot, contourner l'authentification, collecter en masse des ensembles de données complets (échantillon uniquement), effectuer des tests de charge, ou invoquer des points de terminaison administrateurs/mutants/destructeurs (les DOCUMENTER, ne pas les appeler). Observer les expositions ; ne jamais les exploiter. Ne jamais soumettre les données réelles de l'utilisateur dans un formulaire concurrent. En cas de doute, ne pas le faire — et expliquer pourquoi.

Porte d'entrée

Gestionnaire sans contexte

SI $ARGUMENTS est vide : → Utiliser AskUserQuestion :

en-tête : "Expliquer"
question : "Que souhaitez-vous que j'explique ?"
options :
- "Dépôt GitHub" - Analyser une base de code depuis GitHub
- "Site Web ou documentation" - Comprendre un site web, de la documentation ou une API
- "Concurrent / produit en ligne / paysage concurrentiel" - Démonter un produit en ligne, rétro-ingénierie d'un calculateur, ou cartographier tout un espace concurrentiel (Mode B)
- "Concept ou technologie" - Expliquer un concept, un framework ou un outil

Puis passer à context_analysis.

Analyse de contexte

Analyser $ARGUMENTS pour extraire :

Type : dépôt GitHub, site web, concept, ou autre
URL/Sujet : l'élément spécifique à expliquer
Objectif implicite : Apprendre à utiliser ? Évaluer ? Comprendre l'architecture ? Contribuer ?

Détecter le type automatiquement :

Contient github.com → dépôt GitHub (Mode A)
Signaux du mode B → "concurrent", "démontage", "rétro-ingénierie", "vs nous", "comment font-ils", "trouver tous les autres", ou une URL qui est un produit/application/calculateur → Mode B
Contient http (informationnel/documentation) → Site Web (Mode A)
Sinon → Concept (Mode A)

Questions initiales

Utiliser AskUserQuestion uniquement pour les lacunes réelles (2–3 questions max) :

Objectif (si pas clair) :

"Quel est votre objectif ?" avec options :
- "Comprendre comment ça fonctionne" - Architecture, flux, implémentation
- "Évaluer pour adoption" - Avantages/inconvénients, alternatives, adéquation à mon cas d'usage
- "Apprendre à l'utiliser" - Configuration, API, prise en main
- "Apprendre à contribuer" - Structure de la base de code, workflow de développement

Focus (si sujet large) :

"Un focus spécifique ?" avec options :
- "Tout" - Analyse complète exhaustive
- "Architecture uniquement" - Structure et motifs de haut niveau
- "Fonctionnalité spécifique" - Un aspect particulier (à préciser)

Contexte (si utile) :

"Votre niveau technique ?" avec options :
- "Non technique" - Expliquer à partir des principes de base avec des analogies
- "Technique mais nouveau dans ce domaine" - Ignorer les bases, se concentrer sur les spécificités
- "Expert" - Technique approfondi, supposer une connaissance

Porte de décision

Après les réponses, utiliser AskUserQuestion (Mode A) :

question : "Prêt à commencer l'analyse approfondie ?"
options :
- "Oui, allons-y" - Commencer l'analyse multi-phase
- "D'abord d'autres questions" - J'ai des clarifications
- "Laissez-moi ajouter du contexte" - Je veux ajouter des détails

Le mode B remplace cette porte par B2 (instantané + périmètre + limites de reconnaissance + go/profondeur/navigateur) — ne pas poser les deux ; B2 est la porte unique faisant autorité pour les démontages.

Processus

Sélection du mode

Exécuter <porte d'entrée>, puis router selon le tableau des types de sujets. Mode B (produit en ligne / concurrent / produit de données / calculateur / paysage) → charger @references/competitor-teardown.md et suivre son flux éclaireur → confirmation → approfondissement → synthèse (schéma ci-dessous). Mode A (dépôt / concept / documentation) → Phases 1–7 ci-dessous.

Mode B — Démontage d'un produit en ligne / concurrent / produit de données

Manuel complet dans references/competitor-teardown.md. Schéma :

B0 Base : vérifier la mémoire + ~/.claude/explanations/ pour une analyse antérieure ; étendre, ne pas refaire.
B1 Éclaireur : un agent léger de reconnaissance passive par cible (WebFetch + en-têtes + WebSearch) → instantané fondé + ce qui nécessite un navigateur.
B2 Porte de confirmation : présenter l'instantané + le périmètre + les limites de reconnaissance (<limites de la reconnaissance>) ; AskUserQuestion pour go/profondeur/navigateur — sauter uniquement si l'utilisateur a déjà dit "vas-y à fond / full shebang".
B3 Reconnaissance approfondie (Workflow) : un agent structuré par sujet, partageant tous le schéma par sujet (dans la référence). pipeline() par défaut ; diviser les sorties volumineuses sur le disque.
B4 Navigateur (Claude-in-Chrome) : capturer le réseau au chargement, rendre les SPA, sonder en direct les estimateurs sur une grille d'entrées, en-têtes de sécurité, copie des barrières de paiement/authentification — dans les limites (pas de contournement CAPTCHA/auth, pas de points de terminaison mutants, ne jamais soumettre les données de l'utilisateur). Persister les captures au fur et à mesure.
B5 Rétro-ingénierie : chaque calculateur → implémentation de référence TypeScript exécutable → valider par rapport à la grille en direct → comparer à la vérité terrain faisant autorité.
B6 Espace de noms (si "d'autres ?") : DNS+curl+recherche de domaines candidats, classifier, trouver des clusters d'opérateurs, signaler les domaines d'achat défensif, démonter uniquement l'ensemble OUI vraiment distinct.
B7 Synthèse : agents de synthèse en éventail → DETAILED-<slug>.md × N + ESTIMATORS.md + COMPARISON.md (incl. une section intégrité des données + clusters d'opérateurs) + REPLICATION-BLUEPRINT.md + ARCHITECTURE.md + NAMESPACE.md + SOURCES-*.md + SUMMARY.md (résumé exécutif + index des fichiers). Puis Phase 7 sortie/nettoyage.

Mode A — Dépôt / concept / documentation

Phase 1 : Recherche Web parallèle (5 agents de recherche)

Lancer TOUS dans un seul message :

Task(subagent_type="general-purpose", prompt="Recherche [SUJET] : Qu'est-ce que c'est ? Qui l'a créé ? Quand ? Pourquoi ?")
Task(subagent_type="general-purpose", prompt="Recherche [SUJET] : Stack technique, architecture, technologies clés")
Task(subagent_type="general-purpose", prompt="Recherche [SUJET] : Articles, critiques, discussions communautaires, avis")
Task(subagent_type="general-purpose", prompt="Recherche [SUJET] : Alternatives, comparaisons, quand utiliser ou non")
Task(subagent_type="general-purpose", prompt="Recherche [SUJET] : Documentation, tutoriels, guides de prise en main")

Phase 2 : Cloner le dépôt (si GitHub)

REPO_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_$(basename [URL] .git)
git clone [URL] $REPO_DIR
cd $REPO_DIR

Phase 3 : Exploration parallèle de la base de code (6 agents Explore)

Lancer TOUS dans un seul message avec minutie="très minutieuse" :

Task(subagent_type="Explore", prompt="Architecture : Structure globale, modules, comment ils se relient")
Task(subagent_type="Explore", prompt="Points d'entrée : Fichiers principaux, CLI, points de terminaison API, comment ça démarre")
Task(subagent_type="Explore", prompt="Logique métier : Algorithmes clés, motifs, abstractions")
Task(subagent_type="Explore", prompt="Configuration : Paramètres, environnement, points d'extensibilité")
Task(subagent_type="Explore", prompt="Dépendances : Paquets clés, intégrations, services externes")
Task(subagent_type="Explore", prompt="Tests et qualité : Motifs de test, couverture, CI/CD")

Phase 4 : Contexte parallèle Claude Code (2–3 agents généralistes)

Si pertinent pour Claude/AI/agents :

Task(subagent_type="general-purpose", prompt="Expliquer les concepts pertinents de Claude Code pour comprendre ceci")
Task(subagent_type="general-purpose", prompt="Comparer aux outils/SDK Claude si applicable")

Phase 5 : Vérification à mi-parcours (si complexe)

Utiliser AskUserQuestion si les constats révèlent de la complexité :

"J'ai trouvé [X]. Voulez-vous que je me concentre sur quelque chose de spécifique ?"
Options basées sur les découvertes

Phase 6 : Synthèse

Combiner tous les constats en une explication complète avec :

Analogie d'ouverture (comparaison non technique)
Ce que c'est (1–2 phrases)
Schéma d'architecture (ASCII)
Comment ça fonctionne (étape par étape avec schémas)
Tableau des composants clés (nom, objectif, fonctionnement)
Ce qui est spécial (différenciateurs)
Liste des capacités (ce qu'il peut faire)
Tableau de comparaison (vs alternatives)
Analyse technique approfondie (détails d'implémentation)
Pièges et considérations

Phase 7 : Sortie

Afficher dans la conversation

Explication complète formatée avec tous les visuels.

Sauvegarder dans des fichiers

OUTPUT_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_[slug-du-sujet]
mkdir -p $OUTPUT_DIR

# Fichiers à sauvegarder :
# $OUTPUT_DIR/SUMMARY.md - Référence rapide (version 30 secondes)
# $OUTPUT_DIR/DETAILED.md - Analyse complète
# $OUTPUT_DIR/ARCHITECTURE.md - Tous les schémas
# $OUTPUT_DIR/COMPARISON.md - Analyse des alternatives

Suivi

Après l'affichage, demander :

"Quel aspect souhaitez-vous explorer plus en détail ?"
"Des questions sur ce que j'ai expliqué ?"
Encourager le suivi

Nettoyage

Utiliser AskUserQuestion pour le nettoyage (combiner si les deux s'appliquent) :

Si dépôt cloné :

question : "Supprimer le dépôt cloné ?"
options :
- "Oui, supprimez-le" - Supprimer $REPO_DIR automatiquement
- "Non, gardez-le" - Afficher le chemin : "Dépôt conservé à : $REPO_DIR"

Si oui : rm -rf $REPO_DIR Si non : Afficher le chemin pour accès manuel

Toujours (fichiers d'explication) :

question : "Supprimer les fichiers d'explication sauvegardés ?"
options :
- "Oui, supprimez-les" - Supprimer $OUTPUT_DIR automatiquement
- "Non, gardez-les" - Afficher le chemin : "Explications sauvegardées à : $OUTPUT_DIR"

Si oui : rm -rf $OUTPUT_DIR Si non : Afficher le chemin pour accès manuel

Question combinée (si dépôt ET fichiers) :

question : "Analyse terminée. Que souhaitez-vous nettoyer ?"
options :
- "Supprimer le dépôt et les fichiers d'explication"
- "Supprimer uniquement le dépôt, garder les explications"
- "Supprimer uniquement les explications, garder le dépôt"
- "Tout garder"

Exécuter les suppressions en fonction de la sélection, afficher les chemins pour tout ce qui est conservé.

Formats de schémas standards

Architecture :

┌─────────────┐     ┌─────────────┐
│  Composant  │────►│  Composant  │
└─────────────┘     └─────────────┘

Flux :

DÉBUT → Étape 1 → Étape 2 → Décision ?
                              ├─ Oui → Chemin A
                              └─ Non → Chemin B

Tableau de comparaison :

| Aspect        | Option A | Option B | Gagnant |
|---------------|----------|----------|---------|
| Vitesse       | Rapide   | Lent     | A       |

Décomposition des composants :

┌──────────────────────────────────────┐
│           Nom du système             │
├──────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐    │
│ │Module A│ │Module B│ │Module C│    │
│ └───┬────┘ └───┬────┘ └───┬────┘    │
│     └──────────┴──────────┘         │
│           Couche partagée            │
└──────────────────────────────────────┘

Critères de succès

Les deux modes :

Ont posé des questions de clarification / ont étayé avant de commencer ; routé vers le bon mode
Ont produit des schémas visuels pour chaque concept majeur ; ont inclus une profondeur technique reproductible
Ont affiché le résumé exécutif dans la conversation ET sauvegardé l'ensemble des documents dans des fichiers
Ont proposé un suivi + nettoyage ; respecté le choix de conservation/suppression de l'utilisateur

Le mode B (produit en ligne / concurrent / produit de données / paysage) aussi :

A effectué une passe d'éclaireur + une porte de confirmation (ou honoré un "vas-y à fond" explicite) et a énoncé les limites de la reconnaissance
Est resté strictement dans les limites : pas de contournement CAPTCHA/auth, pas de collecte en masse, pas d'appel à des points de terminaison mutants/administrateurs, jamais soumis les données de l'utilisateur ; expositions observées non exploitées
A utilisé l'outil Workflow avec un schéma partagé par sujet dès 3+ sujets/plusieurs phases ; artefacts persistés ; résilient aux coupures (reprise)
A sondé en direct chaque calculateur et livré une implémentation de référence exécutable validée N/N par rapport aux sorties observées, comparée à la vérité terrain faisant autorité
Pour les paysages : a découvert l'espace de noms complet, classé chacun, trouvé des clusters d'opérateurs, signalé les domaines d'achat défensif, démonté uniquement les plus distincts
La synthèse inclut une section d'intégrité des données + une section clusters d'opérateurs + un plan de réplication + un index des fichiers + un résumé exécutif

adamjali/explain

Qu'est-ce que explain ?

Demander à votre IA préférée

Documentation