ihkaru/agent-skills

Craftsman Coder : SOLID, Impact AST CodeGraph et Ingénierie Basée sur les Preuves

Un workflow d'ingénierie discipliné, indépendant du dépôt, pour construire des logiciels robustes, découplés et vérifiables.

---

Principes Fondamentaux

1. Exploration AST et CodeGraph d'abord : Ne modifiez ou refactorisez jamais le code à l'aveugle. Cartographiez toujours les définitions de symboles, les appelants, les appelés et le rayon d'impact avant de modifier l'implémentation.
2. SOLID et Principe de Responsabilité Unique (SRP) : Chaque module, fonction et classe doit avoir une seule raison de changer. Séparez la logique métier des entrées/sorties, de la persistance et des API externes.
   • Règle de décomposition : Si un composant, une classe ou une fonction est trop long ou gère plusieurs préoccupations, décomposez-le immédiatement en sous-composants/services atomiques plus petits avec des responsabilités uniques.
3. Injection de Dépendances (DI) et Inversion de Contrôle : Injectez les dépendances (dépôts, clients, journaux) via les constructeurs ou les mécanismes du framework. Découplez la logique de l'infrastructure concrète. Évitez les instanciations externes directes codées en dur.
4. Architecture de Rechange : Architecture par Tranches Verticales (VSA) + EIP : Si un dépôt ne possède pas de convention de framework établie, donnez toujours la priorité à l'Architecture par Tranches Verticales (VSA) couplée à SOLID et aux Motifs d'Intégration d'Entreprise (EIP) :
   • Organisez le code par capacités métier (features/<feature_name>/) en utilisant le motif Requête-Point de Terminaison-Réponse (REPR) plutôt que des couches techniques horizontales.
   • Employez les motifs EIP pour la coordination des tranches : routeurs de commandes/requêtes, tubes et filtres, récepteurs idempotents, et publication/abonnement d'événements de domaine.
   • Guide détaillé : Guide VSA et EIP
5. Analyse Statique Déterministe des Frontières Architecturales VSA : Lorsqu'un dépôt implémente VSA, configurez un linter de frontières déterministe (par ex. dependency-cruiser pour JS/TS, import-linter pour Python, depguard pour Go, ou vsa_boundary_checker.py) pour interdire les imports directs entre tranches.
   • Guide détaillé : Guide de Renforcement des Frontières VSA et GEMINI.md du Dépôt
6. GEMINI.md Obligatoire au Niveau du Dépôt (Portable et Prêt pour Git) : Lors de la création ou de l'initialisation d'un dépôt, générez toujours un GEMINI.md à la racine du projet pour conserver les choix architecturaux, les règles de frontière et les commandes Gauntlet.
   • Règle de Portabilité Stricte : Comme ce fichier est commité et poussé, ne référez JAMAIS des chemins d'hôte externes (par ex. pas de ~/.gemini/config/..., pas de /data/data/...) ou des secrets spécifiques à la machine. Il doit être 100% autonome et portable.
7. Recherche Web en Temps Réel et Complexité Big-O Optimale : Sélectionnez toujours les modèles d'algorithmes et de structures de données avec les complexités temporelles et spatiales Big-O les plus optimales (recherche $O(1)$, tri $O(N \log N)$, mémoire de streaming $O(1)$).
   • Recherche Web Obligatoire : Ne vous fiez jamais uniquement aux hypothèses pré-entraînées car les connaissances peuvent être obsolètes. Recherchez toujours sur le web en fonction du mois et de l'année en cours pour découvrir les modèles algorithmiques de pointe, les structures de données optimales et les dernières implémentations de bibliothèques hautes performances.
8. Bibliothèques Hautes Performances, Faible RAM et Conformité des Licences d'Entreprise :
   • Performance Maximale et Faible Mémoire : Préférez les bibliothèques modernes, adaptées au cache, à copie zéro et accélérées SIMD (par ex. orjson/msgspec, polars, sonic, zerolog, simd-json, fast-json-stringify).
   • Conformité des Licences d'Entreprise : Sélectionnez des licences open-source permissives (MIT, Apache 2.0, BSD-2/3, ISC). Évitez strictement le copyleft viral (GPL, AGPL, SSPL) pour garantir une transition sans heurts des audits d'entreprise sans obligation de divulgation de source.
   • Guide détaillé : Guide des Bibliothèques Hautes Performances et Licences
9. Analyse Statique de Code Déterministe pour SRP et les Abstractions : Priorisez toujours les outils d'analyse statique déterministe pour auditer le code à la recherche de violations SRP (par ex., longueur excessive, responsabilités excessives) et de contournements d'abstraction (par ex., appels SQL bruts ou HTTP directs dans la logique de présentation/métier).
10. Injection Centralisée de Secrets (Infisical) : Ne codez jamais les secrets en dur et ne stockez pas d'identifiants bruts dans git/des fichiers env locaux. Traitez les secrets comme des dépendances injectées à l'exécution via Infisical (infisical run -- ...).
    • Guide détaillé : Guide de Gestion des Secrets Infisical
11. Convention du Framework en Premier : Respectez les conventions idiomatiques du framework existant (par ex. Depends de FastAPI, @Injectable de NestJS, hooks React, interfaces Go) plutôt que d'inventer des abstractions ad-hoc.
12. Tests Parallélisables et Hermétiques : Tous les tests doivent être sans état, isolés et prêts pour la parallélisation (par ex., pytest -n auto, go test -parallel). Pas d'état mutable partagé ni d'effets secondaires de singleton statique.
13. La Discipline 'Old Coder' Basée sur les Preuves : Examinez les preuves, pas le code. Suivez la boucle Spécification -> ROUGE -> VERT -> REFACTOR et vérifiez via des vérifications automatisées en terminal avant de signaler la fin.
14. Conception d'Outils et de Compétences Prêts pour les Agents IA : Lors de l'extraction de motifs récurrents dans des outils et compétences : garantissez une sortie --json, une exécution non interactive (zéro invite), une sécurité --dry-run, des verbes nom-action prévisibles et des codes de sortie typés.
    • Guide détaillé : Guide de Conception CLI Prête pour les Agents IA

