Regras de Conformidade (Guardrails) - Archyl Docs

Defina regras de arquitetura deterministicas que validam alteracoes de codigo contra seu modelo C4, decisoes tecnologicas e padroes de codificacao — sem IA envolvida

Regras de Conformidade (Guardrails)

Regras de conformidade sao verificacoes deterministicas que validam alteracoes de codigo contra suas decisoes arquiteturais. Elas impoem convencoes de nomenclatura, restricoes tecnologicas, limites entre camadas e padroes de seguranca — sem qualquer IA envolvida.

Navegue ate o Agent Hub na barra lateral para gerenciar suas regras de conformidade.

Por que regras de conformidade?

Quando agentes de codificacao IA (Claude Code, Cursor, Copilot) geram codigo, eles nao conhecem suas decisoes arquiteturais. Regras de conformidade codificam essas decisoes como restricoes executaveis:

  • O agente nao pode usar MongoDB se seu radar tecnologico indica PostgreSQL
  • O agente nao pode colocar chamadas ao banco de dados em handlers HTTP se sua arquitetura requer uma camada de servico
  • O agente nao pode adicionar fmt.Println se sua equipe usa logging estruturado

As regras sao avaliadas de forma deterministica — sem LLM, sem saida probabilistica. O mesmo codigo sempre produz o mesmo resultado.

Tipos de regras

O Archyl suporta sete tipos de regras de conformidade:

Padrao obrigatorio

Verificar padroes que devem existir ou nao devem existir no seu codigo.

Caso de uso Exemplo
Proibir logging de debug Proibir fmt.Println, console.log, print()
Proibir riscos de seguranca Proibir eval(), innerHTML, senhas hardcoded
Exigir tratamento de erros Exigir set -euo pipefail em scripts shell
Impor padroes Proibir SELECT * em consultas SQL

Configuracao:

  • File glob — Verificar apenas arquivos que correspondam a um padrao (ex. *.go, *.ts)
  • Padroes proibidos — Padroes regex que disparam uma violacao quando encontrados
  • Padroes obrigatorios — Padroes regex que disparam uma violacao quando ausentes

Convencao de nomenclatura

Validar padroes de nomenclatura de arquivos, tipos e funcoes.

Escopo Exemplo
Arquivo Arquivos Go devem ser snake_case.go
Tipo Tipos exportados devem ser PascalCase
Funcao Funcoes devem comecar com um verbo (Get, Create, Delete)

Configuracao:

  • Padroes — Lista de escopo (arquivo/tipo/funcao) + regex + descricao

Restricao tecnologica

Restringir quais linguagens e bibliotecas sao permitidas em um container.

Caso de uso Exemplo
Bloqueio de linguagem Backend deve ser apenas Go
Proibicao de dependencia Sem lodash (usar JS nativo)
Imposicao de migracao Sem moment.js (usar date-fns)

Configuracao:

  • Linguagens permitidas — Lista separada por virgulas (ex. go, typescript)
  • Imports proibidos — Um import por linha

Limite de camada

Impor regras de importacao de Clean Architecture, Arquitetura Hexagonal ou DDD.

Camada Pode importar de
Domain Nada (logica de negocio pura)
Service Apenas Domain
Adapter Domain, Service
Infrastructure Apenas Domain

Configuracao:

  • Camadas — Definir cada camada com um nome, padrao de caminho (glob) e fontes de importacao permitidas
  • Clique nos nomes das camadas para alternar as permissoes de importacao

Conformidade de contrato

Validar que os endpoints do codigo correspondam aos seus contratos de API armazenados no Archyl.

Configuracao:

  • Tipo de contrato — HTTP (OpenAPI), gRPC, GraphQL ou AsyncAPI
  • Padroes de arquivos de endpoints — Globs para arquivos contendo definicoes de endpoints
  • Modo estrito — Quando habilitado, qualquer endpoint fora do contrato dispara uma violacao

Regra de dependencia

Garantir que dependencias entre componentes correspondam ao modelo de relacionamentos C4.

