Regole di conformità (guardrail)

Le regole di conformità sono controlli deterministici che validano le modifiche al codice rispetto alle tue decisioni architetturali. Impongono convenzioni di denominazione, vincoli tecnologici, confini tra livelli e pattern di sicurezza — senza alcuna IA coinvolta.

Vai su Hub Agenti nella barra laterale per gestire le tue regole di conformità.

Perché le regole di conformità?

Quando gli agenti di programmazione IA (Claude Code, Cursor, Copilot) generano codice, non conoscono le tue decisioni architetturali. Le regole di conformità codificano queste decisioni come vincoli eseguibili:

• L'agente non può usare MongoDB se il tuo radar tecnologico indica PostgreSQL
• L'agente non può inserire chiamate al database negli handler HTTP se la tua architettura richiede un livello di servizio
• L'agente non può aggiungere fmt.Println se il tuo team usa il logging strutturato

Le regole vengono valutate in modo deterministico — nessun LLM, nessun output probabilistico. Lo stesso codice produce sempre lo stesso risultato.

Tipi di regole

Archyl supporta sette tipi di regole di conformità:

Pattern obbligatorio

Verifica i pattern che devono essere presenti o che non devono esserlo nel tuo codice.

Configurazione:

• File glob — Controlla solo i file che corrispondono a un pattern (ad es. *.go, *.{ts,tsx})
• Forbidden patterns — Pattern regex che generano una violazione quando vengono trovati
• Required patterns — Pattern regex che generano una violazione quando mancano

I glob dei file supportano l'espansione delle parentesi graffe: *.{js,jsx,ts,tsx} corrisponde a tutti i file JavaScript e TypeScript.

Convenzione di denominazione

Valida i pattern di denominazione di file, tipi e funzioni.

Configurazione:

• Patterns — Elenco di ambito (file/tipo/funzione) + regex + descrizione

Vincolo tecnologico

Limita i linguaggi e le librerie consentiti in un container.

Configurazione:

• Allowed languages — Elenco separato da virgole (ad es. go, typescript)
• Forbidden imports — Un import per riga

Confine tra livelli

Applica le regole di import tra livelli di Clean Architecture, architettura esagonale o DDD.

Configurazione:

• Layers — Definisci ogni livello con un nome, un pattern di percorso (glob) e le sorgenti di import consentite
• Clicca sui nomi dei livelli per attivare o disattivare i permessi di import

Conformità ai contratti

Verifica che i file degli handler degli endpoint contengano un'adeguata documentazione del contratto API.

Configurazione:

• Contract type — HTTP (OpenAPI), gRPC, GraphQL o AsyncAPI
• Endpoint file patterns — Glob per i file che contengono definizioni di endpoint
• Strict mode — Se attiva, qualsiasi file corrispondente privo di documentazione del contratto genera una violazione

Regola di dipendenza

Applica i percorsi di import vietati tra confini architetturali.

Configurazione:

