Règles de conformité (garde-fous)

Les règles de conformité sont des vérifications déterministes qui valident les modifications de code par rapport à vos décisions d'architecture. Elles imposent des conventions de nommage, des contraintes technologiques, des frontières entre couches et des patterns de sécurité — sans aucune IA.

Rendez-vous dans Hub Agent dans la barre latérale pour gérer vos règles de conformité.

Pourquoi des règles de conformité ?

Lorsque des agents de code IA (Claude Code, Cursor, Copilot) génèrent du code, ils ne connaissent pas vos décisions d'architecture. Les règles de conformité traduisent ces décisions en contraintes exécutables :

• L'agent ne peut pas utiliser MongoDB si votre radar technologique indique PostgreSQL
• L'agent ne peut pas placer d'appels à la base de données dans les handlers HTTP si votre architecture impose une couche service
• L'agent ne peut pas ajouter fmt.Println si votre équipe utilise la journalisation structurée

Les règles sont évaluées de manière déterministe — pas de LLM, pas de résultat probabiliste. Le même code produit toujours le même résultat.

Types de règles

Archyl prend en charge sept types de règles de conformité :

Pattern requis

Vérifie les patterns qui doivent être présents dans votre code, ou qui ne doivent pas y figurer.

Configuration :

• File glob — Ne vérifier que les fichiers correspondant à un pattern (par exemple *.go, *.{ts,tsx})
• Forbidden patterns — Expressions régulières qui déclenchent une violation lorsqu'elles sont trouvées
• Required patterns — Expressions régulières qui déclenchent une violation lorsqu'elles sont absentes

Les globs de fichiers prennent en charge l'expansion des accolades : *.{js,jsx,ts,tsx} correspond à tous les fichiers JavaScript et TypeScript.

Convention de nommage

Valide les patterns de nommage des fichiers, des types et des fonctions.

Configuration :

• Patterns — Liste d'entrées associant une portée (fichier/type/fonction), une regex et une description

Contrainte technologique

Restreint les langages et les bibliothèques autorisés dans un conteneur.

Configuration :

• Allowed languages — Liste séparée par des virgules (par exemple go, typescript)
• Forbidden imports — Un import par ligne

Frontière de couche

Impose les règles d'import entre couches de la Clean Architecture, de l'architecture hexagonale ou du DDD.

Configuration :

• Layers — Définissez chaque couche avec un nom, un pattern de chemin (glob) et les sources d'import autorisées
• Cliquez sur les noms de couches pour autoriser ou retirer les permissions d'import

Conformité de contrat

Vérifie que les fichiers de handlers d'endpoints contiennent une documentation de contrat d'API appropriée.

Configuration :

• Contract type — HTTP (OpenAPI), gRPC, GraphQL ou AsyncAPI
• Endpoint file patterns — Globs des fichiers contenant des définitions d'endpoints
• Strict mode — Lorsqu'il est activé, tout fichier correspondant dépourvu de documentation de contrat déclenche une violation

Règle de dépendance

Interdit certains chemins d'import entre les frontières d'architecture.

Configuration :

