Solicitacoes de Mudanca de Arquitetura: Pull Requests para Seu Modelo C4

No mes passado, um engenheiro de uma equipe que assessoro renomeou um servico central no diagrama de arquitetura. Sem discussao. Sem revisao. A mudanca ficou ativa instantaneamente, e tres equipes passaram a proxima daily confusas sobre se o servico real tinha sido renomeado ou apenas o diagrama. Nao tinha. Alguem achou que o rotulo era confuso e "corrigiu".

Esse incidente cristalizou algo que vinhamos pensando ha tempos. Codigo tem pull requests. Infraestrutura tem plan/apply. Schemas de banco de dados tem migracoes. Mas diagramas de arquitetura? Qualquer pessoa com acesso de edicao pode mudar qualquer coisa, a qualquer momento, e o resto da equipe descobre... eventualmente.

Hoje estamos mudando isso. Solicitacoes de Mudanca de Arquitetura trazem o fluxo de trabalho de pull request para seu modelo C4.

Como Funciona

O conceito e deliberadamente familiar. Se voce ja abriu um pull request no GitHub, ja sabe como funciona.

Voce comeca criando uma solicitacao de mudanca. De um titulo, descreva o que esta propondo e por que. Depois adicione suas mudancas — crie novos sistemas, atualize containers existentes, exclua componentes nao utilizados, modifique relacionamentos. Cada mudanca e uma operacao discreta: criar, atualizar ou excluir em um elemento C4 especifico.

A solicitacao de mudanca comeca como rascunho. Voce pode continuar adicionando e refinando mudancas ate estar pronto. Quando a proposta estiver completa, voce a abre para revisao.

Seus colegas de equipe veem a solicitacao aberta na lista de solicitacoes de mudanca do projeto. Eles podem revisar cada mudanca proposta, ver exatamente o que esta sendo criado, modificado ou removido. Deixam revisoes: aprovar, solicitar alteracoes ou comentar. Uma vez que o numero necessario de aprovacoes e atingido, a solicitacao pode ser mesclada — aplicando todas as mudancas ao modelo C4 ativo em uma operacao atomica.

Previa Visual

Uma coisa que nao queriamos era uma visualizacao de diff que parecesse um blob JSON. Arquitetura e visual, e revisar mudancas de arquitetura tambem deveria ser visual.

Cada solicitacao de mudanca inclui uma previa ao vivo do diagrama. A previa renderiza o modelo C4 atual com todas as mudancas propostas sobrepostas. Novos elementos aparecem com destaque verde. Elementos modificados recebem um anel ambar. Elementos excluidos mostram um indicador vermelho. Voce pode navegar pelos niveis C4 — sistema, container, componente, codigo — e ver o impacto completo da proposta em cada profundidade.

Este e o mesmo canvas interativo React Flow que voce usa para o diagrama ao vivo, com o mesmo drill-down, zoom e pan. A unica diferenca sao os dados: e uma projecao computada de como a arquitetura ficara apos a mesclagem.

O Processo de Revisao

Revisoes seguem um modelo direto. Um revisor pode:

• Aprovar — "Parece bom, pode mesclar quando estiver pronto."
• Solicitar alteracoes — "Tenho preocupacoes, vamos discutir antes."
• Comentar — "Sem objecoes, mas aqui vai um contexto."

Cada revisao inclui um corpo de texto livre para feedback detalhado. A solicitacao de mudanca rastreia sua contagem de aprovacoes contra o limite requerido do projeto. Por padrao, uma aprovacao e necessaria, mas voce pode configurar por projeto — zero aprovacoes para equipes pequenas que querem rastreamento leve, duas ou tres para organizacoes maiores que precisam de aprovacao formal.

Modo Somente Solicitacoes

Para equipes que querem ir alem, adicionamos um Modo Somente Solicitacoes nas configuracoes do projeto. Quando ativado, edicoes diretas ao modelo C4 sao bloqueadas. A unica forma de modificar a arquitetura e atraves de uma solicitacao de mudanca.

