Regole di conformita (Guardrails)
Le regole di conformita 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.
Naviga su Agent Hub nella barra laterale per gestire le tue regole di conformita.
Perche le regole di conformita?
Quando gli agenti di codifica IA (Claude Code, Cursor, Copilot) generano codice, non conoscono le tue decisioni architetturali. Le regole di conformita codificano queste decisioni come vincoli eseguibili:
- L'agente non puo usare MongoDB se il tuo radar tecnologico indica PostgreSQL
- L'agente non puo inserire chiamate al database negli handler HTTP se la tua architettura richiede un livello di servizio
- L'agente non puo aggiungere
fmt.Printlnse 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 conformita:
Pattern obbligatorio
Verificare la presenza di pattern che devono o non devono esistere nel codice.
| Caso d'uso | Esempio |
|---|---|
| Vietare il logging di debug | Vietare fmt.Println, console.log, print() |
| Vietare rischi di sicurezza | Vietare eval(), innerHTML, password hardcoded |
| Richiedere la gestione degli errori | Richiedere set -euo pipefail negli script shell |
| Imporre standard | Vietare SELECT * nelle query SQL |
Configurazione:
- File glob — Controllare solo i file che corrispondono a un pattern (es.
*.go,*.ts) - Pattern vietati — Pattern regex che generano una violazione quando trovati
- Pattern obbligatori — Pattern regex che generano una violazione quando assenti
Convenzione di denominazione
Validare i pattern di denominazione di file, tipi e funzioni.
| Ambito | Esempio |
|---|---|
| File | I file Go devono essere snake_case.go |
| Tipo | I tipi esportati devono essere PascalCase |
| Funzione | Le funzioni dovrebbero iniziare con un verbo (Get, Create, Delete) |
Configurazione:
- Pattern — Lista di ambito (file/tipo/funzione) + regex + descrizione
Vincolo tecnologico
Limitare quali linguaggi e librerie sono consentiti in un container.
| Caso d'uso | Esempio |
|---|---|
| Blocco linguaggio | Il backend deve essere solo Go |
| Divieto di dipendenza | Niente lodash (usare JS nativo) |
| Imposizione di migrazione | Niente moment.js (usare date-fns) |
Configurazione:
- Linguaggi consentiti — Lista separata da virgole (es.
go, typescript) - Import vietati — Un import per riga
Confine di livello
Imporre le regole di import di Clean Architecture, Architettura Esagonale o DDD.
| Livello | Puo importare da |
|---|---|
| Domain | Nulla (logica di business pura) |
| Service | Solo Domain |
| Adapter | Domain, Service |
| Infrastructure | Solo Domain |
Configurazione:
- Livelli — Definire ogni livello con un nome, pattern di percorso (glob) e sorgenti di import consentite
- Clicca sui nomi dei livelli per alternare i permessi di import
Conformita del contratto
Validare che gli endpoint del codice corrispondano ai contratti API archiviati in Archyl.
Configurazione:
- Tipo di contratto — HTTP (OpenAPI), gRPC, GraphQL o AsyncAPI
- Pattern file endpoint — Glob per file contenenti definizioni di endpoint
- Modalita rigorosa — Quando abilitata, qualsiasi endpoint non presente nel contratto genera una violazione
Regola di dipendenza
Garantire che le dipendenze tra componenti corrispondano al modello di relazioni C4.
Configurazione:
- Ambito — Livello container o componente
- Richiedere l'esistenza della relazione — Ogni import nel codice deve avere una relazione C4 corrispondente
- Coppie vietate — Coppie di elementi specifici che non devono mai dipendere l'uno dall'altro
Conformita dei canali di eventi
Validare che i produttori/consumatori di eventi nel codice corrispondano agli EventChannel dichiarati.
Configurazione:
- Pattern produttori — Pattern regex che identificano il codice di produzione di eventi
- Pattern consumatori — Pattern regex che identificano il codice di consumo di eventi
- Regex topic — Pattern per estrarre i nomi dei topic dal codice
Pacchetti di regole
I pacchetti sono collezioni curate di regole che puoi installare con un clic. Invece di aggiungere regole una per una, installa un pacchetto e ottieni un set completo di regole per il tuo stack.
Clicca su Packs nella toolbar per sfogliare i pacchetti disponibili.
Pacchetti architettura
| Pacchetto | Regole | Cosa impone |
|---|---|---|
| Clean Architecture | 5 | Confini livello domain/service/adapter/infra, isolamento moduli |
| Hexagonal Architecture | 4 | Pattern ports & adapters, isolamento del core |
| Domain-Driven Design | 3 | Livelli DDD, separazione CQRS command/query |
Pacchetti linguaggio
| Pacchetto | Regole | Cosa copre |
|---|---|---|
| Go Backend | 26 | Wrapping errori, sicurezza goroutine, propagazione contesto, naming, no panic, no init() |
| React Frontend | 23 | Rigore TypeScript, pattern componenti, fetching dati, no manipolazione DOM |
| Next.js Full-Stack | 20 | Regole React + sicurezza SSR, guard window, hook localStorage |
| Python Backend | 16 | Gestione eccezioni, pattern async, type hints, no stato globale |
| Java Backend | 11 | Pattern DI Spring, gestione eccezioni, no System.exit |
| Rust Backend | 8 | No unwrap/unsafe, tipi errore corretti, no todo!() |
| Kotlin / Android | 5 | Sicurezza null, immutabilita, no println |
| Vue Frontend | 10 | No v-html, rigore TypeScript, no innerHTML |
| .NET / C# Backend | 5 | Pattern async, gestione eccezioni, ILogger |
| Swift / iOS | 3 | Sicurezza opzionali, no force unwrap |
Pacchetti dominio
| Pacchetto | Regole | Cosa copre |
|---|---|---|
| Security Essentials | 17 | Segreti hardcoded, iniezione, crypto debole, TLS, CORS |
| DevOps & Infrastructure | 24 | Docker, Kubernetes, Terraform, GitHub Actions, script shell |
| API Best Practices | 9 | Codici di stato, sicurezza SQL, documentazione contratti, no URL hardcoded |
| Testing & Reliability | 5 | No test saltati, no .only(), no sleep, no TODO |
| Event-Driven Architecture | 3 | Naming topic Kafka/RabbitMQ, no topic hardcoded |
Catalogo regole
Archyl include un catalogo di 170+ regole precostruite per 24 tecnologie. Sfoglia il catalogo cliccando su Catalog nell'Agent Hub.
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
| Categoria | Esempi |
|---|---|
| Architecture & Design | Clean Architecture, Hexagonal, DDD, MVC, handler-service-repository |
| Sicurezza | Niente segreti hardcoded, niente eval(), niente SQL injection, niente TLS disabilitato, niente CORS wildcard |
| Qualita del codice | Niente logging di debug, niente catch vuoti, niente bare except, niente tipo any, niente unwrap() |
| Infrastructure & DevOps | Fissare le versioni Docker, limiti risorse K8s, niente container privilegiati, tag Terraform |
| Convenzioni di denominazione | snake_case, PascalCase, camelCase per linguaggio |
| Test e affidabilita | Niente test saltati, niente .only(), niente TODO/FIXME |
| Prestazioni | Niente sleep sincrono, niente query N+1, niente await nei cicli |
| API e dati | Niente SQL grezzo, codici di stato HTTP corretti, validare i body delle richieste |
Clicca su qualsiasi regola nel catalogo per aggiungerla — il modulo di configurazione si precompila automaticamente.
Livelli di severita
Ogni regola ha una severita che ne determina l'impatto:
| Severita | Significato | Esempio |
|---|---|---|
| Critical | Da correggere prima del merge | Niente segreti hardcoded, niente eval(), violazioni dei confini di livello |
| High | Da correggere preferibilmente prima del merge | Niente logging di debug, fissare versioni Docker, niente panic in Go |
| Medium | Da correggere quando opportuno | Convenzioni di denominazione, niente tipo any, niente var in JS |
| Low | Informativo | Niente TODO/FIXME, niente stili inline in React |
Gestione delle regole
Creare regole
- Clicca su Packs per installare un set curato di regole per il tuo stack, oppure
- Clicca su Catalog per sfogliare e aggiungere dalle 170+ regole precostruite, oppure
- Clicca su Custom per crearne una nuova manualmente
Abilitare/Disabilitare regole
Attiva o disattiva l'interruttore accanto a qualsiasi regola per abilitarla o disabilitarla. Le regole disabilitate non vengono valutate.
Modificare regole
Clicca sull'icona di modifica (matita) su qualsiasi regola per modificarne il nome, la descrizione, la severita o la configurazione.
Eliminare regole
Clicca sull'icona di eliminazione (cestino), poi conferma. Questa azione non puo essere annullata.
Filtrare le regole
- Ricerca — Filtrare per nome o descrizione della regola
- Filtro per tipo — Clicca sulle pill di tipo per mostrare solo regole di un tipo specifico
Integrazione CI/CD
Le regole di conformita possono essere eseguite automaticamente ad ogni pull request. Consulta Integrazione GitHub Actions per le istruzioni di configurazione.
Come funziona
- Viene aperto o aggiornato un PR su GitHub
- La GitHub Action di Archyl recupera i file modificati
- I file vengono inviati all'API Archyl per la valutazione
- I risultati appaiono come commento PR e stato del commit
- Il workflow fallisce se vengono trovate violazioni critiche o alte
Commento PR
Quando vengono trovate violazioni, Archyl pubblica un commento dettagliato sul PR:
- Tabella riepilogativa con conteggio violazioni per severita
- Violazioni per file con descrizioni e suggerimenti
- Il commento viene aggiornato (non duplicato) nei push successivi
Integrazione MCP
Le regole di conformita sono accessibili agli agenti IA tramite il server MCP:
Strumenti MCP disponibili
| Strumento | Descrizione |
|---|---|
list_conformance_rules |
Elencare tutte le regole con filtro opzionale per progetto |
create_conformance_rule |
Creare una nuova regola |
update_conformance_rule |
Aggiornare configurazione, severita o stato di attivazione di una regola |
delete_conformance_rule |
Eliminare una regola |
get_agent_context |
Ottenere il contesto architetturale completo inclusi i guardrails attivi |
Contesto dell'agente
Lo strumento MCP get_agent_context restituisce tutte le regole di conformita attive come parte del briefing architetturale. Gli agenti IA che chiamano questo strumento prima di iniziare a lavorare sapranno quali guardrails rispettare.
Il contesto include anche:
- Modello C4 (sistemi, container, componenti, relazioni)
- ADR attivi con motivazione
- Stack tecnologico
- Contratti API
- Canali di eventi
REST API
Le regole di conformita sono disponibili anche tramite la REST API:
GET /api/v1/conformance/rules # Elencare le regole
POST /api/v1/conformance/rules # Creare una regola
POST /api/v1/conformance/rules/bulk # Creare piu regole (usato dai pacchetti)
GET /api/v1/conformance/rules/:id # Ottenere una regola
PUT /api/v1/conformance/rules/:id # Aggiornare una regola
DELETE /api/v1/conformance/rules/:id # Eliminare una regola
POST /api/v1/conformance/rules/:id/toggle # Abilitare/disabilitare
POST /api/v1/projects/:id/conformance/check # Eseguire verifica con file modificati
GET /api/v1/projects/:id/conformance/checks # Elencare storico verifiche
GET /api/v1/conformance/checks/:id/report # Ottenere report verifica
GET /api/v1/projects/:id/conformance/stats # Ottenere statistiche progetto
Tutti gli endpoint richiedono autenticazione (JWT o chiave API con scope di scrittura per le mutazioni).