DEV Community: João Mateus Scarpa

How We Stopped Writing Changelogs (and Let AI Do It)

João Mateus Scarpa — Sat, 23 Aug 2025 00:50:11 +0000

For the past few months, my team and I have been working on a project involving AI agents — which is exciting by nature, full of experiments, fast iterations, and plenty of moving parts. Every Friday, three of us — me (backend), our frontend lead, and our designer — had a ritual: each one would write a short summary in our team channel about what happened during the week. It was a way to make sure product and non-technical folks could follow along with the backend, frontend, and design work.

The challenge wasn’t so much about discipline. The real friction was translating what was actually done into something meaningful and digestible for the rest of the team. What made sense as commits and technical details didn’t always land well for product.

Since we were already deep into AI and automation, the question naturally came up: why not automate this weekly process too?

That thought was the seed of Briefly.

From Ritual to CLI

The idea was straightforward: grab the git commits for the week, summarize them with AI, and share the result where the team communicates.

A couple of shell scripts later, the first version of Briefly was alive.

# Setup for your repo
briefly setup

# Generate a changelog from recent commits
briefly generate --since 7d

# Publish to Discord
briefly publish briefly-summary.md --env staging --app-url https://example.com

How It Works

Briefly has three simple commands:

Setup: Creates a local .briefly config with your OpenAI key, Discord webhook, and defaults.
Generate: Collects git commits, summarizes them with OpenAI, and writes a briefly-summary.md.
Publish: Posts the summary directly to Discord via webhook.

The config is just a small .ini file:

OPENAI_API_KEY=...
DISCORD_WEBHOOK=...
DEFAULT_MODEL=gpt-4o-mini
PROJECT_KIND=api
DEFAULT_ENV=staging
DEFAULT_APP_URL=https://example.com

Why Two Commands?

You might wonder: why split generate and publish instead of a single command?

The reason is intentional. AI outputs are, by nature, non-deterministic. I wanted whoever was responsible that week to review the generated changelog before pushing it out. This way they could:

Ensure the summary was factually accurate.
Add or remove emphasis on changes that mattered most.
Adjust wording so it resonated better with product or leadership.

It’s a balance between automation and human judgment: the AI does the heavy lifting, but people keep the final say.

Why It Matters

Most teams struggle with changelogs. They’re either too detailed (commit dumps no one reads) or too sparse ("fixed stuff"). Briefly finds the middle ground: concise, readable summaries generated automatically.

Instead of forgetting to update your team, or spending 30 minutes writing a message at the end of the week, you can run:

briefly generate && briefly publish

And that’s it. Your team gets a digestible changelog, right where they already communicate.

What’s Next

Briefly is still early, but here’s what’s on the roadmap:

Aliases (briefly g, briefly p, briefly .)
Multilingual summaries
Relative dates (--since 7d|1w|2m)
Dry-run mode for CI
Custom prompts for different project styles

And yes, CI integration is coming soon — imagine every Friday your bot dropping the changelog in your channel without anyone lifting a finger.

Give It a Spin ✨

Briefly is published on npm as @jmscarpa/briefly.

npm install -g @jmscarpa/briefly

If your team also shares weekly updates, give it a try. Automating the boring parts leaves more time for the creative ones.

Sometimes the best tools are born not from big visions, but from small rituals that refuse to stay manual.

Simplifying the Software Development Process: A Focus on Needs, Not Whims

João Mateus Scarpa — Thu, 23 Nov 2023 03:18:51 +0000

After a decade in the software industry, I’ve been a part of various projects and have witnessed firsthand the evolution of development methodologies and few generations of developers. One of the most consistent challenges I’ve seen teams face is the complexity of keeping things simple and focused. This article delves into strategies I’ve seem, applied and validate to simplify software development and help the team concentrating on the essential needs of the product you’re developing.

The Pitfall of Over-Engineering

In the software development landscape, the allure of over-engineering is a subtle trap. This occurs when developers, captivated by the newest technologies or the thrill of complex problem-solving, create solutions that are more intricate than necessary. While the drive to innovate is commendable, over-engineering often leads to a host of issues. In those years, I’ve seem many projects with misplaced Mongo DB’s, microservices, many different bundle tools for Front End and several other tools that promise magical results.

Firstly, over-engineering can inflate development time and costs significantly. Complex solutions demand more resources for development, testing, and maintenance. They also introduce the risk of extended project timelines, as teams wrestle with the complexities of advanced but unnecessary code. This not only strains budgets but can also delay the market entry of the product.

Moreover, complexity in software often equates to decreased flexibility and increased fragility. In an industry where requirements and technologies evolve swiftly, simplicity in design allows for easier adaptation to change. Complex systems, conversely, tend to become unwieldy and rigid, making them difficult to modify in response to new demands or opportunities. This inflexibility can also contribute to reduced code readability and a higher propensity for bugs, further complicating maintenance and updates.

Lastly, the focus on technical sophistication can sometimes lead developers astray from the core objective: addressing user needs effectively. The essence of successful software lies in its utility and usability, not just its technical prowess.

Understanding Product Needs vs. Coding for Fun