• Scope — Livello di container o di componente
• Forbidden pairs — Pattern di percorso di origine e di destinazione che non devono mai dipendere l'uno dall'altro (ad es. **/service/** -> **/handler/**)

Conformità dei canali di eventi

Verifica che i pattern di produzione e consumo di eventi rispettino le convenzioni di denominazione.

Configurazione:

• Producer patterns — Pattern regex che identificano il codice che produce eventi (ad es. kafka\.Send)
• Consumer patterns — Pattern regex che identificano il codice che consuma eventi
• Topic regex — Pattern a cui devono corrispondere i nomi di topic validi (ad es. ^[a-z]+\.[a-z]+\.[a-z]+$)

Pacchetti di regole

I pacchetti sono raccolte curate di regole che puoi installare con un clic. Invece di aggiungere le regole una per una, installa un pacchetto e ottieni un set di regole completo per il tuo stack.

Clicca su Packs nella barra degli strumenti per sfogliare i pacchetti disponibili.

Pacchetti di architettura

Pacchetti per linguaggio

Pacchetti di dominio

Catalogo delle regole

Archyl include un catalogo di 169 regole predefinite per 23 tecnologie. Per esplorarlo, clicca su Sfoglia catalogo nell'Hub Agenti.

Tecnologie coperte

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

Categorie

Clicca su una regola qualsiasi del catalogo per aggiungerla — il modulo di configurazione si precompila automaticamente.

Livelli di gravità

Ogni regola ha una gravità che ne determina l'impatto:

Una verifica di conformità fallisce se vengono trovate violazioni di gravità critica o alta. Le violazioni di gravità media e bassa vengono segnalate, ma non fanno fallire la verifica.

Dashboard di conformità

La scheda Dashboard nell'Hub Agenti offre una panoramica in tempo reale di tutte le verifiche di conformità nei tuoi progetti.

Cosa mostra

• Schede statistiche — Verifiche totali, tasso di superamento (con codice colore), numero di verifiche superate e di verifiche fallite
• Rapporto superato / fallito — Barra visiva che mostra la proporzione a colpo d'occhio
• Banner dell'ultima verifica — Stato della verifica più recente, con un link al report completo
• Elenco delle verifiche recenti — Tutte le verifiche con stato, tipo di trigger, nome del progetto, numero di file, numero di violazioni e tempo trascorso

Filtri

Usa il menu a tendina dei progetti in alto per filtrare le verifiche per progetto, oppure seleziona "Tutti i progetti" per vedere tutto.

Report delle verifiche

Clicca su una verifica qualsiasi per aprirne il report completo:

• Barra di ripartizione per gravità — Visualizzazione proporzionale delle violazioni critiche/alte/medie/basse
• Violazioni raggruppate per file — Sezioni comprimibili con gravità, titolo, descrizione e suggerimento per ogni violazione
• Metadati della verifica — Tipo di trigger, SHA del commit, ora di inizio, durata

Ogni report di verifica ha il proprio URL condivisibile (ad es. /agent/dashboard/:checkId).

Eliminare le verifiche

Usa la selezione multipla per eliminare più verifiche in una volta:

1. Seleziona le caselle accanto alle singole verifiche, oppure usa "Seleziona tutto"
2. Clicca sul pulsante rosso Delete che compare
3. Le verifiche e le relative violazioni vengono rimosse definitivamente

Integrazione CI/CD

Le regole di conformità possono essere eseguite automaticamente a ogni pull request. Consulta Integrazione con GitHub Actions per le istruzioni di configurazione.

Come funziona

1. Una PR viene aperta o aggiornata su GitHub
2. La GitHub Action di Archyl recupera i file modificati
3. I file vengono inviati all'API di Archyl per la valutazione
4. I risultati compaiono come commento sulla PR e come controllo di stato del commit
5. Il workflow fallisce se vengono trovate violazioni critiche o alte

Commento sulla PR

Quando vengono trovate violazioni, Archyl pubblica un commento dettagliato sulla PR:

• Tabella riepilogativa con il numero di violazioni per gravità
• Violazioni per file con descrizioni e suggerimenti
• Il commento viene aggiornato (non duplicato) a ogni push successivo

Gestione delle regole

Creare regole

1. Clicca su Packs per installare un set curato di regole per il tuo stack, oppure
2. Clicca su Sfoglia catalogo per esplorare le 169 regole predefinite e aggiungerle, oppure
3. Clicca su Regola personalizzata per creare manualmente una nuova regola

Abilitare/disabilitare le regole

Usa l'interruttore accanto a una regola per abilitarla o disabilitarla. Le regole disabilitate non vengono valutate.

Modificare le regole

Clicca sull'icona di modifica (matita) di una regola per modificarne il nome, la descrizione, la gravità o la configurazione.

Eliminare le regole

Clicca sull'icona di eliminazione (cestino), poi conferma. L'operazione non può essere annullata.

Filtrare le regole

• Ricerca — Filtra per nome o descrizione della regola
• Filtro per tipo — Clicca sulle pill dei tipi per mostrare solo le regole di un tipo specifico

Integrazione MCP

Le regole di conformità sono accessibili agli agenti IA tramite il server MCP:

Strumenti MCP disponibili

Eseguire verifiche da un agente

Lo strumento run_conformance_check permette agli agenti IA di validare il codice prima del commit. L'agente invia i file su cui sta lavorando:

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

La risposta include:

• passed — Se la verifica è stata superata (nessuna violazione critica/alta)
• violations — Elenco delle violazioni con gravità, percorso del file, titolo e suggerimento
• rulesEvaluated — Quali regole sono state valutate
• filesAnalyzed — Quanti file sono stati analizzati
• checkId — L'ID della verifica (visibile nella dashboard)

L'agente può usare questo feedback per correggere le violazioni prima che il codice venga committato.

Contesto dell'agente

Lo strumento MCP get_agent_context restituisce tutte le regole di conformità attive come parte del briefing architetturale. Gli agenti IA che chiamano questo strumento prima di iniziare a lavorare sapranno quali guardrail rispettare.

REST API

# 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

Tutti gli endpoint richiedono l'autenticazione (JWT o chiave API con scope di scrittura per le mutazioni).