Communitygithub.com

renatoxm/leanagentkit

Une alternative plus légère à GitHub Spec Kit

Qu'est-ce que leanagentkit ?

Ce skill implémente les principes de l'architecture en oignon (Clean Architecture) pour guider la structuration du code, l'examen des limites de modules et les décisions de gestion des dépendances. Il repose sur la règle fondamentale selon laquelle les dépendances du code source doivent pointer vers l'intérieur, vers les politiques de plus haut niveau, afin que les règles métier restent indépendantes des frameworks, bases de données et mécanismes de livraison. Le skill fournit un système de notation (de 0 à 10) basé sur sept questions de diagnostic rapide pour évaluer la conformité de l'architecture, ainsi que des références détaillées pour corriger les inversions de dépendances. Il est conçu pour être utilisé avec Claude Code, Cursor, Codex ou tout autre assistant de codage pour analyser et améliorer la qualité architecturale d'un projet logiciel.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add renatoxm/leanagentkit

Demander à votre IA préférée

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

Documentation

Framework d'Architecture Propre

Une approche disciplinée pour structurer un logiciel afin que les règles métier restent indépendantes des frameworks, bases de données et mécanismes de livraison. Appliquez ces principes lors de la conception de l'architecture système, de la révision des limites de modules ou du conseil sur la gestion des dépendances.

Principe Fondamental

Les dépendances du code source doivent pointer vers l'intérieur — vers les politiques de plus haut niveau. Rien dans un cercle intérieur ne peut rien savoir d'un cercle extérieur. Cette règle unique produit des systèmes testables et indépendants des frameworks, de l'interface utilisateur, de la base de données et de toute agence externe. Les règles métier sont ce qui compte ; les bases de données, les frameworks web et les mécanismes de livraison sont des détails — lorsque les détails dépendent des politiques, vous pouvez reporter les décisions, échanger les implémentations et tester la logique métier en isolation.

Score

Objectif : 10/10. Comptez un point pour chacune des sept lignes du Diagnostic Rapide que l'architecture satisfait (0-7), puis reportez-vous à une bande de 0 à 10 : 6-7 satisfaites = 9-10 (la règle de dépendance tient, la logique métier est indépendante du framework et de la base de données) ; 4-5 = 6-8 (le noyau est testable mais certains détails fuient vers l'intérieur) ; 2-3 = 3-5 (le framework ou la persistance dicte la structure) ; 0-1 = 0-2 (aucune frontière — les règles métier vivent dans les contrôleurs et les modèles ORM). Signalez le score, les lignes de diagnostic échouées et l'inversion spécifique nécessaire pour corriger chacune.

1. Règle de Dépendance et Cercles Concentriques

Concept de base : Organisez l'architecture sous forme de cercles concentriques — les Entités (règles métier de l'entreprise) les plus à l'intérieur, puis les Cas d'Utilisation (règles métier de l'application), puis les Adaptateurs d'Interface, avec les Frameworks et Pilotes les plus à l'extérieur. Les dépendances du code source pointent toujours vers l'intérieur.

Pourquoi ça fonctionne : Lorsque les politiques de haut niveau ne dépendent pas des détails de bas niveau, vous pouvez changer la base de données, le framework web ou le style d'API sans toucher à la logique métier — le système devient résilient aux parties les plus volatiles de la pile.

Points clés :

  • Les cercles intérieurs ne peuvent pas mentionner les noms des cercles extérieurs — pas de classes, fonctions, variables ou formats de données provenant de l'extérieur
  • Les données traversant une frontière doivent être sous la forme la plus pratique pour le cercle intérieur, jamais dictées par l'extérieur
  • L'Inversion de Dépendance (interfaces définies vers l'intérieur, implémentées vers l'extérieur) est le mécanisme qui applique la règle
  • Le nombre de cercles n'est pas fixe — quatre est typique ; la règle reste la même
  • Les frameworks sont des détails, pas l'architecture — ils appartiennent au cercle le plus extérieur

Applications dans le code :

ContexteModèleExemple
Direction des couchesLes cercles intérieurs définissent les interfaces ; les extérieurs les implémententInterface UserRepository dans les Cas d'Utilisation ; PostgresUserRepository dans les Adaptateurs
Traversée des donnéesLes DTO traversent les frontières, pas les entités ORMLe Cas d'Utilisation retourne un DTO UserResponse, pas un modèle ActiveRecord
Direction des dépendancesLes flèches d'import pointent toujours vers l'intérieurLe Contrôleur importe le Cas d'Utilisation ; le Cas d'Utilisation n'importe jamais le Contrôleur

Voir references/dependency-rule.md lorsqu'un import du cercle intérieur pointe vers l'extérieur et que vous avez besoin de la procédure de quatre étapes pour l'inversion de dépendance, des règles de traversée des données et de la démonstration du code des quatre cercles pour le corriger.

2. Entités et Cas d'Utilisation

Concept de base : Les Entités encapsulent les règles métier de l'entreprise — des règles qui existeraient même sans logiciel. Les Cas d'Utilisation contiennent des règles spécifiques à l'application qui orchestrent le flux de données vers et depuis les Entités.

Pourquoi ça fonctionne : Séparer ce que l'entreprise fait (Entités) de la manière dont l'application l'orchestre (Cas d'Utilisation) vous permet de réutiliser les Entités dans plusieurs applications et de modifier le comportement de l'application sans altérer les règles métier fondamentales.

