Architecture hexagonale et agent
Pourquoi les ports et adapters rendent le code plus facile à générer, isoler et tester pour un agent. L'architecture comme leverage point (LP8), les ports comme contrats, et les pièges : violation de la règle de dépendance et sur-ingénierie.
Ce que l’hexagonal place au centre
L’architecture hexagonale (ports & adapters) met le domaine métier au centre. Autour, des adapters branchent le monde extérieur : base de données, API web, services tiers. Entre les deux, des ports : de simples interfaces qui décrivent ce que le domaine attend ou expose.
Point clé : La règle de dépendance pointe vers l’intérieur. Les adapters dépendent du domaine, jamais l’inverse. Le domaine ne connaît ni EF Core, ni ASP.NET.
Un port dit quoi (IOrderRepository.Save(order)), un adapter dit comment (l’implémentation EF Core). Le domaine programme contre l’abstraction, pas contre le détail.
Pourquoi ça aide un agent (LP8)
L’architecture est l’un des 12 leverage points (LP8). Une codebase bien structurée augmente l’autonomie de l’agent ; une codebase enchevêtrée le désoriente.
Point clé : Des frontières claires indiquent à l’agent où mettre le code. Il devine la place d’un nouvel adapter parce que la structure le lui dit.
Trois bénéfices concrets :
- Moins de contexte à charger — pour modifier un adapter, l’agent n’a besoin que du port concerné, pas de tout le domaine. Moins de tokens, moins de context rot.
- Des ports = des specs — « implémente
IPriceCalculator» est une consigne nette : la signature borne ce que l’agent doit produire. - Un domaine pur = un feedback loop rapide — testable sans base ni réseau, donc des tests en millisecondes. C’est LP7 + closed-loop : l’agent écrit, teste, corrige.
Isolation et blast radius
Changer de persistance (SQL vers Mongo) ou de fournisseur d’email ne touche qu’un adapter. Le domaine et les autres adapters ne bougent pas.
Point clé : Cette isolation réduit le blast radius d’une modification. Pour un agent out-of-loop, c’est un filet : un effet de bord reste confiné à un adapter au lieu de contaminer le cœur métier (principe ZTE).
| Élément | Rôle | Stabilité |
|---|---|---|
| Domaine | Règles métier pures | Stable |
| Port | Contrat (interface) | Stable, frontière |
| Adapter | Implémentation infra | Volatile, substituable |
Les pièges avec un agent
Attention — violation silencieuse. Un agent peut importer un type EF Core directement dans le domaine « parce que ça marche ». Le code compile, les tests passent, mais l’abstraction est rompue. Remède : l’écrire dans le CLAUDE.md et ajouter un test d’architecture (NetArchTest) qui casse le build si le domaine référence l’infra.
Attention — sur-ingénierie. Un agent zélé crée volontiers un port + adapter pour chaque dépendance, même un logger trivial. L’abstraction a un coût. Réserver les ports aux frontières qu’on veut vraiment substituer, tester ou isoler. Simplicité d’abord.
L’agent ne connaît pas tes bounded contexts par défaut. Rends-les visibles : structure de dossiers, conventions dans CLAUDE.md, exemples existants (LP11).
Remonte relire la fiche memo ci-dessus en pretant attention aux points rates, puis clique sur « Recommencer » pour retenter.