analyze-reference
Extraire des motifs, ne pas cloner. Cette compétence lit UNE page publique (plus au plus deux liens internes nommés par l'utilisateur), décrit comment elle est construite et comment elle bouge en termes abstraits, et écrit patterns/<slug>.md. Rien du site n'est stocké : pas d'images, vidéos, 3D, logos, textes, codes, noms de polices de marque ou codes couleur. Les captures d'écran sont du matériel de travail temporaire sous .cache/analyze/ (ignoré par git) et sont toujours supprimées à la fin.
Ceci est une directive pour le flux de travail propre du dépôt, pas un conseil juridique. Consultez un avocat en propriété intellectuelle avant de productiser (voir docs/roadmap.md).
Entrées
url(obligatoire) : une page http(s) publique. Tout ce qui se trouve derrière une connexion, un paywall ou un défi bot est hors de portée.--focus "..."(optionnel) : ce que l'utilisateur aime sur le site, dans ses mots. Oriente quelles sections de la fiche reçoivent de la profondeur. Enregistrez-le dans le frontmatter (nonesi omis).- Jusqu'à 2 liens internes (optionnel, même site) : analysez chacun avec les mêmes étapes et fusionnez dans une seule fiche. Ne jamais crawler plus loin.
Slug : dérivé du host (www. supprimé, points en tirets, ex. example-com). Passez --slug à recon.mjs si l'utilisateur en nomme un. Si patterns/<slug>.md existe déjà, demandez avant de le remplacer.
Toutes les commandes s'exécutent depuis la racine du dépôt. Les scripts se trouvent dans .claude/skills/analyze-reference/scripts/ ; chacun répond à --help.
Étapes
Exécutez-les dans l'ordre. L'étape 6 (nettoyage) s'exécute quelle que soit la façon dont les étapes 1 à 5 se terminent : succès, abandon ou erreur. Traitez-la comme un finally.
1. Vérifier les permissions (avant de toucher le site avec un navigateur)
node .claude/skills/analyze-reference/scripts/check-robots.mjs <url>
Il évalue robots.txt pour *, ClaudeBot, anthropic-ai et GPTBot, l'en-tête X-Robots-Tag, <meta name="robots">, et les réservations text-and-data-mining (TDMRep : /.well-known/tdmrep.json, en-tête et meta tdm-reservation). Codes de sortie : 0 autorisé, 1 bloqué, 2 ne peut pas vérifier.
- Sortie
1ou2: ARRÊTEZ. Ne produisez aucune fiche, n'exécutez aucune reconnaissance. Dites à l'utilisateur les raisons exactes que le script a imprimées. La sortie2(5xx, timeout, fichiers illisibles) est un abandon conservateur : dites que les permissions n'ont pas pu être vérifiées ; ne réessayez pas en boucle et ne cherchez pas d'autre moyen d'entrée. - Exécutez-le aussi pour chaque lien interne supplémentaire.
- Une erreur 404 pour
robots.txtcompte comme autorisé ; une erreur 401/403 compte comme interdit.
2. Reconnaissance
node .claude/skills/analyze-reference/scripts/recon.mjs <url> [--slug <slug>]
Playwright (Chromium sans tête ; définissez QA_CHROME_PATH ou CHROME_PATH si le navigateur propre de Playwright n'est pas installé) charge la page, la fait défiler, et écrit .cache/analyze/<slug>/recon.json et screens/{375,768,1440}-<n>.png. Le JSON ne contient que la structure et les statistiques : sections dans l'ordre avec hauteurs et comptes de titres/mots (jamais de texte), tailles de police agrégées, hauteurs de ligne, espacements, utilisation de grille/flex, polices classifiées comme serif/sans/mono/display (jamais nommées), couleurs comme descriptions de rôle (jamais de codes), bibliothèques détectées avec preuve et confiance, domaines réseau, présence de canvas/WebGL, et observations de mouvement (reveal, pin, parallax, scrub, en-tête collant, défilement adouci).
Conteneurs de défilement. Certaines pages gardent le document à la hauteur d'une vue et défilent un wrapper interne. recon.mjs détecte cela (l'élément visible overflow-y: auto|scroll|overlay couvrant au moins 60% de la zone d'affichage avec la plus grande plage de défilement) et l'utilise pour les captures d'écran, l'échantillonnage de mouvement et la sonde de roue. recon.json enregistre scroller: { kind: "document" | "container", scrollHeightPx, clientHeightPx }, et viewports[w].docHeightPx est la hauteur défilable réellement utilisée. Vérifiez scroller.kind lors de la lecture des preuves. L'heuristique est enregistrée, non garantie : si les captures d'écran montrent un panneau latéral ou une modale au lieu de la page, dites-le dans la fiche. Non couverts : les défilements imbriqués ou horizontaux, et les scènes pilotées par des événements de roue sans élément défilable. Une page peut aussi arrêter de défiler à une largeur donnée (par exemple un point de rupture tablette) ; alors une capture d'écran à cette largeur est correcte.
Derrière un proxy. Quand HTTPS_PROXY ou HTTP_PROXY est défini (sessions cloud), check-robots.mjs et recon.mjs se réexécutent une fois avec NODE_USE_ENV_PROXY=1 pour que fetch de Node l'utilise, et recon.mjs passe le proxy à Chromium (le loopback reste direct). Aucun flag nécessaire ; la ligne d'avertissement expérimental de Node est cachée. Les certificats proviennent de NODE_EXTRA_CA_CERTS comme d'habitude ; les scripts ne les lisent ni ne les intègrent jamais. Sans proxy, rien ne change.
La sortie 3 signifie que la page n'est pas analysable (formulaire de connexion, défi bot, HTTP 401/403/429, inaccessible). ARRÊTEZ : pas de fiche, dites à l'utilisateur pourquoi (pour une page de connexion : "the page is not public"). N'essayez jamais de contourner un blocage, de résoudre un défi, de vous connecter ou de changer l'agent utilisateur.
3. Lire les preuves
- Lisez entièrement
.cache/analyze/<slug>/recon.json. - Visualisez les captures d'écran avec l'outil de lecture, au moins quelques-unes par largeur, pour juger ce que les chiffres ne peuvent pas : composition du hero, rythme, densité, où une mise en page casse la grille, ce qui bouge. Elles sont pour vos yeux uniquement ; ne les copiez, intégrez ou référencez jamais.
- Confiance : un élément global ou une classe DOM plus un nom de script correspondant est
high; un seul des deux estmedium; un seul domaine réseau estlow. Les bibliothèques regroupées dans le code de l'application apparaissent seulement comme des correspondances de noms de script, donc dites "likely" et conservez la confiance rapportée par la reconnaissance.
4. Écrire la fiche
Copiez la structure de patterns/_template.md dans patterns/<slug>.md. Remplissez le frontmatter (url, slug, la date du jour au format YYYY-MM-DD, focus, libraries comme une liste de noms) et chaque section, dans vos propres mots :
| Section | Contenu |
|---|---|
| Summary | Quel type de page c'est et pourquoi elle vaut la peine d'être étudiée |
| Section map | Sections ordonnées : rôle, hauteur approximative en viewports, idée de mise en page |
| Hero | Type de hero, composition du premier écran, ce qui bouge au chargement |
| Grid and spacing | Système de colonnes, classe de largeur de contenu, échelle d'espacement (unité de base), rythme vertical |
| Typography | Classes génériques ("large grotesque display + serif body"), ratio d'échelle, graisses, habitudes de hauteur de ligne et de crénage, casse |
| Palette | Rôles et tons ("fond presque noir, accent chaud saturé"), caractère de contraste, thème |
| Density | Contenu par écran, espaces blancs, idées par section, équilibre texte-média |
| Motion | Tableau : moment, déclencheur (load, scroll, hover), type (reveal, pin, parallax, scrub, page transition, shader/3D), technique et bibliothèque, confiance |
| Libraries | Bibliothèques détectées avec la classe de preuve et la confiance |
| What to take / what to avoid | Ce qu'il faut réutiliser comme motif dans une landing originale, et ce qui est trop spécifique ou risqué à imiter |
Entrées de motion : une ligne par effet pertinent. Une section qui se fixe pendant que son contenu s'anime avec le défilement a pour déclencheur scroll, type pin+scrub, avec la bibliothèque et sa confiance. Le comportement au survol n'est pas mesuré par la reconnaissance ; regardez les captures d'écran ou le compte hoverTransitionElements et indiquez votre confiance comme faible lorsque vous l'inférez.
5. Valider
npm run validate:patterns
Il doit réussir. S'il signale des violations fichier:ligne, réécrivez ces lignes de manière plus abstraite et relancez-le. N'affaiblissez jamais le validateur, et n'utilisez jamais une ligne > note: pour faire passer du copier-coller : ce préfixe n'exempte que vos propres remarques courtes de la règle des longues citations.
Optionnel, seulement si un effet marqué comme intéressant reste inexpliqué après l'étape 3 : npx rea-agents analyze-javascript-application <url> (lourd, jamais requis). Enregistrez seulement une conclusion écrite ("chemin de caméra lié au défilement piloté par une bibliothèque de timeline, confiance moyenne"), jamais sa sortie, son code ou ses vidages. Sautez-le s'il a besoin d'un accès réseau que vous n'avez pas.
6. Nettoyage (toujours)
node .claude/skills/analyze-reference/scripts/recon.mjs --cleanup <slug>
Exécutez-le après un succès, après un abandon à n'importe quelle étape, et après une erreur. Confirmez ensuite que .cache/analyze/<slug> a disparu et que git status ne montre rien du site (seulement patterns/<slug>.md en cas de succès). recon.mjs supprime également son propre dossier en cas d'échec, mais vous exécutez quand même le nettoyage.
7. Rapporter à l'utilisateur
Dites ce qui a été analysé, le chemin de la fiche, les bibliothèques avec leur confiance, tout ce que vous n'avez pas pu déterminer, et qu'un humain doit relire la fiche dans la PR. En cas d'abandon : la raison, et qu'aucune fiche n'a été écrite.
Règles d'abstraction (strictes)
Ne mettez jamais ce qui suit dans la fiche, le résumé de chat de la fiche, un commit ou tout fichier versionné :
- Texte du site : titres, corps de texte, microcopy, texte alternatif, méta-descriptions (seuls le titre de la page et l'URL sont autorisés).
- URL d'images, vidéos, polices, modèles 3D ou icônes, et tout fichier d'actif.
- Code source, balisage, CSS, JS ou fragments de shader, même courts, minifiés ou modifiés.
- Codes couleur Hex,
rgb(),hsl()ou autres. Décrivez-les par rôle et ton. - Noms de polices de marque ou propriétaires. Utilisez des classes génériques.
- Logos, marques, illustrations.
Écrivez sur les motifs comme un designer le ferait en briefing un collègue : "section d'énoncé fixée, contenu défilé sur environ une vue supplémentaire", pas une transcription du balisage. Si vous n'êtes pas sûr qu'un détail soit un contenu ou un motif, laissez-le de côté.
Cas d'abandon
| Situation | Action |
|---|---|
robots.txt interdit le chemin pour *, ClaudeBot, anthropic-ai ou GPTBot | Arrêtez à l'étape 1, signalez la règle correspondante, pas de fiche |
Réservation TDM (fichier TDMRep, en-tête ou meta, ou directive robots.txt) | Arrêtez à l'étape 1, signalez-le, pas de fiche |
noai, noindex ou none dans X-Robots-Tag ou meta robots | Arrêtez à l'étape 1, signalez-le, pas de fiche |
| Les permissions ne peuvent pas être vérifiées (5xx, timeout, fichier illisible) | Arrêtez à l'étape 1, dites "cannot verify permissions", pas de fiche |
| Formulaire de connexion, paywall, HTTP 401/403/429, défi bot | Arrêtez à l'étape 2, dites que la page n'est pas publique ou bloque les navigateurs automatisés, pas de fiche ; ne contournez pas |
| URL inaccessible ou réponse non-2xx | Arrêtez à l'étape 2, signalez l'erreur, pas de fiche |
| La validation échoue toujours | Corrigez en abstraant davantage ; si elle ne peut pas réussir sans perdre le point, dites-le et n'écrivez pas de fiche |
Dans tous les cas d'abandon, exécutez l'étape 6.
Attribution
L'approche de reconnaissance (captures d'écran à plusieurs largeurs, structure DOM, styles calculés, observation des interactions et du défilement) est adaptée des phases de reconnaissance de la compétence clone-website dans JCodesMore/ai-website-cloner-template, licence MIT. Seule l'idée des phases de reconnaissance a été réutilisée et réécrite pour une description abstraite ; aucun code, et aucune de ses phases de téléchargement d'actifs ou de reconstruction, n'est inclus.