Communitygithub.com

Vigiles — Site de destination

Le guide de conception, d’UX et de contenu pour le site vitrine vigiles.sh (site/). À lire avant toute modification de site/ et à utiliser comme référence pour chaque changement.

Qu'est-ce que Vigiles — Site de destination ?

Ce skill définit la barre de conception et l’orientation produit pour le site de destination de Vigiles (site/), un outil CLI qui audite les configurations des agents d’IA comme Claude Code ou Codex. Il impose une philosophie de « conception par soustraction » : chaque élément ajouté doit être justifié, et tout ce qui ne sert pas la conversion unique (exécuter `npx vigiles audit`) doit être supprimé. Le skill détaille les règles pour la démo en direct (gradation publique, pas de résultats fabriqués), le partage des résultats (liens profonds stables), l’analyse (Plausible/Fathom, pas Vercel), et le traitement des dépôts privés. Il est destiné aux développeurs qui conçoivent ou révisent le site, et s’applique uniquement au dossier `site/`, pas à `docs/` ni à l’application elle-même. Les plateformes cibles sont Claude Code, Codex et Cursor, et le skill agit comme une « spécification de conception vivante » qui évolue avec les décisions stratégiques.

Compatible avec✓Claude Code✓Codex CLI✓Cursor✓Antigravity
npx skills add https://github.com/zernie/vigiles/tree/HEAD/.claude/skills/landing-site

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Site de destination — objectif, UX et barre de conception

La porte d’entrée est site/ (Vite + React + Tailwind, mode sombre uniquement), déployée sur vigiles.sh. Ce skill est la référence à laquelle chaque changement est mesuré. L’échec récurrent qu’il vise à empêcher : ajouter des éléments au lieu d’en retirer, ce qui rend la page chargée et générique (« à la Tilda ») plutôt que moderne.

La règle d’or : en cas de doute, SUPPRIME. Conception par soustraction. Si la suppression d’un élément ne fait perdre aucun sens, supprimez-le. Tout changement qui ajoute une boîte, une légende, un second bouton ou une ligne de réassurance est suspect jusqu’à preuve de sa nécessité.