The key to efficient software development lies in distinguishing between what a product truly needs and what we, as developers, find exciting to code. This understanding begins with an in-depth analysis of the project requirements, focusing solely on features that add real value to the end user.

Strategy 1: Prioritize and Scope

Define Clear Objectives: Start by establishing clear, achievable objectives for your project with your product manager or stakeholders. What problem are you solving? Who is your target audience? What are their primary needs?
Create a Minimal Viable Product (MVP): If you’re building something new, develop an MVP that includes only the essential features. This approach allows for quicker launches and early user feedback, which can guide future development. > Personal Note: If you’re in here, I’d recommend to go with your mostly confortable technology. Delivery the MVP faster will allow you to test your idea before investinig long hours of coding on it.

Strategy 2: Involve Stakeholders Early

Regular Feedback Loops: Engage with stakeholders, including end-users, throughout the development process. Their insights can help steer the project in the right direction and avoid unnecessary features.
Iterative Development: Adopt agile methodologies to incorporate stakeholder feedback iteratively, ensuring the product remains aligned with user needs. If you product is stable, you won’t be afraid of deploy it on friday (or whenever you need)

Personal Note: The dynamic between developers and product teams, designers and stakeholder can be challenging, but it’s essential for success. Our code gains real-world impact through their insights. Embrace this collaboration; it’s how our technical skills create meaningful software that’s actually used and valued.

Strategy 3: Embrace Simplicity

KISS Principle: Follow the ‘Keep It Simple, Stupid’ (KISS) principle. Opt for simpler solutions that are easier to implement, test, and maintain.
Avoid Premature Optimization: Don’t optimize too early. Focus on making the software work correctly first, then refine for efficiency and scalability if needed.

Implementing Simplified Processes

Once you have a clear understanding of the project’s needs, the next step is to streamline the development process.

Strategy 4: Efficient Project Management

Task Prioritization: Use tools like Kanban boards or Scrum methodologies to prioritize tasks effectively.
Sprint Planning: Break down development into manageable sprints, focusing on delivering specific features or improvements in each cycle. Task size: Always split your tasks in small and deliverable pieces. In general lines try to split your tasks in, AT MOST, 1 week tasks.

Personal Note: Try not to underestimate the tasks, I can guarantee if you finish your tasks soon you will always have more things to do. For the PO’s, you’ll be a hero delivering earlier or delivering more than estimated, but they won’t like if you took 2 or 3 weeks more than the estimated to delivery what was agreed.

Strategy 5: Continuous Improvement

Reflect and Adapt: Post each development cycle, review what worked and what didn’t. Use these insights to continuously improve your process.
Invest in Training: Encourage your team to stay updated with relevant technologies and methodologies, but with a focus on applicability to project needs.

Last but not least

The art of software development is not just about coding the most advanced or intricate solution. It’s about understanding and delivering what the project truly needs. By focusing on the essentials, involving stakeholders, embracing simplicity, managing tasks efficiently, and continuously improving, we can develop software that is not only high quality but also relevant and cost-effective. Remember, sometimes less is indeed more in the world of software development.

Join the conversation! Stay tuned for our upcoming posts where I’ll share practical tips for Team Leaders, Developers, and Product Managers on maximizing the effectiveness of async communication.

Share your experiences, challenges, and insights in the comments. Let’s optimize our software development processes together and unlock our team’s full potential. Spread the word to your peers who are eager to explore new communication methods. Let’s rock async!

O problema com seu software não está no código

João Mateus Scarpa — Wed, 23 Mar 2022 13:19:32 +0000

O problema com seu software não está no código
Na real, até pode estar no código e nesse caso vai (quase) sempre ser reflexo de um outro problema.
Eu trabalho com desenvolvimento de software desde 2013 e ao longo desses quase 10 anos já vi muita coisa boa e muita coisa assustadora na área. Eu cheguei até mesmo a acreditar que as empresas de desenvolvimento, depois de tanto tempo, já saberiam que nenhum cliente paga por código fonte (seja ele bem ou mal escrito) e pela solução de um problema. Infelizmente, isso ainda não aconteceu e tem empresas que correm atrás do próprio rabo achando que o problema é puramente técnico.
Nosso principal objetivo, como profissionais na área de software, deveria ser conseguir uma forma simples e otimizada de resolver os problemas e só daí nos preocuparmos com um código lindo e com 100% de cobertura de testes.
Não me entendam mal, eu acho que um código bem escrito e uma boa cobertura de testes é essencial, MAS isso não deve ser desculpa ou ter prioridade sobre agregar valor e entregar uma funcionalidade que realmente faça sentido com o problema do seu cliente.

