#149 - ADRs: o diário de bordo da arquitetura


Hey! 👋

Você sabia que agora temos uma comunidade no Discord?

Bom, na verdade a gente já tinha, só tava abandonada. Mas agora ela tá ativa novamente e estamos sempre trocando ideia por lá (tem até um bot de lo-fi).

E junto dela, a gente também lançou o plano Codecon Pro. Uma forma de você apoiar a Codecon a tirar mais projetos do papel. Mais barato que um lanche por mês

Até mais,
Gabriel Nunes (@nunesgabriel)

ADRs: o diário de bordo da arquitetura

Quando a gente fala de decisões de arquitetura em projetos ágeis, não dá pra pensar em um manualzão gigantesco que ninguém lê. O ideal é documentar de forma leve, prática e, principalmente, útil. Os métodos ágeis não odeiam documentação, eles só não têm paciência pra papelada inútil. A ideia é criar registros pequenos, atualizáveis e que realmente ajudem a equipe no dia a dia.

Sabe aquelas decisões técnicas que a gente toma e depois esquece o porquê? Ou que quem chega no projeto fica perdido tentando entender? Pois é, pra evitar isso, a sugestão é usar os famosos ADRs (Architecture Decision Records): documentos curtos e padronizados que explicam o que foi decidido, por que, quando, qual o contexto, e quais as consequências. Tudo bem direto ao ponto, e em Markdown, claro.

Esses registros vão pro repositório do projeto, com numeração sequencial (nada de reaproveitar número antigo!) e até os desatualizados são mantidos, só que marcados como “substituídos”. É uma forma de conversar com o desenvolvedor do futuro e evitar aquela sensação de “quem foi o maluco que fez isso aqui?”.

O formato é simples: título, contexto, decisão, status e consequências. E o texto precisa ser bem escrito, como se estivesse explicando pra alguém de verdade, nada de bullet point preguiçoso que mais confunde do que ajuda.

Na prática, o uso dos ADRs tem sido bem recebido. Além de ajudar a manter o histórico e o raciocínio por trás das decisões, eles facilitam o onboarding de novos devs e deixam claro quando uma mudança de rumo faz sentido. Resumo da ópera: é uma ferramenta simples, mas poderosa, pra manter a arquitetura viva, compreensível e alinhada ao time.

Esse artigo foi uma dica do leitor Yuri Martins, obrigado!.

Um recado do patrocinador 📣

“Trabalhar na área de tecnologia aqui no Asaas tem sido uma experiência maravilhosa. Estou na empresa há quase quatro anos e, até hoje, me sinto motivada e desafiada todos os dias.
Minha liderança é acolhedora e participativa, o que me incentiva a crescer como profissional e a buscar constantemente novos conhecimentos e soluções para o meu dia a dia. Além disso, temos uma cultura muito forte de code reviews — todos os desenvolvedores participam ativamente da revisão de código, sempre contribuindo com sugestões valiosas e promovendo trocas ricas de aprendizado.
Sinto que minhas ideias são valorizadas e tenho espaço para contribuir de forma significativa com o time. Isso me faz sentir realizada profissionalmente e feliz com o meu trabalho.”

Sarah Tavares, Desenvolvedora Full Stack Pleno no Asaas.

Se você curte trabalhar com propósito, em um ambiente de confiança e parceria, talvez o seu lugar seja no Asaas! Conheça as vagas abertas!

🗣️ feedback

Na Figma, o time de engenharia criou um jeito super colaborativo de pedir feedback: as “críticas de engenharia”. A ideia surgiu pra evitar aqueles feedbacks que chegam tarde demais e travam os projetos. Inspirados pelas críticas de design, os engenheiros começaram a se reunir no FigJam pra trocar ideias desde o início dos projetos, sem pressão de aprovação. Todo mundo pode opinar, e o foco é explorar soluções juntos. Deu tão certo que hoje mais de 200 pessoas participam! É tipo plantar um jardim em grupo, cada um ajuda a crescer algo legal.

🤑 marketing

Marketing para desenvolvedores não é sobre buzzwords ou vendas agressivas, é sobre construir confiança. Desenvolvedores são céticos, atentos e valorizam conteúdo útil, direto e bem feito. Quer conquistá-los? Mostre como seu produto resolve problemas reais, com docs impecáveis, exemplos práticos e uma experiência de uso que se vende sozinha. Nada de enrolação ou promessas vazias. Interaja com a comunidade, ouça o feedback e melhore. No fim das contas, o melhor marketing é aquele que ensina, inspira e faz o dev pensar: “como eles construíram isso?”.

