Solicitações de Mudança de Arquitetura: Pull Requests para Seu Modelo C4
No mes passado, um engenheiro de uma equipe que assessoro renomeou um serviço central no diagrama de arquitetura. Sem discussão. Sem revisão. A mudança ficou ativa instantaneamente, e três equipes passaram a próxima daily confusas sobre se o serviço real tinha sido renomeado ou apenas o diagrama. Não tinha. Alguém achou que o rotulo era confuso e "corrigiu".
Esse incidente cristalizou algo que vinhamos pensando há tempos. Código tem pull requests. Infraestrutura tem plan/apply. Schemas de banco de dados têm migrações. Mas diagramas de arquitetura? Qualquer pessoa com acesso de edição pode mudar qualquer coisa, a qualquer momento, e o resto da equipe descobre... eventualmente.
Hoje estamos mudando isso. Solicitações de Mudança de Arquitetura trazem o fluxo de trabalho de pull request para seu modelo C4.
Como Funciona
O conceito é deliberadamente familiar. Se você já abriu um pull request no GitHub, já sabe como funciona.
Você começa criando uma solicitação de mudança. De um titulo, descreva o que está propondo e por que. Depois adicione suas mudanças — crie novos sistemas, atualize containers existentes, exclua componentes não utilizados, modifique relacionamentos. Cada mudança é uma operação discreta: criar, atualizar ou excluir em um elemento C4 especifico.
A solicitação de mudança começa como rascunho. Você pode continuar adicionando e refinando mudanças ate estar pronto. Quando a proposta estiver completa, você a abre para revisão.
Seus colegas de equipe veem a solicitação aberta na lista de solicitações de mudança do projeto. Eles podem revisar cada mudança proposta, ver exatamente o que está sendo criado, modificado ou removido. Deixam revisões: aprovar, solicitar alterações ou comentar. Uma vez que o numero necessário de aprovações é atingido, a solicitação pode ser mesclada — aplicando todas as mudanças ao modelo C4 ativo em uma operação atômica.
Previa Visual
Uma coisa que não queríamos era uma visualização de diff que parecesse um blob JSON. Arquitetura e visual, e revisar mudanças de arquitetura também deveria ser visual.
Cada solicitação de mudança inclui uma previa ao vivo do diagrama. A previa renderiza o modelo C4 atual com todas as mudanças propostas sobrepostas. Novos elementos aparecem com destaque verde. Elementos modificados recebem um anel âmbar. Elementos excluídos mostram um indicador vermelho. Você pode navegar pelos níveis C4 — sistema, container, componente, código — e ver o impacto completo da proposta em cada profundidade.
Este é o mesmo canvas interativo React Flow que você usa para o diagrama ao vivo, com o mesmo drill-down, zoom e pan. A única diferença são os dados: e uma projeção computada de como a arquitetura ficara apos a mesclagem.
O Processo de Revisão
Revisões seguem um modelo direto. Um revisor pode:
- Aprovar — "Parece bom, pode mesclar quando estiver pronto."
- Solicitar alterações — "Tenho preocupações, vamos discutir antes."
- Comentar — "Sem objeções, mas aqui vai um contexto."
Cada revisão inclui um corpo de texto livre para feedback detalhado. A solicitação de mudança rastreia sua contagem de aprovações contra o limite requerido do projeto. Por padrão, uma aprovação é necessária, mas você pode configurar por projeto — zero aprovações para equipes pequenas que querem rastreamento leve, duas ou três para organizações maiores que precisam de aprovação formal.
Modo Somente Solicitações
Para equipes que querem ir além, adicionamos um Modo Somente Solicitações nas configurações do projeto. Quando ativado, edições diretas ao modelo C4 são bloqueadas. A única forma de modificar a arquitetura e através de uma solicitação de mudança.
Isso não significa que o diagrama se torna somente leitura. Você ainda pode navegar, explorar, vincular ADRs e documentação a elementos, adicionar comentários. Só não pode mover, renomear, criar ou excluir elementos sem passar pelo fluxo de trabalho de solicitação de mudança.
Construímos isso para organizações onde a governança de arquitetura importa — industrias regulamentadas, grandes equipes de engenharia, equipes de plataforma gerenciando infraestrutura compartilhada. A arquitetura se torna um artefato controlado, com cada mudança rastreável e revisada.
Rastreamento de Atividade
Cada evento do ciclo de vida da solicitação de mudança aparece na aba Atividade do projeto. Quando uma solicitação e aberta, fechada, reaberta ou mesclada, um registro de histórico é gravado com o autor, timestamp e titulo da solicitação. Isso dá uma linha do tempo de como a arquitetura evoluiu — não apenas como ela e hoje, mas a sequencia de propostas e decisões que a moldaram.
Combinado com ADRs e links de documentação, você obtém uma narrativa completa: o que mudou (a solicitação de mudança), por que mudou (o ADR), e como se encaixa no contexto mais amplo (a documentação).
Construindo Mudanças
O construtor de mudanças permite construir propostas elemento por elemento. Para cada mudança, você especifica:
- Operação: criar, atualizar ou excluir
- Tipo de elemento: sistema, container, componente, elemento de código, relacionamento ou overlay
- Dados do elemento: a especificação completa do elemento — nome, descrição, tecnologia, tipo e todos os campos que você definiria ao cria-lo diretamente
Para atualizações, o sistema captura tanto o estado atual quanto o estado proposto, para que revisores vejam exatamente o que está mudando. Para exclusões, os dados existentes do elemento são preservados na solicitação para referencia.
Você pode misturar operações livremente. Uma única solicitação de mudança pode criar dois novos containers, atualizar um relacionamento e excluir um componente obsoleto. Quando mesclada, todas as mudanças são aplicadas juntas.
O Que Isso Significa para Equipes
Solicitações de mudança de arquitetura não são sobre adicionar burocracia. São sobre tornar a evolução arquitetural intencional.
Em uma base de código, o pull request não é apenas um portão — é uma ferramenta de comunicação. Diz "aqui está o que estou propondo, aqui está o motivo, o que você acha?" Cria um momento natural para compartilhamento de conhecimento, para pegar erros cedo, para construir entendimento compartilhado.
A arquitetura merece o mesmo tratamento. Quando alguém propõe adicionar um novo serviço, essa é uma conversa que vale a pena ter antes de aparecer no diagrama. Quando alguém quer reestruturar a hierarquia de componentes, a equipe deveria ver o quadro completo antes que se torne a nova realidade.
A solicitação de mudança e essa conversa, tornada estruturada e rastreável.
Começando
Solicitações de Mudança de Arquitetura estão disponíveis agora em todos os planos de equipe. Navegue ate qualquer projeto, e você encontrara a seção "Solicitações" na barra lateral. Crie sua primeira solicitação, adicione algumas mudanças e abra para revisão.
Se quiser impor o fluxo de trabalho, ative o Modo Somente Solicitações nas configurações do projeto. Configure a contagem de aprovações necessárias para atender as necessidades de governança da sua equipe.
Sua arquitetura é uma decisão de equipe. Agora suas ferramentas tornam isso explicito.
Quer entender mais sobre arquitetura colaborativa? Leia sobre Colaboração em Tempo Real em Diagramas C4, ou aprenda como Registros de Decisão de Arquitetura complementam solicitações de mudança ao capturar o "por que" por trás de cada evolução arquitetural.