wuxie888/dianjing

点睛

Pour un code base terminé ou proche de la sortie, réaliser la conception et la décoration visuelle du dépôt afin de le transformer d'« endroit où l'on met du code » en une vitrine produit attrayante, crédible, compréhensible, installable, partageable et diffusible.

Faire d'un produit fini un dépôt public que les autres comprennent, auquel ils font confiance, qu'ils installent, utilisent et souhaitent partager. Livrer l'esthétique, les animations et la crédibilité comme un même livrable produit, et non pas seulement modifier le texte du README ou empiler des images décoratives.

Règles intangibles

1. Vérifier le produit avant de l'emballer. Confirmer le périmètre réel du dépôt, le commit courant, l'état de fonctionnement, les fonctionnalités, la licence, les canaux de publication et les assets existants. Ne pas inventer de fonctionnalités, d'indicateurs, d'avis utilisateurs, de compatibilité ou d'état de publication.
2. Auditer d'abord, modifier ensuite. Exécuter scripts/audit_repository.py, lire le point d'entrée du code source, la documentation produit, le README existant, les assets et l'état Git. Conserver les modifications existantes de l'utilisateur, ne pas écraser le travail non concerné.
3. La valeur produit prime sur les instructions d'installation. Le README doit d'abord répondre à « Qu'est-ce que c'est ? à qui ça s'adresse ? quel problème ça résout ? quel est son état réel ? » avant d'aborder l'installation, le premier succès, la mise à niveau et le dépannage.
4. Privilégier les assets réels. Réutiliser en priorité le vrai logo, les captures d'écran du produit, les enregistrements d'interface et les résultats de sortie. Les visuels générés ne doivent qu'illustrer le produit réel, jamais simuler des interfaces ou capacités inexistantes.
5. Évaluer systématiquement les opportunités d'animation. Évaluer à chaque fois le héros dynamique, le GIF d'opération réelle, la vidéo de démonstration et les médias de Release. N'évaluer un site de démonstration que lorsque le README ne peut pas porter l'expérience clé. Ne pas livrer par défaut un README statique, ni construire un site par défaut pour donner l'impression d'être plus avancé. Quand une animation n'améliore ni la compréhension, ni la confiance, ni la marque, documenter la raison de son rejet.
6. Les capacités des plateformes doivent être stratifiées. README, Social Preview, médias de Release et GitHub Pages sont des surfaces différentes. Ne pas traiter le README comme une page web pouvant exécuter arbitrairement du JavaScript, du CSS ou des SVG animés.
7. L'esthétique doit être utilisable. Les animations ne doivent pas retarder les informations clés. Fournir une première image statique et respecter prefers-reduced-motion. Vérifier le rendu mobile, les thèmes clair/sombre, la taille des fichiers, le rythme de boucle et la licence.
8. Séparer le cœur de la capacité de son packaging. Le code source du produit, les skills, plugins, installateurs, site officiel et configurations de marché ne sont écrits que s'ils existent réellement. Éviter de dupliquer une implémentation qui dériverait.
9. Exprimer l'état de publication selon les preuves. Distinguer : terminé localement, poussé sur le dépôt distant, tagué, en Release, installable, première utilisation, validation de comportement réel, et présence dans un annuaire officiel ou une place de marché.
10. Les actions distantes ne sont pas autorisées automatiquement. Une demande de décoration locale permet de modifier les fichiers concernés dans le dépôt cible. Pousser, créer une Release, modifier les paramètres du dépôt, uploader une Social Preview, activer Pages ou déployer nécessite une demande explicite de l'utilisateur.

Flux de travail

1. Définir le livrable et les permissions

Confirmer le dépôt cible et le point d'arrivée de cette itération :

• Livrer uniquement un plan de décoration
• Réaliser la décoration du dépôt local
• Ajouter un README dynamique
• Évaluer et, si nécessaire, construire un site de démonstration
• Préparer la publication sans pousser
• Réaliser la publication distante et la recette publique

Si l'utilisateur dit « décore » ou « vas-y direct », réaliser par défaut une implémentation locale sécurisée et sa vérification, sans pousser ni modifier les paramètres distants.

2. Auditer le dépôt réel

Exécuter :

python3 <skill-dir>/scripts/audit_repository.py <chemin-du-dépôt>

