Regras de Conformidade (Guardrails)

As regras de conformidade são verificações determinísticas que validam alterações de código contra suas decisões arquiteturais. Elas impõem convenções de nomenclatura, restrições tecnológicas, fronteiras de camadas e padrões de segurança — sem nenhuma IA envolvida.

Acesse o Hub de Agentes na barra lateral para gerenciar suas regras de conformidade.

Por que Regras de Conformidade?

Quando agentes de código com IA (Claude Code, Cursor, Copilot) geram código, eles não conhecem suas decisões arquiteturais. As regras de conformidade codificam essas decisões como restrições executáveis:

• O agente não pode usar MongoDB se o seu radar de tecnologias indica PostgreSQL
• O agente não pode colocar chamadas ao banco de dados em handlers HTTP se a sua arquitetura exige uma camada de serviço
• O agente não pode adicionar fmt.Println se a sua equipe usa logging estruturado

As regras são avaliadas de forma determinística — sem LLM, sem saída probabilística. O mesmo código sempre produz o mesmo resultado.

Tipos de Regras

O Archyl oferece suporte a sete tipos de regras de conformidade:

Padrão Obrigatório

Verifique padrões que devem ou não devem existir no seu código.

Configuração:

• File glob — Verifica apenas os arquivos que correspondem a um padrão (ex.: *.go, *.{ts,tsx})
• Forbidden patterns — Padrões regex que geram uma violação quando encontrados
• Required patterns — Padrões regex que geram uma violação quando ausentes

Os globs de arquivos suportam expansão de chaves: *.{js,jsx,ts,tsx} corresponde a todos os arquivos JavaScript e TypeScript.

Convenção de Nomenclatura

Valide os padrões de nomenclatura de arquivos, tipos e funções.

Configuração:

• Patterns — Lista de escopo (arquivo/tipo/função) + regex + descrição

Restrição Tecnológica

Restrinja quais linguagens e bibliotecas são permitidas em um container.

Configuração:

• Allowed languages — Lista separada por vírgulas (ex.: go, typescript)
• Forbidden imports — Um import por linha

Fronteira de Camadas

Imponha as regras de import entre camadas da Clean Architecture, da Arquitetura Hexagonal ou do DDD.

Configuração:

• Layers — Defina cada camada com um nome, um padrão de caminho (glob) e as origens de import permitidas
• Clique nos nomes das camadas para alternar as permissões de import

Conformidade de Contratos

Valide se os arquivos de handlers de endpoints contêm a documentação adequada do contrato de API.

Configuração:

• Contract type — HTTP (OpenAPI), gRPC, GraphQL ou AsyncAPI
• Endpoint file patterns — Globs para os arquivos que contêm definições de endpoints
• Strict mode — Quando ativado, qualquer arquivo correspondente sem documentação de contrato gera uma violação

Regra de Dependência

Imponha caminhos de import proibidos entre fronteiras arquiteturais.

Configuração:

