Norme de visualisation des flux de code
Ce Skill fournit un ensemble de modèles et de méthodes réutilisables pour analyser les flux de code et générer une documentation visuelle.
Principe fondamental : Expliquer clairement avec du texte et des diagrammes ASCII "d'où viennent les données, par quelles couches elles passent et où elles aboutissent".
Quand l'utiliser
Utilisez ce Skill dans les situations suivantes :
- L'utilisateur demande "comment fonctionne telle fonctionnalité ?"
- Une nouvelle fonctionnalité nécessite la conception de flux de données
- Avant une refactorisation, pour analyser la logique existante
- Rédaction de documentation technique ou d'architecture
- Besoin de visualiser la chaîne d'appels lors d'une revue de code
Modèles principaux
1. Schéma de flux complet (comparaison multi-scénarios)
Idéal pour : analyser plusieurs scénarios d'utilisation d'une fonctionnalité (par exemple manuel vs automatique, succès vs échec)
┌─────────────────────────────────────────────────────────────────────┐
│ Nom de la fonctionnalité (ex : cycle de vie │
│ de la gestion des limites) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Scénario 1 : Nom du scénario (ex : requête automatique de l'état des limites)
═══════════════════════════════════════════════════════════════════════
Commande utilisateur
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ Couche CLI │ Appelle la fonction Flow
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Couche Flow │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Couche Data │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Système externe / Base │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Retour de données
▼
┌──────────────────────────────────┐
│ Traitement des données │
│ (analyse/transformation) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Classe de données │ ← Expliquer pourquoi
│ de retour │ (résultat/élément/...)
│ (Result / Item / ..)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Sortie formatée │
│ par la couche CLI │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Exemple de sortie terminal ║
║ (Encadré pour mettre en évidence le résultat ║
║ visible par l'utilisateur final) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Scénario 2 : Un autre scénario
═══════════════════════════════════════════════════════════════════════
(Répéter la structure ci-dessus, en mettant en évidence les différences)
2. Description de la structure des tables de base de données
Idéal pour : expliquer les tables de base de données liées à une fonctionnalité
CREATE TABLE nom_table (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Expliquer le rôle de la clé primaire
champ1 TEXT NOT NULL, -- Expliquer la signification du champ
champ2 TEXT, -- Signification métier de NULL
...
);
-- Index (expliquer pourquoi cet index est nécessaire)
CREATE INDEX idx_xxx ON nom_table(champ1, champ2);
Exemple de données :
| id | champ1 | champ2 | champ3 | Description |
|---|---|---|---|---|
| 42 | valeur1 | valeur2 | valeur3 | Signification métier de cet enregistrement |
| 43 | ... | ... | ... | ... |
Requêtes typiques :
-- Explication du scénario : quand a-t-on besoin de cette requête ?
SELECT * FROM nom_table
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. Graphe d'appels par couches (version simplifiée)
Idéal pour : expliquer rapidement les relations d'appels entre fonctions
Couche CLI (_do_xxx)
│
└─> Couche Flow (xxx_flow)
│
├─> Data/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Data/Client (xxx_client.fetch)
│
└─> API externe (HTTP GET ...)
4. Tableau d'analyse de conception des classes de données
Idéal pour : évaluer la nécessité des classes de données intermédiaires
| Nom de classe | Nb champs | Utilisation | Décision | Justification |
|---|---|---|---|---|
XxxResult | 6 | Agrégation multi-champs + affichage CLI | ✅ Conserver | Satisfait le "principe de nécessité minimale" |
XxxWrapper | 1 | Emballage d'un seul champ | ❌ Supprimer | Emballage excessif, retourner directement le type primitif |
XxxItem | 3 | Élément de liste détaillée | ✅ Conserver | A une signification métier |
Exemple de comparaison :
# ❌ Emballage excessif
@dataclass
class XxxResult:
champ: SomeType # Un seul champ
def xxx_flow() -> XxxResult:
return XxxResult(champ=valeur)
# ✅ Après simplification
def xxx_flow() -> SomeType: # Retour direct
return valeur
5. Annotation des points clés métier
Idéal pour : mettre en évidence les règles métier et les décisions de conception
┌─────────────────────────────────────────────────────────────┐
│ Points clés métier │
├──────────────────────┬──────────────────────────────────────┤
│ Pourquoi cette │ Décision concrète │
│ conception ? │ │
├──────────────────────┼──────────────────────────────────────┤
│ • Précision données │ Montant en Decimal, 2 décimales │
│ • Idempotence │ Contrainte d'unicité sur │
│ │ (fund_code, date) │
│ • Traçabilité │ record_id comme identifiant global │
└──────────────────────┴──────────────────────────────────────┘
Comment l'utiliser
Étape 1 : Définir l'objectif d'analyse
Répondez aux questions suivantes :
- De quelle fonctionnalité l'utilisateur souhaite-t-il comprendre le flux ?
- Combien de scénarios existe-t-il pour cette fonctionnalité ? (succès/échec, manuel/automatique, etc.)
- Quelles sont les couches impliquées ? (CLI → Flow → Data → DB/API)
- Quelles sont les classes de données clés et pourquoi sont-elles conçues ainsi ?
Étape 2 : Choisir le modèle approprié
- Comparaison multi-scénarios → Modèle 1 (schéma de flux complet)
- Processus unique → Modèle 3 (graphe d'appels par couches)
- Conception de base de données → Modèle 2 (structure de table + exemples de données)
- Évaluation des classes de données → Modèle 4 (tableau d'analyse)
Étape 3 : Remplir le contenu
Principes :
- Utiliser des diagrammes ASCII plutôt que de longs textes
- Utiliser des flèches (
│ ▼ ┐ ┘ └ ├ ─) pour enchaîner les flux de données - Utiliser des bordures (
┌ ┐ └ ┘ │ ─) pour séparer les couches - Utiliser des bordures doubles (
╔ ╗ ╚ ╝ ║ ═) pour mettre en évidence les parties visibles par l'utilisateur - Ajouter des commentaires (
← explication) aux nœuds clés
Norme d'utilisation des symboles :
| Symbole | Utilisation | Exemple |
|---|---|---|
│ ▼ | Flux vertical | Données du haut vers le bas |
→ ← | Explication horizontale | record_id: int ← clé primaire DB |
┌ ┐ └ ┘ | Bordure simple | Encadrer des blocs de code, commandes |
╔ ╗ ╚ ╝ | Bordure double | Mettre en évidence la sortie terminal, résultats importants |
═══ | Ligne de séparation | Séparer différents scénarios |
Étape 4 : Ajouter une analyse comparative
Avant vs Après (scénario de refactorisation) :
# Avant (version problématique)
...code...
# Problèmes :
# - Emballage excessif
# - Champs redondants
# - Augmentation de la charge cognitive
# Après (version améliorée)
...code...
# Améliorations :
# - Retour direct d'un type significatif
# - Réduction des couches intermédiaires
# - Diminution de la charge de maintenance
Exemples concrets
Exemple 1 : Processus de gestion des limites (version complète)
(Voir l'exemple du modèle 1 ci-dessus, en développant le processus complet pour 4 scénarios)
Exemple 2 : Évaluation des classes de données (module fund_restriction)
| Fonction | Retour avant | Retour maintenant | Décision | Raison |
|---|---|---|---|---|
add_restriction | AddRestrictionResult (6 champs) | Conserver | ✅ | La CLI doit afficher tous les champs |
end_restriction | EndRestrictionResult (4 champs) | bool | ❌ | Seul le succès/échec est nécessaire |
check_trading_status | CheckStatusResult (2 champs) | ParsedRestriction | None | ❌ | Simple emballage inutile |
Liste de contrôle (Checklist)
Lors de la génération d'un document de visualisation de flux, assurez-vous d'inclure :
- Aperçu général (objectif de la fonctionnalité, modules impliqués)
- Énumération des scénarios (succès/échec, manuel/automatique, etc.)
- Schéma de flux par couches (CLI → Flow → Data → Externe)
- Structure des tables de base de données (si impliquée)
- Exemples de données et requêtes (pour faciliter la compréhension)
- Explication des classes de données clés (pourquoi conserver/simplifier)
- Raisons de conception (pourquoi cette approche ?)
- Points d'extension futurs (TODO ou interfaces réservées)
Anti-patrons (à ne pas faire)
❌ Description textuelle pure du processus
Il faut d'abord appeler la fonction _do_xxx de la couche CLI, ensuite _do_xxx appelle la fonction xxx_flow de la couche Flow,
puis xxx_flow appelle la méthode xxx_repo.get de la couche Data...
✅ Utiliser un diagramme ASCII
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ Tableau sans accent mis sur l'essentiel
| Champ | Type |
|---|---|
| id | int |
| name | str |
✅ Mettre en évidence la signification métier
| Champ | Type | Description | Contrainte métier |
|---|---|---|---|
| id | int | Clé primaire | Généré automatiquement, unique globalement |
| name | str | Nom du fonds | Non vide, utilisé pour l'affichage |
❌ Requête SQL sans explication du scénario
SELECT * FROM table WHERE id = ?;
✅ Avec scénario métier
-- Scénario : l'utilisateur consulte les détails d'une restriction
SELECT * FROM fund_restrictions WHERE id = ?;
-- Scénario : lors de l'analyse DCA, vérifier si un jour est soumis à une limite
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Collaboration avec d'autres Skills
- code-style : Suivre les normes de codification lors de l'affichage d'exemples de code
- architecture : Les diagrammes de flux doivent respecter les contraintes d'architecture par couches
- dev-workflow : Lire le code et la documentation pertinents avant d'analyser le flux
Résumé
Les valeurs clés de ce Skill sont :
- Modèles réutilisables : Réduire le temps de démarrage à zéro
- Style visuel unifié : Diagrammes ASCII + tableaux + bordures
- Perspective métier : Au-delà du flux de code, se concentrer sur le "pourquoi"
- Analyse comparative : Avant/après refactorisation, comparaison multi-scénarios
- Checklist : Garantir qu'aucune information clé n'est omise
Fréquence d'utilisation : Peut être utilisé chaque fois qu'il est nécessaire d'expliquer "comment fonctionne une fonctionnalité".