Pacotes de Regras de Conformidade

Rules grouped by type, with packs and a browsable catalog

Os pacotes de regras são coleções curadas de regras de conformidade que codificam boas práticas para padrões de arquitetura comuns. Em vez de escrever regras do zero, instale um pacote e tenha em segundos um conjunto de regras opinativo e testado em batalha.

Por que Pacotes de Regras?

A maioria das equipes segue padrões conhecidos — microsserviços, clean architecture, sistemas orientados a eventos. Cada padrão traz restrições que deveriam ser aplicadas automaticamente:

  • Microsserviços não devem compartilhar bancos de dados
  • Camadas de domínio não devem importar código de infraestrutura
  • Eventos devem seguir um contrato de schema

Os pacotes de regras transformam esses princípios em guardrails executáveis.

Pacotes Disponíveis

Pacote Regras Foco
Microservices 10 Fronteiras entre serviços, implantação independente, comunicação delimitada
Clean Architecture 9 Fronteiras de camadas, isolamento do domínio, aplicação de ports/adapters
Event-Driven 8 Conformidade de canais, exigências de schema, dead letter queues
API-First 8 Exigência de contratos, versionamento, documentação de autenticação
Security Baseline 8 Uso obrigatório de gateway, gestão de segredos, controles de acesso externo

Instalando um Pacote

Pela skill archyl-developer

Peça ao seu agente de código com IA:

Install the microservices conformance rules pack

O agente chama o servidor MCP do Archyl e cria todas as regras em uma única operação.

Pelo SDK

import { ArchylClient } from "@archyl/sdk";

const client = new ArchylClient({
  apiKey: process.env.ARCHYL_API_KEY,
  organizationId: "your-org-id",
});

// Install a pack by name
await client.governance.installPack("microservices");

Pela interface

Acesse Hub de Agentes > Packs e clique em Instalar em qualquer pacote.

O que Há em Cada Pacote

Microservices (10 regras)

  • Sem bancos de dados compartilhados — Cada serviço deve ser dono dos seus dados. Consultas entre serviços apenas via APIs.
  • Implantação independente — Nenhuma dependência em tempo de compilação entre serviços. Bibliotecas compartilhadas devem ser versionadas.
  • Comunicação delimitada — Os serviços se comunicam por contratos de API ou canais de eventos definidos, e não por acesso direto ao banco de dados ou compartilhamento de arquivos.
  • Isolamento de serviços — Nenhum import entre serviços. Cada serviço tem sua própria árvore de dependências.

Clean Architecture (9 regras)

  • Pureza da camada de domínio — O código de domínio não tem nenhum import externo. Nada de framework, ORM ou HTTP.
  • Direção das dependências — As dependências apontam para dentro. Handlers dependem de serviços, serviços dependem do domínio, nunca o contrário.
  • Aplicação de ports/adapters — Preocupações de infraestrutura (banco de dados, HTTP, mensageria) ficam em pacotes de adapters, não nas camadas de domínio ou de serviço.
  • Fronteiras por interfaces — Os serviços consomem interfaces (ports), não implementações concretas.

Event-Driven (8 regras)

  • Conformidade de canais — Produtores e consumidores de eventos devem usar canais de eventos declarados. Nada de criar tópicos improvisados.
  • Exigências de schema — Todo evento deve ter um schema definido. Nada de payloads sem tipo.
  • Dead letter queue — Os consumidores devem configurar uma DLQ para tratar mensagens que falharam.
  • Convenções de nomenclatura de tópicos — Os tópicos seguem um padrão de nomenclatura consistente (ex.: domain.entity.event).

API-First (8 regras)

  • Contrato obrigatório — Todo endpoint público deve ter um contrato OpenAPI, gRPC ou AsyncAPI registrado.
  • Versionamento — Os endpoints de API devem incluir um prefixo de versão (/v1/, /v2/).
  • Documentação de autenticação — Os esquemas de segurança devem estar documentados no contrato.
  • Nenhum endpoint não documentado — Arquivos de handler sem documentação de contrato correspondente geram uma violação.

Security Baseline (8 regras)

  • Uso obrigatório de gateway — O tráfego externo deve passar por um API gateway ou load balancer. Nenhum serviço exposto diretamente.
  • Gestão de segredos — Nenhum segredo, chave de API ou senha hardcoded no código-fonte. Use variáveis de ambiente ou um gerenciador de segredos.
  • Controles de acesso externo — Serviços que aceitam requisições externas devem exigir autenticação e aplicar rate limiting.
  • TLS obrigatório — Toda comunicação entre serviços deve usar TLS. Nada de HTTP em texto puro entre serviços.

Personalizando as Regras

Depois de instalar um pacote, cada regra é totalmente editável:

  • Alterar a severidade — Rebaixe uma regra de critical para medium se ela não corresponder à sua tolerância a risco
  • Desativar regras específicas — Desligue regras individuais de que você não precisa sem remover o pacote inteiro
  • Modificar a configuração — Ajuste globs de arquivos, padrões, imports permitidos ou definições de camadas para adequá-los à estrutura do seu projeto

Acesse o Hub de Agentes e clique no ícone de edição de qualquer regra para modificá-la.

Combinando Pacotes

Os pacotes são cumulativos. Instale vários pacotes para cobrir diferentes aspectos da arquitetura:

Combinação Caso de uso
Microservices + API-First + Security Baseline Plataforma de microsserviços orientada a APIs com guardrails de segurança
Clean Architecture + Security Baseline Monólito com fronteiras de camadas rígidas e higiene de segurança
Event-Driven + Microservices Sistema de microsserviços com event sourcing
API-First + Clean Architecture Monólito ou monólito modular orientado a contratos

Se dois pacotes tiverem regras sobrepostas, o Archyl as deduplica — sem conflitos.

Contribuindo

Os pacotes de regras são open source. Você pode propor novos pacotes, adicionar regras aos existentes ou reportar problemas:

Próximos Passos