Points clés :

  • Les Entités ne sont pas des lignes de base de données — ce sont des objets ou des fonctions pures encapsulant des règles métier critiques
  • Les Cas d'Utilisation acceptent des Modèles de Requête et retournent des Modèles de Réponse — jamais d'objets framework
  • Chaque Cas d'Utilisation est une seule opération applicative (CreateOrder, ApproveExpense)
  • Le modèle Interactor : une classe Cas d'Utilisation implémente une interface d'entrée et appelle une interface de sortie
  • Les modifications d'un Cas d'Utilisation ne doivent jamais affecter une Entité ; les modifications d'une Entité peuvent se propager aux Cas d'Utilisation

Applications dans le code :

ContexteModèleExemple
Conception d'EntitéRègles métier critiques, zéro dépendance frameworkOrder.calculateTotal() applique les règles fiscales ; ne sait rien de HTTP
Requête/RéponseStructures de données simples traversent la frontièreCreateOrderRequest { items, customerId } — pas de modèles ORM
Responsabilité uniqueUn Cas d'Utilisation par opérationPlaceOrder, CancelOrder, RefundOrder comme classes séparées
InteractorImplémente le Port d'Entrée, appelle le Port de SortiePlaceOrderInteractor implements PlaceOrderInput

Voir references/entities-use-cases.md lors de la conception d'un Interactor ou pour décider ce qui appartient à une Entité par rapport à un Cas d'Utilisation — traitement complet des Règles Métier d'Entreprise vs. d'Application avec des exemples de modèles de requête/réponse.

3. Adaptateurs d'Interface et Frameworks

Concept de base : Les Adaptateurs d'Interface convertissent les données entre la forme pratique pour les Cas d'Utilisation/Entités et la forme requise par les agences externes. Les Frameworks et Pilotes sont la couche la plus externe — du code de colle avec le monde extérieur.

Pourquoi ça fonctionne : Lorsque le framework web, l'ORM ou la file de messages est confiné aux cercles extérieurs, leur remplacement est un changement localisé. La base de données est un détail ; le web est un détail ; les détails doivent être des plugins de vos règles métier, pas le squelette de l'application.

Points clés :

  • Les Contrôleurs traduisent HTTP en entrée de Cas d'Utilisation ; les Présentateurs traduisent la sortie du Cas d'Utilisation en modèles de vue
  • Les Passerelles implémentent les interfaces de dépôt définies par les Cas d'Utilisation — le cercle intérieur définit le contrat, l'extérieur l'exécute
  • Les règles métier ne savent jamais si les données vivent dans SQL, NoSQL ou des fichiers plats, ni que la livraison est HTTP
  • Traitez les frameworks avec méfiance — ils veulent que vous vous couplez à eux ; gardez-les à distance

Applications dans le code :

ContexteModèleExemple
ContrôleurMécanisme de livraison → entrée du Cas d'UtilisationOrderController.create(req) construit CreateOrderRequest, appelle l'Interactor
PrésentateurSortie du Cas d'Utilisation → modèle de vueOrderPresenter.present(response) formate pour JSON/HTML
PasserelleInterface de dépôt implémentée par base de donnéesSqlOrderRepository implements OrderRepository
Frontière de frameworkLe framework appelle vers l'intérieur, jamais l'inverseLe gestionnaire de route Express appelle le Contrôleur ; le Contrôleur n'importe jamais Express

Voir references/adapters-frameworks.md lors du câblage des contrôleurs, présentateurs ou passerelles, ou pour argumenter que la base de données/le web est un détail — couvre l'architecture de plugin et comment confiner un framework aux bords.