🧓 nostalgia

Você já pensou em transformar anos de conversas no iMessage em um livro físico? Pois é, tem gente que se irritou por não conseguir navegar direito pelas mensagens antigas no celular e decidiu resolver isso de um jeito bem nerd: extraiu o histórico do iPhone, acessou o banco de dados escondido (sms.db) e começou a brincar com SQL. A ideia? "Folhear" suas memórias como se fossem páginas de um livro. Um projeto curioso, nostálgico e com um toque geek, tudo pra matar a saudade e organizar as lembranças!

🧑‍💻 GO

Um programador encarou o desafio de processar um arquivo com 1 bilhão de linhas (13GB!) e extrair dados de temperatura por estação meteorológica, usando a linguagem Go. Começou com uma solução simples que levou 1m45s e foi otimizando até alcançar incríveis 3,4 segundos! Ao longo de nove versões do código, ele testou desde melhorias em mapas até paralelização e criação de estruturas próprias. Tudo usando apenas a biblioteca padrão do Go. O objetivo? Código rápido, limpo e independente, e a jornada foi um baita exercício nerd de performance!

⏳ tempo

Já reparou que o tempo parece voar conforme a gente envelhece? Isso rola porque o nosso cérebro, mestre em economizar energia, só presta atenção no que é novo e surpreendente. Quando somos crianças, tudo é novidade, então cada momento vira uma memória viva. Mas, com a rotina adulta, os dias ficam previsíveis, e o cérebro nem se dá o trabalho de gravar muita coisa. Resultado: os anos parecem passar num piscar de olhos. A solução? Quebrar a mesmice e se jogar no desconhecido. É assim que o tempo desacelera.

🇯🇸 JavaScript

Quer dar um upgrade nos seus códigos JavaScript? Então se liga nesses 30 truques que vão te ajudar a escrever de forma mais rápida, elegante e esperta! Tem de tudo: conversão de tipos com !!, valores padrão em funções, operador ternário, uso de map, filter, reduce, flat, ??, ?. e até como trocar valores sem variável temporária. Tudo isso pra deixar seu código mais limpo e com cara de quem manja dos paranauê. Bora explorar o lado ninja do JavaScript?

Já parou pra pensar que escolher microsserviços ou monolito pode afetar um negócio? Ou React do bom e velho HTML/CSS?

Pois então. Decisões técnicas também podem afetar o business ($$$).

Foi sobre isso que discutimos no episódio dessa semana do Escovando Bits.

Tem alguma pergunta? Só responder o e-mail!

R. Dr. João Colin, 1285, Joinville, SC 89204-001
Desinscrever-se · Preferências

code(weekly)

Junte-se à 7.500+ devs e receba e-mails semanais com a melhor curadoria de artigos, repositórios e outros links interessantes da área tech.

Read more from code(weekly)

Hey! 👋 Que tal apoiar a Codecon e ganhar benefícios exclusivos? Por R$15/mês ou R$ 180/ano, você apoia nossos projetos, entra nos bastidores do que rola por aqui, troca ideia com quem tá por trás da Codecon e ainda curte vantagens em eventos, produtos e muito mais. E mais! Durante esse mês de maio, se a gente conseguir atingir a primeira meta, vamos sortear um NINTENDO SWITCH novinho. Bora lá? Faltam poucas pessoas! SEJA CODECON PRO! 🔥 Veja todos os detalhes e vantagens clicando aqui. Até...

Hey! 👋 O principal encontro de devs sênior+ do Brasil! A Select Experience chega à sua terceira edição como o ponto de encontro das principais referências em tecnologia. Um evento feito sob medida para quem já tem estrada na área e busca conversas que realmente agregam. As inscrições para a edição de 2025 já estão abertas. 01 DE NOVEMBRO ~ STATE INNOVATION CENTER, SÃO PAULO, SPGaranta o seu lugar entre os melhores! Até mais,Gabriel Nunes (@nunesgabriel) Dividir para conquistar Dividir tarefas...

Hey! 👋 Faltam poucos dias para a CODECON UNIVERSE, mas ainda dá tempo de se inscrever! 🗓️ 17 e 18 de maio📍 Ágora Tech Park, Joinville👉 Inscreva-se em: codecon.dev/universe Segue a gente no Insta pra ver toda a cobertura e os resultados do hackathon. Até mais,Gabriel Nunes (@nunesgabriel) O guia definitivo para virar o dev que todo mundo quer na equipe Sabe aqueles programadores tops? Então, eles não nasceram assim. Viraram feras porque seguiram alguns princípios que qualquer um pode adotar...