Configuracao:

  • Escopo — Nivel de container ou componente
  • Exigir existencia de relacionamento — Cada import no codigo deve ter um relacionamento C4 correspondente
  • Pares proibidos — Pares de elementos especificos que nunca devem depender um do outro

Conformidade de canais de eventos

Validar que produtores/consumidores de eventos no codigo correspondam aos EventChannels declarados.

Configuracao:

  • Padroes de produtores — Padroes regex identificando codigo de producao de eventos
  • Padroes de consumidores — Padroes regex identificando codigo de consumo de eventos
  • Regex de topic — Padrao para extrair nomes de topics do codigo

Pacotes de regras

Pacotes sao colecoes curadas de regras que voce pode instalar com um clique. Em vez de adicionar regras uma a uma, instale um pacote e obtenha um conjunto completo de regras para seu stack.

Clique em Packs na barra de ferramentas para explorar os pacotes disponiveis.

Pacotes de arquitetura

Pacote Regras O que impoe
Clean Architecture 5 Limites de camada domain/service/adapter/infra, isolamento de modulos
Hexagonal Architecture 4 Padrao ports & adapters, isolamento do nucleo
Domain-Driven Design 3 Camadas DDD, separacao CQRS comando/consulta

Pacotes de linguagem

Pacote Regras O que cobre
Go Backend 26 Wrapping de erros, seguranca goroutine, propagacao de contexto, nomenclatura, sem panic, sem init()
React Frontend 23 Rigidez TypeScript, padroes de componentes, fetching de dados, sem manipulacao DOM
Next.js Full-Stack 20 Regras React + seguranca SSR, guards window, hooks localStorage
Python Backend 16 Tratamento de excecoes, padroes async, type hints, sem estado global
Java Backend 11 Padroes DI Spring, tratamento de excecoes, sem System.exit
Rust Backend 8 Sem unwrap/unsafe, tipos de erro corretos, sem todo!()
Kotlin / Android 5 Seguranca null, imutabilidade, sem println
Vue Frontend 10 Sem v-html, rigidez TypeScript, sem innerHTML
.NET / C# Backend 5 Padroes async, tratamento de excecoes, ILogger
Swift / iOS 3 Seguranca de optionals, sem force unwrap

Pacotes de dominio

Pacote Regras O que cobre
Security Essentials 17 Segredos hardcoded, injecao, criptografia fraca, TLS, CORS
DevOps & Infrastructure 24 Docker, Kubernetes, Terraform, GitHub Actions, scripts shell
API Best Practices 9 Codigos de status, seguranca SQL, documentacao de contratos, sem URLs hardcoded
Testing & Reliability 5 Sem testes ignorados, sem .only(), sem sleep, sem TODO
Event-Driven Architecture 3 Nomenclatura de topicos Kafka/RabbitMQ, sem topicos hardcoded

Catalogo de regras

O Archyl vem com um catalogo de 170+ regras pre-construidas em 24 tecnologias. Navegue pelo catalogo clicando em Catalog no Agent Hub.

Tecnologias cobertas

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

Categorias

Categoria Exemplos
Architecture & Design Clean Architecture, Hexagonal, DDD, MVC, handler-service-repository
Seguranca Sem segredos hardcoded, sem eval(), sem injecao SQL, sem TLS desabilitado, sem CORS wildcard
Qualidade de codigo Sem logging de debug, sem catch vazios, sem bare except, sem tipo any, sem unwrap()
Infrastructure & DevOps Fixar versoes Docker, limites de recursos K8s, sem containers privilegiados, tags Terraform
Convencoes de nomenclatura snake_case, PascalCase, camelCase por linguagem
Testes e confiabilidade Sem testes ignorados, sem .only(), sem TODO/FIXME
Performance Sem sleep sincrono, sem consultas N+1, sem await em loops
API e dados Sem SQL bruto, codigos de status HTTP corretos, validar corpos de requisicao

Clique em qualquer regra do catalogo para adiciona-la — o formulario de configuracao e preenchido automaticamente.

Niveis de severidade

Cada regra tem uma severidade que determina seu impacto:

