Andy-zch/agent-skills

Carte logique de projet

Aide les mainteneurs et l'IA à répondre : quoi modifier, où cela impacte, ce qu'il ne faut pas casser, et comment valider.

Choisir le périmètre de la tâche

• Génération initiale : À partir des exigences et de l'analyse du code, générer une carte relationnelle en Markdown. Si l'utilisateur a besoin d'une navigation visuelle ou possède déjà un HTML, générer ou maintenir également la carte visuelle.
• Mise à jour incrémentielle : Conserver les identifiants stables, ne mettre à jour que les faits, relations, statuts et cartes qui ont changé. Vérifier les références aux nœuds supprimés.
• Analyse d'impact : Autour d'une modification donnée, suivre les entrées, consommateurs, états, branches exceptionnelles, contraintes et validations ; si l'utilisateur demande uniquement une analyse, ne pas implémenter de modifications.

Privilégier les fichiers et identifiants existants du projet. Par défaut, les nouveaux projets produisent docs/LOGIC_MAP.md ; la version visuelle par défaut est docs/logic-map.html. Respecter les noms existants ou l'emplacement spécifié par l'utilisateur.

Analyser d'abord, établir les relations ensuite

Lire les conventions du projet, la base d'exigences, les points d'entrée clés, les pages/espaces de travail, l'état et le stockage, les processus métier, les tests et les enregistrements de publication. Suivre les tâches utilisateur principales pour lire le code nécessaire, sans parcourir l'intégralité du dépôt fichier par fichier.

Distinguer clairement : promesses des exigences, implémentation réelle, preuves de vérification automatisée, validation de l'environnement d'exécution, audit externe. Annoter les anciens enregistrements avec la date et le périmètre des preuves ; les vérifications non effectuées ne doivent pas être présentées comme réussies.

Points de suivi essentiels :

• Vérifier si plusieurs points d'entrée partagent réellement la même chaîne de traitement, et si certains contournent certaines étapes.
• Qui crée, détient, consomme, écrase, libère les données, et si elles sont persistantes ou quittent la machine.
• Comment se terminent les cas d'annulation, données vides, refus, dépassement de limites, échecs d'analyse.
• Les mises à jour fréquentes, lots, seuils, etc., supportent-ils des invariants propres au projet.

En cas de conflit entre documentation et code, enregistrer séparément ; ne pas forcer la fusion pour des raisons esthétiques. Si un risque dans le code est identifié, le consigner comme lacune sans étendre automatiquement la tâche à une correction.

Établir un modèle traçable

Lire references/model.md et adopter ses champs de nœuds, relations et preuves ; simplifier ou ajuster en fonction des identifiants existants du projet.

Rédiger d'abord une définition en une phrase de la tâche centrale et de sa chaîne principale, puis compléter avec les branches normales/exceptionnelles, l'état transversal, les interfaces, les contraintes et les validations. Sur la carte, deux éléments adjacents ne sont pas nécessairement liés ; chaque arête doit pouvoir être expliquée avec sa signification et sa justification.

Structure de livraison par défaut :

1. Vue d'ensemble des capacités : Permettre au lecteur de savoir d'abord ce que le produit peut faire. Regrouper par tâches utilisateur réelles ; ne pas compter le nombre de sous-cartes techniques comme le nombre de capacités, ni figer l'exemple en cinq groupes.
2. Flux par capacité : Déplier les points d'entrée, actions, traitements, états et sorties, en annotant les conditions de branchement.
3. Description des nœuds et preuves : Responsabilité, relations directes, emplacement d'implémentation, contraintes, validations et statut.
4. Index d'impact des modifications : Quels nœuds, fichiers et vérifications sont concernés par les modifications courantes.

La vue d'ensemble peut omettre les relations secondaires, mais le modèle complet ou la description des nœuds doit pouvoir les retrouver. La documentation d'exigences continue de trancher sur les exigences ; la carte ne doit pas établir une nouvelle base d'exigences.

Livraison visuelle HTML

Lorsque du HTML est nécessaire, lire references/visual.md. Pour un exemple concret, consulter references/wechat-example.html ; il s'agit d'un exemple de projet réalisé, pas d'un modèle universel ou d'une mise en page fixe.

Faire en sorte que les nœuds et les arêtes sémantiques partagent une seule source de données. Gérer séparément les coordonnées de vue, le routage et le thème. Markdown et HTML utilisent les mêmes identifiants. Pour les projets simples, maintenir directement une petite structure de données sans imposer un générateur ou une bibliothèque graphique.

Conserver les orientations visuelles déjà validées par l'utilisateur. Par défaut, adopter un centrage avec largeur limitée, une entrée dans la vue d'ensemble, une navigation par flux de capacité, une légende sous la carte et un thème clair/sombre. Le nombre de nœuds et la manière de diviser les cartes sont déterminés par la densité du contenu.

Ne pas copier dans d'autres projets la terminologie propre à WeChat, les seuils de taille, les statuts à vérifier ou les coordonnées manuelles de l'exemple. Lorsqu'un regroupement racine n'est qu'une structure d'affichage, le marquer clairement sans en faire une nouvelle capacité métier.

Validation et livraison

Contenu et structure :

• Les identifiants sont uniques ; les extrémités des arêtes existent ; chaque capacité clé a une entrée d'exploration ; aucun nœud supprimé n'a de référence pendante.
• Les relations de contenu, flux de données, dépendances, contraintes et validations ont chacune leur sémantique : ne pas les confondre avec un ordre d'exécution.
• Le cycle de vie du stockage, les sorties exceptionnelles, les emplacements d'implémentation et les statuts peuvent être étayés par des preuves.
• Se poser une question concrète sur une modification, par exemple "Changer la mise en page affecte quoi ?", et la carte doit permettre de retrouver les états, consommateurs et validations concernés.

Pour la version visuelle, ouvrir le navigateur et vérifier :

• La vue d'ensemble affiche toutes les capacités principales en même temps, le texte est clair, les flèches ne traversent pas les nœuds ni le texte.
• Ouvrir chaque flux de capacité un par un, vérifier l'exploration, les associations entre cartes, l'état de sélection, la désélection.
• Vérifier le texte, les nœuds, les lignes, les flèches et les légendes en mode clair et sombre ; capturer des captures d'écran.
• Vérifier l'intégrité de la vue d'ensemble à la taille de bureau cible ; sur écran étroit, conserver une taille de police lisible et permettre le défilement horizontal ou le découpage en sous-cartes.

La vérification syntaxique ou structurelle statique ne remplace pas la vérification visuelle. Si le navigateur n'est pas disponible, livrer le fichier et mentionner clairement les vérifications non effectuées ; ne pas utiliser d'anciennes captures d'écran comme résultat actuel.

Livrer les liens, les principaux changements de relations, les résultats réels des vérifications et les lacunes restantes. Sauvegarder le travail selon les conventions Git du projet ; ne pas publier de site web ni installer de Skill globale.