Isso nao significa que o diagrama se torna somente leitura. Voce ainda pode navegar, explorar, vincular ADRs e documentacao a elementos, adicionar comentarios. So nao pode mover, renomear, criar ou excluir elementos sem passar pelo fluxo de trabalho de solicitacao de mudanca.

Construimos isso para organizacoes onde a governanca de arquitetura importa — industrias regulamentadas, grandes equipes de engenharia, equipes de plataforma gerenciando infraestrutura compartilhada. A arquitetura se torna um artefato controlado, com cada mudanca rastreavel e revisada.

Rastreamento de Atividade

Cada evento do ciclo de vida da solicitacao de mudanca aparece na aba Atividade do projeto. Quando uma solicitacao e aberta, fechada, reaberta ou mesclada, um registro de historico e gravado com o autor, timestamp e titulo da solicitacao. Isso da uma linha do tempo de como a arquitetura evoluiu — nao apenas como ela e hoje, mas a sequencia de propostas e decisoes que a moldaram.

Combinado com ADRs e links de documentacao, voce obtem uma narrativa completa: o que mudou (a solicitacao de mudanca), por que mudou (o ADR), e como se encaixa no contexto mais amplo (a documentacao).

Construindo Mudancas

O construtor de mudancas permite construir propostas elemento por elemento. Para cada mudanca, voce especifica:

• Operacao: criar, atualizar ou excluir
• Tipo de elemento: sistema, container, componente, elemento de codigo, relacionamento ou overlay
• Dados do elemento: a especificacao completa do elemento — nome, descricao, tecnologia, tipo e todos os campos que voce definiria ao cria-lo diretamente

Para atualizacoes, o sistema captura tanto o estado atual quanto o estado proposto, para que revisores vejam exatamente o que esta mudando. Para exclusoes, os dados existentes do elemento sao preservados na solicitacao para referencia.

Voce pode misturar operacoes livremente. Uma unica solicitacao de mudanca pode criar dois novos containers, atualizar um relacionamento e excluir um componente obsoleto. Quando mesclada, todas as mudancas sao aplicadas juntas.

O Que Isso Significa para Equipes

Solicitacoes de mudanca de arquitetura nao sao sobre adicionar burocracia. Sao sobre tornar a evolucao arquitetural intencional.

Em uma base de codigo, o pull request nao e apenas um portao — e uma ferramenta de comunicacao. Diz "aqui esta o que estou propondo, aqui esta o motivo, o que voce acha?" Cria um momento natural para compartilhamento de conhecimento, para pegar erros cedo, para construir entendimento compartilhado.

A arquitetura merece o mesmo tratamento. Quando alguem propoe adicionar um novo servico, essa e uma conversa que vale a pena ter antes de aparecer no diagrama. Quando alguem quer reestruturar a hierarquia de componentes, a equipe deveria ver o quadro completo antes que se torne a nova realidade.

A solicitacao de mudanca e essa conversa, tornada estruturada e rastreavel.

Comecando

Solicitacoes de Mudanca de Arquitetura estao disponiveis agora em todos os planos de equipe. Navegue ate qualquer projeto, e voce encontrara a secao "Solicitacoes" na barra lateral. Crie sua primeira solicitacao, adicione algumas mudancas e abra para revisao.

Se quiser impor o fluxo de trabalho, ative o Modo Somente Solicitacoes nas configuracoes do projeto. Configure a contagem de aprovacoes necessarias para atender as necessidades de governanca da sua equipe.

Sua arquitetura e uma decisao de equipe. Agora suas ferramentas tornam isso explicito.

Quer entender mais sobre arquitetura colaborativa? Leia sobre Colaboracao em Tempo Real em Diagramas C4, ou aprenda como Registros de Decisao de Arquitetura complementam solicitacoes de mudanca ao capturar o "por que" por tras de cada evolucao arquitetural.