4. Principes des Composants

Concept de base : Les composants sont les unités de déploiement. Trois principes de cohésion régissent ce qui se trouve à l'intérieur d'un composant ; trois principes de couplage régissent les relations entre composants.

Pourquoi ça fonctionne : Des composants mal composés créent des effets de ripple où un changement force le redéploiement de code non lié ; les principes maintiennent les changements localisés et les versions indépendantes.

Points clés :

  • REP (Équivalence Réutilisation/Version) : les classes d'un composant doivent être versionnables et libérables comme une unité
  • CCP (Fermeture Commune) : les classes qui changent pour la même raison au même moment vont ensemble — SRP pour les composants
  • CRP (Réutilisation Commune) : ne forcez pas les utilisateurs à dépendre de classes qu'ils n'utilisent pas
  • ADP (Dépendances Acycliques) : le graphe de composants ne doit pas contenir de cycles — brisez-les avec DIP ou un nouveau composant
  • SDP (Dépendances Stables) : dépendez dans la direction de la stabilité
  • SAP (Abstractions Stables) : les composants stables doivent être abstraits ; les instables, concrets

Applications dans le code :

ContexteModèleExemple
Regroupement de composantsRegrouper les classes qui changent ensemble (CCP)Tous les Cas d'Utilisation liés aux commandes dans un composant
Briser les cyclesAppliquer DIP pour inverser une arête de dépendanceExtraire une interface dans un nouveau composant pour briser le cycle
Métriques de stabilitéInstabilité I = Ce / (Ca + Ce)Beaucoup de dépendances entrantes, aucune sortante → I proche de 0 (stable)

Voir references/component-principles.md lors du regroupement de classes en composants déployables ou pour briser un cycle de dépendance — chacun de REP, CCP, CRP, ADP, SDP, SAP travaillé avec la métrique d'instabilité.

5. Principes SOLID

Concept de base : Cinq principes au niveau classe et module — Responsabilité Unique, Ouvert-Fermé, Substitution de Liskov, Ségrégation d'Interface, Inversion de Dépendance — les blocs de construction de niveau intermédiaire qui rendent la Règle de Dépendance possible.

Pourquoi ça fonctionne : Chaque principe aborde une manière spécifique dont les dépendances dévient, empêchant la rigidité, la fragilité et l'immobilité qui transforment les bases de code en cauchemars hérités.

Points clés :

  • SRP : un module a une seule raison de changer — il sert un seul acteur (pas "fait une seule chose")
  • OCP : étendez le comportement en ajoutant du nouveau code, pas en modifiant le code existant — modèles de stratégie et de plugin
  • LSP : les sous-types doivent être utilisables via l'interface de base sans que le client le sache — violé par des exceptions inattendues ou des méthodes ignorées
  • ISP : les clients ne doivent pas dépendre de méthodes qu'ils n'utilisent pas — les interfaces trop larges créent un couplage inutile
  • DIP : les modules de haut niveau et les modules de bas niveau dépendent tous d'abstractions définies par le module de haut niveau

Applications dans le code :

ContexteModèleExemple
Violation SRPClasse servant plusieurs acteursEmployee gère la paie (CFO), le reporting (COO), la persistance (CTO)
OCP via stratégieNouveau comportement via de nouvelles classesAjouter ExpressShipping implémentant ShippingStrategy ; Order inchangé
Violation LSPSous-type modifiant le comportement attenduSquare extends Rectangle brise le contrat setWidth()/setHeight()
Application ISPDiviser les interfaces trop larges en interfaces de rôlePrinter, Scanner, Fax au lieu d'un seul MultiFunctionDevice
Câblage DIPLe haut niveau définit l'interface ; le bas niveau implémenteOrderService dépend de PaymentGateway, pas de StripeClient

Voir references/solid-principles.md lors de l'application de SRP/OCP/LSP/ISP/DIP à une classe spécifique ou du diagnostic d'une violation — chaque principe travaillé avec des exemples de code et l'odeur de code qu'il prévient.

6. Frontières et Anatomie des Frontières

Concept de base : Une frontière est une ligne entre ce qui compte et ce qui est détail, implémentée via le polymorphisme : les dépendances traversent en pointant vers l'intérieur tandis que le flux de contrôle peut traverser dans les deux sens.

Pourquoi ça fonctionne : Chaque frontière achète l'option de reporter une décision ou d'échanger une implémentation ; le placement stratégique des frontières détermine si un système est un plaisir ou une douleur à maintenir sur des années.