Puis lire audit-and-positioning.md et vérifier :

• Racine Git, remote, branche/commit courants, modifications dans l'espace de travail
• Point d'entrée réel du produit, degré de fonctionnalité, licence, version, canaux de publication
• README, docs, fichiers de gouvernance, tests, Release
• Logo, captures, enregistrements d'écran, GIF, vidéos, image sociale (Social Preview), site officiel existant
• Chemins absolus locaux, textes de placeholder, liens relatifs cassés, fichiers potentiellement sensibles

Ne pas diagnostiquer not a git repository comme un échec de publication ; d'abord trouver le vrai checkout. Ne pas modifier la logique produit sans autorisation de l'utilisateur.

3. Établir le brief de décoration produit

Extraire des éléments réels :

• Ce que l'utilisateur confie au produit
• Ce que le produit accomplit
• Ce que l'utilisateur obtient au final
• À qui il convient le mieux, à qui il ne convient pas
• Un point de différenciation majeur
• L'état réel actuel et les limites importantes
• Le ton / l'image que l'on souhaite transmettre
• La définition du premier succès

Si nécessaire, copier et remplir repository-brief-template.md. En l'absence de direction de marque, faire des choix clairs basés sur le produit lui-même, sans renvoyer toutes les décisions de conception à l'utilisateur.

4. Choisir la base obligatoire et les modules conditionnels

Réaliser d'abord la base obligatoire pour tout dépôt public, puis choisir les modules selon la tâche produit. Ne pas considérer le nombre de modules comme un indicateur de finition ou d'avancement.

Base obligatoire :

• Positionnement produit et périmètre factuel
• Architecture de l'information du README
• Installation et premier succès
• Vrais assets visuels
• Licence, version et état de publication
• Gouvernance de base et recette publique

Modules conditionnels :

Module	Condition d'adoption
Expression dynamique	Le héros dynamique, un GIF d'opération réelle ou une vidéo améliore(nt) significativement la compréhension, la confiance ou la reconnaissance de marque
Site de démonstration	Le README ne peut pas porter les interactions clés, l'expérience visuelle, la conversion de non-développeurs ou une démo en ligne, ET il n'existe pas de site officiel réutilisable
Publication et diffusion	Le produit est effectivement en phase de versionnage, de partage externe ou de diffusion continue ; nécessite une Social Preview, des médias de Release, une entrée bilingue ou un processus de mise à niveau/dépannage
Documentation avancée	L'installation, l'API, la configuration ou la maintenance sont trop complexes pour que le README soit le seul document adapté

Le site de démonstration est un livrable conditionnel, pas un niveau de décoration supérieur. Les Agent Skills, CLI, SDK, petites librairies ont généralement le README pour page d'accueil. Les produits UI, jeux, codage créatif, démos interactives ou destinés à des non-développeurs peuvent davantage nécessiter un site de démonstration. Quand un site officiel existe déjà, le relier et le réutiliser en priorité, sans créer une redondance avec GitHub Pages.

5. Concevoir le README et la documentation

Lire readme-and-documentation.md. Organiser selon le chemin de compréhension de l'utilisateur :

Comprendre le produit
→ Établir la motivation à l'utiliser
→ Voir des preuves réelles
→ Comprendre les capacités et les limites
→ Installer
→ Réussir la première utilisation
→ Dépanner et mettre à niveau
→ Connaître les tests, la maintenance et la licence

Ne pas appliquer mécaniquement un modèle. CLI, librairie, application, site web, skill/plugin et projet de recherche doivent choisir des démonstrations, installations et premiers succès différents. Si un squelette est nécessaire, copier readme-outline-template.md puis l'adapter au produit.

6. Concevoir le système visuel et d'animation

Lire visual-and-motion.md. D'abord inventorier les assets réels, puis définir un langage de couleurs, typographie, composition, icônes et animations propre au produit.

Si motion-anything-design est disponible, il faut d'abord :

1. Lire le bundle courant.
2. Chercher un système de design adapté au ton du produit.
3. Chercher des animations réelles dont implementation_status: ready.
4. Lire les avoid_when, restraint, reduced_motion, dépendances et licence des animations retenues.
5. Obtenir les fichiers d'implémentation réels avant d'adapter ; ne pas réécrire une implémentation existante de mémoire.
6. Chercher et obtenir les SVG d'icônes précis.