É relativamente comum, times e empresas de software focarem na entrega de código e em eliminar o máximo de tarefas de um quadro e esquecerem que todo software faz parte de um produto e um produto precisa fazer uma coisa bem feita: agregar valor para quem usa.
Entregar 10 funcionalidades com 100% de cobertura de testes, várias linhas de códigos e commits, que serão usadas apenas 1 vez por um usuário interno do sistema tem bem menos impacto do que entregar uma única funcionalidade de ponta-a-ponta com a qual o usuário final consiga interagir e ter algum valor agregado no final daquele fluxo. Ou seja, uma funcionalidade entregue que resolve um problema real é infinitas vezes melhor do que todas as outras não o fazem.
E aqui chegamos no cerne da nossa discussão: apesar de termos pessoas com cargos e com a responsabilidade de levantar requisitos e priorizar tarefas, isso é algo que deveria ser responsabilidade de todos. E é aqui onde mora o problema do seu software (ou até mesmo da sua empresa) e sobre isso que quero trazer 5 reflexões que podem te ajudar a compartilhar melhor essa responsabilidade.

1. Treine desenvolvedores juniores
Nos últimos anos nada recarregou mais minhas baterias profissionais do que receber um time de novos desenvolvedores querendo aprender e evoluir. É uma tarefa difícil e cansativa mas que deve fazer parte do processo de crescimento de toda empresa e esse é o momento perfeito para você ensinar que a responsabilidade sobre um produto esta acima da quantidade de código gerado.
Esse profissional, começando a carreira, está ansioso por aprender e programar, mas também em entregar valor e ser reconhecido. Ensine-o a detectar o que entrega valor, cobrar dos pares caso a atividade priorizada não esteja condizente com o direcionamento do produto e/ou da iteração atual e sem dúvidas ele te ajudará a chegar mais longe.

2. Pense em tecnologia, mas não deixe-a te limitar
Sendo uma empresa que desenvolve software é claro que a tecnologia tem uma grande importância no dia a dia, porém não se prenda a ela para entregar resultados. Seu cliente está mais preocupado em ter seu problema resolvido do que saber se ele foi resolvido com a linguagem X ou Y.
É o papel dos engenheiros e desenvolvedores mais experientes terem a escolha final das tecnologias utilizadas, mas por experiência própria, as que são mais simples, padronizadas e que facilitam a entrada de novas pessoas, geralmente facilitam a entrega de resultados.

A Experiência do time também deve entrar nessa balança, pois por mais legal que seja aquela nova tecnologia do momento, leva tempo para se ter uma equipe madura para solucionar problemas com ela. E isso nos leva ao próximo ponto…

3. Dinheiro não é infinito

Quem dera fosse, não é mesmo?
Dinheiro é um recurso finito. Quem tem pouco tem que economizar e quem tem muito não quer perder. Então toda decisão de arquitetura, ferramenta e serviços deve levar isso em consideração. Uma ideia genial que não possuí investimento para ser executada é o mesmo que ideia nenhuma.

A quantidade de dinheiro que você tem disponível é como o comprimento de uma pista de decolagem. Se você estiver focado nas atividades certas e as fizer bem feito você pode até decolar com um pista curta, mas nunca terá pista o suficiente para decolar se você se preocupar em pintar o avião ao invés de montar o avião que de fato voe.

E deixe seu time saber disso, porque isso implica diretamente na priorização de tarefas e escolha (ou troca) de ferramentas e tecnologias.

4. Faça pequenas (e constantes) entregas

Todo software tende a ser infinito e sempre haverá uma funcionalidade a mais, uma tela a mais e (infelizmente) um problema a mais para ser corrigido.
Dividir as entregas em pequenos pedaços, além de manter um fluxo de entrega continuo, te ajuda a “sentir a temperatura da água” e guiar melhor a priorização das tarefas a serem executadas.
Em um cenário normal, o ideal seria sempre priorizar a “próxima tarefa mais importante” e ela ser o artefato de entrega da sua equipe. Seja essa entrega mensal ou (como eu recomendaria) semanal. Isso ajudará sua equipe a ficar mais focada, haja vista que o foco estará apenas naquela tarefa e deixará seu cliente satisfeito, pois você sempre terá uma entrega a ser feita com riscos mínimos de atraso.

E é claro que decisões ruins de priorização acontecem, infelizmente não podemos evitar, mas entregas pequenas ajudam a minimizar os impactos dessas decisões, nos permite realizar experimentos técnicos e validar tudo com muito mais velocidade e assertividade o rumo do produto.

5. Microgerenciamento

Por fim, mas não menos importante. Não microgerencie sua equipe. Treine e tenha pessoas em quem você confia para executar o precisa ser feito. Partilhe conhecimento e permita que todos tenham a as ferramentas e capacidades de agirem por si.
Vale muito mais um líder que atue como um escudo para equipe, evitando interferências e ruídos externos, do que um líder que questiona e precisa participar de todas as decisões, seja quais forem.

—

Oi, Eu sou o João!
Olá! Me chamo João Mateus Scarpa sou formado em Ciência da Computação com MBA em Gestão de TI e Especialização em Docência do Ensino Superior. Atuo com desenvolvimento Web desde 2013, já atuei como Gestor de TI no Hub de Inovação Tecnológica de Taubaté e atualmente tenho me dedicado em mapear e documentar os processos de gestão e desenvolvimento de software na Designa.
Você pode me encontrar online no LinkedIn, Twitter e Instagram ou através do e-mail joao.scarpa@gmail.com