Severidade Significado Exemplo
Critical Deve ser corrigido antes do merge Sem segredos hardcoded, sem eval(), violacoes de limites de camadas
High Deve ser corrigido preferencialmente antes do merge Sem logging de debug, fixar versoes Docker, sem panic em Go
Medium Corrigir quando conveniente Convencoes de nomenclatura, sem tipo any, sem var em JS
Low Informativo Sem TODO/FIXME, sem estilos inline em React

Gerenciamento de regras

Criar regras

  1. Clique em Packs para instalar um conjunto curado de regras para seu stack, ou
  2. Clique em Catalog para explorar e adicionar das 170+ regras pre-construidas, ou
  3. Clique em Custom para criar uma nova manualmente

Habilitar/Desabilitar regras

Alterne o interruptor ao lado de qualquer regra para habilita-la ou desabilita-la. Regras desabilitadas nao sao avaliadas.

Editar regras

Clique no icone de edicao (lapis) em qualquer regra para modificar seu nome, descricao, severidade ou configuracao.

Excluir regras

Clique no icone de exclusao (lixeira), depois confirme. Esta acao nao pode ser desfeita.

Filtrar regras

  • Pesquisar — Filtrar por nome ou descricao da regra
  • Filtro por tipo — Clique nas pastilhas de tipo para mostrar apenas regras de um tipo especifico

Integracao CI/CD

Regras de conformidade podem ser executadas automaticamente em cada pull request. Consulte Integracao com GitHub Actions para instrucoes de configuracao.

Como funciona

  1. Um PR e aberto ou atualizado no GitHub
  2. A GitHub Action do Archyl busca os arquivos alterados
  3. Os arquivos sao enviados para a API do Archyl para avaliacao
  4. Os resultados aparecem como comentario de PR e status do commit
  5. O workflow falha se violacoes criticas ou altas forem encontradas

Comentario de PR

Quando violacoes sao encontradas, o Archyl publica um comentario detalhado no PR:

  • Tabela resumo com contagem de violacoes por severidade
  • Violacoes por arquivo com descricoes e sugestoes
  • O comentario e atualizado (nao duplicado) em pushes subsequentes

Integracao MCP

Regras de conformidade sao acessiveis para agentes IA atraves do servidor MCP:

Ferramentas MCP disponiveis

Ferramenta Descricao
list_conformance_rules Listar todas as regras com filtro opcional por projeto
create_conformance_rule Criar uma nova regra
update_conformance_rule Atualizar configuracao, severidade ou estado de ativacao de uma regra
delete_conformance_rule Excluir uma regra
get_agent_context Obter o contexto arquitetural completo incluindo guardrails ativos

Contexto do agente

A ferramenta MCP get_agent_context retorna todas as regras de conformidade ativas como parte do briefing arquitetural. Agentes IA que chamam esta ferramenta antes de comecar a trabalhar saberao quais guardrails respeitar.

O contexto tambem inclui:

  • Modelo C4 (sistemas, containers, componentes, relacionamentos)
  • ADRs ativos com justificativa
  • Stack tecnologico
  • Contratos de API
  • Canais de eventos

REST API

Regras de conformidade tambem estao disponiveis atraves da REST API:

GET    /api/v1/conformance/rules              # Listar regras
POST   /api/v1/conformance/rules              # Criar regra
POST   /api/v1/conformance/rules/bulk         # Criar multiplas regras (usado por pacotes)
GET    /api/v1/conformance/rules/:id          # Obter regra
PUT    /api/v1/conformance/rules/:id          # Atualizar regra
DELETE /api/v1/conformance/rules/:id          # Excluir regra
POST   /api/v1/conformance/rules/:id/toggle   # Habilitar/desabilitar
POST   /api/v1/projects/:id/conformance/check # Acionar verificacao com arquivos alterados
GET    /api/v1/projects/:id/conformance/checks # Listar historico de verificacoes
GET    /api/v1/conformance/checks/:id/report  # Obter relatorio de verificacao
GET    /api/v1/projects/:id/conformance/stats  # Obter estatisticas do projeto

Todos os endpoints requerem autenticacao (JWT ou chave API com escopo de escrita para mutacoes).