Si un nouveau logo, un héros ou une illustration est nécessaire, réutiliser d'abord les assets de marque existants. Si la génération est vraiment nécessaire, utiliser les capacités de génération d'image disponibles, en s'appuyant sur des captures d'écran réelles du produit et son interface.

Pour chaque dépôt, réaliser au moins une fois l'audit des opportunités d'animation :

• Un héros de marque animé permet-il de présenter le produit plus rapidement ?
• Un GIF d'opération réelle est-il plus efficace que plusieurs captures ?
• Une Release a-t-elle besoin d'une courte vidéo ?
• Le README ne peut-il vraiment pas porter l'expérience clé ? Si oui, le site officiel existant ou le site de démonstration mérite-t-il de porter l'interaction, le parcours et le CTA ?
• La première image statique, l'état sans animation et les thèmes clair/sombre sont-ils tous satisfaisants ?

7. Réaliser la vitrine du dépôt

Travailler dans la stack technique existante et les conventions du dépôt cible :

• Modifier le README et la documentation nécessaire
• Réutiliser ou créer des médias visuels réels
• Ajouter si nécessaire docs/, guide de démarrage, dépannage, maintenance et notes de version
• Une fois que le module site de démonstration a passé la porte conditionnelle, ajouter si besoin le code source des Pages et la configuration de déploiement
• Conserver une source unique pour le code produit, ne pas dupliquer l'implémentation pour l'exposition
• Utiliser des liens relatifs, éviter les chemins locaux
• Ne pas commiter de clés, cookies, liens privés, assets non autorisés ou licence incompatible

Le choix des animations suit le principe « une animation porte une tâche narrative ». Par défaut, au maximum un effet d'arrière-plan environnemental, un effet de texte principal et un effet de célébration/surbrillance par écran ; le corps du texte et les actions clés restent stables.

8. Valider le résultat local

Relancer le script d'audit et vérifier le Git diff. Ensuite :

• Rendre le README, vérifier l'ordre de lecture sur desktop et écran étroit
• Ouvrir toutes les images, GIF et vidéos réellement
• Vérifier la première image du GIF, la jointure de boucle, les sous-titres et la taille du fichier
• Si le module site de démonstration a été adopté, réaliser une recette navigateur sur Pages ou le site officiel existant : responsive, mode clair/sombre, interactions, console, performances, 404
• Activer la préférence de mouvement réduit, confirmer que le contenu est immédiatement visible et que les fonctionnalités ne sont pas perdues
• Vérifier tous les liens relatifs, commandes d'installation, version, licence et état réel
• Confirmer qu'aucune modification non liée de l'utilisateur n'a été écrasée

9. Valider l'artefact public

Après autorisation de publication par l'utilisateur, lire release-and-acceptance.md. Extraire un nouveau checkout depuis le dépôt public ou le tag, et revérifier le README, les médias, le site de démonstration adopté, l'installation, le premier succès et le chemin de mise à niveau.

Rapporter séparément :

• Décoration locale terminée
• Code source distant visible
• Tag / Release publié(e)
• Social Preview / site de démonstration adopté et actif
• Premier succès utilisateur vérifié
• Parties non encore réalisées ou seulement confirmées oralement par l'utilisateur

Pour un enregistrement formel, copier acceptance-report-template.md.

Conditions d'arrêt

• L'état réel du produit ne peut pas être confirmé : d'abord rapporter les lacunes de preuve, ne pas masquer les problèmes avec du visuel.
• Absence d'images réelles du produit : on peut créer des assets de marque et structurels, mais ne pas simuler de captures d'écran du produit.
• Incompatibilité entre les animations et le README : transformer d'abord en GIF ou vidéo ; ne passer sur Pages qu'après avoir passé la porte conditionnelle du site de démonstration, ne pas prétendre que le README exécute des scripts non supportés.
• Conflit entre les modifications existantes de l'espace de travail et les fichiers de décoration : conserver les modifications de l'utilisateur et expliquer le conflit, demander une direction si nécessaire.
• Nécessité de pousser, déployer, utiliser des assets payants ou modifier des paramètres distants sans autorisation : terminer la partie livrable localement, puis s'arrêter.