Points clés :

  • Les frontières complètes utilisent des interfaces réciproques des deux côtés ; les frontières partielles utilisent une stratégie ou une façade plus simple
  • Le modèle Objet Humble : divisez le code de frontière en une partie difficile à tester (près de la frontière) et une partie facile à tester (la logique)
  • Les services ne sont pas automatiquement des frontières architecturales — un microservice avec un modèle de données partagé volumineux est un monolithe avec des appels réseau
  • Les tests sont le composant le plus isolé : ils dépendent vers l'intérieur, rien ne dépend d'eux
  • Les frontières prématurées sont coûteuses, mais les frontières manquantes aussi — tracez-les aux points de volatilité probable

Applications dans le code :

ContexteModèleExemple
Frontière complète vs. partiellePorts réciproques, ou une stratégie seuleLe Cas d'Utilisation définit PlaceOrderInput/PlaceOrderOutput ; les cas plus simples prennent un ShippingStrategy
Objet HumbleSéparer la logique testable de l'infrastructurePresenterLogic (testable) produit ViewModel ; View (humble) le rend
Main comme pluginRacine de composition assemble le systèmemain() câble toutes les implémentations concrètes et démarre l'application

Voir references/boundaries.md lors de la décision de l'endroit où tracer une frontière, du choix entre complète et partielle, ou de l'application du modèle Objet Humble — couvre également les services comme frontières, les frontières de test et Main comme le plugin ultime.

Erreurs Courantes

ErreurPourquoi Ça ÉchoueCorrection
ORM fuyant dans la logique métierLes entités se couplent au schéma ; les changements de base de données réécrivent les règles métierSéparer les entités domaine des modèles de persistance ; mapper au niveau de l'adaptateur
Règles métier dans les contrôleursNon testables sans HTTP ; dupliquées entre les points de terminaisonDéplacer la logique dans les Interactors de Cas d'Utilisation ; les contrôleurs ne font que traduire et déléguer
Architecture d'abord frameworkLe framework dicte la structure ; le remplacer signifie une réécritureTraiter le framework comme un plugin ; structurer le code par capacité métier
Dépendances circulaires entre composantsLes changements se propagent de manière imprévisible ; pas de versions indépendantesAppliquer DIP ou extraire un composant d'abstraction partagé
Un seul énorme Cas d'Utilisation par fonctionnalitéDes orchestrateurs boursouflés de mille lignesDiviser en Cas d'Utilisation ciblés à opération unique
Sauter les frontières "parce que c'est simple"Le couplage s'accumule silencieusement jusqu'à ce que le coût soit énormeTracer les frontières de manière proactive aux points de volatilité probable
Les microservices comme bonne architecture automatiqueUn monolithe distribué est pire qu'un monolithe propreAppliquer la Règle de Dépendance à l'intérieur et entre les services ; les services sont des frontières de déploiement, pas architecturales

Diagnostic Rapide

QuestionSi NonAction
Pouvez-vous tester les règles métier sans base de données, serveur web ou framework ?Les règles sont couplées à l'infrastructureExtraire les entités et les cas d'utilisation derrière des interfaces ; simuler les couches externes
Toutes les dépendances du code source pointent-elles vers l'intérieur ?Il y a une inversion de dépendanceAppliquer le principe d'inversion de dépendance (DIP) pour inverser la direction
Les entités sont-elles libres de toute dépendance framework ?Les entités importent des objets ORM ou frameworkDéplacer les dépendances framework vers l'extérieur ; les entités ne doivent import\er que des types du langage standard
Les cas d'utilisation acceptent-ils et retournent-ils des structures de données simples plutôt que des modèles framework ?Les cas d'utilisation reçoivent/renvoient des objets framework ou ORMDéfinir des modèles de requête et de réponse simples pour chaque cas d'utilisation
Les contrôleurs se contentent-ils de traduire et de déléguer, sans logique métier ?Les contrôleurs contiennent des règles métier ou d'importantes transformationsExtraire la logique métier dans des cas d'utilisation ; les contrôleurs ne font que traduire et transmettre
Le graphique des dépendances entre composants est-il exempt de cycles ?Une modification dans un composant en affecte un autre de manière imprévisibleCasser le cycle en extrayant une interface ou en divisant le composant
Les implémentations de passerelles (par exemple, les dépôts SQL) résident-elles à l'extérieur de la logique métier ?Les requêtes de base de données sont dispersées dans les cas d'utilisationDéfinir les interfaces de dépôt dans les cas d'utilisation ; implémenter les passerelles dans la couche d'adaptateur

Skills associés