• Scope — Nível de container ou de componente
• Forbidden pairs — Padrões de caminho de origem e de destino que nunca devem depender um do outro (ex.: **/service/** -> **/handler/**)

Conformidade de Canais de Eventos

Valide se os padrões de produtores/consumidores de eventos seguem as convenções de nomenclatura.

Configuração:

• Producer patterns — Padrões regex que identificam código de produção de eventos (ex.: kafka\.Send)
• Consumer patterns — Padrões regex que identificam código de consumo de eventos
• Topic regex — Padrão ao qual os nomes de tópicos válidos devem corresponder (ex.: ^[a-z]+\.[a-z]+\.[a-z]+$)

Pacotes de Regras

Pacotes são coleções curadas de regras que você pode instalar com um clique. Em vez de adicionar regras uma a uma, instale um pacote e tenha um conjunto completo de regras para a sua stack.

Clique em Packs na barra de ferramentas para explorar os pacotes disponíveis.

Pacotes de Arquitetura

Pacotes de Linguagem

Pacotes de Domínio

Catálogo de Regras

O Archyl vem com um catálogo de 169 regras prontas abrangendo 23 tecnologias. Explore o catálogo clicando em Explorar catálogo no Hub de Agentes.

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

Clique em qualquer regra do catálogo para adicioná-la — o formulário de configuração é preenchido automaticamente.

Níveis de Severidade

Cada regra tem uma severidade que determina o seu impacto:

Uma verificação de conformidade falha se forem encontradas violações críticas ou altas. Violações médias e baixas são reportadas, mas não fazem a verificação falhar.

Painel de Conformidade

A aba Painel no Hub de Agentes oferece uma visão geral em tempo real de todas as verificações de conformidade dos seus projetos.

O que Ele Mostra

• Cartões de estatísticas — Total de verificações, taxa de aprovação (com código de cores), número de aprovadas, número de reprovadas
• Proporção aprovado / reprovado — Barra visual que mostra a proporção num relance
• Banner da última verificação — Status da verificação mais recente, com um link para o relatório completo
• Lista de verificações recentes — Todas as verificações com status, tipo de gatilho, nome do projeto, número de arquivos, número de violações e há quanto tempo ocorreram

Filtragem

Use o menu suspenso de projetos no topo para filtrar as verificações por projeto, ou selecione "Todos os projetos" para ver tudo.

Relatórios de Verificação

Clique em qualquer verificação para abrir o relatório completo:

• Barra de distribuição por severidade — Visualização proporcional das violações críticas/altas/médias/baixas
• Violações agrupadas por arquivo — Seções recolhíveis com severidade, título, descrição e sugestão para cada violação
• Metadados da verificação — Tipo de gatilho, SHA do commit, horário de início, duração

Cada relatório de verificação tem sua própria URL compartilhável (ex.: /agent/dashboard/:checkId).

Excluindo Verificações

Use a seleção múltipla para excluir verificações em lote:

1. Marque as caixas de seleção ao lado de verificações individuais, ou use "Selecionar tudo"
2. Clique no botão vermelho Delete que aparece
3. As verificações e suas violações são removidas permanentemente

Integração com CI/CD

As regras de conformidade podem ser executadas automaticamente em cada pull request. Consulte Integração com GitHub Actions para as instruções de configuração.

Como Funciona

1. Um PR é aberto ou atualizado no GitHub
2. A GitHub Action do Archyl busca os arquivos alterados
3. Os arquivos são enviados para a API do Archyl para avaliação
4. Os resultados aparecem como um comentário no PR e uma verificação de status do commit
5. O workflow falha se forem encontradas violações críticas ou altas

Comentário no PR

Quando violações são encontradas, o Archyl publica um comentário detalhado no PR:

• Tabela-resumo com a contagem de violações por severidade
• Violações por arquivo, com descrições e sugestões
• O comentário é atualizado (e não duplicado) nos pushes seguintes

Gerenciando Regras

Criando Regras

1. Clique em Packs para instalar um conjunto curado de regras para a sua stack, ou
2. Clique em Explorar catálogo para navegar pelas 169 regras prontas e adicioná-las, ou
3. Clique em Regra personalizada para criar uma nova regra manualmente

Ativando/Desativando Regras

Use o interruptor ao lado de qualquer regra para ativá-la ou desativá-la. Regras desativadas não são avaliadas.

Editando Regras

Clique no ícone de edição (lápis) em qualquer regra para modificar seu nome, descrição, severidade ou configuração.

Excluindo Regras

Clique no ícone de exclusão (lixeira) e confirme. Esta ação não pode ser desfeita.

Filtrando Regras

• Busca — Filtre por nome ou descrição da regra
• Filtro por tipo — Clique nas pílulas de tipo para mostrar apenas as regras de um tipo específico

Integração MCP

As regras de conformidade ficam acessíveis aos agentes de IA pelo servidor MCP:

Ferramentas MCP Disponíveis

Executando Verificações a partir de um Agente

A ferramenta run_conformance_check permite que agentes de IA validem o código antes de fazer commit. O agente envia os arquivos em que está trabalhando:

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

A resposta inclui:

• passed — Se a verificação foi aprovada (sem violações críticas/altas)
• violations — Lista de violações com severidade, caminho do arquivo, título e sugestão
• rulesEvaluated — Quais regras foram avaliadas
• filesAnalyzed — Quantos arquivos foram analisados
• checkId — O ID da verificação (visível no painel)

O agente pode usar esse retorno para corrigir as violações antes de o código ser commitado.

Contexto do Agente

A ferramenta MCP get_agent_context retorna todas as regras de conformidade ativas como parte do briefing arquitetural. Agentes de IA que chamam essa ferramenta antes de começar a trabalhar saberão quais guardrails respeitar.

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

Todos os endpoints exigem autenticação (JWT ou chave de API com escopo de escrita para mutações).