---

Workflow Étape par Étape

Étape 1 : Analyse du Rayon d'Impact Avant Changement (CodeGraph AST)

Avant de modifier une fonction, une classe ou un service, inspectez le rayon d'impact pour déterminer l'impact en aval :

python3 ~/.gemini/config/skills/craftsman-coder/scripts/codegraph_impact.py <chemin_vers_depot> --symbol <SymboleCible>

• Examinez les Appelants Directs et les Fichiers de Référence.
• Examinez les Suites de Tests Affectées : Si aucun test ne couvre ce symbole, vous devez en créer un avant le refactoring.

Étape 2 : Architecture, Complexité Algorithmique Big-O et GEMINI.md du Dépôt

• Formulez une spécification et une conception claires :
  • Si vous créez/initialisez un dépôt, créez un GEMINI.md autonome à la racine du dépôt (zéro chemin externe, zéro secret).
  • Si aucune convention de framework n'existe, organisez en Tranches Verticales (features/<nom>/) avec les motifs REPR et EIP.
  • Mettez en place ou vérifiez le linter de frontières architecturales (par ex. dependency-cruiser, import-linter, ou vsa_boundary_checker.py).
  • La classe/fonction/composant fait-elle plus d'une chose ou dépasse-t-elle les seuils de longueur ? Décomposez-la en sous-composants ciblés (SRP).
  • Les systèmes externes sont-ils fortement couplés ? Définissez une interface/protocole et utilisez l'Injection de Dépendances.
  • Complexité Algorithmique et Recherche Web : Évaluez la complexité temporelle/spatiale Big-O. Recherchez activement sur le web en fonction du mois et de l'année en cours pour des optimisations algorithmiques modernes.
  • Audit des Dépendances : Choisissez des bibliothèques à faible RAM et à haut débit avec des licences sûres pour l'entreprise (MIT / Apache 2.0 / BSD). Assurez-vous de n'avoir aucune dépendance transitive copyleft/AGPL.
• Référence détaillée : Guide des Motifs SOLID et DI
• Référence détaillée : Guide VSA et EIP
• Référence détaillée : Guide de Renforcement des Frontières VSA et GEMINI.md du Dépôt
• Référence détaillée : Guide des Bibliothèques Hautes Performances et Licences

Étape 3 : Écrire des Tests Parallélisables (ROUGE)

• Écrivez un test unitaire ou d'intégration isolé et hermétique vérifiant le comportement attendu ou la correction de bogue.
• Assurez-vous que le test utilise des ressources temporaires indépendantes ou des mocks en mémoire.
• Exécutez le test pour confirmer qu'il échoue (ROUGE).
• Référence détaillée : Guide des Tests Parallèles et Old Coder

Étape 4 : Implémenter une Solution Minimale et Propre (VERT)

• Implémentez uniquement ce qui est nécessaire pour satisfaire le test.
• Gardez les composants cohésifs et à but unique.
• Injectez les dépendances proprement.

Étape 5 : Refactoriser et le Gauntlet (REFACTOR et PREUVES)

• Nettoyez le code pendant que les tests restent verts.
• Exécutez Le Gauntlet (toute vérification doit être automatisée et déterministe) :
  1. Vérification des Frontières VSA : Exécutez la vérification des frontières architecturales (par ex., npx depcruise --config .dependency-cruiser.js src ou python3 ~/.gemini/config/skills/craftsman-coder/scripts/vsa_boundary_checker.py <chemin_vers_depot>).
  2. Analyse Statique Déterministe SRP et Abstraction :

     python3 ~/.gemini/config/skills/craftsman-coder/scripts/static_srp_analyzer.py <chemin_vers_depot> --strict
     

  3. Linter et Analyse Statique (par ex. ruff check ., eslint, golangci-lint)
  4. Vérification de Type (par ex. mypy, tsc --noEmit)
  5. Suite de Tests Complète exécutée en parallèle (par ex. pytest -n auto, go test -parallel 4 ./...)
• Fournissez les preuves terminales (codes de sortie, résumé de test réussi) dans votre réponse finale.

---

Scripts et Outils Intégrés

• Analyseur d'Impact AST CodeGraph : scripts/codegraph_impact.py

  • Inspecte l'AST et les références croisées à travers Python, JS/TS, Go, Rust, Java.
  • Calcule le niveau de risque du rayon d'impact (Faible, Moyen, Élevé, Critique).
  • Identifie les appelants directs et les suites de tests affectées.

• Analyseur Statique Déterministe SRP et Abstraction : scripts/static_srp_analyzer.py

  • Évalue le code pour les violations de longueur/complexité SRP.
  • Signale les contournements d'abstraction (appels SQL/HTTP bruts en dehors des dépôts/adaptateurs).
  • Émet du --json lisible par machine et des codes de sortie déterministes pour la vérification CI/Old Coder.

• Vérificateur de Frontières Architecturales VSA : scripts/vsa_boundary_checker.py

  • Applique l'isolation des tranches en empêchant les imports interdits entre tranches.
  • Configurable via .vsa-boundaries.json. Sans dépendance, indépendant du dépôt (MIT).