• Scope — Niveau conteneur ou composant
• Forbidden pairs — Patterns de chemins source et cible qui ne doivent jamais dépendre l'un de l'autre (par exemple **/service/** -> **/handler/**)

Conformité des canaux d'événements

Vérifie que les patterns de production et de consommation d'événements respectent les conventions de nommage.

Configuration :

• Producer patterns — Expressions régulières identifiant le code qui produit des événements (par exemple kafka\.Send)
• Consumer patterns — Expressions régulières identifiant le code qui consomme des événements
• Topic regex — Pattern auquel les noms de topics valides doivent correspondre (par exemple ^[a-z]+\.[a-z]+\.[a-z]+$)

Packs de règles

Les packs sont des collections de règles sélectionnées avec soin, que vous pouvez installer en un clic. Au lieu d'ajouter les règles une par une, installez un pack et obtenez un ensemble de règles complet pour votre stack.

Cliquez sur Packs dans la barre d'outils pour parcourir les packs disponibles.

Packs d'architecture

Packs de langage

Packs de domaine

Catalogue de règles

Archyl est livré avec un catalogue de 169 règles prêtes à l'emploi couvrant 23 technologies. Parcourez le catalogue en cliquant sur Parcourir le catalogue dans le Hub Agent.

Technologies couvertes

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, React, Vue, Angular, Next.js, Docker, Kubernetes, Terraform, SQL, Shell, YAML, GitHub Actions

Catégories

Cliquez sur n'importe quelle règle du catalogue pour l'ajouter — le formulaire de configuration se préremplit automatiquement.

Niveaux de sévérité

Chaque règle possède une sévérité qui détermine son impact :

Une vérification de conformité échoue si des violations critiques ou élevées sont détectées. Les violations moyennes et faibles sont signalées, mais ne font pas échouer la vérification.

Tableau de bord de conformité

L'onglet Tableau de bord du Hub Agent offre une vue d'ensemble en temps réel de toutes les vérifications de conformité de vos projets.

Ce qu'il affiche

• Cartes de statistiques — Nombre total de vérifications, taux de réussite (avec code couleur), nombre de vérifications réussies et échouées
• Ratio réussite / échec — Barre visuelle qui montre la proportion en un coup d'œil
• Bannière de la dernière vérification — Statut de la vérification la plus récente, avec un lien vers le rapport complet
• Liste des vérifications récentes — Toutes les vérifications avec leur statut, le type de déclencheur, le nom du projet, le nombre de fichiers, le nombre de violations et leur ancienneté

Filtrer

Utilisez le menu déroulant des projets en haut de la page pour filtrer les vérifications par projet, ou sélectionnez "Tous les projets" pour tout afficher.

Rapports de vérification

Cliquez sur une vérification pour afficher son rapport complet :

• Barre de répartition par sévérité — Visualisation proportionnelle des violations critiques, élevées, moyennes et faibles
• Violations regroupées par fichier — Sections repliables indiquant la sévérité, le titre, la description et une suggestion pour chaque violation
• Métadonnées de la vérification — Type de déclencheur, SHA du commit, heure de début, durée

Chaque rapport de vérification possède sa propre URL partageable (par exemple /agent/dashboard/:checkId).

Supprimer des vérifications

Utilisez la sélection multiple pour supprimer des vérifications en masse :

1. Cochez les cases à côté des vérifications concernées, ou utilisez "Tout sélectionner"
2. Cliquez sur le bouton rouge Delete qui apparaît
3. Les vérifications et leurs violations sont définitivement supprimées

Intégration CI/CD

Les règles de conformité peuvent s'exécuter automatiquement sur chaque pull request. Consultez Intégration GitHub Actions pour les instructions de configuration.

Fonctionnement

1. Une PR est ouverte ou mise à jour sur GitHub
2. L'action GitHub d'Archyl récupère les fichiers modifiés
3. Les fichiers sont envoyés à l'API d'Archyl pour évaluation
4. Les résultats apparaissent sous la forme d'un commentaire sur la PR et d'un statut de commit
5. Le workflow échoue si des violations critiques ou élevées sont détectées

Commentaire sur la PR

Lorsque des violations sont détectées, Archyl publie un commentaire détaillé sur la PR :

• Tableau récapitulatif du nombre de violations par sévérité
• Violations par fichier, avec descriptions et suggestions
• Le commentaire est mis à jour (et non dupliqué) lors des pushs suivants

Gérer les règles

Créer des règles

1. Cliquez sur Packs pour installer un ensemble de règles sélectionnées pour votre stack, ou
2. Cliquez sur Parcourir le catalogue pour explorer les 169 règles prêtes à l'emploi et en ajouter, ou
3. Cliquez sur Règle personnalisée pour créer une nouvelle règle manuellement

Activer/désactiver des règles

Basculez l'interrupteur à côté d'une règle pour l'activer ou la désactiver. Les règles désactivées ne sont pas évaluées.

Modifier des règles

Cliquez sur l'icône de modification (crayon) d'une règle pour changer son nom, sa description, sa sévérité ou sa configuration.

Supprimer des règles

Cliquez sur l'icône de suppression (corbeille), puis confirmez. Cette action est irréversible.

Filtrer les règles

• Recherche — Filtrez par nom ou description de règle
• Filtre par type — Cliquez sur les pastilles de type pour n'afficher que les règles d'un type donné

Intégration MCP

Les règles de conformité sont accessibles aux agents IA via le serveur MCP :

Outils MCP disponibles

Exécuter des vérifications depuis un agent

L'outil run_conformance_check permet aux agents IA de valider le code avant de le committer. L'agent envoie les fichiers sur lesquels il travaille :

{
  "projectId": "your-project-uuid",
  "changedFiles": [
    { "path": "internal/handler/user.go", "status": "modified" }
  ],
  "fileContents": {
    "internal/handler/user.go": "package handler\nimport..."
  }
}

La réponse contient :

• passed — Indique si la vérification a réussi (aucune violation critique ou élevée)
• violations — Liste des violations avec la sévérité, le chemin du fichier, le titre et la suggestion
• rulesEvaluated — Les règles qui ont été évaluées
• filesAnalyzed — Le nombre de fichiers analysés
• checkId — L'identifiant de la vérification (visible dans le tableau de bord)

L'agent peut s'appuyer sur ce retour pour corriger les violations avant que le code ne soit commité.

Contexte de l'agent

L'outil MCP get_agent_context renvoie toutes les règles de conformité actives dans le cadre du briefing architectural. Les agents IA qui appellent cet outil avant de commencer à travailler savent ainsi quels garde-fous respecter.

API REST

# Rules
GET    /api/v1/conformance/rules              # List rules
POST   /api/v1/conformance/rules              # Create rule
POST   /api/v1/conformance/rules/bulk         # Create multiple rules (used by packs)
GET    /api/v1/conformance/rules/:id          # Get rule
PUT    /api/v1/conformance/rules/:id          # Update rule
DELETE /api/v1/conformance/rules/:id          # Delete rule
POST   /api/v1/conformance/rules/:id/toggle   # Enable/disable

# Checks
POST   /api/v1/projects/:id/conformance/check # Trigger check with changed files
GET    /api/v1/conformance/checks             # List all checks (org-wide, ?projectId= filter)
GET    /api/v1/conformance/checks/:id/report  # Get check report with violations
POST   /api/v1/conformance/checks/delete      # Bulk delete checks { ids: [...] }

# Stats
GET    /api/v1/conformance/stats              # Org-wide statistics
GET    /api/v1/projects/:id/conformance/stats  # Project statistics

Tous les endpoints nécessitent une authentification (JWT, ou clé API avec le scope d'écriture pour les mutations).