<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Rodrigo de Oliveira on Medium]]></title>
        <description><![CDATA[Stories by Rodrigo de Oliveira on Medium]]></description>
        <link>https://medium.com/@rodrigodotnet?source=rss-9ad16a333256------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*f2SvdW7gt697xdhbVVUcHg@2x.jpeg</url>
            <title>Stories by Rodrigo de Oliveira on Medium</title>
            <link>https://medium.com/@rodrigodotnet?source=rss-9ad16a333256------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 14:51:07 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@rodrigodotnet/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[MCP além do básico: segurança, governança e arquitetura para agentes de IA]]></title>
            <link>https://medium.com/@rodrigodotnet/mcp-al%C3%A9m-do-b%C3%A1sico-seguran%C3%A7a-governan%C3%A7a-e-arquitetura-para-agentes-de-ia-9669e9a6cfac?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/9669e9a6cfac</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[mcp-server]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Tue, 17 Nov 2026 10:01:03 GMT</pubDate>
            <atom:updated>2026-11-17T10:01:03.266Z</atom:updated>
            <content:encoded><![CDATA[<h3><em>O que realmente importa quando o MCP deixa de ser uma demonstração e passa a fazer parte da arquitetura de um sistema.</em></h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Iiug1oCkYa7mOYksOJHwhg.png" /></figure><p>Nos últimos meses, o Model Context Protocol (MCP) ganhou espaço nas discussões sobre inteligência artificial e desenvolvimento de software. Não é difícil entender o motivo. A possibilidade de conectar modelos de linguagem a ferramentas, sistemas e fontes de dados por meio de um protocolo padronizado resolve um problema que, até pouco tempo atrás, exigia integrações específicas para cada aplicação.</p><p>E os primeiros resultados costumam impressionar.</p><p>Com poucas linhas de código, conseguimos criar um servidor MCP, disponibilizar algumas ferramentas e permitir que um agente consulte um banco de dados, leia arquivos ou interaja com uma API.</p><p>Mas existe uma diferença considerável entre fazer uma integração funcionar e construir uma integração preparada para operar em produção.</p><p>Quando saímos de um ambiente de desenvolvimento e começamos a lidar com informações sensíveis, múltiplos usuários, permissões, concorrência e requisitos de disponibilidade, surgem perguntas que dificilmente aparecem nos exemplos introdutórios.</p><p>Quem realmente autoriza uma operação? Como impedir que um agente execute algo fora do escopo esperado? O que acontece quando uma ferramenta falha? Como investigar uma decisão tomada durante a execução de um fluxo?</p><p>Essas perguntas não são exclusivas do MCP. Na verdade, são bastante familiares para quem trabalha com arquitetura de software.</p><p>A novidade está no contexto em que precisamos respondê-las.</p><h3>Entendendo o papel do MCP na arquitetura</h3><p>Antes de discutir segurança ou escalabilidade, precisamos compreender uma distinção importante: <strong>o MCP não é um agente de inteligência artificial.</strong></p><p>Ele é um protocolo que padroniza a comunicação entre aplicações que utilizam modelos de linguagem e serviços que disponibilizam informações ou funcionalidades.</p><p>Sua arquitetura envolve três elementos principais.</p><p>O <em>host</em> é a aplicação que oferece a experiência de IA ao usuário. Dentro dele, os <em>clients</em> estabelecem comunicação com os servidores MCP. Já os <em>servers</em> disponibilizam capacidades que podem ser utilizadas pela aplicação.</p><p>Essas capacidades aparecem principalmente como <em>tools</em>, <em>resources</em> e <em>prompts</em>.</p><p>As tools permitem executar operações, como consultar um pedido ou analisar um documento. Os resources disponibilizam informações que podem ser utilizadas como contexto. Os prompts oferecem estruturas reutilizáveis para determinadas interações.</p><p>Parece simples, e essa simplicidade é uma das qualidades do protocolo.</p><p>Entretanto, existe uma característica que merece atenção: a decisão de utilizar determinada ferramenta pode surgir da interpretação feita por um modelo de linguagem.</p><p>Isso muda a maneira como pensamos sobre integrações.</p><p>Em um sistema tradicional, normalmente conseguimos identificar um fluxo explícito que leva à execução de uma operação. Em uma aplicação com IA, parte dessa escolha pode acontecer de maneira probabilística, influenciada pelo contexto recebido pelo modelo.</p><p>O MCP padroniza a comunicação, mas não garante que a decisão tomada pelo modelo esteja correta.</p><p>Essa responsabilidade continua distribuída entre a aplicação, seus mecanismos de controle e os serviços envolvidos.</p><h3>MCP não substitui APIs. E isso é uma boa notícia.</h3><p>Uma dúvida recorrente é se o MCP representa uma evolução das APIs REST ou se eventualmente poderá substituí-las.</p><p>Acredito que essa comparação parte de uma premissa equivocada.</p><p>Uma API tradicional oferece um contrato de integração entre sistemas. O MCP estabelece uma maneira padronizada de apresentar capacidades e contexto para aplicações de IA.</p><p>São responsabilidades diferentes, embora complementares.</p><p>Imagine uma plataforma financeira que disponibiliza uma API para consultar a situação de um contrato.</p><p>Poderíamos criar uma tool MCP chamada consultar_contrato, permitindo que um agente utilize essa funcionalidade durante uma conversa.</p><p>Isso não significa que precisamos reimplementar toda a lógica de negócio no servidor MCP.</p><p>Pelo contrário.</p><p>Uma alternativa arquitetural bastante razoável é manter as validações, regras de domínio e integrações existentes nos serviços responsáveis por elas, utilizando o servidor MCP como uma camada de exposição dessas capacidades.</p><p>Com isso, evitamos duplicação de regras e reduzimos o risco de criar dois comportamentos diferentes para a mesma operação.</p><p>Também preservamos investimentos anteriores em autenticação, observabilidade e contratos de integração.</p><p>O MCP passa a complementar a arquitetura existente, não a disputar responsabilidades com ela.</p><p>E aqui existe um princípio importante: <strong>adicionar inteligência artificial a um sistema não deveria ser motivo para abandonar boas práticas de engenharia.</strong></p><h3>O contrato de uma tool importa mais do que parece</h3><p>Quando criamos uma API, dedicamos atenção aos seus contratos. Definimos operações, parâmetros, respostas, erros e restrições.</p><p>Com MCP, precisamos manter o mesmo cuidado, mas considerar um detalhe adicional: a descrição de uma tool também influencia a maneira como o modelo decide utilizá-la.</p><p>Uma ferramenta chamada executar_operacao, por exemplo, oferece pouca informação sobre sua responsabilidade.</p><p>Já uma ferramenta chamada consultar_status_contrato deixa sua intenção mais clara.</p><p>Essa diferença não é apenas estética.</p><p>Uma descrição ambígua pode aumentar a probabilidade de utilização inadequada, especialmente quando existem diversas ferramentas disponíveis com responsabilidades semelhantes.</p><p>Também precisamos pensar na granularidade das operações.</p><p>Disponibilizar uma ferramenta capaz de executar qualquer comando SQL pode parecer flexível, mas amplia significativamente a superfície de risco. Em muitos cenários, é preferível oferecer operações específicas, com parâmetros restritos e regras de autorização explícitas.</p><p>O mesmo raciocínio vale para as respostas.</p><p>Retornar grandes quantidades de dados sem necessidade aumenta o processamento, o consumo de contexto e o risco de exposição de informações.</p><p>Uma boa tool deveria apresentar um contrato compreensível, entradas validadas, respostas previsíveis e limites claros.</p><p>O protocolo permite definir esquemas de entrada e saída, inclusive com JSON Schema. Devemos aproveitar esses recursos, mas sem confundir validação estrutural com validação de negócio.</p><p>Um JSON válido não significa que a operação seja autorizada, segura ou semanticamente correta.</p><p>Essa distinção será ainda mais importante conforme os agentes passarem a executar fluxos com maior autonomia.</p><h3>Segurança: o agente pode executar, mas deveria?</h3><p>Provavelmente este é um dos pontos mais importantes quando falamos de MCP em ambientes corporativos.</p><p>Imagine que um agente tenha acesso a duas ferramentas: uma para consultar informações de clientes e outra para atualizar seus dados cadastrais.</p><p>O usuário solicita apenas uma consulta.</p><p>Durante a interação, porém, o agente recebe um conteúdo externo contendo instruções para realizar uma atualização.</p><p>Se a aplicação não estabelecer limites adequados, poderemos ter uma operação indevida.</p><p>Esse é um exemplo simplificado de como uma tentativa de <em>prompt injection</em> pode explorar uma integração com ferramentas.</p><p>O problema não está necessariamente no protocolo. Está em confiar que todo conteúdo interpretado pelo modelo representa uma instrução legítima.</p><p>É fundamental separar dados de instruções, tratar respostas de ferramentas como conteúdo potencialmente não confiável e manter verificações de segurança fora do modelo.</p><p>A documentação oficial do MCP também chama atenção para problemas como <em>confused deputy</em>, uso inadequado de tokens e falhas na validação de autorização.</p><p>Em servidores MCP remotos protegidos, a especificação prevê mecanismos baseados em OAuth. Mas autenticar uma aplicação ou um usuário não significa conceder acesso irrestrito a todas as ferramentas disponíveis.</p><p>A autorização precisa considerar a operação solicitada, a identidade envolvida, o recurso acessado e os privilégios efetivamente concedidos.</p><p>Outro cuidado importante é não encaminhar indiscriminadamente tokens recebidos pelo servidor MCP para APIs internas. Cada serviço deve validar credenciais destinadas a ele, preservando os limites de confiança entre os componentes.</p><p>E quando uma ação produz efeitos relevantes, como alterar um cadastro, excluir informações ou iniciar uma transação, pode ser necessário exigir confirmação explícita.</p><p>Essa confirmação deve acontecer em um mecanismo confiável da aplicação, não apenas por meio de uma pergunta escrita pelo próprio modelo.</p><p>Um agente pode sugerir executar uma operação. Isso não significa que ele tenha autoridade para realizá-la.</p><p><strong>A autonomia da IA deve existir dentro dos limites definidos pela arquitetura, e não substituir esses limites.</strong></p><h3>Do ambiente local à produção: escalabilidade e estado</h3><p>Grande parte dos primeiros exemplos de MCP utiliza o transporte stdio, no qual cliente e servidor se comunicam por meio dos fluxos de entrada e saída de um processo.</p><p>Esse modelo funciona bem para integrações locais e ferramentas de desenvolvimento.</p><p>Entretanto, quando começamos a oferecer servidores remotos para múltiplos usuários, precisamos pensar em disponibilidade, balanceamento de carga, latência e gerenciamento de recursos.</p><p>Nesse cenário, o Streamable HTTP oferece uma alternativa adequada.</p><p>A revisão MCP 2026-07-28 trouxe uma mudança importante: o núcleo do protocolo passou a adotar requisições autossuficientes, sem depender de sessões de protocolo mantidas entre chamadas.</p><p>Isso facilita distribuir requisições entre múltiplas instâncias e utilizar mecanismos convencionais de infraestrutura HTTP.</p><p>Mas cuidado com uma interpretação comum: um protocolo sem sessão não significa que a aplicação nunca precise manter estado.</p><p>Imagine uma operação que inicia uma análise de documentos e leva vários minutos para terminar.</p><p>Ainda precisamos identificar a execução, acompanhar seu progresso e disponibilizar o resultado.</p><p>O que muda é a maneira de representar esse estado.</p><p>Podemos utilizar identificadores explícitos de execução, associados ao usuário autorizado e armazenados em mecanismos adequados. A extensão Tasks do MCP também oferece recursos para operações de longa duração.</p><p>Outro ponto importante é a compatibilidade. Nem todos os clientes e servidores migram simultaneamente para uma nova revisão do protocolo. Uma arquitetura de produção precisa considerar as versões realmente suportadas pelos componentes utilizados.</p><p>E existe algo que a evolução do transporte não resolve sozinha: a confiabilidade das operações.</p><p>Uma chamada pode falhar, exceder seu tempo limite ou ser repetida após uma interrupção.</p><p>Se uma tool realiza uma operação com efeitos colaterais, precisamos avaliar idempotência, políticas de retry e mecanismos que impeçam execuções duplicadas.</p><p>Essas preocupações já fazem parte da arquitetura de sistemas distribuídos.</p><p>O MCP apenas as coloca em um novo contexto.</p><h3>Observabilidade: entender o que aconteceu não é suficiente</h3><p>Imagine que um usuário solicite a um agente uma análise de impacto arquitetural.</p><p>Para responder, o agente consulta um repositório, recupera decisões técnicas, acessa informações de dependências e chama uma ferramenta responsável pela avaliação.</p><p>A resposta final está incorreta.</p><p>Por onde começamos a investigação?</p><p>Sem observabilidade adequada, teremos dificuldade até para descobrir quais ferramentas foram utilizadas.</p><p>Em sistemas tradicionais, acompanhamos métricas, logs e traces para entender o comportamento das aplicações.</p><p>Em soluções com agentes, precisamos ampliar essa visão.</p><p>Não basta saber que uma requisição HTTP demorou dois segundos. Precisamos compreender qual operação foi chamada, quais dependências participaram, se ocorreram tentativas adicionais e qual foi o resultado de cada etapa.</p><p>Também precisamos distinguir uma falha técnica de uma decisão inadequada do modelo.</p><p>Uma ferramenta pode funcionar perfeitamente e ainda assim ter sido escolhida de forma incorreta.</p><p>O OpenTelemetry oferece mecanismos para correlacionar operações distribuídas, e a especificação MCP de 2026 documenta a propagação de contexto de tracing entre os componentes.</p><p>Isso ajuda a conectar a execução do agente às chamadas realizadas no servidor MCP e aos serviços posteriores.</p><p>Além da telemetria técnica, vale acompanhar indicadores como frequência de utilização das ferramentas, taxa de erros, tempo de execução, operações negadas e consumo de recursos.</p><p>Em fluxos que envolvem modelos pagos, o custo também merece atenção.</p><p>Uma interação aparentemente simples pode provocar diversas chamadas sucessivas, ampliando a latência e o consumo de tokens.</p><p>Naturalmente, precisamos equilibrar observabilidade e privacidade. Registrar indiscriminadamente prompts, credenciais e respostas completas pode criar um problema de segurança enquanto tentamos resolver outro.</p><p>O objetivo não é armazenar tudo.</p><p>É registrar informações suficientes para compreender, diagnosticar e auditar o comportamento do sistema com responsabilidade.</p><h3>Governança: quem decide quais capacidades ficam disponíveis?</h3><p>Conforme o número de servidores MCP cresce, surge outro desafio.</p><p>Como controlar quais ferramentas uma organização disponibiliza? Quem aprova novas integrações? Como garantir que uma alteração não introduza permissões excessivas ou comprometa consumidores existentes?</p><p>Essas perguntas nos levam diretamente à governança arquitetural.</p><p>Uma possibilidade é estabelecer um catálogo de servidores e ferramentas aprovados, com responsáveis definidos, políticas de acesso, versionamento e critérios mínimos de segurança.</p><p>Também podemos utilizar mecanismos de CI/CD para validar contratos, verificar dependências e identificar mudanças potencialmente incompatíveis.</p><p>Em ambientes maiores, gateways ou camadas intermediárias podem ajudar a centralizar controles de roteamento, autenticação, limites de utilização e observabilidade.</p><p>Mas uma camada centralizada não elimina a necessidade de autorização nos serviços responsáveis pelas operações.</p><p>Outro ponto relevante é a relação entre MCP e decisões arquiteturais.</p><p>Se uma organização estabelece que determinados dados não podem ser expostos a modelos externos, essa restrição precisa influenciar o desenho das ferramentas e os mecanismos de execução.</p><p>Não basta registrar a decisão em um documento.</p><p>Precisamos transformá-la em controles verificáveis sempre que possível.</p><p>É nesse ponto que a governança deixa de ser apenas documentação e passa a fazer parte da arquitetura operacional.</p><h3>Um exemplo prático: análise de impacto arquitetural</h3><p>Vamos imaginar um cenário que reúne vários desses conceitos.</p><p>Uma equipe mantém um conjunto de Architecture Decision Records (ADRs), diagramas e informações sobre os serviços de uma aplicação.</p><p>Queremos permitir que um agente analise o possível impacto de uma mudança arquitetural.</p><p>Uma implementação inicial poderia oferecer uma ferramenta que recebe uma descrição da mudança e devolve uma análise.</p><p>Funciona? Possivelmente.</p><p>Mas podemos melhorar esse desenho.</p><p>Primeiro, disponibilizamos capacidades específicas para consultar ADRs, recuperar informações de componentes e identificar dependências conhecidas.</p><p>Em seguida, oferecemos uma operação de análise que utiliza esses dados para construir uma avaliação estruturada.</p><p>A resposta poderia apresentar decisões relacionadas, componentes potencialmente afetados, riscos identificados e pontos que ainda precisam de validação humana.</p><p>Observe que não estamos concedendo ao agente autoridade para modificar decisões arquiteturais.</p><p>Estamos permitindo que ele ajude a analisá-las.</p><p>Se futuramente quisermos possibilitar a criação de propostas de ADR, poderemos introduzir uma ferramenta específica para isso, com autorização própria e registro de auditoria.</p><p>A aprovação definitiva, porém, permaneceria vinculada ao processo de governança estabelecido pela organização.</p><p>Esse exemplo ilustra algo fundamental: não precisamos escolher entre autonomia e controle.</p><p>Podemos desenhar soluções nas quais a IA amplia a capacidade de análise e execução sem assumir responsabilidades que não deveriam ser delegadas a ela.</p><h3>Quando não utilizar MCP?</h3><p>Talvez uma das decisões mais importantes seja reconhecer quando o protocolo não agrega valor suficiente.</p><p>Se dois serviços precisam trocar informações por meio de uma integração determinística, com contratos conhecidos e sem necessidade de interação com aplicações de IA, uma API convencional ou mensageria provavelmente continuará sendo uma opção mais apropriada.</p><p>Adicionar MCP nesse cenário pode introduzir uma camada extra sem resolver um problema real.</p><p>Da mesma forma, não precisamos expor todas as funcionalidades de um sistema como ferramentas apenas porque isso é tecnicamente possível.</p><p>Cada nova capacidade aumenta o trabalho de manutenção, a superfície de ataque e a complexidade de governança.</p><p>Em arquitetura de software, adotar uma tecnologia também significa assumir suas consequências operacionais.</p><p>O melhor desenho não é aquele que utiliza o maior número de tecnologias recentes.</p><p>É aquele que resolve o problema com responsabilidades bem definidas e complexidade justificável.</p><h3>Conclusão: o protocolo simplifica a integração, não a responsabilidade</h3><p>O MCP representa um avanço importante para o ecossistema de aplicações com inteligência artificial.</p><p>Ao padronizar a exposição de ferramentas, recursos e capacidades, ele reduz o esforço necessário para integrar sistemas a agentes e modelos de linguagem.</p><p>Isso abre possibilidades interessantes para automação, produtividade e novas experiências de software.</p><p>Mas a facilidade de criar uma integração não deveria ser confundida com a maturidade necessária para operá-la.</p><p>Segurança, contratos, autorização, observabilidade, confiabilidade e governança continuam sendo fundamentais.</p><p>Aliás, quanto maior a autonomia concedida a um agente, mais importante se torna definir claramente seus limites.</p><p>Talvez essa seja a principal reflexão que gostaria de deixar.</p><p><strong>O desafio não é apenas permitir que a inteligência artificial faça mais coisas. É construir sistemas nos quais possamos compreender, controlar e confiar no que ela está autorizada a fazer.</strong></p><p>E isso, independentemente da tecnologia utilizada, continua sendo um trabalho essencial da arquitetura de software.</p><h3>Para continuar estudando</h3><p>Para quem deseja aprofundar o assunto, recomendo começar pela documentação oficial e, gradualmente, explorar os aspectos operacionais e de segurança.</p><ul><li><a href="https://modelcontextprotocol.io/specification/2026-07-28"><strong>Model Context Protocol: especificação oficial</strong></a>. O melhor ponto de partida para compreender a arquitetura, os contratos e as capacidades do protocolo.</li><li><a href="https://blog.modelcontextprotocol.io/posts/2026-07-28/"><strong>MCP: novidades da versão 2026–07–28</strong></a>. Uma leitura importante para entender a evolução do protocolo, especialmente as mudanças relacionadas a estado, transporte e autorização.</li><li><a href="https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices"><strong>MCP Security Best Practices</strong></a>. Material oficial sobre ameaças, limites de confiança e estratégias de mitigação.</li><li><a href="https://owasp.org/projects/mcp-top-10/"><strong>OWASP MCP Top 10</strong></a>. Uma referência para aprofundar riscos como exposição de credenciais, permissões excessivas e manipulação de ferramentas.</li><li><a href="https://github.com/modelcontextprotocol/csharp-sdk"><strong>SDK oficial de MCP para C#</strong></a>. Uma ótima oportunidade para transformar os conceitos em experimentos práticos com .NET.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9669e9a6cfac" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Modelo C4: como comunicar arquiteturas complexas com clareza, do contexto ao código]]></title>
            <link>https://medium.com/@rodrigodotnet/modelo-c4-como-comunicar-arquiteturas-complexas-com-clareza-do-contexto-ao-c%C3%B3digo-d8301b30a334?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/d8301b30a334</guid>
            <category><![CDATA[system-design-concepts]]></category>
            <category><![CDATA[c4-model]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Tue, 10 Nov 2026 10:01:03 GMT</pubDate>
            <atom:updated>2026-11-10T10:01:03.283Z</atom:updated>
            <content:encoded><![CDATA[<h3>Modelo C4: como comunicar arquiteturas complexas com clareza</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tNwYeVYqoGr1jjALPXXmeQ.png" /></figure><p>Quem trabalha com arquitetura de software provavelmente já passou por uma situação curiosa: depois de semanas discutindo decisões técnicas, integrações e responsabilidades, chega o momento de apresentar a solução e alguém faz uma pergunta aparentemente simples:</p><p>“Mas como tudo isso funciona junto?”</p><p>A pergunta é legítima. E, dependendo de como documentamos nossa arquitetura, pode ser surpreendentemente difícil respondê-la.</p><p>Em sistemas de grande escala, temos aplicações, APIs, bancos de dados, mensageria, serviços externos e diferentes tecnologias trabalhando em conjunto. O desafio não está apenas em fazer esses elementos funcionarem, mas também em conseguir explicar suas responsabilidades e relacionamentos.</p><p>Um desenvolvedor precisa compreender onde implementar determinada funcionalidade. Um arquiteto precisa identificar dependências, limites e riscos. Já alguém de negócios provavelmente quer entender quais capacidades a solução oferece e de quais sistemas ela depende.</p><p>Apresentar o mesmo diagrama para todos esses públicos costuma gerar dois resultados: informações técnicas demais para algumas pessoas e detalhes insuficientes para outras.</p><p>É justamente nesse cenário que o <strong>Modelo C4</strong> se torna interessante.</p><p>Criado por Simon Brown, o C4 propõe uma maneira de visualizar arquiteturas utilizando diferentes níveis de abstração. Sua principal contribuição é permitir que uma solução seja apresentada progressivamente, começando pelo contexto geral e chegando, quando necessário, aos detalhes de implementação.</p><p>A ideia é simples: não precisamos mostrar tudo ao mesmo tempo.</p><h3>Entendendo a proposta do Modelo C4</h3><p>Uma comparação que considero bastante útil é pensar no C4 como um mapa.</p><p>Quando queremos compreender a localização de uma cidade, começamos observando uma região maior. Depois aproximamos a visualização para identificar bairros, ruas e, finalmente, endereços específicos.</p><p>Com arquitetura de software, o princípio é semelhante.</p><p>O C4 organiza a visualização em quatro níveis principais:</p><p><strong>Contexto</strong>, para compreender como o sistema se relaciona com usuários e outros sistemas.</p><p><strong>Contêineres</strong>, para identificar as aplicações e os armazenamentos de dados que compõem a solução.</p><p><strong>Componentes</strong>, para explicar como as responsabilidades estão organizadas dentro de um contêiner.</p><p><strong>Código</strong>, para examinar detalhes de implementação quando eles realmente fazem diferença.</p><p>Esses níveis não representam etapas obrigatórias de desenvolvimento, nem determinam como uma equipe deve trabalhar. São diferentes perspectivas de uma mesma arquitetura.</p><p>Outro ponto importante: o C4 não é uma metodologia para definir se devemos utilizar microsserviços, arquitetura hexagonal, eventos ou qualquer outra abordagem. Ele nos ajuda a representar e comunicar as decisões tomadas.</p><p>Para tornar a explicação mais concreta, vamos acompanhar um exemplo fictício: uma plataforma de comércio eletrônico que processa pedidos, recebe pagamentos e realiza integrações com transportadoras.</p><p>Utilizaremos essa mesma solução nos quatro níveis.</p><h3>Contexto: compreendendo o sistema antes da tecnologia</h3><p>O primeiro nível, conhecido como <strong>C1 ou Diagrama de Contexto</strong>, apresenta o sistema como parte de um ambiente maior.</p><p>Nesse momento, não precisamos explicar quais linguagens foram utilizadas, onde os dados estão armazenados ou quantos serviços existem.</p><p>Queremos responder perguntas mais fundamentais: quem utiliza a solução, qual é sua finalidade e com quais sistemas externos ela precisa interagir?</p><p>Imagine nossa plataforma de comércio eletrônico.</p><p>O cliente acessa a plataforma para pesquisar produtos e realizar compras. A solução se comunica com um provedor de pagamentos para processar cobranças e com um sistema de transportadora para organizar entregas. Operadores internos também podem utilizar a plataforma para acompanhar pedidos.</p><p>Essas relações são suficientes para começar a compreender o contexto.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kALoxlYrS2tl5nsn3VMvgA.png" /></figure><p>O diagrama deve deixar claro qual sistema estamos estudando e quais elementos estão fora de sua responsabilidade direta.</p><p>Isso parece simples, mas tem consequências importantes.</p><p>Quando identificamos sistemas externos, começamos a reconhecer dependências. Uma indisponibilidade no provedor de pagamentos, por exemplo, pode afetar a conclusão das compras. Uma falha na integração logística pode comprometer a atualização das entregas.</p><p>O diagrama ainda não explica como esses problemas serão tratados, mas ajuda a identificar onde eles podem surgir.</p><p>Esse nível costuma ser particularmente útil em conversas com stakeholders, gestores de produto, equipes de negócio e profissionais que precisam compreender o funcionamento geral da solução.</p><p><strong>Um bom C1 deve ser compreensível mesmo por alguém que não conhece a implementação.</strong></p><p>Se precisamos explicar detalhes de infraestrutura para que uma pessoa entenda o diagrama de contexto, provavelmente estamos apresentando informações além do necessário.</p><h3>Contêineres: descobrindo como a solução está organizada</h3><p>Depois de compreender o sistema por fora, podemos olhar para sua estrutura interna.</p><p>É aqui que entra o <strong>C2 ou Diagrama de Contêineres</strong>.</p><p>Antes de continuar, precisamos esclarecer uma confusão bastante comum: no Modelo C4, contêiner não significa necessariamente Docker ou Kubernetes.</p><p>Um contêiner representa uma aplicação ou um armazenamento de dados que possui uma responsabilidade dentro do sistema. Pode ser uma aplicação web, uma API, um serviço executado em segundo plano, um banco de dados ou outro elemento semelhante.</p><p>Nossa plataforma de comércio eletrônico poderia ser composta por:</p><ul><li>Uma aplicação web desenvolvida em React, responsável pela experiência do usuário.</li><li>Uma API em ASP.NET Core, responsável pelo processamento das operações de negócio.</li><li>Um banco SQL Server, utilizado para armazenar produtos, clientes e pedidos.</li><li>Uma fila de mensagens, utilizada para comunicação assíncrona.</li><li>Um worker em .NET, responsável pelo processamento de determinadas atividades em segundo plano.</li></ul><p>Os sistemas externos de pagamentos e logística continuam existindo, mas agora conseguimos visualizar quais partes da plataforma interagem com eles.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wTlLSApXs-mky7pJdV5hAQ.png" /></figure><p>Observe que começamos a responder perguntas diferentes.</p><p>Como a aplicação web se comunica com o backend? Quais componentes da solução acessam o banco de dados? O processamento de pedidos é inteiramente síncrono? Qual aplicação envia informações para a transportadora?</p><p>Nesse nível, faz sentido identificar tecnologias e protocolos relevantes. Podemos mostrar, por exemplo, que o frontend utiliza HTTPS para acessar a API, que a API persiste informações no SQL Server e publica mensagens que serão consumidas pelo worker.</p><p>Esses detalhes ajudam a compreender o desenho da solução sem exigir conhecimento do código-fonte.</p><p>O C2 também é um excelente instrumento para discutir responsabilidades arquiteturais.</p><p>Se várias aplicações acessam diretamente o mesmo banco de dados, temos um acoplamento que merece atenção? Se uma operação depende de cinco chamadas síncronas consecutivas, quais são os possíveis impactos na disponibilidade?</p><p>O diagrama não fornece automaticamente essas respostas, mas torna as relações visíveis, permitindo que sejam discutidas.</p><p>Vale ressaltar que <strong>utilizar C4 não significa incentivar uma arquitetura distribuída</strong>. Uma aplicação monolítica pode ser perfeitamente representada pelo modelo.</p><p>A intenção é documentar a arquitetura existente ou planejada, independentemente do estilo adotado.</p><h3>Componentes: entendendo as responsabilidades internas</h3><p>O terceiro nível, chamado <strong>C3 ou Diagrama de Componentes</strong>, nos aproxima da implementação.</p><p>Agora escolhemos um contêiner específico e investigamos como ele está organizado internamente.</p><p>Vamos utilizar a API de nossa plataforma.</p><p>Sabemos que ela recebe solicitações de compra, valida informações, aplica regras de negócio, registra pedidos e se comunica com serviços externos.</p><p>Mas como essas responsabilidades estão distribuídas?</p><p>Uma possibilidade seria organizar a aplicação em componentes como:</p><p><strong>API de Pedidos:</strong> recebe requisições HTTP e encaminha operações para a camada responsável pela aplicação.</p><p><strong>Processamento de Pedidos:</strong> coordena a criação dos pedidos e a execução das operações necessárias.</p><p><strong>Domínio de Pedidos:</strong> concentra regras e invariantes importantes para o negócio.</p><p><strong>Persistência:</strong> abstrai as operações de leitura e gravação das informações.</p><p><strong>Integração de Pagamentos:</strong> encapsula a comunicação com o provedor externo.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_wR9AATuV_HkwGYT-FdiTQ.png" /></figure><p>Esses componentes são apenas uma possibilidade de organização, e não uma estrutura obrigatória do C4.</p><p>O importante é compreender que um componente representa um conjunto de funcionalidades encapsuladas por uma interface ou responsabilidade bem definida. Ele não precisa corresponder diretamente a uma classe, pasta ou projeto do repositório.</p><p>Por exemplo, o componente responsável pelo processamento de pedidos pode envolver diversas classes trabalhando em conjunto.</p><p>É nessa perspectiva que conseguimos discutir questões relacionadas a coesão, dependências e separação de responsabilidades.</p><p>Uma regra de negócio deveria estar dentro do controller? Uma integração externa está excessivamente acoplada ao domínio? Podemos substituir determinado mecanismo de persistência sem alterar a lógica principal?</p><p>Essas perguntas começam a fazer muito mais sentido quando visualizamos as relações internas da aplicação.</p><p>Também é importante evitar um erro frequente: tentar representar todas as classes do projeto em um C3.</p><p>Se o diagrama contém dezenas de elementos sem uma organização clara, ele provavelmente deixou de cumprir seu papel.</p><p>Em soluções grandes, é perfeitamente aceitável criar diagramas de componentes separados para diferentes áreas ou funcionalidades.</p><p>A documentação precisa facilitar a compreensão, não reproduzir toda a complexidade do código em uma única imagem.</p><h3>Código: quando precisamos examinar a implementação</h3><p>Chegamos ao <strong>C4 ou Diagrama de Código</strong>, o nível mais detalhado do modelo.</p><p>Aqui deixamos de observar apenas responsabilidades arquiteturais e passamos a examinar elementos concretos de implementação, como classes, interfaces, funções e seus relacionamentos.</p><p>Continuando nosso exemplo, podemos escolher o componente responsável pelo processamento de pedidos.</p><p>Imagine que ele utilize uma classe CriarPedidoHandler, responsável por coordenar uma operação de compra.</p><p>Essa classe depende de uma interface IPedidoRepository, utilizada para persistência, e de uma interface IPagamentoGateway, responsável por abstrair a integração com pagamentos.</p><p>Também temos a entidade Pedido, que representa informações e comportamentos do domínio.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5oIbePrL9kt5w66p5HioDQ.png" /></figure><p>Nesse nível, conseguimos visualizar essas dependências e compreender como a implementação foi estruturada.</p><p>Isso pode ser particularmente útil quando estamos analisando componentes com regras complexas, algoritmos importantes ou relacionamentos que não são imediatamente evidentes.</p><p>Também pode ajudar durante uma refatoração, quando precisamos avaliar quais classes serão afetadas por determinada mudança.</p><p>Entretanto, existe uma recomendação importante: <strong>o nível de código é opcional</strong>.</p><p>Não há necessidade de criar diagramas de classes para cada funcionalidade desenvolvida.</p><p>Na maioria dos projetos, ferramentas de desenvolvimento e análise estática conseguem fornecer essas informações diretamente a partir do código-fonte.</p><p>Manter manualmente diagramas muito detalhados pode se tornar um trabalho difícil, especialmente quando a implementação evolui rapidamente.</p><p>Minha preferência é reservar esse nível para situações em que o diagrama realmente ajuda a explicar uma decisão ou compreender um problema específico.</p><p>Caso contrário, o próprio código, acompanhado de testes e boas convenções, costuma ser uma fonte mais adequada de detalhes.</p><h3>Arquitetura em larga escala: os quatro níveis são suficientes?</h3><p>Até aqui, observamos uma progressão relativamente simples: começamos com o sistema visto de fora e terminamos examinando detalhes internos.</p><p>Mas sistemas de grande escala apresentam preocupações que não são totalmente explicadas por esses quatro níveis.</p><p>Por exemplo, um diagrama de contêineres pode mostrar que uma API se comunica com um banco de dados. Isso, por si só, não explica quantas instâncias da aplicação existem, como ocorre o balanceamento de carga ou quais estratégias são utilizadas para recuperação de falhas.</p><p>Da mesma forma, conhecer os componentes de uma aplicação não necessariamente explica a sequência de eventos que acontece quando um cliente realiza uma compra.</p><p>Por esse motivo, o C4 também possui diagramas complementares.</p><h3>Diagramas dinâmicos: mostrando o comportamento</h3><p>Os diagramas dinâmicos representam como determinados elementos colaboram durante a execução de uma funcionalidade.</p><p>Podemos utilizá-los para demonstrar a sequência de operações envolvidas na criação de um pedido.</p><p>A aplicação recebe a solicitação, verifica informações, registra o pedido, solicita o pagamento e inicia o processamento das etapas seguintes.</p><p>Ao visualizar essas interações, conseguimos discutir timeouts, tratamento de falhas, consistência de dados e possíveis operações compensatórias.</p><p>Esse tipo de representação é especialmente útil quando existe comunicação assíncrona ou uma sequência complexa de integrações.</p><h3>Diagramas de implantação: conectando arquitetura e infraestrutura</h3><p>Os diagramas de implantação, ou <em>Deployment Diagrams</em>, mostram como os elementos da arquitetura são executados em determinada infraestrutura.</p><p>Podemos representar ambientes em nuvem, instâncias de aplicações, serviços gerenciados, bancos de dados e recursos de rede.</p><p>Essa perspectiva ajuda a discutir disponibilidade, escalabilidade, redundância e isolamento entre ambientes.</p><p>É importante perceber que um diagrama de implantação não substitui o C2. Eles respondem a perguntas diferentes.</p><p>Enquanto o C2 explica quais aplicações e armazenamentos compõem a solução, o diagrama de implantação mostra onde suas instâncias estão executando.</p><h3>Diagramas de paisagem de sistemas: olhando para toda a organização</h3><p>Em organizações com dezenas ou centenas de aplicações, também pode ser interessante utilizar um <em>System Landscape Diagram</em>.</p><p>Ele permite visualizar o conjunto de sistemas que compõem um departamento ou organização, sem necessariamente escolher um único sistema como elemento central.</p><p>Esse recurso é útil para compreender dependências entre plataformas, identificar integrações críticas e apoiar iniciativas de modernização.</p><p>Em ambientes corporativos grandes, essa visão pode ser tão importante quanto os diagramas individuais de cada aplicação.</p><h3>Como aplicar C4 sem criar burocracia</h3><p>Uma preocupação legítima de qualquer equipe é o custo de manter a documentação atualizada.</p><p>Afinal, não adianta produzir diagramas excelentes durante o início de um projeto se eles deixam de representar a realidade depois de algumas entregas.</p><p>Por isso, recomendo começar pelo necessário.</p><p>Em muitos projetos, um diagrama de contexto e outro de contêineres já oferecem uma base bastante útil para discussões arquiteturais e onboarding de novos profissionais.</p><p>Os diagramas de componentes podem ser adicionados progressivamente, principalmente nas partes mais relevantes ou complexas da solução.</p><p>O nível de código entra quando existe uma necessidade concreta.</p><p>Outra prática interessante é manter a documentação próxima do desenvolvimento.</p><p>Ferramentas como o <strong>Structurizr DSL</strong> permitem descrever modelos arquiteturais em arquivos de texto, facilitando o versionamento com Git e a revisão das alterações.</p><p>Assim, mudanças na arquitetura podem acompanhar o mesmo fluxo de revisão utilizado para o código.</p><p>Também considero importante relacionar diagramas com os <strong>Architecture Decision Records (ADRs)</strong>.</p><p>Os diagramas mostram a estrutura e as relações da solução. Os ADRs registram o contexto das decisões arquiteturais, as alternativas consideradas e os motivos das escolhas realizadas.</p><p>Juntos, esses recursos ajudam a responder duas perguntas fundamentais:</p><p>“Como o sistema está organizado?”</p><p>“Por que decidimos organizá-lo dessa maneira?”</p><p>Essa combinação é particularmente valiosa quando uma equipe precisa compreender decisões tomadas meses ou anos antes.</p><p>Ainda assim, nenhuma ferramenta resolve sozinha o problema da documentação desatualizada.</p><p>É necessário estabelecer responsabilidades e incorporar a revisão arquitetural ao processo de evolução do software.</p><h3>O que diferencia um bom diagrama de um desenho complicado?</h3><p>Uma das maiores armadilhas ao documentar arquitetura é acreditar que um diagrama se torna melhor à medida que adicionamos informações.</p><p>Na prática, frequentemente acontece o contrário.</p><p>Imagine apresentar uma imagem com quarenta serviços, múltiplas bases de dados e dezenas de setas cruzadas. Mesmo que todos os elementos estejam tecnicamente corretos, a visualização pode ser difícil de compreender.</p><p>O primeiro cuidado é definir claramente o propósito do desenho.</p><p>Um diagrama destinado a explicar o processamento de pagamentos não precisa representar todos os serviços responsáveis por autenticação, notificações ou relatórios, a menos que tenham relevância para aquele fluxo.</p><p>Outro cuidado está na descrição dos relacionamentos.</p><p>Uma seta identificada apenas como “utiliza” diz muito pouco. Já uma relação como “publica evento de pedido criado via mensageria” transmite informações mais úteis.</p><p>Também vale identificar claramente os limites dos sistemas, as responsabilidades dos elementos e as tecnologias quando forem relevantes para o nível apresentado.</p><p>É importante manter consistência entre os diagramas. Se uma aplicação recebe determinado nome no C2, não deveria aparecer com outro nome no C3 sem uma justificativa clara.</p><p>Por fim, devemos lembrar que os diagramas precisam refletir a arquitetura real, incluindo limitações e dependências que talvez não sejam ideais.</p><p><strong>Documentação arquitetural não deve ser uma representação embelezada do sistema. Deve ser uma ferramenta para compreendê-lo e evoluí-lo.</strong></p><h3>O verdadeiro valor do C4 está na comunicação</h3><p>Existe uma tendência natural de associar arquitetura de software a decisões técnicas sofisticadas.</p><p>Discutimos padrões, plataformas, protocolos e tecnologias. Tudo isso é importante, mas uma arquitetura também precisa ser compreensível para as pessoas que trabalham com ela.</p><p>Quando conseguimos apresentar um sistema em diferentes níveis de detalhe, facilitamos conversas que antes exigiam longas explicações.</p><p>Uma pessoa de negócios consegue compreender as dependências fundamentais da solução. Um novo desenvolvedor encontra mais rapidamente os componentes pelos quais será responsável. Equipes de operações e segurança conseguem identificar relações relevantes para suas análises.</p><p>E os arquitetos passam a contar com uma representação compartilhada para discutir mudanças e suas consequências.</p><p>Em sistemas grandes, essa clareza contribui para reduzir ambiguidades, acelerar o entendimento e tornar as decisões mais bem fundamentadas.</p><p>O C4 não elimina a complexidade de uma arquitetura. Seu mérito está em nos ajudar a organizá-la em perspectivas que fazem sentido.</p><h3>Para continuar aprendendo</h3><p>Se você deseja aprofundar seus conhecimentos, minha sugestão é começar pela documentação oficial e depois experimentar o modelo em algum sistema que já conheça.</p><p><a href="https://c4model.com/"><strong>C4 Model, site oficial de Simon Brown</strong></a></p><p>É a principal referência para compreender os conceitos, as abstrações e os diferentes diagramas. Recomendo especialmente as seções sobre contêineres, componentes e diagramas complementares.</p><p><a href="https://docs.structurizr.com/"><strong>Structurizr e sua documentação</strong></a></p><p>Uma excelente opção para quem deseja representar arquitetura como código. O tutorial do Structurizr DSL mostra como construir modelos e gerar diferentes visualizações a partir deles.</p><p><a href="https://c4model.com/diagrams/checklist"><strong>Checklist de revisão de diagramas C4</strong></a></p><p>Um material prático para avaliar se os diagramas estão realmente comunicando o necessário. Pode ser utilizado durante revisões arquiteturais e discussões em equipe.</p><p><a href="https://adr.github.io/madr/"><strong>Markdown Architectural Decision Records (MADR)</strong></a></p><p>Uma referência complementar para documentar decisões arquiteturais. Ajuda a preservar o raciocínio por trás das escolhas que aparecem nos diagramas.</p><p>Como exercício, escolha uma aplicação que você conhece bem e tente representar seu contexto e seus contêineres.</p><p>Não se preocupe inicialmente com ferramentas sofisticadas ou diagramas visualmente elaborados. Concentre-se em responder, com clareza, o que cada elemento faz e como se relaciona com os demais.</p><p>Se outra pessoa conseguir compreender a solução a partir desses desenhos, você já terá dado um passo importante.</p><p>Porque, no fim das contas, uma boa documentação de arquitetura não é aquela que impressiona pela quantidade de detalhes, mas aquela que ajuda as pessoas a entender o sistema, tomar decisões e trabalhar melhor juntas.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d8301b30a334" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Exploring MCP: From First Integrations to Architectural Decisions]]></title>
            <link>https://medium.com/@rodrigodotnet/exploring-mcp-from-first-integrations-to-architectural-decisions-954862144a42?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/954862144a42</guid>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Thu, 05 Nov 2026 10:01:08 GMT</pubDate>
            <atom:updated>2026-11-05T10:01:08.527Z</atom:updated>
            <content:encoded><![CDATA[<h3>Explorando MCP: da primeira integração às decisões de arquitetura</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sUN63drdqUu_dKJO86VpFQ.png" /></figure><p>Durante minhas férias, resolvi dedicar parte do tempo a estudar melhor o Model Context Protocol, ou simplesmente MCP.</p><p>Eu já vinha acompanhando o assunto e tinha algumas implementações nos meus projetos open source, mas queria entender melhor o protocolo, experimentar algumas possibilidades e, principalmente, avaliar se as decisões que havia tomado continuavam fazendo sentido.</p><p>Em vez de começar outro projeto do zero, achei mais interessante revisitar o que já tinha desenvolvido. Afinal, são ferramentas com problemas reais para resolver, regras de negócio próprias e uma arquitetura que já existe independentemente de qualquer integração com inteligência artificial.</p><p>Acabei passando por projetos como <a href="https://github.com/rodri-oliveira-dev/adr-guard">ADR Guard</a>, <a href="https://github.com/rodri-oliveira-dev/Repo2C4">Repo2C4</a>, <a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector">DotNetRepoInspector</a> e <a href="https://github.com/rodri-oliveira-dev/complexity-analyzers">Complexity Analyzers</a>.</p><p>O exercício foi interessante porque cada um apresenta um problema diferente. Alguns precisam apenas consultar informações, outros realizam análises mais complexas e há situações em que o agente pode participar da geração de arquivos.</p><p>Quanto mais eu avançava, mais percebia que a parte de implementar o protocolo não era necessariamente a mais complicada.</p><p>As perguntas mais difíceis eram outras: o que vale a pena expor para um agente? Quanta liberdade ele deveria ter? Como preservar as regras existentes? E como garantir que os resultados continuem confiáveis?</p><p>Foi a partir dessas perguntas que organizei algumas das minhas anotações.</p><h3>MCP é interessante, mas não faz mágica</h3><p>Para quem ainda não teve contato com o assunto, MCP é um protocolo aberto que padroniza a comunicação entre aplicações de inteligência artificial e sistemas externos.</p><p>A ideia é permitir que um cliente compatível descubra e utilize capacidades oferecidas por um servidor, sem precisar conhecer todos os detalhes de implementação de cada sistema.</p><p>Pense em uma ferramenta que analisa uma solução .NET.</p><p>Normalmente, você executaria um comando, receberia um relatório e interpretaria as informações. Um agente poderia tentar fazer exatamente isso, executando a CLI e lendo sua saída.</p><p>Funciona, dependendo do caso.</p><p>Mas, se a aplicação oferece uma interface MCP, podemos disponibilizar operações mais específicas, como list_projects, get_sdk_metadata ou get_project_reference_graph.</p><p>Em vez de descobrir como executar um comando e interpretar sua saída textual, o cliente recebe ferramentas com nomes, descrições, parâmetros e respostas estruturadas.</p><p>O protocolo também contempla <em>resources</em>, para disponibilizar conteúdos, e <em>prompts</em>, que podem representar modelos reutilizáveis de interação.</p><p>Não é necessário implementar tudo isso em um único servidor. Nos meus projetos, comecei principalmente pelas <em>tools</em>, porque elas correspondiam melhor às funcionalidades que eu queria disponibilizar.</p><p>E aqui existe uma diferença que considero importante.</p><p><strong>MCP não é um agente de IA. Também não é um modelo de linguagem.</strong></p><p>O servidor disponibiliza capacidades. O cliente organiza a comunicação e pode utilizá-las em conjunto com um modelo de linguagem.</p><p>Essa separação permite que uma ferramenta seja utilizada por diferentes clientes compatíveis, sem necessariamente depender de um provedor específico de IA.</p><p>Até aqui, parece bastante simples. E conceitualmente é mesmo. O interessante começa quando precisamos decidir quais funcionalidades disponibilizar e como elas devem se comportar.</p><h3>Nem tudo precisa de inteligência artificial</h3><p>Uma das coisas que mais me chamaram a atenção nesse estudo foi perceber como podemos aproveitar funcionalidades tradicionais de software no contexto dos agentes.</p><p>No <a href="https://github.com/rodri-oliveira-dev/adr-guard">ADR Guard</a>, por exemplo, tenho operações para validar Architecture Decision Records, analisar relacionamentos entre decisões e identificar possíveis impactos de mudanças no código.</p><p>Boa parte disso funciona com regras determinísticas.</p><p>Se um ADR precisa seguir determinado formato, apresentar certos campos ou respeitar regras de validação, não preciso de um modelo de linguagem para verificar essas condições.</p><p>O código já sabe fazer isso.</p><p>O que o MCP acrescenta é a possibilidade de um agente consultar essas informações e utilizá-las durante uma análise.</p><p>Uma operação como validate_adrs pode retornar os problemas encontrados em determinados documentos. A partir daí, o agente consegue explicar os diagnósticos e sugerir melhorias.</p><p>Mas existe um limite importante: o agente não deveria transformar uma validação malsucedida em uma aprovação só porque interpretou o documento de outra maneira.</p><p>O resultado da ferramenta precisa continuar representando aquilo que foi efetivamente verificado.</p><p>Esse raciocínio vale para análise estática, testes automatizados, verificação de contratos e diversas outras atividades de engenharia de software.</p><p>O modelo de linguagem pode ajudar a interpretar os resultados, relacionar informações e elaborar explicações. Mas não precisa substituir a lógica que já produz essas evidências.</p><p>Aliás, em muitos casos, prefiro que não substitua.</p><p>Quando tenho uma regra verificável, quero que ela produza o mesmo resultado independentemente do modelo utilizado ou da maneira como uma pergunta foi formulada.</p><h3>A importância de não duplicar regras de negócio</h3><p>Outro ponto que procurei preservar foi a separação entre a implementação das funcionalidades e a interface MCP.</p><p>Essa preocupação não surgiu especificamente por causa da inteligência artificial. É algo que já faz parte do desenvolvimento de software há bastante tempo.</p><p>Imagine manter duas implementações para validar um ADR: uma utilizada pela CLI e outra utilizada pelo servidor MCP.</p><p>No começo, ambas podem funcionar perfeitamente. Depois de algumas correções e novas funcionalidades, começam a aparecer diferenças.</p><p>Uma regra é atualizada em um lugar, mas não no outro. Um diagnóstico passa a ter comportamento diferente. Um teste cobre apenas um dos caminhos.</p><p>É o tipo de problema que prefiro evitar.</p><p>No ADR Guard, a CLI e o servidor MCP utilizam os mesmos serviços internos de domínio.</p><p>No <a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector">DotNetRepoInspector</a>, o mecanismo responsável pela inspeção continua independente de quem consome os resultados.</p><p>A mesma ideia aparece no <a href="https://github.com/rodri-oliveira-dev/complexity-analyzers">Complexity Analyzers</a>, em que o servidor MCP reutiliza os recursos de análise de complexidade já existentes.</p><p>O MCP acaba sendo uma camada de adaptação.</p><p>Ele recebe os parâmetros, verifica os limites da operação, utiliza os serviços necessários e devolve uma resposta adequada ao protocolo.</p><p>Parece uma decisão pequena, mas traz benefícios importantes. As regras continuam centralizadas, os testes podem ser reaproveitados e uma mudança no protocolo não exige reescrever o domínio.</p><p>Isso também ajuda a evitar um acoplamento desnecessário com SDKs de inteligência artificial.</p><p>Se amanhã eu quiser disponibilizar uma funcionalidade por HTTP, por uma CLI ou por outra integração, a lógica principal continua disponível.</p><p>Depois de tantos anos trabalhando com software, continuo achando essa separação bastante valiosa. A tecnologia de integração muda, mas o domínio não deveria precisar acompanhar cada mudança.</p><h3>O agente não precisa receber o repositório inteiro</h3><p>No DotNetRepoInspector e no Complexity Analyzers, encontrei outro aspecto interessante: a quantidade de informações que disponibilizamos.</p><p>É tentador criar uma ferramenta que retorna um relatório enorme com tudo o que foi encontrado.</p><p>O problema é que nem sempre o agente precisa de tudo aquilo.</p><p>Imagine que a pergunta seja: quais projetos desta solução ainda utilizam uma versão antiga do .NET?</p><p>Uma consulta inicial ao inventário pode ser suficiente para identificar os candidatos. Depois, o agente pode buscar detalhes apenas sobre os projetos relevantes.</p><p>Não há muita vantagem em retornar informações detalhadas de toda a solução logo na primeira chamada.</p><p>No DotNetRepoInspector, essa abordagem aparece na separação entre ferramentas de inventário, detalhes de projetos, referências e diagnósticos.</p><p>No Complexity Analyzers, existe algo semelhante. Uma análise pode retornar um resumo e permitir a consulta posterior de evidências específicas de um método ou membro analisado.</p><p>Também há mecanismos para reutilizar snapshots, evitando repetir desnecessariamente uma análise mais custosa.</p><p>Isso ajuda a reduzir o volume de dados transferido ao cliente, o consumo de contexto do modelo e o trabalho realizado pelo servidor.</p><p>Mas existe outra vantagem: as operações ficam mais fáceis de compreender e testar.</p><p>Uma ferramenta que responde a uma pergunta específica tende a apresentar um contrato mais claro do que outra que tenta resolver qualquer necessidade.</p><p>Naturalmente, não significa que toda funcionalidade deva ser dividida em dezenas de ferramentas. Existe um equilíbrio entre granularidade e complexidade.</p><p>O objetivo é disponibilizar informações suficientes para o agente trabalhar, sem transformar cada chamada em um despejo de dados.</p><h3>E quando não existe uma resposta definitiva?</h3><p>Esse assunto também me fez pensar sobre a maneira como representamos incerteza.</p><p>No Complexity Analyzers, por exemplo, determinadas análises podem produzir resultados desconhecidos ou inconclusivos.</p><p>Nesses casos, prefiro preservar essa condição no contrato.</p><p>Uma resposta Unknown pode ser menos satisfatória à primeira vista, mas é tecnicamente mais correta do que apresentar uma estimativa sem evidências suficientes.</p><p>Isso é especialmente importante quando existe um modelo de linguagem interpretando os resultados.</p><p>Um agente pode transformar dados incompletos em uma explicação muito convincente. Se o contrato não deixa claras as limitações da análise, fica mais difícil distinguir o que foi realmente verificado daquilo que está sendo inferido.</p><p>Por isso, considero importante que ferramentas MCP retornem não apenas resultados, mas também diagnósticos, limitações e estados inconclusivos quando necessário.</p><h3>Repo2C4: quando o agente pode ir além da leitura</h3><p>O <a href="https://github.com/rodri-oliveira-dev/Repo2C4">Repo2C4</a> acabou sendo um dos casos mais interessantes dessa revisão.</p><p>Diferentemente das ferramentas voltadas principalmente à consulta, ele trabalha com a geração de representações arquiteturais em LikeC4.</p><p>Nesse cenário, existe uma diferença importante entre identificar fatos no repositório e interpretar sua arquitetura.</p><p>Encontrar referências entre projetos, dependências ou determinados padrões de implementação fornece evidências. Mas essas informações, isoladamente, nem sempre são suficientes para definir corretamente os elementos de um modelo C4.</p><p>No fluxo MCP do Repo2C4, o servidor disponibiliza evidências estruturadas da inspeção.</p><p>O cliente pode utilizar essas informações para propor um ArchitectureModel. Depois, o servidor valida esse modelo e consegue gerar os arquivos LikeC4 de maneira determinística.</p><p>A interpretação arquitetural permanece fora do servidor MCP.</p><p>Essa escolha permite que a análise seja realizada por um agente, por outro mecanismo ou até a partir de um modelo preparado manualmente.</p><p>Mas a parte que exigiu mais cuidado foi a escrita dos arquivos.</p><p>Consultar informações e modificar um repositório são responsabilidades bem diferentes.</p><p>Por isso, a geração utiliza inicialmente uma prévia, com dryRun=true. Para persistir os arquivos, é necessário solicitar explicitamente a escrita, incluindo write=true e dryRun=false.</p><p>Existem também verificações para evitar conflitos com arquivos gerenciados e propostas que não correspondam mais ao estado esperado.</p><p>Além do servidor MCP, o projeto possui um agente separado, desenvolvido com Microsoft Agent Framework, que utiliza essas capacidades e incorpora uma etapa de aprovação humana antes da escrita.</p><p>Gosto dessa separação porque ela deixa claro quem faz o quê.</p><p>O servidor conhece suas operações e limitações. O agente organiza o processo e interpreta as evidências. A aprovação humana faz parte do fluxo antes de aplicar alterações.</p><p>Isso não elimina todos os riscos, claro. Uma aprovação precisa estar associada a uma proposta concreta, e o estado do repositório pode mudar entre a prévia e a execução.</p><p>Mas são exatamente esses detalhes que começam a aparecer quando saímos de um exemplo simples e tentamos construir algo utilizável no dia a dia.</p><h3>Segurança não é só marcar uma ferramenta como ReadOnly</h3><p>Durante essa revisão, segurança apareceu várias vezes.</p><p>A primeira preocupação foi limitar o acesso ao sistema de arquivos.</p><p>Nos servidores locais, procuro trabalhar com uma raiz de repositório previamente autorizada. As ferramentas precisam respeitar esse limite, mesmo quando recebem caminhos informados pelo cliente.</p><p>Isso envolve tratar caminhos relativos, tentativas de acessar diretórios externos, links simbólicos e arquivos que ultrapassam limites definidos.</p><p>Também é necessário considerar tempo de execução, cancelamento e tamanho das respostas.</p><p>Uma ferramenta que analisa algumas dezenas de arquivos pode funcionar muito bem, mas apresentar um comportamento bastante diferente quando recebe um repositório grande.</p><p>Outro cuidado está no conteúdo que será processado.</p><p>Um arquivo Markdown, uma configuração ou até um comentário no código pode conter texto tentando se passar por uma instrução para o agente.</p><p>Esse conteúdo deve continuar sendo tratado como dado.</p><p>No ADR Guard, por exemplo, o servidor identifica conteúdos retornados como não confiáveis. Isso ajuda a tornar a fronteira explícita para quem consome as informações.</p><p>Entretanto, uma anotação de segurança não transforma automaticamente o ambiente em algo isolado.</p><p>O próprio DotNetRepoInspector ilustra isso. Embora suas ferramentas MCP sejam declaradas somente leitura, a inspeção de projetos .NET pode envolver avaliação MSBuild, que por sua vez pode carregar lógica definida pelo repositório.</p><p>Portanto, declarar uma operação como ReadOnly não equivale a garantir que nenhum código potencialmente perigoso possa ser executado.</p><p>Da mesma maneira, utilizar stdio evita a necessidade de expor um endpoint de rede, mas não resolve questões relacionadas às permissões do processo ou ao comportamento do cliente.</p><p>O servidor pode controlar aquilo que acessa e devolve. Já o cliente pode transmitir essas informações a um modelo externo, dependendo de sua configuração.</p><p>São fronteiras distintas e precisam ser avaliadas separadamente.</p><h3>MCP, agentes e skills: onde cada coisa entra?</h3><p>Outro projeto que utilizei nesse estudo foi o <a href="https://github.com/rodri-oliveira-dev/ai-ready-dotnet-workspace">AI-Ready .NET Workspace</a>.</p><p>A proposta dele é oferecer um ambiente de desenvolvimento .NET preparado para trabalhar com ferramentas e agentes de IA.</p><p>Nesse contexto, achei importante separar conceitos que frequentemente aparecem misturados.</p><p>Um agente pode assumir um papel, como revisar arquitetura ou auxiliar em uma implementação.</p><p>Uma skill pode descrever um procedimento reutilizável, por exemplo, quais verificações devem ser executadas antes de considerar uma alteração concluída.</p><p>Um prompt organiza uma solicitação ou um fluxo de interação.</p><p>O MCP, por sua vez, oferece capacidades concretas que podem ser utilizadas durante essas atividades.</p><p>No workspace, o servidor MCP disponibiliza apenas duas ferramentas: uma para consultar metadados dos projetos .NET e outra para recuperar regras arquiteturais.</p><p>Não existe uma necessidade de oferecer um terminal genérico, acesso irrestrito ao filesystem ou execução arbitrária de comandos.</p><p>Essa decisão foi registrada em um ADR do projeto justamente para deixar as responsabilidades explícitas.</p><p>O interessante é que nem sempre precisamos de um servidor MCP sofisticado.</p><p>Às vezes, duas operações bem definidas, com contratos pequenos, já resolvem uma necessidade real.</p><h3>E como saber se tudo isso funciona?</h3><p>Uma coisa é implementar um servidor MCP que compila e inicia corretamente. Outra é verificar se um cliente consegue utilizá-lo de maneira consistente.</p><p>Nos projetos, procurei incluir testes que vão além da execução isolada das regras de negócio.</p><p>Eles verificam aspectos como inicialização do protocolo, descoberta de ferramentas, chamadas reais, tratamento de entradas inválidas, cancelamento e limites operacionais.</p><p>Alguns testes iniciam o servidor como um processo separado e utilizam o cliente do SDK oficial para se comunicar com ele.</p><p>Isso ajuda a detectar problemas bastante específicos da integração.</p><p>Um exemplo simples é o uso da saída padrão.</p><p>No transporte stdio, ela é utilizada pela comunicação do protocolo. Se a aplicação começar a escrever mensagens de log nesse mesmo canal, pode comprometer o funcionamento do cliente MCP.</p><p>É um detalhe fácil de ignorar quando estamos acostumados a aplicações de console.</p><p>Mas há outra distinção que considero importante: testar o protocolo não significa testar o comportamento de um agente.</p><p>Um teste pode comprovar que determinada ferramenta retorna exatamente os dados esperados.</p><p>Isso não garante que um modelo de linguagem escolherá a ferramenta correta, interpretará adequadamente o resultado ou evitará chamadas desnecessárias.</p><p>Para avaliar esse comportamento, precisamos de cenários mais próximos do uso real.</p><p>No DotNetRepoInspector, por exemplo, existem avaliações determinísticas e registros de compatibilidade com clientes, distinguindo o que foi executado daquilo que ainda depende de validação.</p><p>É um cuidado que pretendo continuar aplicando e aprimorando.</p><p>Também vale separar o que está implementado no repositório daquilo que foi publicado e validado como pacote distribuível. Uma implementação funcional não significa, necessariamente, que todo o processo de distribuição esteja concluído.</p><h3>O que ainda quero explorar</h3><p>O MCP continua evoluindo, assim como os SDKs e os clientes que o utilizam.</p><p>Isso abre algumas frentes interessantes de estudo.</p><p>Uma delas é aprofundar a interoperabilidade entre clientes. Não apenas verificar se conseguem iniciar o servidor, mas também comparar como selecionam ferramentas e trabalham com respostas estruturadas.</p><p>Outra é entender melhor os impactos das revisões mais recentes do protocolo sobre servidores que mantêm dados temporários, como os snapshots utilizados pelo Repo2C4.</p><p>Também quero dedicar mais atenção à avaliação do uso de contexto. Ferramentas muito detalhadas podem ser úteis em determinados cenários, mas também podem aumentar o custo e a complexidade da interação sem trazer benefícios proporcionais.</p><p>E existe a questão da distribuição: versionamento, compatibilidade de contratos, publicação no NuGet e registro de servidores MCP.</p><p>São assuntos menos atraentes do que uma demonstração de agente executando tarefas, mas fazem bastante diferença para quem pretende manter uma ferramenta por mais tempo.</p><h3>Algumas considerações depois desse estudo</h3><p>Aproveitar as férias para estudar MCP foi uma boa oportunidade de revisitar conceitos que já utilizo há bastante tempo no desenvolvimento de software.</p><p>Separação de responsabilidades, reaproveitamento de regras de negócio, contratos explícitos, segurança e testes continuam sendo fundamentais.</p><p>O protocolo traz uma maneira interessante de disponibilizar capacidades para agentes, mas não substitui essas preocupações.</p><p>Também fiquei com uma percepção mais clara de que nem toda aplicação precisa de um agente complexo, e nem toda ferramenta precisa utilizar IA internamente.</p><p>Em muitos casos, o melhor caminho é justamente combinar mecanismos determinísticos, que conhecem bem um problema, com modelos de linguagem capazes de interpretar informações e ajudar a trabalhar sobre elas.</p><p>Por enquanto, sigo experimentando essas possibilidades nos meus projetos.</p><p>Ainda há bastante coisa para aprender, principalmente sobre interoperabilidade, segurança e comportamento dos agentes em situações reais.</p><p>Mas uma conclusão já me parece razoável: <strong>antes de pensar em tudo o que um agente poderia fazer, vale entender muito bem o que queremos permitir que ele faça.</strong></p><h3>Resumindo o que aprendi</h3><p>Se tivesse que resumir esse estudo em poucas ideias, diria que o MCP é mais interessante quando utilizado para disponibilizar capacidades que já possuem responsabilidades bem definidas.</p><p>Reaproveitar o domínio costuma ser melhor do que reconstruí-lo dentro do servidor. Respostas estruturadas e consultas específicas ajudam a controlar o consumo de contexto. Resultados inconclusivos precisam continuar inconclusivos, mesmo quando serão interpretados por IA.</p><p>E, principalmente, ferramentas que podem alterar o ambiente precisam de limites e mecanismos de autorização proporcionais ao que conseguem fazer.</p><p>Nada disso é particularmente novo para quem trabalha com arquitetura de software. Talvez seja justamente esse o ponto: estamos aprendendo a utilizar novas tecnologias, mas muitos dos problemas que precisamos resolver continuam bastante familiares.</p><h3>Para quem quiser continuar estudando</h3><p>Reuni algumas referências que considero bons pontos de partida:</p><ul><li><a href="https://modelcontextprotocol.io/">Documentação oficial do Model Context Protocol</a>: para compreender os conceitos, os mecanismos de comunicação e as responsabilidades de clientes e servidores.</li><li><a href="https://github.com/modelcontextprotocol/csharp-sdk">SDK oficial de MCP para C#</a>: especialmente interessante para quem trabalha com .NET e deseja explorar a implementação do protocolo.</li><li><a href="https://github.com/microsoft/mcp-for-beginners">MCP for Beginners, da Microsoft</a>: material com exemplos e exercícios para começar a experimentar.</li><li><a href="https://modelcontextprotocol.io/specification">Model Context Protocol Specification</a>: para aprofundar o entendimento dos contratos, transportes e aspectos de segurança.</li></ul><p>Também deixo os repositórios que utilizei como parte desses estudos:</p><p><a href="https://github.com/rodri-oliveira-dev/adr-guard">ADR Guard</a> | <a href="https://github.com/rodri-oliveira-dev/Repo2C4">Repo2C4</a> | <a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector">DotNetRepoInspector</a> | <a href="https://github.com/rodri-oliveira-dev/complexity-analyzers">Complexity Analyzers</a> | <a href="https://github.com/rodri-oliveira-dev/ai-ready-dotnet-workspace">AI-Ready .NET Workspace</a></p><p>Para quem está começando, minha sugestão é experimentar com uma funcionalidade que já exista em algum projeto próprio.</p><p>Não precisa ser nada sofisticado. Uma operação de consulta, com parâmetros claros e um retorno estruturado, já é suficiente para começar a entender como o protocolo funciona.</p><p>Depois disso, vale adicionar testes, experimentar clientes diferentes e observar quais dificuldades aparecem.</p><p>Foi esse tipo de exercício que mais contribuiu para o meu aprendizado.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=954862144a42" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Dapper FluentMap: o que mudou da versão 2.0 à 3.6]]></title>
            <link>https://medium.com/@rodrigodotnet/dapper-fluentmap-o-que-mudou-da-vers%C3%A3o-2-0-%C3%A0-3-6-f404a0045367?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/f404a0045367</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[dapper]]></category>
            <category><![CDATA[dotnet]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 10:01:10 GMT</pubDate>
            <atom:updated>2026-10-27T10:01:10.899Z</atom:updated>
            <content:encoded><![CDATA[<h3>Dapper FluentMap está de volta: o que mudou da versão 2.0 à 3.6?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nNStbPQjYahXxnv4dmH0Ng.png" /></figure><p><em>Depois de seis anos sem uma nova versão estável, o Dapper FluentMap voltou a receber atualizações. Mas retomar uma biblioteca utilizada por outras aplicações envolve mais do que atualizar dependências. É preciso evoluir sem comprometer os contratos que fizeram parte de sua história.</em></p><p>Imagine uma aplicação .NET que utiliza Dapper para consultar um banco de dados legado. No código, temos uma entidade Customer, com propriedades como Id e Name. No banco, as colunas seguem outra convenção: customer_id e customer_name.</p><p>Resolver essa diferença não parece complicado. Podemos utilizar aliases no SQL, criar objetos intermediários ou configurar um mapeamento explícito. Todas são alternativas válidas, dependendo do contexto.</p><p>O problema aparece quando essas diferenças se espalham por dezenas de consultas e entidades. Convenções de nomenclatura, particularidades de sistemas legados e decisões de persistência começam a interferir na organização do código.</p><p>Foi para lidar com esse tipo de situação que o Dapper FluentMap surgiu: permitir o mapeamento entre propriedades .NET e colunas do banco sem adicionar atributos de persistência às entidades.</p><p>Em agosto de 2020, foi publicada a versão 2.0.0, atualizando a integração para Dapper 2.0.35 e Dommel 2.0. Depois disso, o projeto passou um longo período sem novas releases estáveis.</p><p>Em 2026, retomei sua manutenção. A primeira questão não era quantas funcionalidades poderiam ser adicionadas, mas como evoluir uma biblioteca existente sem comprometer aplicações que ainda dependiam dela.</p><p>Hoje, na versão 3.6.0, publicada em 13 de outubro de 2026, o FluentMap mantém sua proposta original, mas oferece recursos que não faziam parte da linha 2.x.</p><h3>A primeira decisão: preservar o que já funcionava</h3><p>Uma biblioteca de uso geral possui uma responsabilidade diferente daquela de uma aplicação mantida por uma única equipe.</p><p>Quando alteramos uma aplicação, normalmente conhecemos seus consumidores e conseguimos coordenar uma migração. Em uma biblioteca pública, não sabemos quantos projetos dependem de determinado comportamento, nem quais decisões foram tomadas a partir dele.</p><p>Por isso, considero a compatibilidade um requisito de arquitetura, não apenas uma preocupação com versionamento.</p><p>No FluentMap, a configuração tradicional continua disponível:</p><pre>public class Customer<br>{<br>    public int Id { get; set; }<br>    public string Name { get; set; } = string.Empty;<br>}<br><br>public sealed class CustomerMap : EntityMap&lt;Customer&gt;<br>{<br>    public CustomerMap()<br>    {<br>        Map(x =&gt; x.Id).ToColumn(&quot;customer_id&quot;);<br>        Map(x =&gt; x.Name).ToColumn(&quot;customer_name&quot;);<br>    }<br>}</pre><p>O registro permanece familiar:</p><pre>FluentMapper.Initialize(config =&gt;<br>{<br>    config.AddMap&lt;CustomerMap&gt;();<br>});<br><br>FluentMapper.Validate();</pre><p>E as consultas continuam utilizando o Dapper normalmente:</p><pre>var customer = connection.QuerySingle&lt;Customer&gt;(<br>    &quot;SELECT customer_id, customer_name FROM customers WHERE customer_id = @Id&quot;,<br>    new { Id = 10 });</pre><p>O FluentMap estabelece a correspondência entre os nomes das colunas e as propriedades. A execução SQL, o gerenciamento de conexões e a materialização básica continuam sob responsabilidade do Dapper.</p><p>Internamente, essa integração utiliza o mecanismo de mapeamento de tipos do Dapper, associado à configuração global da biblioteca.</p><p>Esse comportamento foi preservado na linha 3.x.</p><p>Para aplicações que utilizam somente mapeamentos tradicionais, a migração normalmente não exige reescrever as entidades ou substituir as chamadas existentes. Isso não significa compatibilidade irrestrita: as versões das dependências e os cenários de integração ainda precisam ser validados.</p><p>A evolução também não transforma o FluentMap em um ORM completo. Ele não introduz rastreamento de entidades, gerenciamento de migrations ou geração genérica de operações CRUD no pacote principal.</p><p>A intenção continua sendo complementar o Dapper, não substituí-lo.</p><h3>Quando mapear propriedades deixa de ser suficiente</h3><p>O mapeamento entre uma coluna e uma propriedade resolve muitos problemas, mas modelos de domínio nem sempre são compostos apenas por propriedades escalares.</p><p>Em aplicações que utilizam DDD, por exemplo, é comum encontrar objetos de valor, propriedades aninhadas e entidades imutáveis. Também existem situações em que uma mesma entidade precisa ser materializada a partir de consultas com formatos diferentes.</p><p>Na versão 3.x, o FluentMap passou a oferecer mecanismos específicos para esses cenários.</p><p>Uma entidade pode mapear uma propriedade aninhada:</p><pre>public sealed class CustomerMap : EntityMap&lt;Customer&gt;<br>{<br>    public CustomerMap()<br>    {<br>        Map(x =&gt; x.Address.City).ToColumn(&quot;city&quot;);<br>    }<br>}</pre><p>Para materializar esse caminho, utiliza-se uma das APIs controladas pelo próprio FluentMap:</p><pre>var customer = connection.QueryMappedSingle&lt;Customer&gt;(<br>    &quot;SELECT &#39;Sao Paulo&#39; AS city&quot;);</pre><p>Essa distinção é importante.</p><p>Registrar um mapeamento aninhado não faz com que todas as consultas tradicionais do Dapper passem automaticamente a construir objetos complexos. A funcionalidade depende do caminho de materialização apropriado.</p><p>Além dos objetos aninhados, a linha 3.x introduziu mapping profiles, conversores por propriedade e estratégias explícitas de construção com ConstructUsing(...).</p><p>Os profiles permitem representar diferentes formatos de consulta para uma mesma entidade. Os converters tratam transformações específicas entre valores do banco e propriedades do modelo. Já a construção explícita oferece uma alternativa quando a seleção automática de construtores não atende às necessidades da entidade.</p><p>Esses recursos ampliam as possibilidades de modelagem, mas também aumentam as decisões que precisam ser tomadas.</p><p>Um TypeHandler&lt;T&gt; do próprio Dapper, por exemplo, continua sendo uma boa alternativa quando um tipo possui uma representação escalar consistente em toda a aplicação. Não há motivo para substituí-lo por um converter específico se o mecanismo existente já resolve corretamente o problema.</p><p>Essa é uma distinção que procuro preservar: uma funcionalidade nova não torna automaticamente a abordagem anterior inadequada.</p><h3>Configuração global e isolamento: dois modelos de execução</h3><p>Outro ponto relevante da evolução está na forma de configurar o FluentMap.</p><p>Historicamente, FluentMapper.Initialize(...) estabelece uma configuração global. Esse modelo é simples e continua adequado para aplicações com um único conjunto de mapeamentos.</p><p>Entretanto, configurações globais exigem atenção em testes paralelos, aplicações com múltiplos contextos e cenários nos quais uma mesma entidade pode precisar de diferentes definições de mapeamento.</p><p>A linha 3.x acrescentou configuração imutável e instâncias isoladas de FluentMapRuntime:</p><pre>var runtime = new FluentMapConfigurationBuilder()<br>    .AddMap&lt;CustomerMap&gt;()<br>    .Build()<br>    .CreateRuntime();<br><br>var customer = runtime.QueryMappedSingle&lt;Customer&gt;(<br>    connection,<br>    sql);</pre><p>Nesse modelo, a configuração pertence à instância de runtime utilizada na consulta.</p><p>Também foi criado o pacote FluentMap.DependencyInjection, para integração com o contêiner de injeção de dependências do .NET.</p><p>Mas existe um limite importante: o isolamento se aplica às APIs de materialização controladas pelo FluentMap. Consultas tradicionais Dapper.Query&lt;T&gt;() continuam utilizando os mapas globais registrados no Dapper, enquanto a integração Dommel permanece associada à configuração global.</p><p>Portanto, adicionar Dependency Injection não elimina automaticamente o estado global de uma aplicação.</p><p>A escolha entre os modelos depende da necessidade de isolamento. Para uma aplicação simples, manter a configuração tradicional pode ser a solução com menor custo de manutenção. Para cenários com múltiplos mapeamentos independentes, o runtime isolado oferece maior controle.</p><h3>Do runtime ao compilador</h3><p>Uma das mudanças mais interessantes foi a introdução de recursos que atuam durante a compilação.</p><p>O FluentMap passou a disponibilizar dois pacotes adicionais: FluentMap.Analyzers e FluentMap.Generators.</p><p>Os Roslyn Analyzers identificam determinados problemas de configuração antes da execução da aplicação. Isso permite antecipar erros que, de outra maneira, poderiam aparecer somente durante a inicialização ou materialização de uma consulta.</p><p>Os Source Generators oferecem registro gerado de mapeamentos e materializadores para cenários compatíveis.</p><p>A diferença é arquitetural: em vez de depender exclusivamente de mecanismos dinâmicos em tempo de execução, parte do trabalho pode ser transferida para a compilação.</p><p>Esse caminho também abriu espaço para a materialização gerada estrita, que rejeita formatos incompatíveis em vez de recorrer silenciosamente ao materializador baseado em reflexão.</p><p>Há benefícios potenciais para previsibilidade, diagnósticos e redução do uso de reflexão, mas seria precipitado afirmar que a geração de código torna qualquer consulta mais rápida.</p><p>Desempenho depende do formato dos resultados, volume de dados, provedor ADO.NET e características da aplicação. As melhorias precisam ser avaliadas com benchmarks representativos, não presumidas apenas pela existência de código gerado.</p><p>Da mesma forma, embora existam testes específicos para cenários Native AOT, a versão 3.6.0 não declara compatibilidade Native AOT completa. Registro por reflexão e outros caminhos dinâmicos ainda possuem limitações documentadas.</p><h3>Dommel e o significado das operações de persistência</h3><p>A integração com Dommel também evoluiu.</p><p>Na linha histórica, Ignore() podia acabar sendo utilizado como alternativa para evitar a escrita de determinadas propriedades. Entretanto, ignorar uma propriedade no mapeamento não equivale a informar que ela pode ser lida, mas não deve participar de um INSERT ou UPDATE.</p><p>A versão atual distingue essas situações com metadados específicos:</p><pre>Map(x =&gt; x.CreatedAt)<br>    .ToColumn(&quot;created_at&quot;)<br>    .DatabaseDefaultOnInsert();<br><br>Map(x =&gt; x.UpdatedAt)<br>    .ToColumn(&quot;updated_at&quot;)<br>    .ReadOnly();<br><br>Map(x =&gt; x.Total)<br>    .ToColumn(&quot;total&quot;)<br>    .Computed();</pre><p>Agora é possível expressar se uma coluna possui valor padrão no banco, se é computada ou se deve ser excluída de operações de escrita.</p><p>A versão 3.5.0 acrescentou ainda operações InsertMapped* e UpdateMapped*, capazes de aplicar conversores por propriedade durante a persistência.</p><p>Essas operações são opcionais e não alteram automaticamente o comportamento das chamadas tradicionais do Dommel.</p><p>Para quem está migrando, esse é um dos pontos que exigem maior cuidado. Uma consulta de leitura funcionando corretamente não comprova que inserts e updates continuam produzindo os resultados esperados.</p><h3>Compatibilidade precisa ser demonstrada</h3><p>Uma dificuldade recorrente em bibliotecas baseadas em ADO.NET é definir o que significa ser compatível com determinado banco.</p><p>O fato de o Dapper funcionar com um provedor não significa que todos os recursos adicionais de uma biblioteca estejam automaticamente certificados para ele.</p><p>Na versão 3.6.0, o projeto passou a documentar níveis distintos de compatibilidade, apoiados por testes obrigatórios contra bancos reais.</p><p>SQLite, SQL Server, PostgreSQL, MySQL e MariaDB possuem cobertura certificada tanto para o FluentMap Core quanto para a integração Dommel.</p><p>Oracle e Firebird possuem certificação para o Core, mas não para Dommel.</p><p>SQL Server Compact Edition continua tratado como integração legada, sem certificação moderna.</p><p>Essa separação evita transformar uma expectativa de compatibilidade em uma garantia que os testes não demonstram.</p><p>A matriz também define versões específicas dos provedores e dos bancos utilizados na validação. Atualmente, os pacotes mantêm compatibilidade declarada com Dapper a partir da versão 2.1.79 e anterior à 3.0.0. Para Dommel, o intervalo é de 3.5.3 até versões anteriores à 4.0.0.</p><p>Os pacotes distribuídos continuam utilizando .NET Standard 2.0, preservando um conjunto amplo de aplicações consumidoras.</p><p>Além dos testes funcionais, a manutenção passou a incluir verificações de API pública, análise estática, cobertura, artefatos de release e validações automatizadas de compatibilidade.</p><p>Não considero essas atividades secundárias. Em uma biblioteca open source, o processo de publicação e a capacidade de detectar regressões fazem parte da confiabilidade que entregamos aos consumidores.</p><h3>Migrar ou continuar na versão antiga?</h3><p>Para quem utiliza a 2.0.0, a minha recomendação é começar pelo comportamento existente, não pelas funcionalidades novas.</p><p>Primeiro, identifique como os mapeamentos são registrados, quais versões do Dapper e do Dommel estão instaladas e se existem integrações que dependem de comportamentos específicos.</p><p>Depois, atualize os pacotes FluentMap para a mesma versão, compile a aplicação, valide os mapeamentos e execute os testes.</p><p>Se houver Dommel, verifique principalmente operações de escrita, chaves geradas, valores padrão e propriedades ignoradas. Configurações contraditórias antes toleradas também podem passar a produzir erros de validação.</p><p>Outro cuidado está na compatibilidade binária: a integração Dommel possui diferenças em sua superfície pública, e não se deve presumir compatibilidade binária total com a antiga 2.0.0.</p><p>Somente depois dessa validação eu consideraria adotar recursos como runtime isolado, materialização avançada ou Source Generators.</p><p>Uma migração bem-sucedida não precisa utilizar todas as funcionalidades disponíveis. Em muitos casos, a melhor decisão é atualizar a biblioteca mantendo o código de aplicação praticamente inalterado.</p><h3>O que essa retomada representa</h3><p>Entre a 2.0.0 e a 3.6.0, o FluentMap deixou de ser apenas uma biblioteca com manutenção interrompida e passou a contar novamente com evolução funcional, documentação, testes de compatibilidade e um processo de releases.</p><p>Mas o aspecto que considero mais importante não é o número de recursos adicionados.</p><p>É a possibilidade de continuar utilizando uma abstração conhecida, sem exigir que aplicações existentes mudem sua maneira de trabalhar, enquanto novos projetos podem optar por mecanismos mais adequados às suas necessidades.</p><p>Manter software open source exige equilibrar duas responsabilidades que frequentemente entram em conflito: preservar o que os consumidores já utilizam e permitir que o projeto continue evoluindo.</p><p>No FluentMap, a abordagem adotada foi manter a API histórica como caminho de compatibilidade e introduzir novos comportamentos de maneira predominantemente opcional.</p><p>Ainda existem limitações, especialmente no isolamento de integrações globais e na cobertura de cenários Native AOT. Elas fazem parte do contrato atual e precisam permanecer explícitas.</p><p>Para mim, esse é um dos critérios mais importantes na evolução de uma biblioteca: não apenas oferecer mais possibilidades, mas permitir que quem depende dela compreenda seus contratos, seus limites e as consequências de cada escolha.</p><p>O FluentMap está novamente em desenvolvimento ativo. E, para quem utiliza Dapper, a versão 3.6.0 oferece novas alternativas sem exigir que aquilo que já funciona seja reescrito.</p><h3>Referências</h3><ul><li><a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap">Dapper FluentMap: repositório oficial</a></li><li><a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/compare/v2.0.0...v3.6.0">Comparativo de código entre as versões 2.0.0 e 3.6.0</a></li><li><a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/releases/tag/v2.0.0">Release 2.0.0</a></li><li><a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/releases/tag/v3.6.0">Release 3.6.0</a></li><li><a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/blob/v3.6.0/MIGRATION.md">Guia de migração da versão 2.x para 3.x</a></li><li><a href="https://github.com/rodri-oliveira-dev/Dapper-FluentMap/blob/v3.6.0/COMPATIBILITY.md">Matriz de compatibilidade e limitações</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f404a0045367" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Decisões de arquitetura merecem contexto: conheça o ADR Guard para VS Code]]></title>
            <link>https://medium.com/@rodrigodotnet/decis%C3%B5es-de-arquitetura-merecem-contexto-conhe%C3%A7a-o-adr-guard-para-vs-code-91919dbf58fa?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/91919dbf58fa</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[adr]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Tue, 20 Oct 2026 11:33:30 GMT</pubDate>
            <atom:updated>2026-10-20T11:33:30.835Z</atom:updated>
            <content:encoded><![CDATA[<h3>Decisões de arquitetura não deveriam se perder: conheça o ADR Guard para VS Code</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HmLjaSQWYN5UxRuj7Z48Qg.png" /></figure><p>Existe uma pergunta que provavelmente todo desenvolvedor já fez ao trabalhar em um sistema com alguns anos de vida: <strong>“Por que isso foi implementado dessa maneira?”</strong></p><p>Às vezes, a resposta está em uma discussão antiga no GitHub. Em outros casos, em uma conversa no Teams, em uma documentação desatualizada ou, na pior hipótese, na memória de alguém que já não faz parte da equipe.</p><p>O código mostra como uma solução foi implementada, mas raramente explica por que determinada abordagem foi escolhida, quais alternativas foram descartadas ou quais restrições existiam naquele momento.</p><p>Esse é um problema que vai muito além da documentação. Estamos falando da capacidade de uma equipe compreender e evoluir sua própria arquitetura.</p><p>Foi pensando nessa dificuldade que desenvolvi o <strong>ADR Guard</strong>, um projeto open source que busca tornar o registro e a governança das decisões arquiteturais mais acessíveis e consistentes. E, recentemente, essa experiência ganhou uma interface visual integrada ao Visual Studio Code.</p><h3>ADRs: preservar o contexto é tão importante quanto preservar o código</h3><p>Architecture Decision Records, ou simplesmente ADRs, são documentos que registram decisões arquiteturais relevantes de um sistema.</p><p>A proposta é simples: documentar o contexto de uma decisão, a solução escolhida e suas consequências. Dependendo do formato adotado, também podemos registrar alternativas consideradas, critérios de avaliação e justificativas técnicas.</p><p>Imagine uma equipe decidindo substituir a comunicação síncrona entre determinados serviços por eventos assíncronos.</p><p>Daqui a dois anos, alguém poderá questionar essa escolha. Talvez o sistema tenha mudado, talvez a complexidade operacional tenha aumentado ou talvez uma nova tecnologia ofereça alternativas melhores.</p><p>Sem um registro, essa pessoa precisará reconstruir todo o raciocínio original. Com uma ADR, poderá compreender quais problemas motivaram a decisão e avaliar se aquelas condições continuam válidas.</p><p><strong>Uma ADR não existe para impedir que uma decisão seja modificada. Ela existe para permitir que essa mudança aconteça de maneira consciente.</strong></p><p>E existe outro aspecto importante: decisões arquiteturais também são compromissos. Quando escolhemos determinada abordagem, aceitamos seus benefícios, limitações e custos. Registrar essas consequências ajuda a evitar que decisões antigas sejam tratadas como verdades absolutas.</p><h3>O problema não é criar ADRs. É manter a prática funcionando.</h3><p>Embora o conceito seja relativamente simples, sua adoção apresenta dificuldades bastante conhecidas.</p><p>No começo, a equipe cria alguns documentos, estabelece um diretório no repositório e define um template. Tudo funciona bem.</p><p>Com o tempo, entretanto, começam a aparecer inconsistências. Alguns documentos deixam de ter seções importantes, outros utilizam estruturas diferentes e determinados registros permanecem desatualizados mesmo depois de mudanças significativas na arquitetura.</p><p>A documentação continua existindo, mas sua confiabilidade diminui.</p><p>Na minha visão, esse é um dos principais desafios da documentação arquitetural: <strong>transformar uma boa intenção em uma prática que consiga acompanhar a evolução do software.</strong></p><p>Não basta pedir que os desenvolvedores documentem suas decisões. Precisamos reduzir o esforço necessário para criar, consultar, revisar e validar esses registros.</p><p>Foi justamente esse espaço que procurei explorar com o ADR Guard.</p><h3>ADR Guard: aproximando documentação e governança arquitetural</h3><p>O <a href="https://github.com/rodri-oliveira-dev/adr-guard">ADR Guard</a> é uma ferramenta open source construída sobre .NET, projetada para apoiar o ciclo de vida dos Architecture Decision Records.</p><p>A proposta não é substituir o Markdown ou introduzir um repositório proprietário de decisões. Pelo contrário: os documentos permanecem próximos ao código, podendo ser versionados, revisados e acompanhados pelo mesmo fluxo de trabalho utilizado no desenvolvimento.</p><p>A ferramenta oferece recursos para inicialização, criação, validação e organização dos registros, com suporte a formatos como o modelo canônico de ADR e MADR 4.0.</p><p>A validação permite identificar problemas estruturais nos documentos. Além disso, a CLI oferece recursos para verificações incrementais, comparação com baselines e integração com processos automatizados.</p><p>Isso permite evoluir de uma documentação puramente informativa para uma prática com verificações reproduzíveis.</p><p>Naturalmente, há um limite importante: nenhuma ferramenta consegue determinar, apenas pela estrutura de um documento, se uma decisão arquitetural é tecnicamente correta.</p><p>O objetivo é garantir que os registros tenham consistência suficiente para apoiar uma boa discussão técnica, não automatizar o julgamento de arquitetura.</p><h3>Levando os ADRs para dentro do Visual Studio Code</h3><p>Apesar das possibilidades oferecidas pela linha de comando, percebi que havia espaço para facilitar ainda mais a experiência dos desenvolvedores.</p><p>Afinal, se boa parte do trabalho acontece dentro do editor, por que exigir que a consulta e a manutenção das decisões arquiteturais ocorram em um fluxo separado?</p><p>Foi dessa ideia que surgiu o <strong>ADR Guard for VS Code</strong>.</p><p>A extensão utiliza a CLI do ADR Guard como mecanismo responsável pelas operações, mas disponibiliza uma interface visual para as atividades mais comuns.</p><p>O primeiro ganho é a visibilidade.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PdCTjKBcNaPvTKzMiyKfuw.png" /><figcaption><em>Listagem visual de ADRs com informações de identificação, status e ações de navegação.</em></figcaption></figure><p>Em vez de navegar manualmente por vários arquivos Markdown, o desenvolvedor encontra uma listagem organizada das decisões existentes, com informações como identificador, título, status e localização.</p><p>É possível pesquisar, filtrar, ordenar e abrir os documentos diretamente pelo editor. O ADR Explorer também facilita a navegação pelas decisões e seus relacionamentos reconhecidos.</p><p>Parece algo pequeno, mas acredito que existe uma diferença significativa entre uma documentação que precisamos procurar e uma documentação que está acessível no ambiente onde trabalhamos diariamente.</p><h3>Criar uma decisão não deveria exigir decorar um template</h3><p>Outro ponto importante é o processo de criação.</p><p>A extensão oferece formulários visuais que orientam o preenchimento dos campos necessários para registrar uma decisão arquitetural.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hd0EPdrjhq9gI247Rd2ZpQ.png" /><figcaption><em>Criação visual de uma ADR utilizando o template Minimal.</em></figcaption></figure><p>Com o template Minimal, por exemplo, o desenvolvedor pode concentrar-se em três questões fundamentais: qual é o contexto, qual decisão foi tomada e quais são suas consequências.</p><p>Para situações que exigem uma análise mais detalhada, o template Extended oferece campos adicionais, como alternativas consideradas, justificativas, riscos e direcionadores da decisão.</p><p>Também é possível visualizar uma prévia do Markdown antes de criar o arquivo.</p><p>A intenção é reduzir o atrito do processo, sem retirar do desenvolvedor a responsabilidade pelo conteúdo. Afinal, preencher um formulário não substitui a reflexão necessária para tomar uma boa decisão.</p><h3>Edição, validação e feedback no próprio editor</h3><p>A extensão também permite editar ADRs existentes por meio da interface visual, respeitando os formatos suportados e preservando partes do documento que não foram alteradas.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*b0TUvTimd0wjJCCMTmHhuw.png" /><figcaption><em>Edição de uma decisão arquitetural diretamente no VS Code.</em></figcaption></figure><p>Há inclusive proteção contra conflitos de edição: quando um arquivo muda depois de ser carregado, o salvamento é rejeitado para evitar sobrescrever alterações externas inadvertidamente.</p><p>Mas um dos recursos que considero mais importantes é a integração da validação com o painel <strong>Problems</strong> do VS Code.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kpmjJPko2Acjj5fqG7zSwQ.png" /><figcaption><em>Diagnósticos do ADR Guard integrados ao painel Problems do Visual Studio Code.</em></figcaption></figure><p>Quando uma ADR apresenta problemas estruturais, os diagnósticos podem ser apresentados no próprio ambiente de desenvolvimento.</p><p>A validação pode ser executada explicitamente ou, quando configurada, após o salvamento de documentos relevantes.</p><p>Também existem comandos para validar apenas ADRs modificadas em relação a uma referência Git e consultar resultados considerando um baseline existente.</p><p>Isso ajuda a aproximar a governança arquitetural dos ciclos normais de desenvolvimento e revisão de código.</p><p>É importante destacar que essa validação identifica inconsistências documentais. Ela não representa uma aprovação automática do conteúdo arquitetural.</p><h3>A documentação precisa acompanhar a arquitetura, não competir com ela</h3><p>Uma preocupação durante o desenvolvimento da extensão foi evitar que a ferramenta se tornasse mais uma fonte de complexidade.</p><p>Por isso, a CLI continua responsável pelas regras e operações principais, enquanto a extensão se concentra na experiência de utilização.</p><p>Essa separação permite utilizar o ADR Guard em diferentes contextos, incluindo terminal, editor e pipelines de CI/CD, sem depender de implementações independentes das mesmas regras.</p><p>Também preserva uma característica que considero essencial: operações que modificam arquivos precisam ser explícitas e previsíveis.</p><p>A extensão não deve surpreender o desenvolvedor alterando suas decisões em segundo plano.</p><h3>Um convite para repensar como documentamos arquitetura</h3><p>Não acredito que toda decisão de implementação precise de uma ADR. Isso criaria burocracia e provavelmente afastaria as equipes da prática.</p><p>Mas decisões que afetam a estrutura do sistema, introduzem dependências importantes, estabelecem restrições ou representam compromissos técnicos de longo prazo merecem ter seu contexto preservado.</p><p>O verdadeiro valor de uma ADR aparece quando alguém consegue compreender uma decisão sem depender das pessoas que participaram da discussão original.</p><p>É essa continuidade que procuro incentivar com o ADR Guard.</p><p>A extensão para VS Code é mais um passo nessa direção: trazer as decisões para perto do desenvolvimento cotidiano e tornar sua consulta, criação e validação parte de um processo natural.</p><p>O projeto continua evoluindo, e contribuições, sugestões e experiências de outras equipes são muito bem-vindas.</p><p>Se você trabalha com arquitetura de software, liderança técnica ou desenvolvimento de sistemas que precisam evoluir ao longo dos anos, convido você a conhecer a ferramenta e compartilhar suas impressões.</p><p><strong>Porque uma boa arquitetura não é construída apenas pelas decisões que tomamos, mas também pela capacidade de compreender por que elas foram tomadas.</strong></p><h3>Conheça o ADR Guard</h3><ul><li><strong>Extensão para VS Code:</strong> <a href="https://marketplace.visualstudio.com/items?itemName=rodrioliveira.adr-guard">Instalar pelo Visual Studio Marketplace</a></li><li><strong>Documentação oficial:</strong> <a href="https://rodri-oliveira-dev.github.io/adr-guard/pt-br/product/vscode-visual-guide/">Guia Visual do ADR Guard para VS Code</a></li><li><strong>Código-fonte:</strong> <a href="https://github.com/rodri-oliveira-dev/adr-guard">ADR Guard no GitHub</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=91919dbf58fa" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[GitHub Dotfiles: versionando e sincronizando seu ambiente de desenvolvimento entre máquinas]]></title>
            <link>https://medium.com/@rodrigodotnet/github-dotfiles-versionando-e-sincronizando-seu-ambiente-de-desenvolvimento-entre-m%C3%A1quinas-5b74f501b20f?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/5b74f501b20f</guid>
            <category><![CDATA[github]]></category>
            <category><![CDATA[portabilidade]]></category>
            <category><![CDATA[automação]]></category>
            <category><![CDATA[dotfiles]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Tue, 13 Oct 2026 10:01:03 GMT</pubDate>
            <atom:updated>2026-10-13T10:01:03.313Z</atom:updated>
            <content:encoded><![CDATA[<h3>Dotfiles: transformando seu ambiente de desenvolvimento em código</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bvnNjibcqtJkzbUDPjkaaA.png" /></figure><p>Quem trabalha com desenvolvimento há algum tempo inevitavelmente começa a personalizar o próprio ambiente. Primeiro aparece um alias para não digitar git status toda hora. Depois outro para dotnet build. Em seguida vem uma configuração de Git, uma função Bash, algum script para descobrir qual SDK um projeto está usando e, quando percebemos, existe uma pequena coleção de arquivos espalhada pelo computador.</p><p>O problema começa quando precisamos trocar de máquina.</p><p>Ou trabalhar em um Codespace.</p><p>Ou reinstalar o sistema.</p><p>Ou simplesmente lembrar, seis meses depois, por que determinada configuração existe.</p><p>É exatamente nesse ponto que entram os <strong>dotfiles</strong>.</p><p>O repositório <a href="https://github.com/rodri-oliveira-dev/dotfiles">rodri-oliveira-dev/dotfiles</a> nasceu dessa ideia, mas acabou seguindo um caminho que considero mais interessante do que simplesmente versionar um .bashrc: tratar o ambiente de desenvolvimento como software.</p><p>E isso muda bastante a forma de pensar sobre dotfiles.</p><h3>Afinal, o que são dotfiles?</h3><p>Em sistemas Unix e Linux, arquivos cujo nome começa com ponto normalmente são utilizados para armazenar configurações. .bashrc, .gitconfig, .editorconfig e .profile são exemplos conhecidos.</p><p>Daí vem o nome <strong>dotfiles</strong>: literalmente, “arquivos com ponto”.</p><p>Quando alguém cria um repositório de dotfiles, normalmente está centralizando essas configurações em um lugar versionado. Em vez de manter ajustes importantes presos a uma única máquina, eles passam a fazer parte de um repositório Git.</p><p>Na prática, isso transforma algo que normalmente seria artesanal em algo reproduzível.</p><p>A pergunta deixa de ser:</p><blockquote><em>“Como estava configurado meu computador antigo?”</em></blockquote><p>e passa a ser:</p><blockquote><em>“Como instalo novamente meu ambiente?”</em></blockquote><p>Essa diferença parece pequena, mas é enorme.</p><h3>O objetivo não é configurar tudo</h3><p>Uma decisão importante nesse projeto foi evitar transformar os dotfiles em um instalador universal da máquina.</p><p>O repositório não tenta instalar cada SDK, extensão, ferramenta ou dependência utilizada em todos os projetos. Ele se concentra em fornecer uma <strong>camada pessoal de produtividade sobre o ambiente de desenvolvimento</strong>.</p><p>Isso aparece claramente na maneira como o .NET é tratado.</p><p>O SDK necessário para um projeto continua sendo responsabilidade do próprio projeto, por meio de global.json. Ferramentas .NET utilizadas pelo projeto continuam em .config/dotnet-tools.json. Extensões específicas do VS Code continuam pertencendo ao .vscode/extensions.json.</p><p>Esse isolamento é saudável.</p><p>Meu ambiente pessoal sabe <strong>como trabalhar com um repositório .NET</strong>, mas não tenta decidir <strong>qual versão do .NET cada repositório deve utilizar</strong>.</p><p>Essa fronteira evita que os dotfiles se tornem uma coleção de dependências globais difíceis de manter.</p><h3>Instalar precisa ser previsível</h3><p>O coração do projeto é o install.sh.</p><p>Ao executá-lo, as configurações gerenciadas pelo repositório são integradas ao ambiente do usuário. Os arquivos de shell ficam disponíveis através de links simbólicos, os executáveis em bin passam a ser acessíveis por ~/.local/bin e uma pequena seção controlada é adicionada ao .bashrc.</p><p>A palavra importante aqui é <strong>controlada</strong>.</p><p>O instalador não assume que pode destruir ou sobrescrever qualquer coisa que encontrar. Antes de alterar arquivos, ele verifica se os caminhos existentes realmente pertencem aos dotfiles. Se encontrar algo inesperado, prefere parar a instalação a substituir silenciosamente uma configuração do usuário.</p><p>Também existe uma preocupação explícita com idempotência.</p><p>Executar o instalador novamente não deveria adicionar o mesmo bloco dez vezes ao .bashrc ou recriar configurações de forma inconsistente.</p><p>Isso aproxima o projeto muito mais de uma pequena ferramenta de provisionamento do que de um simples conjunto de scripts copiados para $HOME.</p><p>E essa é, para mim, uma das características mais interessantes de um bom repositório de dotfiles: você precisa confiar nele o suficiente para executá-lo novamente.</p><h3>Pequenos atalhos ainda têm muito valor</h3><p>Claro que existem aliases.</p><p>Comandos como:</p><pre>gs<br>gd<br>gl<br>db<br>dt<br>dr</pre><p>representam operações frequentes de Git e .NET.</p><p>Individualmente, economizar alguns caracteres parece irrelevante. Mas o objetivo não é apenas digitar menos. É diminuir atrito em comandos utilizados dezenas de vezes durante o dia.</p><p>O importante é não exagerar.</p><p>Um alias como db para dotnet build continua sendo fácil de lembrar e não esconde comportamento inesperado. Quando a operação começa a exigir lógica, validação ou descoberta de contexto, o projeto utiliza helpers propriamente ditos.</p><p>Essa distinção entre <strong>alias</strong> e <strong>ferramenta</strong> mantém o ambiente relativamente simples.</p><h3>Helpers que entendem repositórios .NET</h3><p>Aqui o projeto começa a ficar mais interessante para quem trabalha diariamente com .NET.</p><p>Imagine entrar em um repositório que você não acessa há algum tempo.</p><p>Você pode executar:</p><pre>dotnet-context</pre><p>e obter rapidamente informações sobre o SDK resolvido, presença de global.json, Directory.Build.props, Central Package Management, ferramentas locais e solutions existentes.</p><p>Para uma inspeção mais completa existe:</p><pre>dotnet-repo-doctor</pre><p>A intenção é responder rapidamente perguntas que normalmente exigiriam abrir diversos arquivos: qual SDK foi solicitado? Qual SDK está sendo efetivamente utilizado? Quantos projetos existem? Há projetos de teste? Quais target frameworks aparecem? O repositório usa Central Package Management?</p><p>Existe inclusive saída JSON, tornando o comando útil tanto para humanos quanto para automações.</p><p>Essa é uma ideia que gosto bastante: <strong>transformar conhecimento operacional recorrente em comandos reutilizáveis</strong>.</p><p>Em vez de lembrar novamente onde procurar determinada informação, o ambiente passa a conhecer esse procedimento.</p><h3>Um preflight antes de enviar código</h3><p>Outro exemplo é o dotnet-verify.</p><p>A proposta é simples: executar localmente uma sequência próxima daquilo que esperamos antes de considerar uma alteração pronta.</p><p>Por padrão ele pode restaurar ferramentas locais, restaurar dependências, compilar, verificar formatação e executar testes.</p><p>Então, antes de um push ou pull request, posso usar:</p><pre>dotnet-verify</pre><p>Há também um modo mais rápido:</p><pre>dotnet-verify --quick</pre><p>O interessante aqui não é substituir a pipeline.</p><p>CI continua sendo CI.</p><p>A função desse comando é reduzir o clássico ciclo:</p><p>“push → pipeline quebra → corrige → novo push → pipeline quebra novamente”.</p><p>Quando uma verificação é barata o suficiente para executar localmente, vale a pena aproximá-la do desenvolvedor.</p><h3>Git também faz parte do ambiente</h3><p>Os dotfiles incluem ainda algumas preferências globais de Git.</p><p>Por exemplo, novos repositórios usam main como branch padrão, fetch remove referências remotas que deixaram de existir e push.autoSetupRemote simplifica o primeiro push de uma branch.</p><p>Também está habilitado o rerere.</p><p>Essa é uma configuração pouco comentada, mas bastante útil: o Git pode reutilizar resoluções de conflitos que você já realizou anteriormente.</p><p>A configuração de diff utiliza o algoritmo histogram, e branches e tags recebem ordenações mais convenientes para uso cotidiano.</p><p>Nenhuma dessas opções muda radicalmente o Git.</p><p>Esse é justamente o ponto.</p><p>Um bom dotfile tende a eliminar pequenas fricções repetidas, não reinventar a ferramenta.</p><h3>Se existe instalação, deveria existir diagnóstico</h3><p>Um dos comandos que considero conceitualmente mais importantes no projeto é:</p><pre>dotfiles-doctor</pre><p>Ele verifica se o ambiente continua configurado da maneira esperada.</p><p>O Bash está disponível? O Git está acessível? Os links simbólicos continuam corretos? O bloco esperado existe no .bashrc? ~/.local/bin está no PATH? A configuração do Git continua referenciando o arquivo correto?</p><p>É o equivalente ao conhecido padrão de comandos doctor encontrado em diversas ferramentas.</p><p>Isso é especialmente útil porque ambientes de desenvolvimento sofrem alterações constantemente. Atualizações, instalações e mudanças manuais podem quebrar premissas que eram verdadeiras meses atrás.</p><p>Em vez de investigar tudo manualmente, existe um diagnóstico reproduzível.</p><h3>E desinstalar também faz parte do design</h3><p>Existe ainda um uninstall.sh.</p><p>Pode parecer um detalhe, mas considero isso um ótimo teste para qualquer automação de ambiente.</p><p>Se não sabemos exatamente como remover aquilo que instalamos, provavelmente também não temos uma definição muito clara do que estamos gerenciando.</p><p>O desinstalador remove somente os elementos reconhecidos como pertencentes ao projeto. Configurações desconhecidas ou arquivos que não correspondam aos links esperados são preservados.</p><p>Esse comportamento conservador é proposital.</p><p>Dotfiles mexem em arquivos pessoais do desenvolvedor. Nesse contexto, falhar por excesso de cuidado costuma ser melhor do que apagar algo por excesso de confiança.</p><h3>Dotfiles também podem ter engenharia de software</h3><p>Talvez a parte menos óbvia do repositório esteja na infraestrutura em volta dos scripts.</p><p>Eles possuem testes automatizados com <strong>Bats</strong>, análise estática com <strong>ShellCheck</strong>, validação de formatação com <strong>shfmt</strong> e testes do ciclo completo de instalação dentro de um container limpo.</p><p>A pipeline também executa verificações de segurança, incluindo ferramentas como Gitleaks, actionlint, zizmor e Hadolint.</p><p>Até o contexto utilizado pelo Docker possui verificações para evitar que arquivos locais inesperados acabem sendo incluídos na imagem de teste.</p><p>Pode parecer muito esforço para “alguns scripts Bash”.</p><p>Mas existe uma razão.</p><p>O install.sh altera o ambiente do usuário. O uninstall.sh remove configurações. O mecanismo de atualização baixa alterações e as aplica posteriormente.</p><p>Quanto maior o poder de uma automação, maior deveria ser nossa preocupação em verificar seu comportamento.</p><h3>Atualizar sem simplesmente executar qualquer coisa</h3><p>O projeto também possui um dotfiles-update.</p><p>Ele não funciona como um simples git pull &amp;&amp; ./install.sh.</p><p>Antes de aplicar uma atualização, verifica condições como branch atual, alterações locais, upstream configurado e origem do repositório. A atualização precisa ser um fast-forward válido e alguns arquivos importantes da revisão recebida também são verificados antes da execução.</p><p>Depois da atualização, o instalador é executado novamente e o dotfiles-doctor valida o resultado.</p><p>Isso fecha um ciclo interessante:</p><p><strong>instalar → usar → atualizar → diagnosticar → remover.</strong></p><p>Quando todas essas etapas são consideradas, os dotfiles deixam de ser apenas armazenamento de configuração e passam a representar o <strong>ciclo de vida do ambiente pessoal de desenvolvimento</strong>.</p><h3>Mais do que copiar configurações</h3><p>Provavelmente essa é a principal ideia que eu gostaria de deixar.</p><p>Um repositório de dotfiles não precisa começar sofisticado.</p><p>Você pode começar apenas com seu .gitconfig e alguns aliases.</p><p>Mas, conforme o ambiente cresce, vale perceber que o ativo mais importante não são necessariamente os arquivos.</p><p>É o conhecimento que existe por trás deles.</p><p>Como descubro rapidamente o contexto de um projeto .NET?</p><p>Como verifico meu ambiente antes de enviar uma alteração?</p><p>Quais padrões de Git prefiro utilizar?</p><p>Como reproduzo essas escolhas em uma máquina nova?</p><p>Como sei que minha configuração não está quebrada?</p><p>Quando essas respostas estão codificadas e versionadas, trocar de máquina deixa de significar reconstruir anos de pequenos ajustes a partir da memória.</p><p>E talvez essa seja a melhor definição de dotfiles que encontrei durante esse processo:</p><p><strong>não é um backup da sua configuração; é uma descrição executável de como você gosta de trabalhar.</strong></p><h3>Concluindo</h3><p>O projeto <strong>dotfiles</strong> centraliza e versiona uma camada pessoal de desenvolvimento focada principalmente em <strong>Bash, Git e .NET</strong>, com atenção especial ao uso em ambientes Linux e GitHub Codespaces.</p><p>Além de aliases e configurações, ele oferece instalação idempotente, atualização controlada, diagnóstico do ambiente, desinstalação segura e helpers que entendem o contexto de repositórios .NET.</p><p>Mais importante, o projeto aplica aos próprios dotfiles práticas normalmente associadas a software de produção: testes automatizados, análise estática, CI, validações de segurança e preocupação com ciclo de vida.</p><p>No fim, a ideia é bastante simples: <strong>se o ambiente de desenvolvimento é uma ferramenta importante para o nosso trabalho, faz sentido tratá-lo como código.</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5b74f501b20f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[O que acontece depois do commit? Arquitetura event-driven com .NET e Kafka]]></title>
            <link>https://medium.com/@rodrigodotnet/o-que-acontece-depois-do-commit-arquitetura-event-driven-com-net-e-kafka-62b69e4a6106?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/62b69e4a6106</guid>
            <category><![CDATA[apache-kafka]]></category>
            <category><![CDATA[event-driven-architecture]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[microservices]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Tue, 06 Oct 2026 11:22:27 GMT</pubDate>
            <atom:updated>2026-10-06T11:22:27.779Z</atom:updated>
            <content:encoded><![CDATA[<h3>Construindo fluxos event-driven confiáveis com .NET e Kafka</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*I0FMgIEuQMmzZKUeR1jqkQ.png" /></figure><p>Salvar um registro no banco de dados é fácil.</p><p>Ou, pelo menos, é uma parte do desenvolvimento para a qual temos ferramentas bastante maduras. Abrimos uma transação, alteramos o estado necessário e fazemos o commit. Se alguma coisa der errado antes disso, fazemos rollback.</p><p>A situação fica mais interessante quando o commit não é o fim da operação.</p><p>Imagine um lançamento financeiro. Depois de persistido, outro serviço precisa conhecer esse lançamento para atualizar uma projeção de saldo. Talvez outros consumidores também precisem reagir a ele no futuro.</p><p>A primeira implementação que vem à cabeça parece perfeitamente razoável:</p><pre>salvar no banco<br>publicar evento</pre><p>Só que existe uma pergunta incômoda entre essas duas linhas:</p><p><strong>e se o banco confirmar a transação e o broker estiver indisponível logo depois?</strong></p><p>O lançamento existirá, mas ninguém receberá o evento.</p><p>Foi esse tipo de problema que quis explorar no poc-arquitetura, um laboratório que venho usando para estudar arquitetura com código executável. Ele usa .NET, PostgreSQL e Kafka, entre outras tecnologias, mas a intenção nunca foi simplesmente reunir patterns conhecidos dentro de um repositório.</p><p>O que me interessa é observar o que acontece quando esses patterns precisam conviver.</p><p>Outbox resolve um problema e cria outras responsabilidades. At-least-once delivery nos obriga a pensar em idempotência. Consistência eventual muda a forma de consultar o estado. Uma Saga exige compensação. Retry exige limites. Mensageria exige observabilidade além do HTTP.</p><p>No fim, a pergunta inicial — <strong>o que acontece depois do commit?</strong> — acaba abrindo boa parte da discussão sobre sistemas distribuídos.</p><h3>Primeiro, vamos separar fato de projeção</h3><p>No exemplo que uso no projeto, existem dois bounded contexts importantes para essa história.</p><p>O LedgerService é responsável pelos fatos financeiros. Quando um lançamento acontece, é ali que ele deve ser registrado.</p><p>O BalanceService possui outra responsabilidade: manter uma projeção adequada para consultas de saldo.</p><p>Simplificando bastante a arquitetura:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JRES9GogAZuSaojuFSvQ7Q.png" /></figure><p>Essa separação é importante porque um saldo é diferente de um lançamento.</p><p>O lançamento representa algo que aconteceu.</p><p>O saldo é uma visão construída a partir desses acontecimentos.</p><p>Poderíamos manter tudo no mesmo modelo e no mesmo banco? Claro. Dependendo do sistema, provavelmente seria até a melhor escolha.</p><p>Mas o laboratório parte justamente da hipótese de que queremos separar essas responsabilidades para estudar as consequências da decisão.</p><p>Uma delas aparece imediatamente: o saldo deixa de estar sincronizado com o Ledger dentro da mesma transação.</p><p>Entramos no mundo da <strong>consistência eventual</strong>.</p><p>Isso não quer dizer que o sistema seja inconsistente no sentido de estar errado. Significa que existe uma janela na qual o fato já foi registrado no Ledger, mas a projeção ainda não recebeu esse fato.</p><p>A arquitetura precisa assumir essa janela como parte normal do funcionamento.</p><h3>O problema não é Kafka. É o dual write</h3><p>Suponha que o Ledger faça isto:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GxqK81tmnM-aDXxwjwg6Cw.png" /></figure><p>No happy path, parece perfeito.</p><p>Agora retire a última resposta do Kafka.</p><p>O banco já confirmou a transação. Não há mais rollback possível daquele lançamento.</p><p>Se o processo morrer antes que o evento seja publicado, temos duas representações do sistema contando histórias diferentes: o Ledger sabe que o lançamento aconteceu; o Balance nunca ficou sabendo.</p><p>Publicar primeiro e salvar depois apenas inverte o problema. Nesse cenário, poderíamos produzir um evento sobre uma transação que posteriormente falhou.</p><p>Isso é o <strong>dual-write problem</strong>: precisamos alterar dois recursos independentes e gostaríamos que ambos se comportassem como se participassem da mesma transação.</p><p>Uma possibilidade seria introduzir uma transação distribuída. Para esse cenário, preferi outra abordagem: aceitar que banco e broker têm ciclos de vida independentes e tornar a intenção de publicação durável.</p><p>É aí que entra o Transactional Outbox.</p><h3>Outbox: não publique agora, registre que precisa publicar</h3><p>Em vez de salvar o lançamento e imediatamente depender do Kafka, o Ledger persiste o lançamento e uma mensagem de Outbox dentro da <strong>mesma transação PostgreSQL</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ur9eD6nxnxYISrmigsuATQ.png" /></figure><p>Essa mudança parece pequena, mas altera bastante as garantias do sistema.</p><p>Se o Kafka estiver fora do ar, o lançamento continua existindo <strong>junto com a informação de que existe algo esperando para ser publicado</strong>.</p><p>Se o worker cair, outro ciclo pode continuar o processamento.</p><p>A falha deixa de ser uma janela perdida entre duas operações e passa a ser um estado que podemos observar e recuperar.</p><p>Isso, para mim, é a parte mais interessante do Outbox.</p><p>Ele não torna Kafka e PostgreSQL uma única transação. Também não garante magicamente exactly-once processing.</p><p>Ele simplesmente transforma uma falha difícil de recuperar em uma falha explicitamente representada.</p><p>E sistemas recuperáveis costumam ser bem mais interessantes do que sistemas que fingem que não falham.</p><h3>Resolver a perda da mensagem cria o problema da duplicação</h3><p>Agora aparece outra consequência.</p><p>Imagine que o worker publique uma mensagem no Kafka com sucesso, mas caia antes de marcar a Outbox como processada.</p><p>Quando voltar, aquela mensagem poderá ser publicada novamente.</p><p>Isso não é necessariamente um bug.</p><p>É uma consequência normal de um modelo de entrega <strong>at-least-once</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*K3G25ftDVo5Nsr5nkVk9SQ.png" /></figure><p>A responsabilidade agora muda para o consumidor.</p><p>No BalanceService, eventos processados são identificados para que a mesma mensagem não seja aplicada duas vezes à projeção.</p><p>É a idempotência entrando na conversa.</p><p>Esse é um ponto que considero importante porque, às vezes, retry é tratado como uma configuração genérica de resiliência: coloca-se uma política, três tentativas, exponential backoff e pronto.</p><p>Mas retry é uma decisão de negócio também.</p><p>Se repetir uma operação duas vezes produz dois efeitos diferentes, então retry pode causar mais problemas do que a falha original.</p><p>Antes de perguntar <em>“quantas vezes devemos tentar novamente?”</em>, vale perguntar:</p><p><strong>“o que acontece se executarmos isto novamente?”</strong></p><h3>Consistência eventual precisa aparecer no desenho</h3><p>Ao separar Ledger e Balance, estamos aceitando que por algum período teremos algo semelhante a:</p><pre>Ledger: lançamento existe<br>Balance: lançamento ainda não foi projetado</pre><p>Isso é esperado.</p><p>O erro seria projetar a arquitetura de maneira assíncrona e depois escrever o restante da aplicação como se todas as leituras fossem imediatamente consistentes.</p><p>Há várias maneiras de tratar essa diferença, dependendo do negócio: indicar processamento pendente, consultar a fonte de verdade em operações específicas, trabalhar com estados intermediários ou simplesmente aceitar um pequeno atraso de atualização.</p><p>Não existe uma resposta universal.</p><p>O importante é que eventual consistency não seja apenas uma consequência acidental de usar Kafka. Ela deve ser uma decisão conhecida.</p><h3>Contratos de eventos também são APIs</h3><p>Depois que começamos a depender de eventos, surge outro problema inevitável: eles mudam.</p><p>No laboratório existe evolução, por exemplo, de LedgerEntryCreated.v1 para LedgerEntryCreated.v2.</p><p>Durante a transição, consumidores podem precisar compreender ambas.</p><p>Isso nos força a tratar eventos como contratos de integração de verdade.</p><p>Uma API HTTP possui OpenAPI, versionamento, breaking changes e clientes dependentes. Um evento merece praticamente o mesmo cuidado — talvez até mais.</p><p>Um endpoint normalmente responde a uma requisição presente.</p><p>Uma mensagem pode permanecer em um tópico, uma DLQ ou um mecanismo de replay por muito mais tempo do que a versão da aplicação que originalmente a publicou.</p><p>Por isso, schema, compatibilidade e versionamento são partes importantes do desenho.</p><p>Outro detalhe é a ordenação.</p><p>Kafka preserva ordenação dentro de uma partição, não uma ordem global de todo o sistema. A escolha da message key influencia quais eventos precisam caminhar juntos e qual paralelismo o sistema consegue explorar.</p><p>Até coisas aparentemente pequenas, como escolher a chave da mensagem, acabam carregando decisões arquiteturais.</p><h3>Retry não resolve tudo: em algum momento precisamos desistir</h3><p>Algumas falhas são temporárias.</p><p>O broker pode ficar indisponível. Uma conexão pode sofrer timeout. Uma dependência pode demorar mais que o esperado.</p><p>Nesses casos, retry com backoff faz sentido.</p><p>Mas um payload estruturalmente inválido continuará inválido daqui a dez segundos.</p><p>Um contrato incompatível não ficará magicamente compatível na tentativa número 47.</p><p>Repetir indefinidamente só transforma uma mensagem problemática em consumo constante de CPU, logs e atenção operacional.</p><p>É aí que entra a DLQ, ou Dead Letter Queue.</p><p>O objetivo não deveria ser simplesmente “tirar a mensagem do caminho”. Uma DLQ precisa preservar contexto suficiente para investigação e recuperação: payload original, tipo do evento, causa da falha, origem e informações de correlação.</p><p>Depois vem a parte frequentemente esquecida: <strong>o que faremos com essa mensagem?</strong></p><p>No projeto, essa preocupação aparece junto com conceitos de requeue, replay e reconstrução de projeções.</p><p>Essa experiência reforçou uma ideia que gosto bastante:</p><p><strong>DLQ sem estratégia de recuperação é só um arquivo morto distribuído.</strong></p><p>A arquitetura de processamento precisa ser acompanhada pela arquitetura de recuperação.</p><h3>Uma transferência deixa o problema ainda mais interessante</h3><p>Atualizar uma projeção é relativamente simples quando comparado com uma operação distribuída que produz múltiplos efeitos.</p><p>Pense em uma transferência.</p><p>Precisamos debitar uma origem e creditar um destino.</p><p>Se ambos acontecessem dentro de uma única transação local, o banco cuidaria de muita coisa para nós.</p><p>Quando dividimos a operação em componentes independentes, essa garantia desaparece.</p><p>No laboratório, o TransferService modela a operação como uma Saga.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QLJeLyEY6p1tksqeZGeW2w.png" /></figure><p>Esse fluxo deixa algo explícito que às vezes fica escondido quando falamos de microservices: distribuir uma operação também distribui suas falhas.</p><p>Se o débito foi concluído, mas o crédito falhou, não temos um ROLLBACK global que volte o tempo.</p><p>Precisamos decidir o que significa compensar aquela operação.</p><p>A compensação também não é necessariamente a remoção do fato original. Em um domínio financeiro, normalmente faz mais sentido registrar um novo fato que neutralize o anterior, preservando a trilha do que aconteceu.</p><p>A Saga não recria ACID entre serviços.</p><p>Ela modela explicitamente aquilo que perdemos ao sair da transação local.</p><h3>Circuit breaker é sobre controlar a falha, não escondê-la</h3><p>Outro cenário do laboratório derruba deliberadamente o LedgerService enquanto o worker de transferência continua funcionando.</p><p>Sem proteção, podemos criar uma tempestade de chamadas contra uma dependência que já sabemos estar indisponível.</p><p>Retry sozinho inclusive pode piorar esse comportamento.</p><p>O circuit breaker tenta interromper temporariamente esse ciclo.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uqgCv3cCfzHZhWhA9xxBCQ.png" /></figure><p>O estado Open não quer dizer que o sistema foi “curado”.</p><p>Quer dizer exatamente o contrário: reconhecemos que existe uma falha e decidimos parar de desperdiçar recursos insistindo nela durante algum tempo.</p><p>Depois, em HalfOpen, permitimos uma tentativa controlada para verificar se a dependência se recuperou.</p><p>É uma distinção que gosto de fazer:</p><p><strong>resiliência não é fazer parecer que nada falhou.</strong></p><p>Resiliência é fazer o sistema se comportar de maneira previsível quando alguma coisa falha.</p><h3>Observabilidade começa a ficar séria quando deixamos o HTTP</h3><p>Em uma aplicação simples, seguir um request pelos logs não costuma ser muito difícil.</p><p>Em um fluxo assíncrono, aquela mesma operação pode atravessar vários processos:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FCYsSBDG1syehMZA_MFBeQ.png" /></figure><p>Se cada trecho produzir apenas logs independentes, investigar um problema vira uma espécie de arqueologia por timestamp.</p><p>Por isso o projeto propaga correlation_id e, quando OpenTelemetry está habilitado, contexto W3C como traceparent e tracestate através da Outbox e das mensagens.</p><p>A stack local permite observar traces, métricas e logs com OpenTelemetry, Jaeger, Prometheus, Grafana e Loki.</p><p>Mas a parte mais importante não são as ferramentas.</p><p>São as perguntas que passamos a conseguir responder.</p><p>A API está respondendo, mas a Outbox está acumulando?</p><p>O producer está falhando?</p><p>O consumidor está ficando para trás?</p><p>A quantidade de duplicatas aumentou?</p><p>A DLQ começou a crescer?</p><p>Qual request HTTP originou o evento que falhou minutos depois em outro processo?</p><p>Em arquiteturas assíncronas, health check sozinho conta uma parte muito pequena da história.</p><h3>Testar métodos é pouco quando o risco está no fluxo</h3><p>Uma arquitetura desse tipo pode ter excelente cobertura unitária e ainda falhar justamente nas fronteiras entre componentes.</p><p>Por isso o laboratório também possui testes de integração e cenários com k6 que exercitam coisas como Ledger → Outbox → Kafka → Balance, transferências completas e comportamento durante a indisponibilidade do Ledger.</p><p>Existe uma preocupação importante aqui: não confundir esses testes com prova de escala produtiva.</p><p>Os thresholds atuais são guardrails para um ambiente local controlado. Eles ajudam a detectar regressões e validar o comportamento arquitetural, mas não são SLOs de produção.</p><p>Dizer que um teste local executou determinada quantidade de requests por segundo não significa que descobrimos a capacidade de um sistema financeiro em produção.</p><p>Capacidade depende da infraestrutura, topologia, número de partitions, banco, rede, autoscaling, comportamento real da carga e várias outras condições.</p><p>Ainda assim, testar o fluxo completo é extremamente útil.</p><p>Às vezes, o melhor teste arquitetural não é aquele que verifica se determinada classe foi chamada.</p><p>É aquele em que deliberadamente desligamos uma dependência e observamos o que o sistema faz.</p><h3>O laboratório não é uma arquitetura de produção</h3><p>Faço questão de deixar isso explícito porque projetos demonstrativos podem facilmente cair na armadilha de parecer uma arquitetura de referência universal.</p><p>O poc-arquitetura não é uma plataforma bancária pronta para produção.</p><p>Ele é um ambiente para experimentar decisões.</p><p>Uma implantação real ainda teria preocupações como secret management produtivo, identidade de workload, estratégia de alta disponibilidade, capacidade e replicação do Kafka, disaster recovery, políticas de segurança de borda, infraestrutura distribuída, SLOs reais e muitas outras decisões específicas do contexto.</p><p>E talvez esse seja outro aprendizado importante.</p><p>Arquitetura não é encontrar a maior quantidade possível de patterns e colocá-los em um diagrama.</p><p>É escolher mecanismos proporcionais aos problemas que realmente temos.</p><h3>O que ficou de mais importante</h3><p>Se eu tivesse que resumir esta experiência em poucas ideias, começaria por uma que parece simples: <strong>o commit do banco muitas vezes é apenas o começo do fluxo</strong>.</p><p>O Outbox não oferece exatamente uma transação entre PostgreSQL e Kafka; ele torna a intenção de publicação durável. At-least-once delivery implica aceitar duplicações e, portanto, desenhar consumidores idempotentes. Consistência eventual precisa ser assumida pelo negócio, não escondida atrás do broker.</p><p>Retries precisam de operações seguras para repetição. DLQs precisam de procedimentos de recuperação. Sagas tornam estados e compensações explícitos quando uma transação local deixa de existir. Circuit breakers controlam falhas em vez de fingir que elas desapareceram.</p><p>E observabilidade precisa atravessar as mesmas fronteiras que os eventos atravessam.</p><p>Talvez a maior mudança de mentalidade seja esta:</p><p><strong>em sistemas distribuídos, não projetamos apenas o caminho de sucesso. Projetamos também como detectar, entender e recuperar os caminhos de falha.</strong></p><h3>Para continuar estudando</h3><p>Se você quiser aprofundar esses assuntos, eu seguiria uma trilha mais ou menos assim, sem tentar aprender todos os patterns de sistemas distribuídos de uma vez.</p><p>Para uma visão geral bastante prática de arquitetura de microservices com .NET, a documentação <strong>“.NET Microservices: Architecture for Containerized .NET Applications”</strong>, da Microsoft, é um bom ponto de partida:</p><p><a href="https://learn.microsoft.com/dotnet/architecture/microservices/">https://learn.microsoft.com/dotnet/architecture/microservices/</a></p><p>Para entender melhor o <strong>Transactional Outbox</strong>, <strong>Saga</strong> e <strong>Idempotent Consumer</strong>, o catálogo de patterns de Chris Richardson é uma referência muito útil:</p><p><a href="https://microservices.io/patterns/">https://microservices.io/patterns/</a></p><p>O livro <em>Microservices Patterns</em>, também de Chris Richardson, entra com mais profundidade nos motivos e trade-offs por trás desses mecanismos.</p><p>Para Kafka, vale ir além de tutoriais de producer e consumer e conhecer suas garantias, partitions, consumer groups e semântica de entrega diretamente na documentação oficial:</p><p><a href="https://kafka.apache.org/documentation/">https://kafka.apache.org/documentation/</a></p><p>Na parte de observabilidade distribuída, a documentação do <strong>OpenTelemetry</strong> ajuda bastante a entender traces, spans, context propagation, métricas e baggage sem ficar preso a uma ferramenta específica:</p><p><a href="https://opentelemetry.io/docs/">https://opentelemetry.io/docs/</a></p><p>Para quem quiser experimentar carga e falhas de forma reproduzível, o <strong>k6</strong> também possui uma documentação bastante didática:</p><p><a href="https://grafana.com/docs/k6/latest/">https://grafana.com/docs/k6/latest/</a></p><p>Eu adicionaria ainda <em>Designing Data-Intensive Applications</em>, de Martin Kleppmann. Não é um livro sobre .NET, Kafka ou microservices especificamente — e talvez exatamente por isso seja tão útil. Ele ajuda a construir o modelo mental por trás de replicação, particionamento, transações, streams e sistemas distribuídos.</p><p>Por fim, se quiser ver essas ideias funcionando juntas em código, ADRs, contratos de eventos, testes e cenários de falha, o laboratório que originou este artigo está disponível em:</p><p><a href="https://github.com/rodri-oliveira-dev/poc-arquitetura">https://github.com/rodri-oliveira-dev/poc-arquitetura</a></p><p>Ainda há bastante coisa que quero experimentar nele. E essa talvez seja justamente a parte divertida: quanto mais começamos a tratar falhas como parte normal da arquitetura, mais perguntas interessantes aparecem.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=62b69e4a6106" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Um repositório .github como camada central de governança e automação]]></title>
            <link>https://medium.com/@rodrigodotnet/um-reposit%C3%B3rio-github-como-camada-central-de-governan%C3%A7a-e-automa%C3%A7%C3%A3o-14f478b247a0?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/14f478b247a0</guid>
            <category><![CDATA[github-actions]]></category>
            <category><![CDATA[platform-engineering]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[github]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Mon, 28 Sep 2026 12:01:02 GMT</pubDate>
            <atom:updated>2026-09-28T12:01:02.694Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*y_JOQA0LsKyvGSyk0EXUZw.png" /></figure><p>Como organizei políticas de segurança, workflows reutilizáveis, manutenção de projetos .NET e governança de agentes de IA a partir de um único repositório.</p><p>Projetos mencionados neste artigo:</p><ul><li><a href="https://github.com/rodri-oliveira-dev/.github">.github — Governança e automação de repositórios</a></li><li><a href="https://github.com/rodri-oliveira-dev/DotNetRepoInspector">DotNetRepoInspector — Inspeção e inventário de projetos .NET</a></li></ul><h3>O problema de manter vários repositórios</h3><p>Quando mantemos um ou dois repositórios, repetir algumas configurações não parece um problema. Um CONTRIBUTING.md aqui, um template de Pull Request ali, algumas regras de segurança e um workflow de GitHub Actions. Tudo funciona e seguimos desenvolvendo.</p><p>O problema começa a aparecer conforme a quantidade de projetos aumenta.</p><p>Uma correção feita em um repositório não chega aos demais. Um workflow evolui, mas outros projetos continuam utilizando versões antigas. As regras de contribuição deixam de ser consistentes e políticas de segurança começam a divergir.</p><p>Esse fenômeno é conhecido como configuration drift, ou desvio de configuração.</p><p>Foi a partir desse problema que comecei a evoluir meu repositório .github, transformando-o em uma camada central de governança e automação para os demais projetos que mantenho no GitHub.</p><p>A ideia não é colocar todas as configurações em um único lugar nem retirar a autonomia de cada projeto. É estabelecer uma base compartilhada, reduzir duplicações e automatizar tarefas recorrentes, preservando as particularidades de cada repositório.</p><p>Neste artigo, compartilho como essa estrutura funciona, o que implementei e as principais decisões arquiteturais envolvidas.</p><h3>O que há de especial em um repositório .github?</h3><p>O GitHub oferece um comportamento específico para repositórios públicos chamados .github.</p><p>Neles podemos definir determinados arquivos de community health, ou arquivos de saúde da comunidade, que funcionam como configurações padrão para outros repositórios públicos da mesma conta.</p><p>Isso permite centralizar arquivos como CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, templates de issues e templates de Pull Request.</p><p>Quando um projeto não possui sua própria versão de um arquivo suportado, o GitHub pode utilizar a versão definida no repositório .github.</p><p>O detalhe mais interessante desse mecanismo é a precedência das configurações locais.</p><p>Se um projeto precisa de uma política de segurança específica, ele pode manter seu próprio SECURITY.md. Se outro precisa de um template de Pull Request diferente, também pode definir sua própria versão.</p><p>Isso nos permite trabalhar com um modelo simples: um padrão central, com possibilidade de sobrescrita local quando necessário.</p><p>No meu caso, comecei utilizando esse comportamento para estabelecer uma base consistente de contribuição, segurança e suporte.</p><p>Entretanto, conforme os repositórios evoluíram, percebi que outras responsabilidades compartilhadas poderiam ser coordenadas a partir do mesmo lugar.</p><h3>De arquivos compartilhados para uma camada de governança</h3><p>Manter vários projetos envolve mais do que organizar documentação.</p><p>Existem atualizações de dependências, versões de SDKs, políticas de segurança, validações de pipelines e tarefas de manutenção que se repetem constantemente.</p><p>Com o tempo, passei a utilizar o .github como ponto de coordenação dessas responsabilidades.</p><p>Atualmente, ele reúne arquivos de comunidade, workflows reutilizáveis, automações de manutenção, políticas de segurança, scripts de validação e um registro versionado de instruções e skills para agentes de desenvolvimento.</p><p>Aqui existe uma distinção importante.</p><p>O GitHub não distribui automaticamente todo o conteúdo de um repositório .github para os demais projetos.</p><p>O comportamento de herança automática está limitado aos recursos especificamente suportados pela plataforma.</p><p>Workflows, configurações do Dependabot, scripts e instruções para agentes precisam de mecanismos próprios de reutilização ou distribuição.</p><p>Portanto, a arquitetura que construí combina recursos nativos do GitHub com automações desenvolvidas sobre GitHub Actions e a API do GitHub.</p><h3>Workflows reutilizáveis e políticas centralizadas</h3><p>Uma das primeiras responsabilidades que procurei centralizar foi a implementação de políticas utilizadas em múltiplos pipelines.</p><p>O GitHub Actions permite criar reusable workflows, ou workflows reutilizáveis, que podem ser chamados por outros workflows.</p><p>Imagine que diferentes repositórios precisam executar uma verificação de segurança.</p><p>Em vez de manter cópias independentes da mesma implementação, podemos disponibilizar um workflow reutilizável que cada projeto consumidor chama a partir de seu próprio pipeline.</p><p>Um exemplo conceitual seria:</p><p>YAML</p><pre>jobs:<br>  security:<br>    uses: owner/.github/.github/workflows/reusable-secret-scan.yml@v1</pre><p>O projeto continua responsável por decidir quando executar a análise e como ela se integra ao seu processo de desenvolvimento.</p><p>O repositório central fica responsável pela implementação compartilhada.</p><p>A aplicação continua dona do pipeline; o repositório central passa a ser responsável pela política compartilhada.</p><p>No meu projeto, um dos exemplos dessa abordagem é o workflow reutilizável de secret scanning, desenvolvido para identificar possíveis credenciais e outros dados sensíveis no histórico Git, independentemente da linguagem utilizada pelo projeto consumidor.</p><h3>Versionamento também faz parte da reutilização</h3><p>Quando vários repositórios dependem de um workflow compartilhado, uma alteração pode afetar diferentes consumidores.</p><p>Por esse motivo, implementei um processo de versionamento e publicação dos workflows reutilizáveis.</p><p>A estratégia contempla versões semânticas, referências por versão principal e a possibilidade de utilizar um SHA completo de commit quando for necessária uma referência imutável.</p><p>Cada opção representa um equilíbrio entre facilidade de atualização e controle sobre as alterações recebidas.</p><p>O ponto central é que reutilização não elimina acoplamento; ela exige que esse acoplamento seja administrado.</p><p>Versionamento, compatibilidade e revisão de alterações são partes importantes dessa responsabilidade.</p><h3>Segurança das próprias automações</h3><p>Quando um repositório passa a coordenar automações que operam sobre outros projetos, sua importância aumenta.</p><p>Ele deixa de armazenar apenas documentação e passa a executar código com capacidade de consultar informações, abrir Pull Requests e modificar branches.</p><p>Isso exige cuidados adicionais.</p><p>Uma das práticas que adotei foi manter as Actions externas referenciadas por SHA completo de commit, identificando exatamente qual versão do código será executada.</p><p>Também configurei o Dependabot para acompanhar essas dependências e propor atualizações por meio de Pull Requests.</p><p>Entretanto, atualização automática não significa integração automática.</p><p>Uma nova versão de uma Action continua sendo uma alteração no código executado pelo pipeline. Dependendo do workflow, esse código pode ter acesso a tokens, secrets ou outros recursos sensíveis.</p><p>Por isso, mantenho a revisão humana como parte do processo.</p><h3>Autenticação e princípio do menor privilégio</h3><p>Outra decisão foi utilizar uma GitHub App para determinadas operações entre repositórios.</p><p>Em vez de depender de um token pessoal permanente com permissões amplas, as automações utilizam tokens temporários de instalação da aplicação.</p><p>Isso permite controlar as permissões concedidas e delimitar quais operações podem ser realizadas.</p><p>No inventário de projetos .NET, por exemplo, a arquitetura separa a descoberta de repositórios da inspeção de código.</p><p>A descoberta utiliza as credenciais necessárias para identificar os projetos elegíveis. A inspeção recebe apenas os dados necessários para processar os repositórios públicos selecionados, sem precisar receber a chave privada da GitHub App.</p><p>Essa separação reduz a exposição de credenciais durante operações que envolvem o processamento de código de diferentes projetos.</p><p>É uma aplicação prática do princípio do menor privilégio: cada componente deve possuir apenas o acesso necessário para executar sua responsabilidade.</p><h3>Automatizando a manutenção dos projetos .NET</h3><p>Além das políticas compartilhadas, implementei automações voltadas à manutenção dos próprios repositórios.</p><p>Uma delas é a sincronização das versões do SDK .NET.</p><p>O workflow identifica repositórios elegíveis, verifica o arquivo global.json e consulta as versões disponíveis dentro da política de atualização definida.</p><p>Quando encontra uma atualização aplicável, prepara a alteração em uma branch e abre um Pull Request.</p><p>A automação não realiza o merge diretamente na branch principal. Essa decisão preserva o processo de revisão e permite verificar possíveis impactos antes de integrar a atualização.</p><p>Outra automação realiza um inventário dos projetos .NET existentes nos repositórios acessíveis à GitHub App.</p><p>Nesse caso, a responsabilidade não é modificar os projetos, mas produzir uma visão consolidada de seus metadados.</p><p>Para realizar a inspeção, utilizo o DotNetRepoInspector, outro projeto que desenvolvi para analisar repositórios .NET utilizando informações efetivas do MSBuild, em vez de depender apenas da leitura direta dos arquivos .csproj.</p><p>Essa integração demonstra uma característica importante da estrutura.</p><p>Cada projeto continua tendo uma responsabilidade específica: o DotNetRepoInspector realiza a análise, enquanto o .github coordena sua execução em múltiplos repositórios e consolida os resultados.</p><p>Não precisei incorporar a implementação de inspeção ao repositório central para aproveitar suas capacidades.</p><h3>Automações também precisam de testes e governança</h3><p>Scripts de manutenção frequentemente começam pequenos.</p><p>Um Bash de algumas linhas resolve determinado problema, entra em um workflow e continua funcionando por meses.</p><p>O cenário muda quando esse mesmo script passa a operar sobre diferentes repositórios e realizar alterações automaticamente.</p><p>Nesse momento, ele precisa ser tratado como qualquer outro componente de software.</p><p>Por isso, o .github também possui testes de regressão, validações de contratos e verificações de qualidade utilizando ferramentas como actionlint e ShellCheck.</p><p>Também implementei mecanismos para lidar com falhas durante operações em lote.</p><p>Se uma atualização falha em determinado repositório, os demais podem continuar sendo processados quando isso é seguro. Ao final, as falhas precisam ser registradas e apresentadas explicitamente.</p><p>Outro cuidado está relacionado à propriedade das branches utilizadas pelas automações.</p><p>O simples fato de existir uma branch chamada chore/sync-dotnet-sdk não significa que uma automação possa assumir que aquela branch pertence a ela.</p><p>Uma branch com esse nome pode ter sido criada manualmente ou estar associada a uma alteração que não deve ser sobrescrita.</p><p>Por isso, o fluxo utiliza verificações adicionais de ownership e estado do Pull Request antes de reutilizar ou atualizar uma branch de automação.</p><p>São cuidados que fazem diferença quando estamos desenvolvendo ferramentas com capacidade de modificar múltiplos projetos.</p><h3>Governança para agentes de desenvolvimento</h3><p>Mais recentemente, comecei a enfrentar outro problema de configuração compartilhada: as instruções utilizadas por agentes de desenvolvimento.</p><p>Ferramentas capazes de analisar código, implementar issues e revisar Pull Requests precisam compreender as regras e particularidades de cada projeto.</p><p>Isso pode incluir convenções de arquitetura, estratégias de teste, políticas de segurança e procedimentos de revisão.</p><p>Quando mantemos vários repositórios, é natural que parte dessas instruções seja semelhante.</p><p>Copiar os mesmos arquivos entre projetos, entretanto, cria novamente o problema de desvio de configuração.</p><p>Para organizar essa responsabilidade, criei a área agent-governance dentro do repositório central.</p><p>Ela contém uma base comum de instruções, perfis, skills reutilizáveis, um manifesto de controle e um arquivo de versão.</p><p>Entre as skills existentes estão orientações para investigação de bugs, implementação de issues, revisão de Pull Requests, análise de segurança, refatoração e avaliação de cobertura de testes.</p><p>O objetivo é estabelecer uma base de instruções compartilhadas e permitir que cada projeto complemente essas orientações conforme suas necessidades.</p><h3>Como essas instruções chegam aos demais repositórios?</h3><p>Diferentemente dos arquivos de community health, as instruções de agentes não são herdadas automaticamente a partir do repositório .github.</p><p>Foi necessário construir um processo específico para gerenciar sua evolução e distribuição.</p><p>Existem workflows para validar o registro central, sincronizar determinadas skills de uma origem controlada e distribuir alterações aprovadas aos repositórios consumidores.</p><p>Quando é identificada uma diferença entre a versão central e a utilizada por um projeto, a automação pode preparar um Pull Request com a atualização.</p><p>O processo preserva a revisão da mudança, o histórico de alterações e a possibilidade de manter particularidades locais.</p><p>A mesma lógica aplicada aos workflows reutilizáveis aparece novamente: centralizar aquilo que é compartilhado sem retirar o controle dos projetos consumidores.</p><h3>O que realmente ganhamos com essa abordagem?</h3><p>O principal benefício não está simplesmente em reduzir a quantidade de arquivos.</p><p>Está em diminuir o número de lugares onde uma mesma decisão precisa ser mantida.</p><p>Quando uma política de segurança possui várias cópias independentes, cada uma delas pode evoluir de maneira diferente.</p><p>Quando existe uma fonte central e um mecanismo controlado de consumo ou distribuição, o problema muda de natureza.</p><p>Deixamos de perguntar como manter várias configurações iguais e passamos a pensar em como manter uma política compartilhada compatível com seus consumidores.</p><p>Isso não elimina a complexidade, mas permite administrá-la de maneira mais explícita.</p><p>Também facilita identificar quais responsabilidades pertencem ao ecossistema e quais devem continuar dentro de cada projeto.</p><p>Essa distinção é importante porque nem toda configuração merece ser centralizada.</p><p>Um workflow específico de uma aplicação pode não ter utilidade para outros repositórios. Da mesma forma, determinadas instruções de agentes podem depender de decisões arquiteturais que só fazem sentido naquele contexto.</p><p>Por isso, procuro tratar o .github como uma camada de governança compartilhada, e não como um depósito universal de configurações.</p><h3>Os limites da centralização</h3><p>Uma estrutura centralizada também introduz responsabilidades.</p><p>Uma alteração incorreta em uma política compartilhada pode afetar vários repositórios. Uma atualização incompatível em um workflow pode interromper pipelines consumidores. Uma automação com permissões excessivas pode ampliar o impacto de uma falha de segurança.</p><p>Por esse motivo, mecanismos de versionamento, validação, revisão e controle de acesso precisam evoluir junto com a centralização.</p><p>Também é importante reconhecer que existem diferentes formas de compartilhar configurações.</p><p>Arquivos de community health podem utilizar a herança nativa do GitHub. Workflows reutilizáveis são chamados explicitamente pelos consumidores. Outras configurações precisam ser distribuídas por processos próprios.</p><p>Esses mecanismos possuem características e limitações diferentes, e cada um deve ser utilizado de acordo com a responsabilidade envolvida.</p><p>O objetivo não é eliminar todas as diferenças entre os projetos, mas garantir que sejam intencionais, e não simplesmente consequência da falta de manutenção.</p><h3>Principais aprendizados</h3><p>A evolução desse repositório reforçou uma ideia importante em arquitetura de software: centralização e autonomia não precisam ser conceitos opostos.</p><p>É possível estabelecer políticas compartilhadas sem impedir que cada projeto mantenha suas próprias decisões.</p><p>Também ficou claro que reutilização exige governança. Workflows compartilhados precisam de versionamento, automações precisam de testes e mecanismos de distribuição precisam preservar rastreabilidade e revisão.</p><p>A segurança merece atenção especial quando uma ferramenta passa a operar sobre múltiplos repositórios. Credenciais temporárias, permissões limitadas e separação de responsabilidades ajudam a reduzir os riscos dessa concentração de capacidades.</p><p>Por fim, instruções para agentes de desenvolvimento devem ser tratadas como outros artefatos de engenharia: precisam de manutenção, versionamento e mecanismos controlados de atualização.</p><p>O aprendizado principal é simples: centralize as políticas que realmente são compartilhadas e preserve localmente aquilo que pertence ao contexto de cada projeto.</p><p>Mesmo em um portfólio pessoal, essa abordagem permite experimentar conceitos de Platform Engineering, Developer Experience e governança de software em um ambiente real.</p><h3>Para continuar estudando</h3><p>A documentação oficial do GitHub é um bom ponto de partida para explorar os conceitos apresentados neste artigo.</p><p>Para compreender o funcionamento nativo do repositório .github, recomendo começar por <a href="https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file">Creating a default community health file</a> , que explica quais arquivos podem ser compartilhados e como funciona sua utilização pelos demais repositórios.</p><p>Em seguida, vale estudar <a href="https://docs.github.com/en/actions/sharing-automations/reusing-workflows">Reusing workflows</a> , principalmente os mecanismos de chamada entre workflows, parâmetros, secrets e limitações de reutilização.</p><p>Para entender os cuidados necessários ao construir automações com acesso a repositórios, recomendo a documentação <a href="https://docs.github.com/en/actions/reference/security/secure-use">Secure use reference</a> , que aborda permissões, riscos e práticas de segurança no GitHub Actions.</p><p>Também vale conhecer a documentação sobre <a href="https://docs.github.com/en/apps/creating-github-apps">GitHub Apps</a> , especialmente os mecanismos de autenticação, permissões de instalação e geração de tokens temporários.</p><p>O código dos projetos apresentados neste artigo está disponível nos links do início do texto, incluindo os workflows, scripts, políticas e documentos que utilizo para coordenar a governança e a automação dos meus repositórios.</p><p>Se alguma dessas ideias for útil para seus próprios projetos, fique à vontade para explorar o código, adaptar o que fizer sentido ou contribuir.</p><p>E, se o trabalho te ajudou ou trouxe alguma ideia nova, deixe uma ⭐ no <a href="https://github.com/rodri-oliveira-dev/.github">repositório </a><a href="https://github.com/rodri-oliveira-dev/.github">.github</a> . É uma forma simples de apoiar o projeto.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=14f478b247a0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ADR: registrando o porquê das decisões e como o ADR Guard ajuda a manter esse histórico confiável]]></title>
            <link>https://medium.com/@rodrigodotnet/adr-registrando-o-porqu%C3%AA-das-decis%C3%B5es-e-como-o-adr-guard-ajuda-a-manter-esse-hist%C3%B3rico-confi%C3%A1vel-1fca8a3f1780?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/1fca8a3f1780</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[adr]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Mon, 21 Sep 2026 19:08:38 GMT</pubDate>
            <atom:updated>2026-09-21T19:08:38.936Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1sLM6JL5b5qOuPLU" /></figure><p><strong>Código registra o que mudou. Git registra quando mudou. ADRs ajudam a preservar algo igualmente importante: por que uma decisão arquitetural foi tomada.</strong></p><p>Em projetos que vivem por alguns anos, existe um tipo de pergunta que aparece com uma frequência impressionante:</p><blockquote><strong><em>“Por que fizemos isso desse jeito?”</em></strong></blockquote><p>Talvez seja a escolha de PostgreSQL em vez de MongoDB. Talvez seja a decisão de usar mensageria, adotar microsserviços, manter um monólito modular, implementar cache distribuído ou escolher determinada estratégia de observabilidade.</p><p>O código normalmente mostra <strong>o que</strong> foi feito.</p><p>O Git mostra <strong>quando</strong> aquilo mudou.</p><p>Mas nenhum dos dois necessariamente explica <strong>por que</strong> aquela decisão foi tomada.</p><p>É justamente aí que entram os <strong>Architecture Decision Records</strong>, ou simplesmente <strong>ADRs</strong>.</p><h3>Uma decisão arquitetural raramente acontece no vácuo</h3><p>Imagine que, alguns anos atrás, uma equipe decidiu não utilizar determinada tecnologia. Quem chega depois pode olhar para a arquitetura atual e pensar que outra solução talvez fosse melhor.</p><p>Talvez fosse.</p><p>Mas talvez aquela tecnologia tivesse sido descartada porque o sistema precisava atender uma restrição regulatória, porque a equipe não possuía maturidade operacional suficiente, porque havia um problema de licenciamento ou simplesmente porque, naquele momento, ela ainda não resolvia determinado requisito.</p><p>Sem esse contexto, decisões antigas parecem arbitrárias.</p><p>Michael Nygard popularizou os ADRs justamente a partir dessa percepção: documentação arquitetural útil não precisa necessariamente ser um grande documento descrevendo todo o sistema.</p><p>Pequenos registros independentes, cada um explicando uma decisão relevante, têm uma chance muito maior de permanecer compreensíveis e úteis ao longo do tempo.</p><blockquote><strong><em>Um ADR é uma espécie de fotografia do raciocínio arquitetural naquele momento.</em></strong></blockquote><p>Ele não tenta explicar toda a arquitetura.</p><p>Ele explica <strong>uma decisão</strong>.</p><h3>O que existe dentro de um ADR?</h3><p>Existem diferentes templates, mas um dos formatos mais conhecidos é extremamente simples:</p><ul><li><strong>Context</strong> — explica o problema, as restrições e as forças que levaram à necessidade de tomar uma decisão.</li><li><strong>Decision</strong> — registra o que foi decidido.</li><li><strong>Consequences</strong> — descreve o que muda como consequência daquela escolha, incluindo vantagens, custos e trade-offs.</li><li><strong>Status</strong> — indica se a decisão está sendo proposta, foi aceita, foi descontinuada ou foi substituída por outra.</li></ul><p>Um exemplo mínimo seria:</p><pre># Use PostgreSQL<br><br>## Status<br>Accepted<br>## Context<br>We need a relational database.<br>## Decision<br>Use PostgreSQL.<br>## Consequences<br>The service depends on PostgreSQL operational knowledge.</pre><p>A AWS, por exemplo, recomenda que ADRs sejam utilizados para decisões arquiteturalmente significativas relacionadas à estrutura do sistema, requisitos não funcionais, dependências, interfaces e técnicas de construção.</p><p>Isso é importante porque ADR não deveria virar um diário de desenvolvimento.</p><blockquote><em>“Atualizamos a versão de uma biblioteca.”</em></blockquote><p>Provavelmente não precisa de um ADR.</p><blockquote><em>“Padronizamos todos os serviços da empresa em uma estratégia específica de autenticação.”</em></blockquote><p>Provavelmente merece um.</p><p>Uma pergunta útil é:</p><blockquote><strong><em>Essa decisão afeta significativamente a forma como o sistema será construído, operado ou evoluído?</em></strong></blockquote><p>Se a resposta for sim, provavelmente há uma decisão arquitetural ali.</p><h3>ADRs criam memória arquitetural</h3><p>Quando vários ADRs começam a existir, eles formam aquilo que costuma ser chamado de <strong>decision log</strong>.</p><p>Esse histórico se torna especialmente valioso quando pessoas entram e saem das equipes.</p><p>Em vez de depender daquele desenvolvedor que “lembra por que fizemos aquilo em 2023”, o contexto passa a fazer parte do próprio repositório.</p><p>E existe um benefício ainda menos óbvio: <strong>ADRs reduzem discussões repetidas</strong>.</p><p>Sem registro, uma equipe pode discutir a mesma questão arquitetural várias vezes ao longo dos anos.</p><p>Alguém propõe uma tecnologia, o time debate, decide não utilizá-la e, seis meses depois, outra pessoa reabre exatamente a mesma discussão porque não existe registro do raciocínio anterior.</p><p>Com um ADR, a conversa pode começar alguns passos adiante:</p><blockquote><strong><em>“Essa decisão foi tomada por estes motivos. Alguma dessas premissas mudou?”</em></strong></blockquote><p>Essa é uma discussão muito melhor.</p><h3>O problema aparece quando os ADRs começam a crescer</h3><p>Adotar ADRs parece simples: cria-se uma pasta docs/adr, adicionam-se alguns arquivos Markdown e pronto.</p><p>Na prática, depois de algum tempo aparecem pequenos problemas.</p><p>Um arquivo chama:</p><pre>0003-use-redis.md</pre><p>Outro chama:</p><pre>adr4-rabbitmq.md</pre><p>Um ADR possui status Approved, outro usa Accepted.</p><p>Algumas decisões não possuem consequências.</p><p>Dois arquivos acabam usando o mesmo número.</p><p>Um ADR informa que determinada decisão foi substituída por outra, mas o arquivo referenciado não existe mais.</p><p>E, talvez o problema mais comum, alguém cria um índice manual de ADRs que deixa de ser atualizado depois de alguns meses.</p><p>Separadamente, nada disso parece grave.</p><p>Em conjunto, porém, essas pequenas inconsistências fazem com que a documentação deixe de transmitir confiança.</p><p>É exatamente esse espaço que o <strong>ADR Guard</strong> procura ocupar.</p><h3>Transformando convenções em validações</h3><p>O ADR Guard é uma ferramenta de linha de comando em .NET que valida e indexa ADRs.</p><p>A ideia é simples:</p><blockquote><strong><em>Se determinadas convenções são importantes para a documentação arquitetural, elas podem deixar de ser apenas recomendações em um README e passar a ser invariantes verificáveis automaticamente.</em></strong></blockquote><p>Por padrão, o ADR Guard espera nomes como:</p><pre>0001-use-postgresql.md</pre><p>E uma estrutura baseada no modelo clássico:</p><pre># Use PostgreSQL<br><br>## Status<br>Accepted<br>## Context<br>We need a relational database.<br>## Decision<br>Use PostgreSQL.<br>## ConsequencesThe service depends on PostgreSQL operational knowledge.</pre><p>Para validar os ADRs:</p><pre>adr-guard check docs/adr</pre><p>O comando analisa os registros e verifica nomes de arquivos, IDs, títulos, status, seções obrigatórias e relacionamentos entre ADRs.</p><p>Hoje as validações possuem códigos estáveis como ADR001 até ADR009, incluindo problemas como:</p><ul><li>IDs duplicados;</li><li>referências relativas quebradas;</li><li>seções obrigatórias ausentes;</li><li>status inválidos;</li><li>ADRs Superseded que não indicam corretamente qual decisão os substituiu.</li></ul><p>Parece um detalhe, mas códigos estáveis tornam a ferramenta especialmente adequada para automação.</p><h3>O lugar mais interessante para executar o ADR Guard é o pipeline</h3><p>O ponto mais interessante do ADR Guard talvez não seja executá-lo manualmente.</p><p>É executá-lo no <strong>CI/CD</strong>.</p><p>A partir desse momento, as convenções arquiteturais passam a participar do mesmo fluxo de qualidade usado pelo código.</p><p>Um pull request que quebra um link entre decisões pode falhar.</p><p>Um ADR incompleto pode falhar.</p><p>Dois ADRs com o mesmo identificador podem falhar.</p><p>Isso não transforma arquitetura em código, obviamente.</p><p>A ferramenta não consegue dizer se a decisão de usar Kafka é melhor do que RabbitMQ.</p><p>Mas consegue verificar algo muito mais objetivo:</p><blockquote><strong><em>O registro dessa decisão continua estruturalmente íntegro?</em></strong></blockquote><p>Essa separação é importante.</p><p><strong>Automatizamos aquilo que é mecânico para preservar o tempo humano para aquilo que exige julgamento.</strong></p><h3>O índice também pode deixar de ser manual</h3><p>Outro comando é:</p><pre>adr-guard index docs/adr</pre><p>Ele primeiro valida o conjunto de ADRs e somente depois gera um índice Markdown determinístico.</p><p>Essa ordem não é acidental.</p><p>O próprio ADR Guard possui um ADR explicando a escolha: gerar um índice de documentos inválidos poderia fazer um conjunto inconsistente parecer confiável.</p><p>Se a validação falhar, o índice anterior permanece intacto.</p><p>Se nada mudou, o arquivo também não é reescrito desnecessariamente.</p><p>O resultado é pequeno, mas importante:</p><p><strong>desaparece mais uma tarefa manual que inevitavelmente acabaria esquecida.</strong></p><h3>IA pode ajudar a escrever um ADR — mas não deveria decidir por você</h3><p>Uma das funcionalidades mais interessantes adicionadas ao projeto é o comando draft.</p><p>O ADR Guard pode utilizar <strong>OpenAI, Anthropic, Gemini ou um endpoint compatível com OpenAI</strong> para ajudar a produzir um primeiro rascunho.</p><p>Mas existe uma decisão arquitetural importante por trás disso:</p><blockquote><strong><em>A IA não decide arquitetura pelo time.</em></strong></blockquote><p>Todo ADR produzido dessa maneira recebe obrigatoriamente o status Proposed.</p><p>A ferramenta controla a estrutura final, valida o documento produzido e deixa a mudança para Accepted sob responsabilidade humana.</p><p>Isso evita uma confusão que provavelmente veremos cada vez mais:</p><p><strong>utilizar IA para acelerar a documentação é bastante diferente de delegar autoridade arquitetural para um modelo.</strong></p><p>O projeto também evita ingerir o repositório inteiro silenciosamente.</p><p>Contexto adicional precisa ser fornecido explicitamente, e ADRs existentes só são enviados ao provider quando:</p><pre>--include-existing-adrs</pre><p>é utilizado.</p><p>Também existe um modo de preview:</p><pre>--dry-run</pre><p>ou:</p><pre>--preview</pre><p>que permite gerar, montar e validar o ADR sem persistir nada.</p><p>É uma abordagem interessante para IA aplicada à engenharia:</p><blockquote><strong><em>assistência, não autonomia irrestrita.</em></strong></blockquote><h3>O que o ADR Guard deliberadamente não faz</h3><p>Entender os limites da ferramenta também ajuda a entender sua proposta.</p><p>O ADR Guard:</p><ul><li>não analisa automaticamente um Git diff para descobrir que uma alteração deveria possuir um ADR;</li><li>não percorre todo o código-fonte procurando decisões arquiteturais;</li><li>não faz RAG sobre o repositório;</li><li>não aceita ADRs automaticamente;</li><li>não tenta avaliar se a decisão registrada é arquiteturalmente boa.</li></ul><p>Isso significa que ainda existe uma responsabilidade essencial do time:</p><blockquote><strong><em>perceber quando uma decisão merece ser registrada.</em></strong></blockquote><p>A ferramenta começa a trabalhar <strong>depois</strong> dessa decisão humana.</p><p>E isso é uma divisão de responsabilidades bastante saudável.</p><h3>Dogfooding: o ADR Guard valida os próprios ADRs</h3><p>O próprio projeto mantém seus registros em:</p><pre>docs/adr</pre><p>Entre as decisões atualmente documentadas estão utilizar ADRs Markdown convencionais, manter a CLI sem dependências externas de runtime, validar os registros antes de gerar o índice e manter a geração assistida por IA independente de provider.</p><p>Ou seja:</p><p><strong>a ferramenta aplica a si mesma as regras que propõe.</strong></p><p>Além de ser um bom exemplo de <em>dogfooding</em>, isso mostra algo importante sobre ADRs: eles não precisam documentar apenas grandes decisões como “monólito versus microsserviços”.</p><p>Decidir manter uma CLI sem dependências externas também é uma decisão arquitetural quando isso influencia distribuição, manutenção e evolução futura.</p><h3>ADR não significa que uma decisão nunca poderá mudar</h3><p>Talvez esse seja o ponto mais importante de todos.</p><p>Um ADR não existe para dizer:</p><blockquote><strong><em>“Decidimos isso uma vez, então nunca mais podemos mudar.”</em></strong></blockquote><p>Arquitetura precisa evoluir.</p><p>Quando as premissas mudam, uma nova decisão pode substituir a anterior.</p><p>O importante é preservar o histórico.</p><p>Em vez de editar o passado até fazê-lo parecer coerente com o presente, cria-se uma nova decisão e registra-se que ela <strong>supersede</strong> a anterior.</p><p>Essa sequência acaba contando uma história muito mais útil sobre a arquitetura do que qualquer diagrama isolado.</p><h3>Em resumo</h3><ul><li><strong>Código registra implementação; ADR registra intenção e contexto.</strong></li><li>Um conjunto de ADRs cria uma memória arquitetural do projeto e reduz discussões repetidas.</li><li>Documentação simples ainda pode sofrer <em>drift</em>, inconsistências e links quebrados — exatamente o tipo de problema que automação pode resolver.</li><li>ADR Guard transforma convenções de ADR em verificações executáveis localmente e no CI, além de manter o índice consistente.</li><li>IA pode acelerar a criação do primeiro rascunho, mas decisões arquiteturais continuam sendo responsabilidade das pessoas.</li></ul><p>Talvez seja justamente essa combinação que torne ADRs tão úteis:</p><p><strong>eles são suficientemente simples para continuar sendo documentação humana, mas suficientemente estruturados para que ferramentas consigam ajudar a mantê-los saudáveis.</strong></p><p>O ADR Guard segue exatamente essa direção.</p><p>Ele não pretende substituir arquitetos, code reviews ou discussões técnicas.</p><p>A proposta é bem mais pragmática:</p><blockquote><strong><em>Quando uma equipe decide registrar sua arquitetura, garantir que esse histórico continue legível, consistente e confiável conforme o projeto cresce.</em></strong></blockquote><h3>Para continuar estudando</h3><p>Um ótimo ponto de partida continua sendo <strong>“Documenting Architecture Decisions”</strong>, de Michael Nygard, texto que popularizou o formato moderno de ADR.</p><p>A organização <strong>Architectural Decision Records</strong> mantém uma boa coleção de conceitos, templates e exemplos, incluindo alternativas como MADR para equipes que desejam registros um pouco mais detalhados.</p><p>O guia <strong>AWS Prescriptive Guidance — Using architectural decision records to streamline decision-making during development</strong> vale a leitura principalmente pela discussão sobre adoção, ciclo de vida e utilização de ADRs por equipes.</p><p>Também recomendo o guia <strong>The GDS Way — Documenting architecture decisions</strong>, do governo britânico, que apresenta uma abordagem bastante pragmática para manter decisões junto ao código.</p><p>E, naturalmente, vale estudar o próprio <strong>ADR Guard</strong>.</p><p>Além da implementação, os ADRs existentes dentro do repositório são pequenos exemplos reais de como registrar não apenas a decisão, mas principalmente os motivos e consequências que levaram até ela.</p><h3>Referências</h3><ul><li><strong>Michael Nygard — Documenting Architecture Decisions</strong><br><a href="https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions">https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions</a></li><li><strong>Architectural Decision Records</strong><br><a href="https://adr.github.io/">https://adr.github.io/</a></li><li><strong>AWS Prescriptive Guidance — Architectural Decision Records</strong><br><a href="https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html">https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html</a></li><li><strong>The GDS Way — Documenting architecture decisions</strong><br><a href="https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html">https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html</a></li><li><strong>ADR Guard — GitHub</strong><br><a href="https://github.com/rodri-oliveira-dev/adr-guard">https://github.com/rodri-oliveira-dev/adr-guard</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1fca8a3f1780" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Aggregates e Aggregate Roots: desenhando fronteiras de consistência]]></title>
            <link>https://medium.com/@rodrigodotnet/aggregates-e-aggregate-roots-desenhando-fronteiras-de-consist%C3%AAncia-64a22cef822d?source=rss-9ad16a333256------2</link>
            <guid isPermaLink="false">https://medium.com/p/64a22cef822d</guid>
            <category><![CDATA[aggregates]]></category>
            <category><![CDATA[ddd]]></category>
            <dc:creator><![CDATA[Rodrigo de Oliveira]]></dc:creator>
            <pubDate>Mon, 14 Sep 2026 11:53:16 GMT</pubDate>
            <atom:updated>2026-09-14T11:53:16.382Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XBc-ECOI3KQhy1jl9rlkrg.png" /></figure><p>Este é o oitavo artigo da série sobre Domain-Driven Design. No <a href="https://medium.com/@rodrigodotnet/primitive-obsession-e-modelo-an%C3%AAmico-quando-o-dom%C3%ADnio-vira-apenas-um-conjunto-de-dados-dd4c927afda0"><strong>texto anterior</strong></a>, falamos sobre Primitive Obsession e modelo anêmico, discutindo como trazer significado e comportamento de volta ao domínio.</p><p>Chegamos a um dos conceitos de DDD que mais geram dúvidas na prática: <strong>Aggregates</strong>.</p><p>Quando conhecemos o conceito pela primeira vez, é fácil chegar a uma definição mais ou menos assim:</p><blockquote><em>Um Aggregate é um conjunto de Entities e Value Objects agrupados em torno de uma Aggregate Root.</em></blockquote><p>Não está errado.</p><p>Mas também não ajuda tanto quanto parece.</p><p>Seguindo apenas essa definição, é natural olhar para relacionamentos entre objetos e começar a montar grandes árvores:</p><pre>Loan<br>├── Customer<br>│   ├── Address<br>│   └── Documents<br>├── Installments<br>│   └── Payments<br>├── CreditAnalysis<br>├── Contract<br>├── Notifications<br>└── CollectionHistory</pre><p>Tudo está relacionado a um empréstimo, então tudo deveria fazer parte do Loan Aggregate, certo?</p><p>Provavelmente não.</p><p>O ponto central de um Aggregate não é <strong>relacionamento</strong>.</p><p>É <strong>consistência</strong>.</p><p>Vaughn Vernon dedica sua série <em>Effective Aggregate Design</em> justamente a esse problema: Aggregates são frequentemente desenhados como grandes grafos de objetos por conveniência de navegação, quando sua verdadeira função é estabelecer uma fronteira cuidadosamente definida de consistência.</p><p>Uma pergunta muda completamente a forma de modelá-los:</p><blockquote><strong><em>Quais informações precisam permanecer consistentes juntas, na mesma transação, para proteger uma regra real do negócio?</em></strong></blockquote><p>É a partir daí que um Aggregate começa a surgir.</p><h3>Antes do Aggregate, precisamos falar de invariantes</h3><p>Uma <strong>invariante</strong> é uma regra que deve permanecer verdadeira para que o estado do domínio seja considerado válido.</p><p>Considere um empréstimo.</p><p>Podemos ter uma regra:</p><blockquote><em>Um empréstimo aprovado precisa possuir a data e o responsável pela aprovação.</em></blockquote><p>Portanto, isto seria inválido:</p><pre>Status: Approved<br>ApprovedAt: null<br>ApprovedBy: null</pre><p>Outra regra poderia ser:</p><blockquote><em>Um empréstimo cancelado não pode liberar recursos.</em></blockquote><p>Ou ainda:</p><blockquote><em>O valor aprovado não pode ser inferior ao valor já liberado.</em></blockquote><p>Essas regras não são simplesmente validações de entrada.</p><p>Elas definem estados permitidos para o negócio.</p><p>Um modelo poderia protegê-las assim:</p><pre>public sealed class Loan<br>{<br>    public LoanId Id { get; }<br>    public Money Amount { get; }<br>    public LoanStatus Status { get; private set; }<br>    public UserId? ApprovedBy { get; private set; }<br>    public DateTimeOffset? ApprovedAt { get; private set; }<br>    public Result Approve(<br>        UserId approvedBy,<br>        DateTimeOffset approvedAt)<br>    {<br>        if (Status != LoanStatus.UnderAnalysis)<br>        {<br>            return LoanErrors.InvalidStatusForApproval;<br>        }<br>        Status = LoanStatus.Approved;<br>        ApprovedBy = approvedBy;<br>        ApprovedAt = approvedAt;<br>        return Result.Success();<br>    }<br>}</pre><p>A alteração dessas propriedades acontece como uma única operação de negócio.</p><p>Não existe:</p><pre>loan.Status = LoanStatus.Approved;</pre><p>seguido, talvez alguns métodos depois, por:</p><pre>loan.ApprovedAt = now;</pre><p>A transição inteira é protegida pelo modelo.</p><p>Esse é um exemplo simples de uma <strong>fronteira de consistência</strong>.</p><h3>Então o que é um Aggregate?</h3><p>Eric Evans define Aggregate como um agrupamento de objetos associados tratados como uma unidade para fins de alteração de dados, com uma raiz e uma fronteira bem definida. Objetos externos podem referenciar a raiz, enquanto as regras de consistência são aplicadas dentro da fronteira. O <em>DDD Reference</em> mantém essa definição como um dos building blocks centrais do DDD tático.</p><p>Podemos representar assim:</p><pre>┌──────────────────────────────────┐<br>│          LOAN AGGREGATE          │<br>│                                  │<br>│    ┌────────────────────────┐    │<br>│    │          Loan          │    │<br>│    │     Aggregate Root     │    │<br>│    └───────────┬────────────┘    │<br>│                │                 │<br>│      Entities / Value Objects    │<br>│      necessários às invariantes  │<br>│                                  │<br>└──────────────────────────────────┘</pre><p>Tudo dentro dessa fronteira deve permanecer consistente conforme as regras daquele Aggregate.</p><p>Isso nos leva à <strong>Aggregate Root</strong>.</p><h3>Aggregate Root: a guardiã da fronteira</h3><p>A Aggregate Root é uma Entity especial.</p><p>Ela é o ponto de entrada para alterações no Aggregate e deve proteger suas invariantes.</p><p>Suponha que um pedido possua itens:</p><pre>Order Aggregate<br>│<br>├── Order<br>│   → Aggregate Root<br>│<br>└── OrderItem<br>    → Entity interna</pre><p>Se uma regra diz:</p><blockquote><em>Não é possível adicionar itens depois que o pedido foi fechado.</em></blockquote><p>Não queremos:</p><pre>order.Items.Add(newItem);</pre><p>Queremos:</p><pre>order.AddItem(productId, quantity, price);</pre><p>A raiz pode então verificar:</p><pre>public Result AddItem(ProductId productId, Quantity quantity,Money unitPrice)<br>{<br>    if (Status == OrderStatus.Closed)<br>    {<br>        return OrderErrors.OrderAlreadyClosed;<br>    }<br>    _items.Add(OrderItem.Create(productId, quantity, unitPrice));<br>    RecalculateTotal();<br>    return Result.Success();<br>}</pre><p>OrderItem pode ser uma Entity.</p><p>Mas isso não significa que o mundo externo deva recuperá-la e alterá-la diretamente.</p><p>A Aggregate Root controla essa modificação porque é ela quem possui a responsabilidade de preservar a consistência do conjunto.</p><p>Uma frase útil para memorizar:</p><blockquote><strong><em>Aggregate define a fronteira; Aggregate Root protege a fronteira.</em></strong></blockquote><h3>Relacionamento não determina Aggregate</h3><p>Esse talvez seja o erro mais frequente.</p><p>Considere:</p><pre>Loan<br>→ Customer</pre><p>Existe uma relação óbvia.</p><p>Um empréstimo pertence a um cliente.</p><p>Isso significa que Customer deve estar dentro do Loan Aggregate?</p><p>Não.</p><p>Precisamos perguntar:</p><blockquote><em>Para aprovar ou alterar um empréstimo, preciso modificar o cliente atomicamente na mesma transação?</em></blockquote><p>Na maioria dos modelos, provavelmente não.</p><p>O empréstimo pode simplesmente manter:</p><pre>public CustomerId CustomerId { get; }</pre><p>Em vez de:</p><pre>public Customer Customer { get; }</pre><p>Ainda existe relacionamento no negócio.</p><p>O que desapareceu foi a necessidade de montar um grande grafo de objetos dentro da mesma fronteira transacional.</p><p>Essa ideia é uma das recomendações mais importantes de Vaughn Vernon: <strong>referencie outros Aggregates por identidade</strong>. Em sua série, ele destaca que uma referência entre raízes não faz com que dois Aggregates passem a formar uma única fronteira de consistência.</p><p>Assim:</p><pre>Loan Aggregate<br>│<br>└── CustomerId<br>        │<br>        ▼<br>Customer Aggregate</pre><p>continua representando dois Aggregates independentes.</p><h3>Primeira regra de Vernon: proteja invariantes verdadeiras</h3><p>Antes de adicionar algo a um Aggregate, pergunte:</p><blockquote><em>Qual invariante exige que esses objetos sejam alterados atomicamente?</em></blockquote><p>Essa pergunta evita decisões como:</p><blockquote><em>Installment está dentro de </em><em>Loan porque uma parcela pertence ao empréstimo.</em></blockquote><p>Talvez pertença conceitualmente, mas isso não resolve a questão transacional.</p><p>Imagine um empréstimo com 48 parcelas.</p><p>Cada parcela pode receber:</p><ul><li>pagamentos;</li><li>juros;</li><li>multas;</li><li>estornos;</li><li>renegociações;</li><li>alterações relacionadas à cobrança.</li></ul><p>Duas parcelas diferentes podem ser atualizadas simultaneamente por processos distintos.</p><p>Se todas estiverem dentro de um enorme Loan Aggregate, qualquer alteração pode exigir concorrência sobre a mesma raiz.</p><p>Talvez o modelo adequado seja:</p><pre>Loan Aggregate</pre><pre>Installment Aggregate<br>    → LoanId</pre><pre>Payment Aggregate<br>    → InstallmentId</pre><p>Talvez não.</p><p>A resposta depende das invariantes reais do domínio.</p><p>O ponto importante é não transformar relacionamento em fronteira transacional automaticamente.</p><h3>Segunda regra: desenhe Aggregates pequenos</h3><p>Aggregates grandes costumam trazer consequências desagradáveis:</p><ul><li>maior contenção transacional;</li><li>mais dados carregados;</li><li>maior probabilidade de conflitos de concorrência;</li><li>maior acoplamento;</li><li>dificuldade para compreender invariantes;</li><li>menor escalabilidade.</li></ul><p>Vernon coloca o desenho de Aggregates pequenos entre suas heurísticas principais. Sua série mostra como grandes clusters de objetos frequentemente surgem da tentativa de navegar convenientemente pelo modelo, e como repensar as verdadeiras restrições de consistência costuma produzir fronteiras menores.</p><p>Mas existe uma ressalva importante:</p><blockquote><em>Aggregate pequeno não significa “uma classe por Aggregate”.</em></blockquote><p>Podemos perfeitamente ter:</p><pre>Order Aggregate<br>│<br>├── Order<br>│   → Aggregate Root<br>│<br>├── OrderItem<br>│   → Entity<br>│<br>├── ShippingAddress<br>│   → Value Object<br>│<br>└── Money<br>    → Value Object</pre><p>Se OrderItem precisa participar das invariantes do pedido, faz sentido permanecer dentro da fronteira.</p><p>A recomendação não é fragmentar tudo.</p><p>É manter apenas o necessário.</p><h3>Terceira regra: referencie outros Aggregates por identidade</h3><p>Considere novamente:</p><pre>public sealed class Loan<br>{<br>    public Customer Customer { get; }<br>}</pre><p>Essa navegação aparentemente conveniente pode induzir:</p><pre>loan.Customer.ChangeAddress(...);</pre><p>Agora modificamos dois conceitos através do mesmo grafo.</p><p>Em vez disso:</p><pre>public sealed class Loan<br>{<br>    public CustomerId CustomerId { get; }<br>}</pre><p>A aplicação pode coordenar aquilo que realmente necessita:</p><pre>var loan = await loanRepository.GetAsync(loanId);<br><br>var customer = await customerRepository.GetAsync(<br>    loan.CustomerId);</pre><p>Mas há uma questão importante aqui:</p><p>Carregar informações de outro Aggregate para tomar uma decisão não significa que esse outro Aggregate deva passar a fazer parte da fronteira.</p><p>Imagine:</p><pre>loan.Approve(<br>    creditEligibility,<br>    currentExposure,<br>    creditPolicy);</pre><p>O empréstimo pode precisar dessas informações para decidir.</p><p>Isso não implica que CreditProfile, Customer e todo o motor de política precisem estar armazenados dentro dele.</p><p>Uma das perguntas mais úteis nesse ponto é:</p><blockquote><strong><em>Eu preciso dessa informação ou preciso controlar o ciclo de vida desse objeto?</em></strong></blockquote><p>São coisas diferentes.</p><h3>Quarta regra: prefira uma instância de Aggregate por transação</h3><p>Outra recomendação importante de Vernon é tentar modificar apenas uma instância de Aggregate em cada transação.</p><p>Não gosto de apresentar isso como uma lei absoluta.</p><p>Sistemas reais possuem exceções.</p><p>Mas funciona muito bem como <strong>alerta de design</strong>.</p><p>Se todo caso de uso precisa fazer:</p><pre>Atualizar Aggregate A<br>+<br>Atualizar Aggregate B<br>+<br>Atualizar Aggregate C<br>+<br>commit</pre><p>vale perguntar:</p><blockquote><em>Existe uma invariante real exigindo isso?</em></blockquote><p>Se existe, talvez nossa fronteira esteja errada.</p><p>Se não existe, talvez estejamos exigindo consistência imediata onde o negócio aceitaria consistência eventual.</p><p>A heurística ajuda a revelar problemas de modelagem.</p><h3>Quinta ideia: fora do Aggregate, considere consistência eventual</h3><p>Dentro de um Aggregate:</p><pre>→ consistência imediata</pre><p>Entre Aggregates:</p><pre>→ avaliar consistência eventual</pre><p>Imagine:</p><pre>Loan Approved</pre><p>A aprovação precisa garantir atomicamente:</p><pre>Status = Approved<br>ApprovedAt != null<br>ApprovedBy != null</pre><p>Mas também precisamos:</p><pre>enviar e-mail<br>atualizar analytics<br>registrar informação em outro contexto<br>atualizar determinada projeção</pre><p>Essas operações realmente precisam acontecer dentro da mesma transação?</p><p>Provavelmente não.</p><p>Podemos ter:</p><pre>Loan<br>   │<br>   │ LoanApproved<br>   ▼<br>Domain Event<br>   │<br>   ├──► Notification<br>   ├──► Analytics<br>   └──► outro processo</pre><p>A parte crítica do empréstimo permanece imediatamente consistente.</p><p>Outras consequências podem acontecer depois.</p><p>Isso é consistência eventual.</p><p>Mas há um cuidado importante: consistência eventual não significa:</p><blockquote><em>“Joga numa fila e torce para funcionar.”</em></blockquote><p>Ela exige arquitetura confiável:</p><ul><li>idempotência;</li><li>retries;</li><li>tratamento de duplicidade;</li><li>observabilidade;</li><li>ordenação quando necessária;</li><li>dead-letter;</li><li>Outbox em determinados cenários;</li><li>mecanismos de compensação.</li></ul><p>Teremos um artigo específico para aprofundar esse assunto.</p><h3>Um exemplo: evitando o Aggregate gigante</h3><p>Imagine inicialmente:</p><pre>Loan<br>├── Customer<br>├── CreditAnalysis<br>├── Contract<br>├── Installments<br>│   └── Payments<br>└── CollectionHistory</pre><p>Depois de investigar as invariantes, chegamos a algo como:</p><pre>Loan Aggregate<br>├── Loan<br>├── Approval<br>└── LoanTerms</pre><pre>Customer Aggregate<br>└── Customer</pre><pre>Installment Aggregate<br>├── Installment<br>└── PaymentAllocation</pre><pre>CollectionCase Aggregate<br>└── CollectionCase</pre><p>As relações passam a acontecer por identidade:</p><pre>Loan<br>→ CustomerId</pre><pre>Installment<br>→ LoanId</pre><pre>CollectionCase<br>→ LoanId</pre><p>Não significa que esse segundo modelo esteja automaticamente correto.</p><p>Ele simplesmente representa uma mudança importante de raciocínio:</p><pre>ANTES<br>→ agrupamos porque os objetos estão relacionados</pre><pre>DEPOIS<br>→ agrupamos porque precisam proteger invariantes juntos</pre><p>Essa é provavelmente a maior mudança mental necessária para compreender Aggregate Design.</p><h3>O banco de dados também não deveria definir a fronteira</h3><p>Outra armadilha aparece quando usamos Entity Framework Core.</p><p>Imagine:</p><pre>Loans<br>LoanInstallments<br>LoanPayments<br>Customers</pre><p>com Foreign Keys entre todas as tabelas.</p><p>É tentador refletir exatamente essa estrutura:</p><pre>Loan<br>    .Installments<br>        .Payments</pre><p>e concluir que temos um Aggregate.</p><p>Mas Foreign Key é uma decisão de modelo de dados.</p><p>Aggregate é uma decisão de modelo de domínio.</p><p>As duas estruturas podem se parecer.</p><p>Não precisam ser iguais.</p><p>Da mesma forma:</p><pre>ON DELETE CASCADE</pre><p>não nos diz automaticamente qual é a fronteira de consistência do negócio.</p><p>É por isso que Aggregate Design deveria começar pelas regras do domínio, não pelo diagrama relacional.</p><h3>Uma ferramenta prática: Aggregate Design Canvas</h3><p>Depois de compreender a teoria, existe uma pergunta bastante razoável:</p><blockquote><em>Como fazemos esse exercício com uma equipe?</em></blockquote><p>Uma ferramenta interessante é o <strong>Aggregate Design Canvas</strong>, utilizado para tornar explícitas as decisões sobre um Aggregate e estimular discussões sobre regras, responsabilidades e fronteiras.</p><p>Ele aparece também no <strong>Domain-Driven Design Starter Modelling Process</strong>, iniciativa do DDD Crew que oferece uma jornada introdutória desde a compreensão do negócio até a codificação do modelo. O processo possui oito etapas e deixa claro que não pretende ser uma sequência rígida: DDD continua sendo um processo iterativo de aprendizado e descoberta.</p><p>As etapas passam por:</p><pre>Alinhar<br>↓<br>Descobrir<br>↓<br>Decompor<br>↓<br>Criar Estratégia<br>↓<br>Conectar<br>↓<br>Organizar<br>↓<br>Definir<br>↓<br>Codificar</pre><p>A ordem é interessante porque reforça algo que considero importante nesta série:</p><blockquote><strong><em>Não deveríamos começar Aggregate Design olhando para classes ou tabelas.</em></strong></blockquote><p>Antes dele vêm domínio, linguagem, Subdomains, estratégia, Bounded Contexts e suas relações.</p><p>É justamente na etapa de <strong>Codificar</strong> que o processo recomenda o Aggregate Design Canvas como uma ferramenta de apoio para começar a materializar o modelo.</p><p>Para ajudar a tornar esse conteúdo mais acessível para a comunidade brasileira, participei da tradução do <strong>Domain-Driven Design Starter Modelling Process</strong> para português brasileiro.</p><p><a href="https://ddd-crew.github.io/ddd-starter-modelling-process/translations/pt-br/README.html?utm_source=chatgpt.com#domain-driven-design-starter-modelling-process">Domain-Driven Design Starter Modelling Process — Português Brasileiro</a></p><p>Recomendo o material principalmente para quem sente a dificuldade de saber “por onde começar” em DDD. Ele conecta diversas técnicas que estudamos ao longo desta série e mostra que a codificação é consequência de um processo maior de aprendizado do domínio.</p><h3>Conclusão</h3><p>Aggregates são frequentemente ensinados como agrupamentos de objetos.</p><p>Essa definição é incompleta.</p><p>A ideia realmente importante está na <strong>fronteira de consistência</strong>.</p><p>Um Aggregate existe porque determinadas regras precisam ser protegidas atomicamente. Sua Aggregate Root controla alterações e impede que estados inválidos sejam construídos por modificações arbitrárias em seus objetos internos.</p><p>As heurísticas apresentadas por Vaughn Vernon ajudam muito a transformar esse princípio em decisões práticas:</p><ul><li>proteja invariantes verdadeiras;</li><li>mantenha Aggregates pequenos;</li><li>referencie outros Aggregates por identidade;</li><li>prefira modificar uma instância de Aggregate por transação;</li><li>considere consistência eventual entre Aggregates.</li></ul><p>Isso também significa abandonar uma ideia bastante confortável:</p><blockquote><em>Objetos relacionados não precisam necessariamente morar juntos.</em></blockquote><p>Loan, Customer, Installment e CollectionCase podem participar do mesmo processo de negócio sem fazer parte do mesmo Aggregate.</p><p>Quando mudamos a pergunta de:</p><blockquote><em>“Quais objetos estão relacionados?”</em></blockquote><p>para:</p><blockquote><em>“Quais regras precisam permanecer consistentes juntas?”</em></blockquote><p>Aggregate Design começa a fazer muito mais sentido.</p><h3>No próximo artigo</h3><p>No próximo texto da série, vamos estudar:</p><p><strong>Application Services, Domain Services e Policies: onde cada regra deveria viver?</strong></p><p>Depois de colocar comportamento dentro do domínio, surge outro problema: nem toda lógica pertence naturalmente a uma Entity ou Aggregate.</p><p>Vamos separar a responsabilidade da camada Application, que coordena casos de uso, das regras genuinamente pertencentes ao domínio e entender quando Domain Services e Policies fazem sentido — e quando uma classe chamada SomethingService está apenas escondendo um modelo anêmico.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=64a22cef822d" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>