Domínios

Domínios são categorias que agrupam ADRs relacionados. Cada ADR pertence a exatamente um domínio, e o domínio determina o prefixo usado no identificador do ADR.

Domínios Integrados

O Archgate vem com cinco domínios integrados. Cada um tem um prefixo curto que aparece no início de cada ID de ADR naquele domínio.

Domínio	Prefixo	Uso para
backend	BE	Lógica server-side, APIs, bancos de dados, serviços
frontend	FE	Componentes de UI, lógica client-side, padrões de estilo
data	DATA	Modelos de dados, schemas, pipelines, estratégias de armazenamento
architecture	ARCH	Decisões arquiteturais transversais
general	GEN	Convenções gerais do projeto e workflows

Por exemplo, o terceiro ADR de backend teria o ID BE-003, e o primeiro ADR de frontend seria FE-001.

Como os Domínios São Usados

Identificação de ADR

O prefixo do domínio é incorporado ao campo id de cada ADR. Quando você executa archgate adr create e seleciona um domínio, a CLI determina automaticamente o próximo número de sequência disponível para o prefixo daquele domínio. Um domínio de arquitetura com dois ADRs existentes (ARCH-001, ARCH-002) atribuiria ARCH-003 ao próximo.

O nome do arquivo espelha o ID:

ARCH-003-dependency-policy.md
ARCH-003-dependency-policy.rules.ts

Filtragem

O comando archgate adr list suporta a flag --domain para mostrar apenas ADRs de um domínio específico:

archgate adr list --domain backend
archgate adr list --domain architecture

Isso é útil em projetos grandes onde dezenas de ADRs abrangem múltiplas preocupações. Filtrar por domínio permite que você foque nas decisões relevantes para seu trabalho atual.

Contexto para Agentes de IA

O comando archgate review-context agrupa arquivos alterados por domínio ao fornecer contexto para agentes de IA. Quando um agente está prestes a escrever código, ele recebe apenas os resumos de ADR relevantes para os domínios que suas alterações afetam, em vez do conjunto completo de todos os ADRs. Esse escopo reduz o ruído e ajuda os agentes a focar nas restrições que realmente se aplicam.

Validação com Escopo

Embora os domínios em si não restrinjam quais arquivos uma regra pode verificar (esse é o trabalho do glob files no frontmatter do ADR), os domínios fornecem um agrupamento lógico que ajuda as equipes a organizar sua governança. Uma equipe de backend pode revisar todos os ADRs BE-* para entender suas restrições, enquanto a equipe de frontend foca nos FE-*.

Quando Usar Qual Domínio

backend

Use para decisões sobre código server-side: padrões de design de API, convenções de acesso a banco de dados, fluxos de autenticação, comunicação entre serviços, tratamento de filas e padrões de jobs em background.

Exemplos de ADRs: Formato de envelope de resposta de API, estratégia de migração de banco de dados, taxonomia de códigos de erro.

frontend

Use para decisões sobre código client-side: estrutura de componentes, padrões de gerenciamento de estado, abordagens de estilização, requisitos de acessibilidade e escolhas de ferramentas de build.

Exemplos de ADRs: Estrutura de arquivo de componente, metodologia CSS, padrão de validação de formulário.

data

Use para decisões sobre dados: design de schema, convenções de pipeline de dados, escolhas de engine de armazenamento, formatos de serialização e estratégias de validação de dados.

Exemplos de ADRs: Versionamento de schema de eventos, convenções de nomenclatura de banco de dados, política de retenção de dados.

architecture

Use para decisões transversais que abrangem múltiplos domínios ou afetam a estrutura geral do projeto. São decisões que equipes de backend, frontend e dados precisam seguir.

Exemplos de ADRs: Estrutura de comandos, convenções de tratamento de erros, política de gerenciamento de dependências, padrões de teste.

general

Use para convenções de projeto que não se encaixam perfeitamente em um domínio técnico: processos de revisão de código, formatos de mensagem de commit, padrões de documentação e práticas de onboarding.

Exemplos de ADRs: Formato de mensagem de commit, template de descrição de PR, requisitos de documentação.

Escolhendo o Domínio Certo

Ao decidir a qual domínio um ADR pertence, considere quem precisa segui-lo:

• Se apenas desenvolvedores de backend precisam segui-lo, use backend.
• Se apenas desenvolvedores de frontend precisam segui-lo, use frontend.
• Se diz respeito especificamente a modelagem de dados ou pipelines, use data.
• Se se aplica a múltiplos domínios técnicos, use architecture.
• Se é um processo ou convenção em vez de uma decisão técnica, use general.

Em caso de dúvida entre architecture e um domínio específico, prefira o domínio mais específico. Reserve architecture para decisões que genuinamente cruzam fronteiras.

Domínios Personalizados

Quando os cinco domínios integrados realmente não encaixam uma categoria de decisões (por exemplo, security, ml-ops ou compliance), você pode registrar um domínio personalizado via CLI:

# Ver o conjunto reconhecido atualmente neste projeto
archgate adr domain list

# Registrar um novo domínio com seu prefixo de ID
archgate adr domain add security SEC

# Remover um domínio personalizado (integrados não podem ser removidos)
archgate adr domain remove security

Os mapeamentos de domínio personalizado para prefixo persistem em .archgate/config.json e são mesclados com os integrados no momento da leitura. Um domínio personalizado registrado se comporta exatamente como um integrado: archgate adr create --domain security gera IDs como SEC-001, e archgate adr list --domain security filtra esses ADRs.

Regras de nomenclatura

• Nome: kebab-case em minúsculas, 2–32 caracteres (ex.: security, ml-ops, compliance).
• Prefixo: letras maiúsculas, dígitos ou underscores, 2–10 caracteres (ex.: SEC, MLOPS, COMP).
• Nomes e prefixos personalizados não podem colidir com integrados ou com qualquer outro personalizado.

Quando preferir um integrado

Os cinco integrados são deliberadamente opinativos. Antes de registrar um domínio personalizado, verifique se a decisão pode ser agrupada sob um existente:

• Uma decisão sobre middleware de autenticação geralmente cabe em backend, mesmo que a motivação seja de segurança.
• Uma decisão sobre versionamento de schema geralmente cabe em data, mesmo que a motivação seja de compliance.
• Uma decisão que abrange múltiplas áreas técnicas geralmente cabe em architecture.

Recorra a um domínio personalizado apenas quando nenhum dos integrados for uma opção genuína, por exemplo, quando você tem uma equipe dedicada ou um regime de compliance que precisa de sua própria superfície de governança.

Orientação para agentes de IA

Ao usar o plugin de editor do Archgate para criar ADRs, os agentes são instruídos a priorizar os domínios integrados e a perguntar antes de introduzir um personalizado. Eles mostrarão a lista mesclada via archgate adr domain list e só registrarão um novo domínio depois de confirmar com você que nenhum integrado serve.