Objectif (à quoi sert le site)

  • OBJECTIF PRINCIPAL — maximiser le % de visiteurs qui exécutent EFFECTIVEMENT npx vigiles audit. C’est le SEUL indicateur de conversion auquel chaque décision de conception sert. L’appel à l’action doit être EXCELLENT (sans friction, évident, toujours accessible). Si un changement n’aide pas quelqu’un à exécuter la commande, il n’a pas sa place.
  • Public : des développeurs qui vivent déjà dans des outils de codage agentiques (Claude Code, Codex, Cursor). Ils sont sceptiques et parcourent rapidement sur un téléphone.
  • L’effet « waouh » est le rapport gradué — montrez le résultat, n’expliquez pas le mécanisme.
  • Promesse de la porte d’entrée : « Lighthouse pour votre harnais d’agent » — une note en une commande, zéro configuration, rien à télécharger de vos compétences/hooks/sous-agents/références.
  • LE CADRE DE DÉMO REMPLIT QUATRE FONCTIONS À LA FOIS — concevez pour les quatre, ne laissez pas l’une évincer les autres. (1) INTRODUCTION — apprenez ce qu’est Vigiles en un coup d’œil (le rapport gradué EST le pitch). (2) DÉMO — des notes réelles instantanées sans effort (les puces FEATURED intégrées). (3) EXÉCUTION DANS LE NAVIGATEUR — notez votre dépôt public EN DIRECT en le tapant (API anonyme de GitHub ; public uniquement). (4) COPIE DE COMMANDE pour le reste — un dépôt privé ou local ne peut pas s’exécuter dans le navigateur, donc le travail ici est une COPIE propre et évidente de npx vigiles audit (un transfert de commande, PAS une fausse exécution dans le navigateur). Deux règles de clarté en découlent et sont essentielles : (a) le cadre doit toujours indiquer CLAIREMENT QUEL dépôt est affiché et s’il s’agit d’un EXEMPLE PRÉDÉFINI (une puce) ou du VÔTRE (tapé) — jamais ambigu ; (b) le chemin du dépôt privé est une fonctionnalité de première classe, pas une réflexion après coup intégrée dans une phrase — une copie de commande propre et étiquetée, vérifiée à 390 px. Ne répétez pas la commande sur trois lignes empilées (l’en-tête affichant $ vigiles audit <slug> au-dessus d’une puce en surbrillance qui la nomme déjà, c’est TROP — le travail de l’en-tête est d’IDENTIFIER le dépôt noté + sa source, pas de réafficher la commande).
  • CONTENU : concret plutôt qu’astucieux, et ne JAMAIS éveiller un doute que le lecteur n’avait pas déjà. Deux erreurs réelles que cela empêche : (1) un titre astucieux qui semble cryptique (« « Valide » n’est pas « vrai ». ») — menez par la douleur concrète (« Configuration valide. Agent cassé. »), laissez les cartes ci-dessous porter la nuance ; (2) une FAQ DÉFENSIVE qui met en lumière une faiblesse que le lecteur n’avait pas remarquée (« Est-ce assez stable pour l’adopter ? » attire l’attention sur un numéro de version effrayant) — remplacez les semeurs de doute par des éléments de confiance qu’un sceptique demande réellement (« Est-ce que quelque chose quitte ma machine ? », « Puis-je noter un dépôt privé ? »). Testez chaque ligne en tant que sceptique : est-ce que cela me donne PLUS ou MOINS envie d’exécuter la commande ? Si moins, coupez ou reformulez.
  • CRÉDIBILITÉ : le rapport de démo montre UNIQUEMENT des analyses réelles — ne fabriquez jamais de résultat. La marque est « mesuré, pas prétendu », donc un seul nombre codé en dur/faux dans le rapport empoisonne rétroactivement la confiance dans toutes les découvertes réelles. Un APERÇU VERROUILLÉ avec des ESPACES RÉSERVÉS HONNÊTES (tiret cadratin « exécuter pour remplir », pas de chiffres) pour un élément qui ne peut vraiment pas être exécuté ici (taux de déclenchement limité par modèle) convient — cela ne FAIT RIEN de faux. Des « résultats » fabriqués pour un élément que l’outil calcule réellement, ce n’est PAS acceptable — montrez le RÉSULTAT RÉEL calculé ou gardez-le comme une carte explicative honnête À L’EXTÉRIEUR du cadre du rapport.
  • Réduisez la friction pour essayer : proposez des dépôts OSS populaires PRÉREMPLIS comme puces « notez ceci » en un clic, afin qu’un visateur voie un rapport réel sans taper ni avoir son propre dépôt. EXPÉDIÉ — les puces FEATURED dans DemoAudit affichent des rapports réels intégrés instantanément.
  • CHAQUE SURFACE DE RÉSULTAT COMPORTE UNE FONCTIONNALITÉ DE PARTAGE ET UN LIEN STABLE. Une note qu’un lecteur ne peut pas transmettre à un coéquipier est une impasse, donc : (1) chaque note terminée est un lien profond copiable (vigiles.sh/?repo=owner/repo#try) qui EXÉCUTE AUTOMATIQUEMENT l’audit au chargement — l’URL EST l’unité de partage ; (2) tout résultat obtient un partage en un tap (feuille de partage native sur mobile, copie de lien ailleurs — le ShareRow dans DemoAudit) ; (3) le lien profond est le même slug que celui utilisé par l’entrée/les puces, donc un lien partagé, un dépôt tapé et une puce aboutissent tous au même chemin de code. Une nouvelle surface de résultat DOIT avoir les deux. EXPÉDIÉ — continuez à le faire fonctionner. (Les règles de réputation sous lesquelles cela fonctionne — le partage est facultatif, le refus est libre, les artefacts de note ne sont pas des personnes — sont la règle gate-first-adoption dans le CLAUDE.md racine ; ne les répétez pas ici.)
  • Instrumentez la conversion : analyses sur l’entonnoir (copies de commande, envois tapés, essais de puces, re-notes, clics de partage). Le site est sur GitHub Pages, PAS sur Vercel — donc Vercel Analytics ne s’applique PAS. Utilisez une analyse légère, respectueuse de la vie privée, par balise de script pour un hébergement statique : Plausible / Fathom / GoatCounter. L’entonnoir est déjà INSTRUMENTÉ — track() (site/src/lib/track.ts) déclenche des événements demo_* et est une opération sans danger jusqu’à ce qu’un fournisseur soit câblé. RESTANT : ajoutez la balise de script du fournisseur dans index.html et confirmez que les événements arrivent. Les analyses portent UNIQUEMENT sur le type de RÉSULTAT, jamais un slug tapé (un nom de dépôt privé ne doit pas fuiter).

Direction — décisions de référence (à conserver ; c’est là que vit la DIRECTION)

Les choix stratégiques derrière le site actuel. Mettez à jour cette section lorsqu’une direction change — c’est le document de conception, pas seulement un guide de style. Chacune est une décision qui a coûté de réelles itérations pour être atteinte ; n’en annulez pas une en silence.

  • LA DÉMO PAR DÉFAUT DOIT MONTRER UNE DÉTECTION — menez par une note faible réelle, jamais un mur de A. Les puces FEATURED forment une échelle F → C → B → A authentique sur des dépôts RECONNAISSABLES (actuellement davila7/claude-code-templates F, disler/claude-code-hooks-mastery C, madappgang B, obra/superpowers A). POURQUOI cela doit être ainsi : les plugins populaires réels obtiennent pour la plupart une note A/B sur l’axe déterministe que le navigateur peut exécuter — les échecs dramatiques (les compétences ne se déclenchent pas, les descriptions se heurtent) se situent dans le niveau de taux de déclenchement limité par modèle que le navigateur NE PEUT PAS exécuter — donc une valeur par défaut bien propre argumente CONTRE l’outil (« tout va bien, pourquoi en ai-je besoin ? »). La valeur par défaut doit être un dépôt réellement cassé pour que l’effet « waouh » (le rapport) montre Vigiles en train de détecter quelque chose. Rafraîchir la valeur par défaut de note faible (les dépôts sont corrigés avec le temps) : balayez avec git clone https://github.com/<slug> puis node dist/cli.js audit <dir> --json (REMARQUE : codeload/api.github.com sont bloqués par proxy dans l’environnement cloud — git clone via github.com fonctionne). Choisissez un dépôt qui est (a) reconnaissable, (b) a des constatations OBJECTIVES, réparables en une ligne (outil mort, répertoire skills/ invisible, événement de hook mort — pas gênant par conception), afin que la note publique soit juste (le modèle Lighthouse EST des notes publiques d’artefacts publics). Intégrez le rapport dans site/src/demo/reports/ et connectez-le dans FEATURED. Les constatations au niveau modèle restent EN DEHORS de la démo du navigateur : elle est uniquement déterministe par conception (voir les invariants de la démo dans le navigateur ci-dessous), donc la surface honnête pour elles est l’aperçu LockedRow, pas un résultat fabriqué.
  • LES NOMS SANS JAMAIS EXPLIQUER est l’erreur de contenu n° 1 — expliquez chaque concept ou supprimez-le. Un visiteur novice ne sait pas ce que signifient « linter », « référence », « appliquer », « spécification » ou un nom de catégorie. Chaque concept reçoit une explication en anglais simple à la PREMIÈRE utilisation, ou est supprimé. Ne mentionnez pas de jargon (l’ANCIEN README l’a appris — « DÉFINISSEZ HARNACHE à la première utilisation » ; le site a régressé et a dû le réapprendre). Testez chaque ligne en tant qu’utilisateur novice de Claude Code/Codex qui n’a jamais entendu parler de Vigiles.
  • INTÉGREZ LES ÉCHOS DANS LE RAPPORT — n’ajoutez pas de cartes explicatives autonomes. Le rapport EST l’effet « waouh ». Un concept que le navigateur ne peut pas montrer (taux de déclenchement limité par modèle, la référence croisée du linter qui nécessite votre configuration locale) est une ligne pointillée UNIQUEMENT CLI À L’INTÉRIEUR du rapport (LockedRow / CliRulesRow dans report-view/src/Report.tsx), pas une carte flottant en dessous du cadre. Si le site explique le rapport à deux endroits, supprimez l’écho (c’est pourquoi la bande à cinq catégories Wedge et la carte autonome « Vos règles → appliquées » ont été supprimées — le rapport porte déjà les deux).
  • UNE SEULE AFFORDANCE DE SAISIE À LA FOIS — onglets Public/Privé, pas une pile. La saisie du héros était une saisie + légende « API publique » + transfert de commande privé + ligne de confidentialité, le tout empilé (chargé). C’est maintenant des onglets Public | Privé dans DemoAudit : Public = la zone de saisie de dépôt en direct ; Privé = la copie de commande npx vigiles audit. Une affordance visible à la fois.
  • APERÇU HONNÊTE, JAMAIS DE FLOU/FAUX (remplace toute note antérieure de « l’afficher flouté »). La ligne limitée par modèle utilise des espaces réservés avec tiret cadratin (rappel — · précision —), PAS des chiffres flous faux. Le flou est interprété comme un bug de rendu ET un motif sombre de paywall, et fabriquer un nombre brise le principe « mesuré, pas prétendu » — doublement faux à côté d’un texte qui se moque des nombres prétendus. Si un aperçu plus fort est jamais souhaité, utilisez un nombre RÉEL mesuré avec une étiquette exemple, jamais un nombre fabriqué/flou.

Exigences UX

  • Priorité à la commande. npx vigiles audit est l’action universelle (fonctionne sur tous les OS, tous les terminaux). C’est l’appel à l’action PRINCIPAL. Tout le reste est secondaire.
  • Le lien profond Claude Code (claude-cli://) est une AMÉLIORATION UNIQUEMENT BUREAU, jamais le chemin principal — il échoue silencieusement sur mobile / CC Web / bureau sans CC. Ne l’affichez que là où il peut fonctionner ; n’expédiez jamais un bouton qui ne fait rien.
  • Soyez honnête sur mobile. Pas de boutons morts. Lorsqu’une action réservée au bureau ne peut pas s’exécuter, dites-le clairement et donnez l’action réelle (la commande) à la place.
  • Une action principale par écran. Les actions secondaires sont discrètes — un lien texte ou une pilule légère, jamais un second bouton lourd pleine largeur en compétition avec l’action principale.
  • Neutre en matière de harnais. Dites « Claude Code ou Codex », ne commencez pas par Claude Code — c’est un détail d’implémentation, pas le titre. Ne surexpliquez pas les détails internes.
  • Faible friction + accueillant. Un lecteur rapide doit comprendre ce que c’est et comment l’essayer en un écran, sans lire un mur de texte.

Barre de conception — moderne et minimaliste (les règles anti-encombrement)

Référez-vous à l’ambiance de Linear / Vercel / Raycast : foncé avec confiance, espace généreux, peu de mots, un point focal clair par section. PAS un modèle surchargé de fonctionnalités.

  • Chaque élément doit gagner sa place. Supprimez tout ce qui ne fait que répéter un autre (une légende répétant la capture d’écran ; une ligne de confiance dite deux fois ; un sous-titre redondant).
  • Supprimez toute étiquette qu’un autre élément IMPLIQUE DÉJÀ. Un badge « libre & open source » est redondant lorsqu’un lien GitHub/étoiles est présent ; un badge « AUDITER UN DÉPÔT SPÉCIFIQUE » au-dessus d’un titre « Noter un dépôt spécifique » le répète. Si le contexte indique déjà l’information au lecteur, l’étiquette est du bruit.
  • Chaque lien/CTA est ACTIONNABLE et spécifique. Le lecteur doit savoir exactement ce qui se passe au clic. Pas de liens secondaires vagues ou passifs (« Vous avez Claude Code ?… »). Si un chemin secondaire ne vaut pas une action claire et concrète, supprimez-le (ou déplacez-le dans la navigation, où un lien persistant bat un lien plié faible).
  • Un point focal par section. L’œil doit atterrir sur une chose en premier.
  • Espaces blancs + typographie plutôt que boîtes. N’empilez pas 3+ boîtes bordées pleine largeur ; cette répétition est ce qui donne une impression de surcharge. Préférez la hiérarchie typographique et l’espace aux bordures. Mais les espaces blancs doivent être intentionnels — pas de vides de fenêtre presque vides non plus.
  • Réassurance une fois, en une ligne. Le texte de confiance (« rien téléchargé ») apparaît une fois, compact — jamais un paragraphe de 3 lignes, jamais répété par section.
  • Cohésion. Le héros (badge + titre + sous-titre + visuel) doit se lire comme UNE idée, chaque partie ajoutant une information nouvelle. Si le sous-titre ne fait que dire ce que la capture d’écran montre déjà, coupez-le ou renforcez-le.
  • Retenue dans la couleur/l’emphase. Un accent, des couleurs de bande sémantiques qui signifient toujours quelque chose (bandes de notes). Gras sur une phrase par point, pas sur chaque clause. Pas de confettis d’émojis décoratifs.
  • Échelle d’espacement cohérente. Ne réglez pas manuellement des marges ponctuelles qui contredisent le rythme.

Anti-patrons (choses qui ont mal tourné ici)

  • Empiler la saisie + gros bouton + ligne de confiance de 3 lignes + séparateur + commande + légende + un autre bouton dans un même pli. (Solution : gardez ~3 éléments, supprimez le reste.)
  • Une légende sous la photo du produit répétant la photo du produit.
  • Ajouter une notification/un bouton par problème au lieu de repenser le flux.
  • Deux CTA principaux concurrents (lien profond + commande) sans hiérarchie.
  • Cadrage CC-first (« s’exécute dans votre propre Claude Code… ») comme réassurance de titre.
  • Un flux réservé au bureau (le lien profond claude-cli:// de Claude Code) laissé visible sur mobile comme solution de repli qui répète simplement la commande déjà montrée dans une autre section — le même bloc npx vigiles audit dans des sections consécutives sur le téléphone. (Solution : hidden sm:block toute la section réservée au bureau ; le héros + CTA la portent déjà.)

Démo dans le navigateur (EXPÉDIÉE — les invariants à conserver)

La démo en direct « noter n’importe quel dépôt » est CONSTRUITE (dans DemoAudit.tsx + site/src/demo/) : tapez/collez un dépôt public ou tapez sur une puce en vedette, elle récupère les fichiers de harnachement côté client et exécute le MÊME moteur compilé que la CLI. Les règles ci-dessous sont maintenant des INVARIANTS à préserver, pas une orientation future.

  • Chaque résultat est partageable (voir l’objectif de partage ci-dessus). Une note terminée comporte un partage en un tap + un lien profond stable ?repo= à exécution automatique. C’est une exigence ferme de la démo, pas un bonus — n’expédiez pas une surface de résultat sans cela.
  • Dans le navigateur, PAS hébergé. Le calcul d’audit s’exécute entièrement CÔTÉ CLIENT dans le navigateur du visiteur (récupère les fichiers du dépôt via l’API GitHub, exécute les détecteurs purs en JS) → renforce le principe « rien ne quitte votre machine » ; zéro backend/frais. Le seul « hébergement » est le service de fichiers statiques sur GitHub Pages (pas de backend dynamique, pas de base de données, pas de fonction serveur).
  • Limité aux vérifications déterministes. La démo dans le navigateur exécute UNIQUEMENT les vérifications qui peuvent être terminées sans modèle de langage (détection de répertoire, collisions de descriptions, raccourcis cassés, outils morts). Les vérifications limitées par modèle (taux de déclenchement, respect des règles) sont exclues. Ne les fabriquez pas ; utilisez des espaces réservés honnêtes (LockedRow).
  • La démo doit fonctionner sans CORS ni proxy. L’appel API GitHub est api.github.com (pas de proxy, pas de CORS — c’est une API publique). Si vous ajoutez une source de données qui nécessite un proxy, cette source ne fait PAS partie de la démo dans le navigateur (restructurez-la en étape CLI ou en point de terminaison côté serveur documenté ; n’ajoutez pas de proxy au site statique).
  • Le résultat de la démo est mis en cache localement (pas d’API côté serveur). Une fois qu’un rapport est généré, il est mis en cache dans localStorage (par slug de dépôt). Pas d’appel API, pas de re-exécution lors d’un re-rendu. Le cache est invalidé lorsqu’un utilisateur tape un nouveau dépôt.

À faire (tâches non expédiées connues par rapport à la vision actuelle)

  • Ajouter plusieurs fournisseurs de modèles dans le rapport. Actuellement, toutes les vérifications limitées par modèle sont verrouillées (LockedRow) car le moteur ne supporte qu’un seul fournisseur (Claude). Objectif : prendre en charge plusieurs fournisseurs de LLM (OpenAI, Gemini, etc.) pour que les vérifications limitées par modèle soient actives dans la démo.
  • Section « Comment ça marche ». Une explication courte, en langage simple, du pipeline d’audit : (1) lire la configuration locale, (2) analyser les conventions de fichiers, (3) exécuter des vérifications déterministes, (4) signaler des collisions/descriptions manquantes/outils morts. Pas de jargon. Placer après la démo, avant le pied de page.
  • Page d’état/témoignages. Citations d’utilisateurs réels ou résultats de notes de dépôts connus. Actuellement absent ; une fois que 3+ témoignages existent, ajoutez-les comme une section défilante.
  • Améliorer le rendu mobile des boîtes de résultats. Les tableaux de rapport sont actuellement étroits sur mobile (< 400 px). Refactorez en liste verticale avec des badges de catégorie.

Références

Skills associés