Forem: He4rt Developers

DataAccess: ADO.net

Bruno Freschi — Fri, 10 Apr 2026 11:31:20 +0000

Controle total e performance máxima

Se você usa .NET, precisa entender o ADO.NET. Ele é a base de tudo — inclusive do Dapper e do Entity Framework.

O que é?

ADO.NET é o conjunto de APIs nativas do .NET para acessar banco de dados diretamente. Sem abstrações pesadas. Sem mágica.

👉 Resultado: máxima performance e controle absoluto.

Quando faz sentido usar?

Use ADO.NET quando:

Performance é crítica (ETL, alto volume, baixa latência)
Você precisa de controle fino sobre SQL e transações
Quer evitar dependências externas

Evite quando:

Precisa de produtividade rápida (CRUDs simples)
Não quer escrever mapeamento manual

Como funciona (essencial)

Os 3 principais componentes:

SqlConnection → abre conexão
SqlCommand → executa SQL
SqlDataReader → lê dados (streaming, rápido)

Exemplo direto:

using var connection = new SqlConnection(connectionString);
var command = new SqlCommand("SELECT Id, Nome FROM Clientes", connection);

connection.Open();

using var reader = command.ExecuteReader();
while (reader.Read())
{
    var id = reader.GetInt32(0);
    var nome = reader.GetString(1);
}

Sem ORM. Sem mapeamento automático. Só você e o banco.

Segurança básica (obrigatório)

Nunca faça isso:

$"SELECT * FROM Clientes WHERE Email = '{email}'"

Use parâmetros:

command.Parameters.AddWithValue("@Email", email);

👉 Evita SQL Injection e melhora cache de execução.

Performance: por que é tão rápido?

Sem reflexão
Sem geração de SQL
Leitura em streaming (DataReader)
Controle total de conexões

ETL? Aqui ele brilha

Para cargas massivas no SQL Server:

using var bulkCopy = new SqlBulkCopy(connection);
bulkCopy.DestinationTableName = "Clientes";
bulkCopy.WriteToServer(reader);

👉 Ordens de magnitude mais rápido que INSERT em loop

Comparação rápida

	ADO.NET	Dapper	EF
Performance	🔥 Máxima	Alta	Média
Controle SQL	Total	Total	Parcial
Facilidade	Baixa	Média	Alta

Regra prática

Quer controle e performance → ADO.NET
Quer equilíbrio → Dapper
Quer produtividade → EF

Insight final

Dominar ADO.NET muda seu nível como backend .NET.

Você passa a entender o que realmente acontece entre sua aplicação e o banco.

E isso impacta diretamente em performance, custo e escalabilidade.

Link para o repo.

BrunoSFreschi / DataAccess.Benchmark

DataAccess Benchmark é um laboratório de engenharia de software criado para analisar, o custo das diferentes abordagens de acesso a dados no ecossistema .NET.

DataAccess Benchmark

Ao estudar performance, não estamos apenas medindo tempo de execução Estamos observando a história da engenharia de software se manifestando em código.

Este repositório foi criado para demonstrar, de forma prática, a evolução das abordagens de acesso a dados no ecossistema .NET, comparando:

ADO.NET (baixo nível, controle total)
Dapper (micro-ORM, performance com praticidade)
Entity Framework Core (ORM completo, foco em produtividade)

Tudo medido com precisão usando BenchmarkDotNet, a ferramenta padrão para benchmarks profissionais em .NET.

Este projeto não é apenas um teste Ele é um laboratório para entender como a engenharia de software evoluiu ao longo dos anos.

A História do Acesso a Dados no .NET

Assim como a POO surgiu da Crise do Software, as diferentes formas de acessar banco de dados surgiram de um problema recorrente:

Como acessar dados com segurança, performance e manutenibilidade ao mesmo tempo?

Durante a evolução do .NET, três…

View on GitHub

Por que eu começo 10 projetos e não termino nenhum?

Yuri Souza — Sun, 05 Apr 2026 23:48:52 +0000

Você já passou uma tarde inteira configurando um projeto novo, escolhendo a stack, criando o repositório, estruturando as pastas e sentiu que estava voando? Aquela sensação de que dessa vez vai ser diferente, que essa ideia é boa demais pra morrer na gaveta? Eu também. O problema é que dois dias depois eu estava fazendo exatamente a mesma coisa, só que com outra ideia.

Se você se identificou, esse artigo é pra você. Não porque eu tenho a solução mágica, mas porque finalmente entendi o mecanismo por trás disso. E entender já muda muita coisa.

O prazer de começar
O momento em que tudo desmorona
O objeto brilhante
A culpa que ninguém fala
Não é preguiça. É neurologia.
Conclusão

O prazer de começar

Tem algo muito específico que acontece quando você começa um projeto novo.

O problema ainda não existe de verdade. Tudo é possibilidade. Você ainda não encontrou o bug impossível de reproduzir, ainda não percebeu que a arquitetura que escolheu não escala, ainda não chegou na parte chata de fazer o CRUD de usuário pela décima vez na vida.

Nessa fase, o cérebro libera dopamina. Bastante. A antecipação de uma recompensa futura ativa os mesmos circuitos que uma conquista real. Ou seja: só de imaginar o projeto funcionando, você já sente parte da recompensa.

Isso explica o prazer visceral do setup. Escolher o nome do repositório, montar a estrutura de pastas, escrever o README antes de ter uma linha de código que funciona... tudo isso alimenta aquela sensação.

O problema? É que ela passa.

O momento em que tudo desmorona

Existe um ponto específico em todo projeto onde a magia some. Eu chamo de o vale do tédio.

É quando você já sabe o que precisa fazer, mas o trabalho deixou de ser estimulante. As decisões arquiteturais foram tomadas. O setup tá pronto. Agora é só... executar. Implementar a feature chata. Escrever o teste. Lidar com o caso que você não previu.

Para a maioria das pessoas, esse momento é desconfortável mas passável. Você empurra, entrega, segue.

Para alguns cérebros, incluindo o meu, esse momento é quase fisicamente doloroso. Não é falta de vontade. É que o sistema de recompensa do cérebro simplesmente não libera o combustível necessário pra continuar uma tarefa que deixou de ser nova.

E aí começa o ciclo de autos sabotagem mais clássico do mundo do dev:

"Antes de continuar, vou refatorar essa parte aqui."

"Preciso repensar a arquitetura antes de avançar."

"Deixa eu criar um boilerplate melhor pra usar nos próximos projetos."

Você não está sendo preguiçoso. Você está inconscientemente procurando a dopamina do recomeço dentro do próprio projeto.

O objeto brilhante

E então aparece. Uma ideia nova.

Pode ser um problema que você viu no trabalho, uma conversa no Twitter, um repositório no GitHub que te inspirou. De repente, aquela ideia nova parece muito mais interessante do que o projeto que você abandonou no vale do tédio.

E ela realmente é, pelo mesmo motivo que o projeto anterior era interessante no início. Ela ainda não tem o peso da implementação. Ainda não tem os bugs, as decisões difíceis, o trabalho repetitivo.

Esse fenômeno tem um nome informal: Síndrome do Objeto Brilhante. E ele é mais intenso em cérebros que têm dificuldade de regular dopamina naturalmente.

O que acontece na prática? O projeto antigo não morre oficialmente. Ele só vai pra uma pasta chamada projetos/ e fica lá, acumulando poeira junto com outros oito projetos que passaram pelo mesmo ciclo.

A culpa que ninguém fala

Aqui está a parte que eu não via ninguém discutir: a culpa.

Porque quando você abandona um projeto, você não apenas perde o projeto. Você coleciona evidência contra si mesmo.

"Eu nunca termino nada."
"Eu começo cheio de energia e nunca entrego."
"Por que eu deveria começar esse projeto se vou abandonar igual aos outros?"

E essa narrativa é perigosa por dois motivos.

Primeiro, porque ela não é completamente verdadeira. Você provavelmente termina muita coisa, no trabalho, em tarefas com prazo real, em situações onde tem alguém esperando. O problema não é terminar em si. É terminar coisas que dependem 100% da sua motivação interna, sem deadline, sem stakeholder, sem pressão externa.

Segundo, você começa a acreditar que não é capaz de terminar, então para de tentar de verdade, e aí realmente não termina. O ciclo se fecha.

Não é preguiça. É neurologia.

Vou ser direto: se você se reconheceu em tudo que eu escrevi acima, há uma chance real de que seu cérebro simplesmente funciona de um jeito diferente da média.

Tem um tipo de cérebro que odeia repetição mas ama coisa nova. Não é fraqueza, é como ele funciona. O problema é que todo projeto tem uma fase nova e uma fase chata — e esse cérebro simplesmente apaga na segunda.

Não é falta de disciplina. É que o combustível que o seu cérebro usa pra manter o foco não funciona igual ao de todo mundo.

A diferença entre entender isso e não entender é enorme. Quando você não entende, você passa anos se achando preguiçoso, incompetente, incapaz de terminar o que começa e quando entende você começa a fazer perguntas diferentes:

"Como eu estruturo esse projeto pra ter recompensas menores e mais frequentes?"

"Como eu crio pressão externa pra compensar a falta de pressão interna?"

"Qual é o menor projeto possível que ainda entrega valor?"

Não são perguntas fáceis de responder. Mas são as perguntas certas.

Conclusão

Eu ainda começo projetos demais. Provavelmente sempre vou começar. Mas aprendi a parar de tratar isso como um defeito de caráter e passei a tratar como uma característica que precisa de estratégia.

O problema nunca foi a quantidade de projetos que eu começo. Foi a narrativa que eu construí em volta dos que eu não terminei.

Se você chegou até aqui e se reconheceu em alguma parte desse texto: você não está sozinho. E você provavelmente é melhor em começar coisas do que 90% das pessoas. Isso não é pouco, é uma habilidade real, que só precisa de direção.

O próximo projeto vai começar. A questão é o que você vai fazer diferente dessa vez.

Escrito por alguém que tem pelo menos dez pastas projetos/ abertas no VS Code agora mesmo.

O que uma usina nuclear tem a ver com o seu processo de QA?

Alicia Marianne 🇧🇷 — Sun, 05 Apr 2026 12:02:52 +0000

A gente sabe que testar e validar um software antes de ir para produção é importante. Mas você já parou para pensar no peso real que isso carrega?

Recentemente, estava revendo a série Chernobyl, e ela me fez refletir sobre muita coisa — especialmente sobre a forma como encaro minha área, sendo QA, e sobre a responsabilidade que ela traz. Resolvi compartilhar isso com vocês.

Para quem não conhece, Chernobyl é uma minissérie dramática lançada em 2019 que retrata o desastre nuclear ocorrido na usina de mesmo nome, na então União Soviética, em 26 de abril de 1986. A história acompanha os eventos logo após a explosão do reator número 4 — o caos, as tentativas do governo soviético de esconder a gravidade do acidente e o enorme esforço de cientistas, bombeiros, militares e trabalhadores que arriscaram, e muitas vezes perderam, suas vidas para evitar uma catástrofe ainda maior. A série também segue o cientista Valery Legasov, que tenta descobrir a verdadeira causa do acidente e expor a verdade por trás da tragédia.

Mas o ponto aqui vai além da série.

O que mais me chamou atenção foi o quanto aquela tragédia conversa com algo que vivemos diariamente no desenvolvimento de software: a responsabilidade nas decisões.

O que aconteceu em Chernobyl?

Mesmo sabendo que existem elementos dramatizados, dá para aprender muita coisa com esse desastre. Não sou física nuclear, mas vou tentar resumir o que aconteceu — porque foi justamente essa parte que mais me fez refletir sobre responsabilidade e tomada de decisão.

Na madrugada do dia 26 de abril de 1986, os operadores da usina realizavam um teste de segurança no reator 4. O objetivo era validar se, em caso de queda de energia, as turbinas ainda conseguiriam gerar eletricidade por alguns segundos — tempo suficiente até que os geradores de emergência fossem acionados. No papel, o teste parecia simples.

O problema é que, para executá-lo, diversos sistemas de segurança foram desativados e a potência do reator foi reduzida para um nível muito abaixo do ideal. Foi aí que tudo começou a sair do controle.

O reator utilizado era do tipo RBMK, um modelo com uma falha crítica de projeto: em determinadas condições, quanto mais vapor era gerado dentro do sistema, maior ficava a potência do reator. Em vez de estabilizar, ele se tornava cada vez mais instável. Para piorar, o teste foi conduzido sob forte pressão da liderança, mesmo diante de sinais claros de que não era seguro continuar.

Ao longo da série, vemos os próprios operadores levantando preocupações — que foram ignoradas. Quando perceberam que a situação era crítica, acionaram o botão de desligamento de emergência. Em teoria, esse comando deveria encerrar a reação. Mas, por uma falha no design das barras de controle, o efeito inicial foi o oposto: a potência disparou. Em poucos segundos, temperatura e pressão subiram de forma descontrolada.

O resultado foram duas explosões que destruíram o topo do reator, expuseram o núcleo à atmosfera e liberaram uma enorme quantidade de material radioativo. O incêndio que se seguiu espalhou radiação por boa parte da Europa, transformando Chernobyl no maior desastre nuclear da história.

O que mais me impactou foi perceber que a tragédia não aconteceu por um único erro. Ela foi consequência de uma cadeia de decisões ruins: falhas técnicas ignoradas, riscos mal avaliados e pessoas que não foram ouvidas.

E o que isso tem a ver com software?

Depois de assistir à série, comecei a fazer um paralelo com a nossa área. Porque, no fim, quantas vezes um incidente em produção também não nasce da mesma forma?

Nem sempre o problema vem de um único bug. Muitas vezes, ele é o resultado de uma sequência de decisões tomadas sem o devido cuidado: um requisito mal definido, um risco não mapeado, uma validação superficial, uma entrega apressada — ou um alerta levantado pelo time que acabou sendo ignorado.

Foi aí que a série me fez enxergar algo que vai além do contexto dela: quando a pressa fala mais alto do que a análise, o custo quase sempre aparece depois.

O maior problema: risco tratado de forma rasa

Um dos maiores desafios que vejo hoje no desenvolvimento de software é justamente o planejamento e o levantamento de riscos feitos de maneira superficial.

Tenho certeza de que você vai concordar: não tem coisa pior do que refazer algo ou ficar apagando incêndios que poderiam ter sido discutidos antes.

Vivemos num mundo onde tempo é dinheiro. E é exatamente por isso que qualidade precisa estar presente desde o início — não como uma etapa final, mas como parte do processo.

Como QA, vou compartilhar duas coisas que considero essenciais.

Ouça sua equipe

Independentemente da sua posição no time, ouça as pessoas ao seu redor.

Ninguém conhece melhor o produto do que quem o construiu, testou e convive com ele diariamente. Antes de uma nova funcionalidade entrar ou de um teste ser executado, converse com o time.

Escute quem desenvolveu. Escute o produto. Escute suporte. Escute quem está mais próximo do usuário.

Muitas vezes, o risco já foi identificado por alguém. Ele só não foi ouvido.

Analise antes de agir

Entender o impacto de uma mudança não é só uma questão técnica — é também uma questão de negócio.

Por exemplo: você vai melhorar a query de uma API. Em teoria, isso pode não alterar nenhuma regra de negócio. Mas como isso afeta o usuário final? A performance realmente melhorou? Existe algum impacto colateral? Como vamos medir se essa mudança foi positiva ou negativa?

Nem toda melhoria técnica gera melhoria de produto. E esse olhar crítico é parte fundamental do papel de QA.

Conclusão

No fim, Chernobyl me fez refletir sobre algo que vai muito além de uma série: a responsabilidade por trás de cada decisão que tomamos no dia a dia.

A gente não está lidando com um reator nuclear. Mas ainda assim lida com impacto real — no usuário, no negócio e no próprio time. Um risco ignorado, um teste mal planejado ou uma decisão tomada sem ouvir a equipe podem não gerar uma catástrofe, mas certamente geram problemas que poderiam ter sido evitados com mais atenção, diálogo e análise.

Para mim, ser QA vai muito além de encontrar bugs.

É questionar antes que o problema aconteça. É analisar cenários com olhar crítico. É antecipar riscos. É provocar conversas importantes dentro do time. É ajudar a construir decisões mais seguras e conscientes.

No final, qualidade não é apenas sobre software funcionando.

É sobre responsabilidade, colaboração e cuidado com tudo aquilo que criamos.

De front-end para UX, e de volta ao código: o que significa ser Design Engineer em 2026

vitoriazzp — Fri, 03 Apr 2026 13:00:00 +0000

Sou UX/UI designer, mas antes disso fui front-end.

Atuei cerca de 5 anos trabalhando com HTML e CSS, transformando layouts em páginas, entendendo hierarquia de informação e estrutura de interface. Depois, tomei o caminho oposto: migrei para UX/UI e agora completo 5 anos atuando em produtos, passando por fintech, utilities e atuando como Product Designer.

Essa trajetória, de front para UX e agora voltando a se aproximar do código, é justamente o que me levou a me reconhecer em um termo que gosto bastante: Design Engineer.

Minha trajetória: 5 anos de front-end, 5 anos de UX

Quando era front-end, eu via a tela como um resultado de código: HTML estruturando a informação, CSS dando forma e layout, um pouco de JavaScript dando comportamento.

Quando migrei para UX, passei a olhar mais para o todo do produto: pesquisa, fluxos, contexto do usuário, design systems, governança, revisão de interfaces, conversa com times de produto e de negócios.
Hoje, percebo que essas duas visões não são opostas. Elas se completam.

O que é design engineer em 2026?

Se você pesquisar sobre "Design Engineer", vai encontrar muitas definições técnicas, mas na prática o que mais faz sentido para mim é:

A pessoa que entende UX, código e um pouco de backend ao mesmo tempo, e usa isso para desenhar interfaces que são pensadas desde o primeiro pixel até a última chamada de API.

Não é só "quem desenha + quem programa"
É quem pensa em experiência e implementação juntas:

Um botão que não só parece bem-desenhado, mas também considera estados de loading, erro, disabled.
Um fluxo de cadastro que não só é bonito, mas que já prevê o que o backend vai precisar para validar, salvar e devolver feedback.
Um produto que pensa em performance, acessibilidade e usabilidade em uma única conversa.

Como front-end e UX mudam sua forma de ver produto

Como eu via a tela como desenvolvedor front-end
HTML estruturando a informação. CSS dando forma. Um pouco de JavaScript dando comportamento. A tela era resultado direto do código.

O que mudou quando migrei para UX/UI
Passei a olhar para o produto como um todo: pesquisa, fluxos, contexto do usuário. O código virou uma consequência, não o ponto de partida.

O que muda agora é que percebo que não preciso mais ficar só de um lado

Por que estou voltando ao código agora

Com o avanço de ferramentas como IA integrada ao Figma, prototipagem cada vez mais próxima do código e experiências acumuladas como Product Designer, foi aí que o conceito de Design Engineer passou a fazer sentido de verdade pra mim.

JavaScript moderno, React e um pouco de backend
Comecei a estudar de forma mais focada para:

Atualizar meu JavaScript (ES2024, async/await, fetch, arrays/objetos)
Reativar React (componentes, hooks, estado compartilhado)
Entender backend leve (Node/Express, rotas simples, persistência básica)
Pensar em performance e otimização das interfaces que ajudo a construir

Como estou usando IA no processo de aprendizado

Hoje, uso o Claude AI não como substituto, mas como apoio para:

Quebrar problemas de código em etapas menores
Revisar fluxos de dados entre front e backend
Organizar pensamentos e lógica de features

Design Engineer não é um cargo. É uma forma de pensar

O que mais gosto de dizer é que, em 2026, Design Engineer não é só um título de empresa grande ou de time específico. Pode existir em qualquer lugar onde UX e código se encontram:

Em um produto próprio
Em um projeto freelancer
Em um repositório público
Em um fluxo de trabalho híbrido, mesmo sem ter um cargo oficial com esse nome

O que importa é a maneira de pensar: UX + código ao mesmo tempo. Protótipos e implementação como parte do mesmo processo. Interfaces que consideram o que o usuário sente e o que o backend precisa.

O que vem por aí: UX data-driven e componentes React

Esse movimento não é só "voltar" ao front-end. É re-aprender JavaScript, entender melhor React e backend, e levar essa visão de UX para dentro do código.
Em breve, quero escrever mais sobre:

Como transformo um fluxo de UX do Figma em componentes React
Como penso em performance e carregamento em UX para web
Como organizar estudos de UX + código em ciclos curtos e práticos

E numa parte que ainda não me sinto confortável, mas sei que é essencial: vou falar sobre como estou começando a me tornar uma UX mais data-driven, porque ser Design Engineer em 2026 também é aprender a ouvir o que os números dizem sobre o UX que eu desenho.

Você também está nesse meio-termo entre UX e código?

Se você chegou até aqui, é bem provável que também se sinta em algum meio-termo entre UX e código.

Que tal comentar:

Como você se vê hoje entre design e desenvolvimento?
Você já tentou voltar pro código depois de virar UX, ou está no caminho invertido?

Esse é o tipo de conversa que me ajuda a entender como o conceito de Design Engineer está se moldando, bem além de títulos de empresa.

Construí um gerador de playlists no Spotify com Claude

Leo Garcez — Tue, 24 Mar 2026 02:01:08 +0000

Eu queria digitar “noite chuvosa, meio melancólica” e receber uma playlist perfeita. Então eu construí isso.

TL;DR

Eu construí um gerador de playlists com IA usando Claude + Spotify API
Você descreve um humor → ele gera 50 músicas → salva direto no Spotify
O maior problema foi OAuth local com NextAuth (sim, foi um inferno)
Claude funciona bem, mas precisa de bastante controle pra não inventar músicas
Streaming com SSE melhorou muito a UX

Links:

Índice

A Ideia
A Stack
O Problema de Trabalhar com OAuth Localmente
Endpoints Deprecated do Spotify
Spotify em Produção
Fazendo o Claude Obedecer
Prompt Engineering Anti-Alucinação
Modo Related Artists
Construindo o Perfil Musical
Streaming com SSE
O Que Aprendi

A Ideia

Fazer um gerador de playlists que realmente entendesse vibes, não só tags de gênero. Algo tipo: você digita "tarde fria num apartamento vazio" e recebe uma playlist boa de verdade, já salva no seu Spotify.

O conceito:

Usuário descreve um humor
Claude retorna 50 músicas em JSON
App busca cada faixa no Spotify
Cria e salva a playlist na conta do usuário

Três APIs, um app.

A Stack

Next.js 14 (App Router)
NextAuth v5 beta
Anthropic Claude API (claude-sonnet-4-6)
Spotify Web API
Supabase (PostgreSQL)
TypeScript + Tailwind CSS + Framer Motion

Escolhi o Claude porque ele tá bem em alta agora e, na prática, é confiável, alucina menos do que eu esperava pra esse tipo de tarefa. Ele é um pouco menos criativo que o GPT nas recomendações, mas compensa sendo mais previsível no formato das respostas, o que importa bastante quando você tá parseando JSON.

O Problema de Trabalhar com OAuth Localmente

Isso me custou algumas horas e sessões de debug. Vou detalhar porque tem várias camadas de problema e você provavelmente vai bater na mesma parede se estiver usando NextAuth v5 com Spotify.

O Spotify não aceita `localhost`

O Spotify proíbe localhost como redirect URI pra URIs de loopback. A solução é usar 127.0.0.1. Cadastrei http://127.0.0.1:3000/api/auth/callback/spotify no dashboard e setei AUTH_URL=http://127.0.0.1:3000 no .env.local.

Não foi suficiente.

O `NextRequest` normaliza URLs pra `localhost`

O Next.js, independente do host que você passa pra next dev -H, normaliza req.url e req.nextUrl.href de volta pra localhost em desenvolvimento. Isso não é bug documentado — é comportamento interno do framework.

O NextAuth v5 tem um utilitário chamado reqWithEnvURL que tenta corrigir exatamente isso, mas falha silenciosamente:

// Dentro do next-auth — simplificado
function reqWithEnvURL(req: NextRequest): NextRequest {
  const url = process.env.AUTH_URL ?? req.url;
  return new NextRequest(url, req); // ← o construtor normaliza de volta pra localhost
}

Mesmo passando 127.0.0.1 explicitamente, o construtor do NextRequest sobrescreve. A "correção" não funciona.

Dois momentos onde o redirect URI importa

O OAuth tem dois momentos distintos onde o redirect URI aparece:

Requisição de autorização — a URL do Spotify onde o usuário loga. O redirect_uri aqui vem dos seus params de configuração, então você pode hardcodar 127.0.0.1 na config do provider. Isso funcionou.
Troca de token — quando o Spotify manda o código de volta, o @auth/core envia um POST pra trocar o código por tokens. O redirect_uri nessa requisição vem de provider.callbackUrl, que é derivado de params.url.origin — ou seja, da URL da requisição de callback. Se essa URL ainda diz localhost, a troca falha com invalid_grant: Invalid redirect URI.

O sintoma era desconcertante: a URL de autorização mostrava 127.0.0.1 corretamente, mas a troca de token continuava falhando. Fui atrás do código do @auth/core pra entender o que tava acontecendo.

A solução: `Auth()` direto com `Request` nativo

Objetos Request nativos do browser/Node não normalizam URLs. A correção é contornar os route handlers do NextAuth e chamar Auth() do @auth/core diretamente, passando um Request nativo com a URL já corrigida:

// src/app/api/auth/[...nextauth]/route.ts
import { Auth } from "@auth/core";
import { authConfig } from "../../../../../auth";
import { NextRequest } from "next/server";

function buildRequest(req: NextRequest): Request {
  const authOrigin = process.env.AUTH_URL ?? `http://${req.headers.get("host")}`;
  const fixedUrl = req.url.replace(/^https?:\/\/[^/]+/, authOrigin);

  const hasBody = req.method !== "GET" && req.method !== "HEAD";
  return new Request(fixedUrl, {
    method: req.method,
    headers: req.headers,
    body: hasBody ? req.body : undefined,
    // duplex necessário para streaming de body no Node.js
    ...(hasBody && ({ duplex: "half" } as object)),
  });
}

const handler = (req: NextRequest) =>
  Auth(buildRequest(req), authConfig as Parameters<typeof Auth>[1]);

export { handler as GET, handler as POST };

Versão do @auth/core: ao usar Auth() diretamente, instale a versão exata que o next-auth usa internamente:

npm ls @auth/core  # veja qual versão o next-auth requer
npm install @auth/core@0.41.0 --save-exact

Versões diferentes criam conflitos de tipo que explodem em runtime.

Configuração explícita no auth.ts: ao contornar os handlers do NextAuth, setEnvDefaults não roda mais. Configure basePath, secret e redirect_uri explicitamente:

// auth.ts
export const authConfig: NextAuthConfig = {
  trustHost: true,
  basePath: "/api/auth",
  secret: process.env.AUTH_SECRET,
  providers: [
    Spotify({
      clientId: process.env.AUTH_SPOTIFY_ID,
      clientSecret: process.env.AUTH_SPOTIFY_SECRET,
      authorization: {
        url: "https://accounts.spotify.com/authorize",
        params: {
          scope: SPOTIFY_SCOPES,
          show_dialog: true,
          redirect_uri: `${process.env.AUTH_URL}/api/auth/callback/spotify`,
        },
      },
    }),
  ],
  // ... callbacks e pages como antes
};

Bônus: problema de domínio do cookie PKCE

Mesmo com tudo acima, pode acontecer mais uma falha: se o usuário acessa http://localhost:3000, o navegador seta o cookie PKCE pro domínio localhost. Quando o Spotify redireciona de volta pra http://127.0.0.1:3000/..., o navegador não envia o cookie — domínios diferentes — e o code_verifier some. A troca falha de novo.

A correção é garantir que localhost:3000 nunca apareça pro usuário, redirecionando via next.config.mjs:

async redirects() {
  return [
    {
      source: "/:path*",
      has: [{ type: "host", value: "localhost:3000" }],
      destination: "http://127.0.0.1:3000/:path*",
      permanent: false,
    },
    {
      source: "/",
      has: [{ type: "host", value: "localhost:3000" }],
      destination: "http://127.0.0.1:3000/",
      permanent: false,
    },
  ];
},

Com isso, todo o fluxo de auth fica em 127.0.0.1 e os cookies PKCE chegam onde precisam chegar.

Endpoints Deprecated do Spotify

Com o auth funcionando, bati num muro de 403s.

O Spotify deprecated alguns endpoints sem muito alarde:

Antigo (deprecated)	Novo
`POST /playlists/{id}/tracks`	`POST /playlists/{id}/items`
`GET /playlists/{id}/tracks`	`GET /playlists/{id}/items`
`GET /audio-features`, `GET /recommendations`	Deprecated, sem substituto

A migração /tracks → /items está documentada, mas é fácil de perder se você seguiu um tutorial de 2022. Audio features e recomendações sumindo foi mais chato — tive que construir contexto de energia de outra forma, mais sobre isso abaixo.

Spotify em Produção

Tem uma limitação que eu não vi muito discutida: no modo de desenvolvimento, o Spotify permite apenas 5 usuários autenticados E eles precisam ser adicionados manualmente via allowlist no dashboard.

Pra ir além disso, você precisa solicitar Extended Quota Mode. E o processo atual é bem pesado:

Entidade jurídica registrada (pessoa física não é aceita desde maio de 2025)
Serviço já lançado e ativo
Mínimo de 250.000 usuários ativos mensais
Viabilidade comercial

A análise pode levar até seis semanas, e sem garantia de aprovação.

Na prática, isso significa que se você tá construindo algo novo como indie dev, vai ficar travado em modo de desenvolvimento. Você consegue testar e mostrar pra até 4 pessoas além de você — e só. Vale saber disso antes de planejar algum lançamento público.

Fazendo o Claude Obedecer

O system prompt instrui o Claude a retornar apenas um array JSON, sem markdown, sem explicações. Essa parte é direta. O problema mais difícil é conseguir 50 faixas que realmente existam.

One-shot prompting

Incluir uma conversa de exemplo completa (usuário + assistente) antes do request real reduziu bastante os erros de formato, especialmente com artistas não-ingleses:

messages: [
  {
    role: "user",
    content: "Create a playlist for this mood/vibe: late night drive, nostalgic",
  },
  {
    role: "assistant",
    content: JSON.stringify([
      { title: "Drive", artist: "The Cars", reason: "Synth-pop clássico com energia perfeita de madrugada" },
      { title: "Running Up That Hill", artist: "Kate Bush", reason: "Art-pop etéreo, emocionalmente assombroso" },
      // ...
    ]),
  },
  { role: "user", content: actualUserMessage },
],

Extração de JSON como fallback

Mesmo com prompting cuidadoso, modelos eventualmente jogam texto de introdução. Sempre extraia o array:

const match = raw.match(/\[[\s\S]*\]/);
if (!match) throw new Error("Nenhum array JSON encontrado");
const suggestions = JSON.parse(match[0]);

Prompt Engineering Anti-Alucinação

Descobri que quanto mais músicas você pede, mais o modelo inventa títulos.

Pedindo 70 músicas, o Claude começa a criar faixas com nomes plausíveis que não existem. Com 50 e restrições explícitas, fica bem melhor.

O que adicionei ao system prompt:

EXISTÊNCIA NO SPOTIFY — CRÍTICO:
Cada música DEVE existir no Spotify. Antes de incluir uma faixa, pergunte:
"Tenho certeza que esta música existe no Spotify com este título e artista exatos?"
Se houver qualquer dúvida, escolha outra música que você tem certeza.

REGRAS DE FORMATO DO TÍTULO:
- Use apenas o título canônico limpo do lançamento
- SEM sufixos: sem "- Remastered", "- Live at...", "- Radio Edit"
- Use o nome do lançamento mais conhecido, não compilações

ARMADILHAS COMUNS DE ALUCINAÇÃO:
- Não invente títulos de músicas que parecem plausíveis mas podem não existir
- Não confunda dois artistas com nomes similares
- Não sugira deep cuts que você não tem certeza

Também removi a abordagem de duas etapas "gerar 70, refinar pra 50". Era cara em tempo e custo, e uma única geração de 50 com boas instruções performa melhor.

O system prompt atual completo

Esse é o prompt que tá rodando em produção hoje:

You are a world-class Spotify playlist curator.

GOAL:
Generate EXACTLY 50 high-quality songs for a playlist.

OUTPUT:
Return ONLY a raw JSON array. No markdown, no explanations.

Each item:
- "title": string — the canonical Spotify title, nothing else
- "artist": string — the primary artist exactly as listed on Spotify
- "reason": string — max 10 words

SPOTIFY EXISTENCE — CRITICAL:
Every song MUST exist on Spotify. Before including a track, ask yourself:
"Am I certain this song exists on Spotify under this exact title and artist?"
If there is any doubt, pick a different song you are certain about.

TITLE FORMAT RULES:
- Use the clean, canonical release title only
- NO suffixes: no "- Remastered", "- Live at...", "- Radio Edit", "- feat. X"
- NO parentheticals unless part of the official title
- Use the most well-known release name, not compilations or bonus versions

COMMON HALLUCINATION TRAPS TO AVOID:
- Do not invent song titles that sound plausible but may not exist
- Do not confuse two artists with similar names
- Do not suggest deep cuts you are uncertain about
- Do not suggest songs only released in specific regions unavailable globally

DISTRIBUTION:
- 50% recognizable hits (high confidence they exist)
- 40% lesser-known but confirmed tracks
- 10% deep cuts you are fully certain about

DIVERSITY:
- At least 2 genres
- At least 3 decades
- Non-English tracks welcome if you are certain they are on Spotify

CURATION:
- Cohesive flow, playlist-worthy, non-random
- No duplicates

Return ONLY the JSON array. Exactly 50 items.

Curiosidade: o prompt tá em inglês mesmo que o usuário escreva em português. O Claude entende o humor no idioma que vier e retorna os dados no formato esperado sem problema.

Melhor resolução de busca no Spotify

Mesmo com um bom prompt, algumas faixas voltam com títulos ou artistas levemente errados. Três ajustes no lado da busca:

1. Buscar 10 candidatos em vez de 1
Em vez de limit=1, buscar limit=10 e escolher o melhor match.

2. Filtro de popularidade
Pular resultados com popularity < 30 — evita gravar versões ao vivo obscuras quando a faixa correta não é encontrada:

const POPULARITY_FLOOR = 30;
const aboveFloor = candidates.filter(t => t.popularity >= POPULARITY_FLOOR);
const pool = aboveFloor.length > 0 ? aboveFloor : candidates;

3. Fuzzy matching + seleção por popularidade
Normalizar strings e verificar correspondência bidirecional de substring, depois escolher o match com maior popularidade:

function fuzzyMatch(candidate: SpotifyTrack, suggestion: ClaudeTrackSuggestion): boolean {
  const trackName = normalizeStr(candidate.name);
  const artistName = normalizeStr(candidate.artists[0]?.name ?? "");
  const sugTitle = normalizeStr(suggestion.title);
  const sugArtist = normalizeStr(suggestion.artist);
  const titleMatch = trackName.includes(sugTitle) || sugTitle.includes(trackName);
  const artistMatch = artistName.includes(sugArtist) || sugArtist.includes(artistName);
  return titleMatch && artistMatch;
}

Modo Related Artists

Playlists geradas por IA alucinam mais quando o humor é específico de artista — tipo "algo como Radiohead". Nesses casos, o grafo de artistas do próprio Spotify é mais confiável que o Claude.

Adicionei detecção automática: uma chamada rápida ao Claude Haiku (~0,5s) classifica o prompt antes da geração principal:

// Retorna { mode: "ai" | "related", artists: ["Radiohead", "Nick Cave"] }
const detected = await detectPlaylistMode(mood);

Se artistas são detectados, o app:

Os resolve no Spotify
Busca artistas relacionados (GET /artists/{id}/related-artists)
Pega top tracks de cada artista relacionado
Monta uma playlist com dados reais do Spotify, sem depender do Claude pra nada

Se não detectar artistas, cai pro fluxo normal com Claude.

if (detected.mode === "related" && detected.artists.length > 0) {
  const { suggestions, resolvedSeeds } = await buildRelatedArtistsPlaylist(
    detected.artists,
    accessToken,
    energy
  );
  if (suggestions.length > 0) {
    return NextResponse.json({ suggestions, mode: "related", seedArtists: resolvedSeeds });
  }
  // fallthrough para modo AI se não encontrou nada
}

Construindo o Perfil Musical

O app deixa usuários escolher uma playlist de referência ou seus top artistas do Spotify (último mês / 6 meses / histórico completo). Esse contexto é passado pro Claude como uma impressão digital musical.

Mandar nomes de faixas brutos confunde o modelo. Em vez disso, agregue num perfil:

// Contar frequência de artistas em todas as faixas da playlist
const artistFreq = new Map<string, { name: string; count: number }>();
for (const track of tracks) {
  const a = track.artists[0];
  const prev = artistFreq.get(a.id);
  artistFreq.set(a.id, { name: a.name, count: (prev?.count ?? 0) + 1 });
}

Pra playlists, também busco dados de gênero dos artistas principais via GET /artists/{id} (5 chamadas paralelas), já que os itens de playlist não retornam gêneros nativamente.

Mesmo sem seleção de referência explícita, o app passa os top artistas e gêneros baseline do usuário como contexto suave pra cada geração.

A instrução no prompt mudou de "não recomende esses artistas" pra algo mais útil:

→ Biase as recomendações em direção a este DNA musical: tempo, humor e estilo de produção similar.
→ Descubra artistas com som SIMILAR — não necessariamente os mesmos artistas.
→ NÃO repita faixas já listadas acima.

Streaming com SSE

O fluxo original: buscar todas as 50 faixas em paralelo, retornar tudo de uma vez, mostrar um spinner.

O problema é que o usuário ficava olhando "Salvando no Spotify..." por 5-10 segundos sem nenhum feedback. Server-Sent Events resolve isso — cada faixa é emitida conforme resolve:

// Na rota da API
const stream = new ReadableStream({
  async start(controller) {
    const send = (data: object) =>
      controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));

    await Promise.all(
      suggestions.map(async (suggestion) => {
        const track = await searchTrack(suggestion, accessToken);
        if (track) {
          foundTracks.push({ track, suggestion });
          send({ type: "track", track, suggestion }); // emitido imediatamente
        }
      })
    );

    // Criar playlist depois que todas as buscas terminam
    const playlist = await createPlaylist(...);
    send({ type: "done", playlist, found: foundTracks.length });
    controller.close();
  },
});

return new Response(stream, {
  headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
});

A busca paralela continua na velocidade máxima. Mas agora o cliente vê cada faixa aparecer com album art conforme resolve, com uma barra de progresso ao vivo — em vez de um spinner em branco por 10 segundos.

O Que Aprendi

Sobre prompt engineering:

Menos é mais (50 > 70)
Exemplos one-shot (par de mensagens usuário + assistente) são mais confiáveis que instruções de formato detalhadas.
Dizer o que não fazer funciona muito bem
Contexto de perfil funciona melhor como guia de DNA musical, não como lista de restrições.

Sobre a API do Spotify:

Sempre verifique se o endpoint ainda é atual. /tracks → /items, audio features sumiu, recomendações sumiram.
GET /artists/{id}/related-artists funciona bem pra descoberta e quase ninguém usa.
O score de popularidade nas faixas é um bom proxy pra "essa faixa existe como esperado."

Sobre streaming no Next.js:

ReadableStream + text/event-stream funciona limpo no App Router.
Promise.all + emit-on-resolve te dá paralelismo real com UI progressiva de graça.

Sobre Next.js + OAuth:

NextRequest normaliza URLs pra localhost em desenvolvimento, mesmo que você passe 127.0.0.1 explicitamente. Use Request nativo quando a URL importa.
O NextAuth v5 tem um utilitário reqWithEnvURL que tenta corrigir isso mas usa new NextRequest() internamente — que normaliza de novo. A correção do framework não funciona.
O OAuth tem dois momentos onde o redirect_uri é verificado: na requisição de autorização e na troca de token. Você precisa garantir que os dois mostrem 127.0.0.1.
provider.callbackUrl é derivado da URL da requisição de callback — não da sua config. Se a URL da requisição ainda diz localhost, a troca falha com invalid_grant.
Ao usar Auth() do @auth/core diretamente, pin a versão exata que o next-auth requer. Versões diferentes causam conflitos de tipo em runtime.
Cookies PKCE são scopados por domínio. Se o usuário começa em localhost e o callback chega em 127.0.0.1, o code_verifier some. Redirecione todo o tráfego de localhost pra 127.0.0.1 no next.config.mjs.
NextAuth v5 é poderoso mas a documentação beta é bem escassa. Ler o código-fonte do @auth/core foi necessário pra entender o que estava acontecendo.

Teste Você Mesmo

O app se chama Moodify. Está OpenSource no GitHub. Se você tá fazendo algo parecido, espero que ajude um pouco.

Como vocês melhorariam esse prompt? Se alguém já passou por algo parecido ou tiver ideias, comenta aí

Construído com Next.js, Claude API, Spotify Web API e Supabase. Deploy no Vercel.

Engenharia de Prompt: Por Que a Forma Como Você Pergunta Muda Tudo(Um guia introdutório)

Fran Borges — Mon, 23 Mar 2026 16:20:34 +0000

Neste artigo irei explicar alguns pontos importantes sobre Engenharia de prompt, e como saber esses pontos pode te ajudar muito no dia a dia lidando com IAs, no seus estudos, pesquisas, trabalho, vibeconding, whatever.

Prefácio
Antes de tudo, para lembrar, o que é uma LLM mesmo?
Fazendo Perguntas
- 1 - Evite a Ambiguidade
- 2 - Delimite o Escopo
- 3 - Forneça Contexto Relevante
Considerações Finais

Prefácio

A base do conhecimento é necessária em tudo que se quer aprender, com LLMs não é diferente. Analisando padrões, conversando com amigos, observei que a grande parte das pessoas que usam LLMs no dia a dia de trabalho, estudo, pessoas que trabalham com tecnologia e principalmente quem está começando na área tech, não tem ideia de como a LLM funciona e de como fazer as perguntas e tirar dúvidas de forma certa para um ChatGPT da vida.

Tendo isso em vista, e como venho estudando bastante sobre esse assunto, como forma de compartilhar o conhecimento, já dizia a poetisa brasileira Cora Coralina: "Feliz aquele que transfere o que sabe, e aprende o que ensina", farei uma série de artigos explicando sobre o tema, e esse é só o primeiro deles...

Antes de tudo, para lembrar, o que é uma LLM mesmo?

A LLM pode ser definida de algumas formas. Uma delas é: "São modelos de linguagem de máquina, que usam algoritmos de aprendizado profundo (Deep Learning) para processar e aprender a linguagem natural", essa é a sua definição estrutural. A definição que mais gosto é: "A LLM, na sua essência, é composta por dois arquivos: um contendo os pesos (parâmetros) com os conhecimentos aprendidos, e o outro com o código necessário para rodar os dados aprendidos.", como uma pessoa visual, consigo imaginar melhor como funciona.

Então, ChatGPT, Claude e muitos outros são exatamente isso, e atualmente têm a capacidade de executar várias atividades, como escrever código, traduzir texto, responder às mais variadas dúvidas e, dependendo da sua capacidade de escrever prompts mais robustos, pode até criar arquiteturas de produtos, te ajudar a resolver bugs complexos, te dar ideias, e até criar um SaaS revolucionário (risos).

O ponto é que a capacidade das LLMs de "compreender" e "criar" chegou a um ponto bem avançado, e você só chega na camada -17 de boas respostas fazendo as perguntas de forma certa!

Nota: Camada -17 se refere à camada onde se acha o minério de ouro no jogo Minecraft ;).

Fazendo Perguntas

Como fazer as perguntas certas? E por que saber isso importa? Vamos lá.

Saber fazer as perguntas certas para uma LLM é tão importante que existe uma área da tecnologia específica só para isso: a Engenharia de Prompts, definida como "a ciência empírica de planejar, criar e testar prompts para gerar melhores respostas em LLMs". Saber fazer as perguntas certas te coloca em outro nível, você consegue obter as melhores respostas, e isso te traz muitos ganhos, sendo o principal deles a produtividade.

Mas afinal, como perguntar de forma certa?

A LLM é poderosa, mas não adivinha sua intenção. Para obter os melhores resultados nas suas buscas, você precisa se concentrar na criação de prompts claros, na especificidade e ser rico em dar contexto. E tudo isso envolve:

1 - Evite a Ambiguidade

"Espaço de possibilidades"

Quando você escreve um prompt muito ambíguo, vago, o modelo enxerga vários caminhos estatisticamente válidos. É como se ele estivesse numa encruzilhada com 50 estradas e todas tivessem placas dizendo "Talvez por aqui", ele vai escolher uma, mas não necessariamente a que você precisa: a estrada com o percurso mais rápido e sem trânsito (a resposta correta de fato).

Exemplos:

Prompt ambíguo:

"Crie uma API."

O que a LLM "vê": Vários caminhos, API REST? GraphQL? Em qual linguagem? Para qual domínio? Com autenticação? Com banco? O modelo vai escolher o caminho mais estatisticamente comum nos dados de treino (provavelmente uma API REST genérica em Node.js com Express), que pode não ter nada a ver com o que você precisa.

Prompt sem ambiguidade:

"Crie um microsserviço em Node.js com Express e TypeScript para processar pagamentos via
Stripe. Endpoints: criar pagamento, confirmar webhook e consultar status. O payload tem:
orderId(UUID), amount(number), currency(enum: BRL, USD) e customerId(string).
Use zod para validação, Prisma com PostgreSQL para persistir as transações e winston
para logs. Retorne status codes apropriados como(201, 200, 400, 422, 500). Trate falhas de
rede com retry automático (máx. 3 tentativas)."

O que a LLM "vê": Um caminho quase único. Cada detalhe funciona como uma restrição que elimina ambiguidade: "Node.js com Express e TypeScript" define runtime, framework e linguagem de uma vez. "Pagamentos via Stripe" restringe o SDK e o domínio. "3 endpoints explícitos + payload com tipos" elimina adivinhações sobre rotas e schema. "Zod, Prisma, PostgreSQL, Winston" travam a stack, o modelo não vai sugerir alternativas. "Status codes específicos + retry com máximo de 3 tentativas" definem os status HTTP e a estratégia com limites claros. A distribuição de probabilidade fica concentrada e o modelo praticamente "só tem uma opção" a cada token gerado.

2 - Delimite o Escopo

"Janela de atenção"

LLMs têm um context window(Janela), uma quantidade de tokens (pedaço de palavra) que conseguem ser processados de uma vez. Isso inclui o seu prompt e a resposta gerada. Dentro dessa janela, existe um fenômeno importante: nem todos os tokens recebem a mesma "atenção" no processamento.

O mecanismo de self-attention (o coração da arquitetura Transformer, não é um cubo rsrsrs, e a arquitetura de rede neural, que seria o framework da LLM se a mesma fosse uma linguagem de programação), ela define a estrutura de tudo, calcula relações entre todos os tokens do prompt. Quanto mais tokens irrelevantes existem, mais o modelo precisa "dividir atenção" entre informações úteis e inúteis.

Exemplos:

Sem escopo:

"Me ensine Docker."

O que acontece internamente: O modelo precisa decidir entre centenas de subtópicos, instalação, conceitos básicos, Dockerfile, docker-compose, volumes, orquestração, a atenção se fragmenta e o resultado é um overview superficial de tudo.

Com escopo:

"Explique o conceito de multi-stage build no Docker para um dev backend pleno que já usa
Docker no dia a dia mas nunca otimizou o tamanho das imagens. Mostre um exemplo prático
com uma aplicação JavaScript, comparando o Dockerfile sem e com multi-stage build,
incluindo o tamanho final de cada imagem."

O que acontece internamente: O mecanismo de atenção se concentra em uma região muito específica, a interseção entre "Docker", "multi-stage build", "otimização de imagem" e "JavaScript". Os pesos de atenção ficam fortemente direcionados.

3 - Forneça Contexto Relevante

"Estado da aplicação"

Uma LLM é stateless por natureza, ela não tem memória entre requisições. Cada prompt é processado do zero, o único "estado" que ela tem é o que você coloca no prompt. Isso significa que todo contexto que você não fornece simplesmente não existe para o modelo.

Internamente, o contexto funciona como um sistema de pesos no mecanismo de atenção. Quando você adiciona informações, elas criam "âncoras" que influenciam a distribuição de probabilidades de todos os tokens subsequentes, é como se cada pedaço de contexto fosse um ímã que puxa a resposta para uma direção específica.

Exemplos:

Sem contexto:

"Revise meu código."

O que a LLM faz: Sem saber a linguagem, o framework, o nível do dev, o objetivo do código, o padrão do time ou o tipo de revisão esperada, ela vai fazer comentários genéricos: "adicione tratamento de erro", "use nomes mais descritivos", "considere adicionar testes".

Com contexto:

"Revise este endpoint Node.js com Express que lida com upload de arquivos para o S3.
O time usa ESLint + Prettier, então ignore estilo. O padrão do time é async/await com
try/catch e erros customizados. Endpoint em produção, recebe 200 uploads/min.
Foque em: memory leaks, tratamento de erros e uso correto do SDK do S3."

O que a LLM faz: Cada informação do prompt funciona como um filtro que elimina ruído e concentra a revisão: "Node.js com Express + upload para S3" ativa conhecimento específico sobre streams, buffers, multipart e AWS SDK. "ESLint + Prettier, ignore estilo" elimina os comentários possíveis que o linter já resolve. "async/await com erros customizados" faz o modelo pular sugestões que o time já aplica e focar em como estão sendo usadas. "Produção, 200 uploads/min" muda o peso de cada problema, um buffer não liberado que seria aceitável em dev vira um incidente crítico sob carga. "Foque em: memory leaks, erros, SDK S3" restringe a revisão a 3 eixos e ignora dezenas de outros tópicos.

Com base nisso, saber as limitações do modelo que você está usando, te ajuda também a entender até aonde você pode ir nas perguntas e inferências, então escolha a sua melhor IA, treine ela, faça as suas perguntas, teste, tente! ;)

É Lembre-se: a LLM não "pensa", ela calcula probabilidades!

Considerações Finais

É isto, tentei resumir cada ponto que achei interessante abordar e explicar nessa primeira etapa, mas há muito mais sobre engenharia de prompt de LLM para falar, como técnicas mais clássicas de engenharia de prompts(Zero-shot prompting, Role prompting), técnicas mais avançadas(Chain-of-Thought (CoT), Prompt Chaining), são muitas camadas que tentarei destrinchar nos próximos artigos, esse é apenas o primeiro que traz a minha volta para a escrita de artigos após alguns bons anos. Espero que você caro leitor tenha entendido e aprendido algo. Obrigado por ler até aqui. ;)

Onde me encontrar:

Meu LinkedIn
Meu GitHub

Do commit ao deploy: CI/CD de uma API na AWS usando GitHub Actions, ECS e Terraform

Fernando Andrade — Thu, 12 Mar 2026 00:07:27 +0000

Sumário

Introdução
Pré-requisitos
Visão Geral da Arquitetura
Configurando o IAM para o Terraform
Infraestrutura como Código com Terraform
- Recursos Provisionados
- IAM Role para Tarefas ECS
- Task Definition (Fargate)
- ECS Service
- OIDC: Autenticação Sem Credenciais Estáticas
Dockerfile Multi-Stage
Pipeline de CI
Protegendo a Branch Main
Configurando as Secrets no GitHub
Pipeline de CD
Acessando a Aplicação após o Deploy
Segurança: OIDC em Detalhe
Fluxo Completo: Do Commit ao Deploy
Considerações Finais

Introdução

Colocar uma aplicação em produção vai muito além de escrever código. Envolve compilar, testar, empacotar e entregar de forma confiável e repetível. Neste artigo, vou mostrar como construir uma pipeline completa — do commit ao deploy — usando GitHub Actions para CI/CD, Terraform para infraestrutura como código e AWS (ECR, ECS Fargate) como plataforma de execução.

O conceito apresentado aqui é agnóstico de linguagem — funciona para qualquer stack que rode em um container Docker (Node.js, Go, Java, Python, etc.). Para os exemplos práticos, vamos utilizar .NET como referência, mas os workflows, a infraestrutura Terraform e o fluxo de deploy são os mesmos independente da tecnologia escolhida.

O objetivo é demonstrar como essas ferramentas se conectam para formar um fluxo automatizado onde um simples merge na branch main resulta em uma nova versão rodando em produção, sem intervenção manual.

Pré-requisitos

Antes de começar, você precisa ter as seguintes ferramentas instaladas e configuradas:

Ferramenta	Descrição	Link de instalação
Docker	Para construir e executar containers	docs.docker.com/get-docker
Terraform	Para provisionar infraestrutura como código	developer.hashicorp.com/terraform/install
AWS CLI	Para interagir com os serviços da AWS via terminal	docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html
Git	Para versionamento de código	git-scm.com/downloads
Conta AWS	Com permissões para criar recursos (IAM, ECS, ECR)	aws.amazon.com/free
Conta GitHub	Para hospedar o repositório e rodar os workflows	github.com

Nota: Para o exemplo deste artigo, também é necessário o .NET SDK instalado localmente para desenvolvimento. Se você estiver usando outra stack, substitua pelo SDK correspondente (Node.js, Go, JDK, etc.). Outro ponto é que a escolha em utilizar o ECS ao invés de um EKS ou EC2 é devido sua simplicidade na curva de aprendizado, baixo gerenciamento e que para fins de aprendizado os recursos mínimos definidos para esse laboratório não gerem altos gastos para o aprendizado.

Visão Geral da Arquitetura

O fluxo completo funciona assim:

Developer → Feature Branch → Pull Request → Validação (CI)
                                                  ↓
                                            Merge na main
                                                  ↓
                                         Build & Push (CD)
                                                  ↓
                                        Deploy no ECS Fargate

Configurando o IAM para o Terraform

Antes de rodar qualquer terraform apply, é necessário que o Terraform tenha permissões para criar recursos na AWS. Para isso, precisamos de um usuário IAM (ou role) com as permissões adequadas e configurar suas credenciais localmente.

Criando um usuário IAM para o Terraform

No console da AWS (IAM > Users), crie um usuário dedicado para o Terraform:

Acesse IAM > Users > Create User
Nomeie o usuário (ex: terraform-deployer)
Anexe as policies necessárias para os recursos que serão criados:

AmazonECS_FullAccess
AmazonEC2ContainerRegistryFullAccess
AmazonVPCReadOnlyAccess
IAMFullAccess
CloudWatchLogsFullAccess
AmazonS3FullAccess

Nota de segurança: Em um ambiente produtivo, o ideal é criar uma policy customizada com o princípio do menor privilégio, concedendo apenas as permissões estritamente necessárias. Para fins de estudo, as managed policies acima simplificam o setup.

Após criar o usuário, gere um Access Key (IAM > Users > Security credentials > Create access key)
Selecione o caso de uso Command Line Interface (CLI)

Configurando as credenciais localmente

Com o AWS CLI instalado, configure as credenciais:

aws configure

Será solicitado:

AWS Access Key ID: AKIA...
AWS Secret Access Key: wJal...
Default region name: us-east-1
Default output format: json

Isso cria o arquivo ~/.aws/credentials que o Terraform utilizará automaticamente via o provider AWS. Com isso feito, o Terraform tem autorização para provisionar os recursos que definiremos a seguir.

Infraestrutura como Código com Terraform

Antes de qualquer pipeline rodar, a infraestrutura precisa existir. Com o Terraform, declaramos todos os recursos AWS em arquivos .tf e provisionamos com um único comando.

Recursos Provisionados

# Provider AWS
provider "aws" {
  region = "us-east-1"
}

# Repositório ECR para armazenar imagens Docker
resource "aws_ecr_repository" "app_repository" {
  name = "minha-app-repository"
}

# Cluster ECS
resource "aws_ecs_cluster" "app_cluster" {
  name = "minha-app-cluster"
}

IAM Role para Tarefas ECS

O ECS precisa de uma role para puxar imagens e enviar logs:

resource "aws_iam_role" "ecs_task_execution_role" {
  name = "ecs-task-execution-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Action    = "sts:AssumeRole"
      Effect    = "Allow"
      Principal = { Service = "ecs-tasks.amazonaws.com" }
    }]
  })
}

resource "aws_iam_role_policy_attachment" "ecs_policy" {
  role       = aws_iam_role.ecs_task_execution_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
}

Task Definition (Fargate)

Aqui definimos como o container será executado:

resource "aws_ecs_task_definition" "app_task" {
  family                   = "minha-app-task"
  network_mode             = "awsvpc"
  requires_compatibilities = ["FARGATE"]
  cpu                      = "256"
  memory                   = "512"
  execution_role_arn       = aws_iam_role.ecs_task_execution_role.arn

  container_definitions = jsonencode([{
    name      = "app"
    image     = "${aws_ecr_repository.app_repository.repository_url}:latest"
    portMappings = [{
      containerPort = 8080
      hostPort      = 8080
    }]
    logConfiguration = {
      logDriver = "awslogs"
      options = {
        "awslogs-group"         = "/ecs/minha-app"
        "awslogs-region"        = "us-east-1"
        "awslogs-stream-prefix" = "ecs"
      }
    }
  }])
}

ECS Service

O service mantém o container rodando e gerencia o deploy:

resource "aws_ecs_service" "app_service" {
  name            = "minha-app-service"
  cluster         = aws_ecs_cluster.app_cluster.id
  task_definition = aws_ecs_task_definition.app_task.arn
  desired_count   = 1
  launch_type     = "FARGATE"

  network_configuration {
    subnets          = data.aws_subnets.default.ids
    security_groups  = [aws_security_group.app_sg.id]
    assign_public_ip = true
  }
}

OIDC: Autenticação Sem Credenciais Estáticas

Este é um dos pontos mais importantes da arquitetura. Em vez de armazenar AWS_ACCESS_KEY e AWS_SECRET_KEY como secrets no GitHub, usamos OIDC (OpenID Connect) para que o GitHub Actions troque um token temporário por credenciais AWS.

# Registra o GitHub como provedor OIDC na AWS
resource "aws_iam_openid_connect_provider" "github" {
  url             = "https://token.actions.githubusercontent.com"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = ["ffffffffffffffffffffffffffffffffffffffff"]
}

# Role que o GitHub Actions vai assumir
resource "aws_iam_role" "github_actions_role" {
  name = "github-actions-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Principal = {
        Federated = aws_iam_openid_connect_provider.github.arn
      }
      Action = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
        }
        StringLike = {
          "token.actions.githubusercontent.com:sub" = "repo:meu-usuario/meu-repo:ref:refs/heads/main"
        }
      }
    }]
  })
}

Por que isso importa? Credenciais estáticas são um risco de segurança. Com OIDC, as credenciais são temporárias e o acesso é restrito a uma branch específica de um repositório específico. Mesmo que alguém tenha acesso ao repositório, não consegue assumir a role a partir de outra branch.

Dockerfile Multi-Stage

Usamos um build multi-stage para separar o ambiente de compilação do ambiente de execução, resultando em uma imagem final menor e mais segura:

# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MeuProjeto/MeuProjeto.csproj", "MeuProjeto/"]
RUN dotnet restore "MeuProjeto/MeuProjeto.csproj"
COPY . .
WORKDIR "/src/MeuProjeto"
RUN dotnet build -c Release -o /app/build

# Stage 2: Publish
FROM build AS publish
RUN dotnet publish -c Release -o /app/publish /p:UseAppHost=false

# Stage 3: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
EXPOSE 8080
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MeuProjeto.dll"]

Benefícios do multi-stage:

A imagem final contém apenas o runtime, não o SDK completo
Reduz significativamente o tamanho da imagem
O código-fonte não fica presente na imagem de produção

Pipeline de CI

A primeira pipeline roda automaticamente quando um Pull Request é aberto contra a branch main. Seu objetivo é validar que o código compila e que os testes passam.

name: PR Validation

on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Restore
        run: dotnet restore MinhaSolution.sln

      - name: Build
        run: dotnet build MinhaSolution.sln --no-restore -c Release

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Run Tests with Coverage
        run: |
          dotnet test MinhaSolution.sln \
            --collect:"XPlat Code Coverage" \
            --results-directory ./coverage

O que acontece nesta pipeline:

Job build — Compila a solução para garantir que não há erros de compilação
Job test — Roda os testes unitários com cobertura de código usando Coverlet

Separar em dois jobs traz clareza: se o build falha, você sabe que é erro de compilação. Se o test falha, o código compila mas tem um bug.

Protegendo a Branch Main

Com a pipeline de CI configurada, é fundamental garantir que nenhum código chegue à main sem passar pela validação. Para isso, configuramos uma branch protection rule no GitHub.

Acesse Settings > Branches > Add branch protection rule no seu repositório e configure:

Branch name pattern: main
Marque Require a pull request before merging — impede push direto na main
Marque Require status checks to pass before merging — bloqueia o merge até que os checks passem
Em Status checks that are required, busque e adicione os jobs da pipeline de CI:
- build
- test

Nota: Na primeira vez que configurar, os status checks podem não aparecer na busca. Eles só ficam disponíveis após a pipeline rodar pelo menos uma vez no repositório. Abra um PR de teste para que os checks sejam registrados.

Configurando as Secrets no GitHub

Antes de configurar a pipeline de deploy, é necessário cadastrar as secrets no repositório do GitHub. A pipeline de CD depende delas para autenticar na AWS e saber para onde enviar a imagem Docker.

Acesse Settings > Secrets and variables > Actions > New repository secret no seu repositório e crie as seguintes secrets:

Secret	Valor	Exemplo
`AWS_ROLE`	O ARN completo da IAM Role criada para o GitHub Actions	`arn:aws:iam::123456789012:role/github-actions-role`
`ECR_REPOSITORY`	A URI completa do repositório ECR (não apenas o nome)	`123456789012.dkr.ecr.us-east-1.amazonaws.com/minha-app-repository`
`AWS_ACCOUNT_ID`	O ID numérico da sua conta AWS	`123456789012`

Atenção: Um erro comum é colocar apenas o nome do repositório ECR (ex: minha-app-repository) na secret ECR_REPOSITORY. O valor correto é a URI completa que inclui o domínio do ECR. Você pode obter essa URI no console da AWS em ECR > Repositories ou via CLI:

aws ecr describe-repositories --repository-names minha-app-repository \
  --query "repositories[0].repositoryUri" --output text

Da mesma forma, a secret AWS_ROLE deve conter o ARN (Amazon Resource Name) completo da role, não apenas o nome. Para consultar:

aws iam get-role --role-name github-actions-role \
  --query "Role.Arn" --output text

Com as secrets configuradas, a pipeline de deploy consegue autenticar via OIDC, fazer push da imagem para o ECR e disparar o deploy no ECS.

Pipeline de CD

Quando o PR é aprovado e mergeado na main, a pipeline de deploy entra em ação:

name: Build and Deploy

on:
  push:
    branches: [main]

permissions: #permissões necessárias para autenticação OIDC
  id-token: write
  contents: read 

env:
  AWS_REGION: us-east-1

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Login to Amazon ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build Docker Image
        run: docker build -t minha-app .

      - name: Tag Image
        run: docker tag minha-app:latest ${{ secrets.ECR_REPOSITORY }}:latest

      - name: Push to ECR
        run: docker push ${{ secrets.ECR_REPOSITORY }}:latest

      - name: Deploy to ECS
        run: |
          aws ecs update-service \
            --cluster minha-app-cluster \
            --service minha-app-service \
            --force-new-deployment

O que acontece nesta pipeline:

Autenticação OIDC — O GitHub troca seu token JWT por credenciais AWS temporárias
Login no ECR — Autentica o Docker no registro da AWS
Build e Push — Constrói a imagem Docker e envia para o ECR
Deploy — Dispara um novo deployment no ECS, que puxa a imagem atualizada e substitui o container antigo

O --force-new-deployment garante que o ECS vai iniciar uma nova task mesmo que a tag da imagem (latest) não tenha mudado.

Acessando a Aplicação após o Deploy

Após a pipeline de CD concluir com sucesso, a aplicação estará rodando no ECS Fargate. Como configuramos assign_public_ip = true no Terraform, a task recebe um IP público que pode ser usado para acessar a API.

Obtendo o IP público pelo Console AWS

Acesse ECS > Clusters > minha-app-cluster
Clique na aba Tasks
Clique na task em execução (status RUNNING)
Na seção Network, copie o Public IP
Acesse no navegador: http://<PUBLIC_IP>:8080

Obtendo o IP público via CLI

# 1. Obtenha o ARN da task em execução
TASK_ARN=$(aws ecs list-tasks \
  --cluster minha-app-cluster \
  --service-name minha-app-service \
  --query "taskArns[0]" --output text)

# 2. Obtenha o ID da interface de rede (ENI)
ENI_ID=$(aws ecs describe-tasks \
  --cluster minha-app-cluster \
  --tasks $TASK_ARN \
  --query "tasks[0].attachments[0].details[?name=='networkInterfaceId'].value" \
  --output text)

# 3. Obtenha o IP público
aws ec2 describe-network-interfaces \
  --network-interface-ids $ENI_ID \
  --query "NetworkInterfaces[0].Association.PublicIp" \
  --output text

Importante: O IP público muda toda vez que uma nova task é criada (ou seja, a cada deploy). Para um ambiente produtivo, o ideal é utilizar um Application Load Balancer (ALB) ou um domínio com Route 53 apontando para o serviço ECS, garantindo um endereço fixo. Para fins de estudo, o IP público direto é suficiente.

Segurança: OIDC em Detalhe

Vale reforçar a importância do OIDC neste fluxo. O modelo tradicional funciona assim:

❌ Modelo Tradicional:
   GitHub Secrets → AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
   - Credenciais estáticas que nunca expiram
   - Se vazadas, acesso total até serem rotacionadas manualmente

Com OIDC:

✅ Modelo OIDC:
   GitHub Actions → JWT Token → AWS STS → Credenciais Temporárias
   - Credenciais expiram automaticamente
   - Escopo restrito: apenas uma branch de um repositório específico
   - Sem segredos de longa duração armazenados

A configuração requer:

Registrar o GitHub como OIDC Provider na AWS (via Terraform)
Criar uma IAM Role com trust policy apontando para o repositório
No workflow, usar permissions: id-token: write e a action configure-aws-credentials com role-to-assume

Fluxo Completo: Do Commit ao Deploy

Resumindo o ciclo de vida de uma mudança:

1. git checkout -b feature/minha-feature
2. # Desenvolve e commita
3. git push origin feature/minha-feature
4. # Abre Pull Request → Dispara pr-validation.yml
   │
   ├── ✅ Build compila com sucesso
   └── ✅ Testes passam com cobertura
   │
5. # Code review + Aprovação
6. # Merge na main → Dispara build-and-deploy.yml
   │
   ├── 🔐 Autenticação via OIDC
   ├── 🐳 Build da imagem Docker (multi-stage)
   ├── 📦 Push para o ECR
   └── 🚀 Deploy no ECS Fargate
   │
7. # Nova versão rodando em produção

Considerações Finais

Este setup demonstra como é possível construir uma pipeline profissional de CI/CD com ferramentas modernas e boas práticas:

Infraestrutura como Código — Toda a infraestrutura é versionada e reproduzível
Autenticação Keyless — OIDC elimina o risco de credenciais estáticas
Serverless Containers — Fargate remove a necessidade de gerenciar servidores
Separação CI/CD — Validação em PRs e deploy apenas na main
Imagens otimizadas — Multi-stage build reduz a superfície de ataque

O custo de infraestrutura para um setup como esse é mínimo — com Fargate usando 0.25 vCPU e 512MB de memória, o custo fica na faixa de poucos dólares por mês para ambientes de estudo e projetos pequenos.

A barreira de entrada para CI/CD profissional diminuiu muito. Ferramentas como GitHub Actions e Terraform tornam acessível o que antes exigia equipes dedicadas de DevOps. O importante é começar simples, entender cada peça, e evoluir conforme a necessidade.

Este artigo foi escrito com base em um projeto prático de estudo. Todo o código-fonte está disponível publicamente neste repositório do GitHub.

Criei uma pipeline de planejamento no OpenCode e olha no que deu

Clinton Rocha — Mon, 09 Mar 2026 04:37:00 +0000

Você é como eu e vem buscando formas de otimizar o uso de ferramentas como o OpenCode? Talvez este conteúdo te ajude a ter novas ideias e até mesmo entender alguns fluxos dessa e de outras ferramentas.

Enquanto eu estudava a documentação do OpenCode, encontrei a aba de plugins feitos pela comunidade. Ali, encontrei três plugins que, na minha visão, se complementam bem. Na verdade, um deles eu já utilizava: o Plannotator.

A partir disso, comecei a estudar como funcionava os comandos, agentes e como eu poderia fazer um fluxo que fizesse sentido e principalmente que funcionasse, calma que já te explico oq cada um dos plugins fazem e qual a ideia final da integração.

Índice

Como eu estava usando o OpenCode
Objetivo da integração
Plannotator: Revisão Visual
Octto: Coleta estruturada de contexto
Subtask2: Orquestração de Pipeline
Comandos
Considerações
Referências

Como eu estava usando o OpenCode

Após começar a utilizar o OpenCode, notei o quão importante é o uso do módulo de planejamento e, principalmente, não apenas o planejamento em si, mas também as perguntas que são feitas durante esse processo. O resultado dessas duas novas abordagens (planejamento e perguntas) melhora bastante não só o código produzido, mas também a minha compreensão sobre a regra de negócio, além de comportamentos e fluxos do sistema.

Mesmo com todas essas descobertas que trouxeram otimizações para o processo, eu ainda sentia que dava para melhorar mais.

O fluxo de uso do OpenCode era basicamente o seguinte: eu enviava o prompt, a ferramenta vasculhava o código para obter contexto, depois vinham algumas perguntas e, em seguida, ela ia para a parte de build, ou seja, para colocar em prática o que tinha sido planejado.

Objetivo da integração

A ideia vai ser conseguir extrair o máximo de contexto com o Octto, usar o subtask2 para orquestrar os comandos e visualizar o plano final com Plannotator.

+---------------------------------------------------------------+
|                                                               |
|  IDEIA -> CONTEXTO -> PLANO -> REFINAMENTO -> REVISAO -> OK   |
|                                                               |
+---------------------------------------------------------------+

O resultado é um único comando que orquestra todo o processo:

/generate-plan "descrição do objetivo"

Plannotator: Revisão visual

O primeiro plugin chegou até mim por recomendação de uma amiga da comunidade (He4rtDevs), a Cherry, e o plugin era o Plannotator.

Esse plugin basicamente faz com que, ao final de um planejamento, seja aberta uma página no navegador contendo todo o plano gerado. Isso facilita muito a visualização em comparação com o terminal. Na interface do navegador, você consegue selecionar trechos do planejamento e dar feedback, que retorna para o processo de planejamento. Também é possível aprovar o plano e seguir diretamente para a etapa de build, ou seja, aplicar o que foi planejado.

Octto: Coleta estruturada de contexto

O Octto quando você envia o primeiro prompt, ele abre uma página no navegador com perguntas relacionadas ao que você pediu inicialmente. Essa página funciona como uma interface interativa de brainstorming. Conforme você responde às perguntas, o sistema utiliza essas respostas para gerar novas perguntas dentro da mesma sessão, aprofundando o entendimento do problema e ajudando a estruturar melhor o contexto antes de seguir para as próximas etapas, ao final ele gera um arquivo .md no diretório /docs/plans dentro do projeto.

A unica configuração que adicionei a ele, foi uma que faz com que a primeira pergunta seja um campo de texto livre onde o usuário consiga descrever o contexto com maior liberdade (colocar uma task completa, por exemplo).

Fluxo de Funcionamento

+----------------------+
|       ask_text       |  <-- Primeira ação obrigatória
+----------+-----------+
           |
           | Campo de texto no browser:
           | "Descreva com detalhes o que
           | você quer planejar..."
           v
+----------------------+
|   create_brainstorm  |  <-- Agente inicia sessão
+----------+-----------+      com contexto coletado
           |
           | Define branches de exploração
           v
+--------------------------------------------------------------+
|                    BRANCHES DE EXPLORAÇÃO                    |
|                                                              |
|  +----------------+  +-------------------+  +---------------+|
|  | Motivação &    |  | Requisitos &      |  | Riscos &      ||
|  | Objetivos      |  | Restrições        |  | Dependências  ||
|  +--------+-------+  +---------+---------+  +-------+-------+|
|           |                    |                    |        |
+-----------+--------------------+--------------------+--------+
            |
            v
+----------------------+
|      BROWSER UI      |
|                      |
|  [ Pergunta 1 ]      |
|  [ Pergunta 2 ]      |
|  [ Pergunta N ]      |
|                      |
|      [Responder]     |
+----------+-----------+
           |
           | Usuário responde
           v
+----------------------+
| await_brainstorm_    |
| complete             |  <-- Agente aguarda respostas
+----------+-----------+
           |
           | Sintetiza respostas
           v
+----------------------+
|      docs/plans/     |
| 2026-03-08-objetivo  |  <-- Arquivo gerado
|        .md           |
+----------------------+

Configuração via Fragments

O comportamento do Octto é customizado através de fragments, instruções adicionadas ao prompt dos agentes internos:

{
    "fragments": {
        "octto": [
            "Sempre pergunte a motivação e o 'porquê' das mudanças",
            "Gere nomes de arquivo no formato: YYYY-MM-DD-slug.md",
            "Salve os planos em docs/plans/"
        ],
        "probe": [
            "Priorize perguntas sobre motivações e restrições",
            "Inclua perguntas sobre requisitos não-funcionais"
        ],
        "bootstrapper": [
            "Crie branches focados em: requisitos, arquitetura, riscos"
        ]
    }
}

Função de cada agente interno:

bootstrapper: cria a estrutura inicial de branches
probe : gera perguntas de aprofundamento
octto: define o comportamento geral da coleta de contexto

Subtask2: Orquestração de pipeline

O Subtask2 permite encadear comandos de forma sequencial. Quando um comando termina, o próximo da cadeia é executado automaticamente.

Nesse meu contexto só vou usar a funcionalidade de return, mas esse plugin tem muitas outras funcionalidades interessantes como:

loop de subtarefas até que a condição do usuário seja atendida
paralela de subtarefas simultaneamente - PR pendente.
$TURN[n] passa turnos da sessão (mensagens do usuário/assistente).
{as:name} + $RESULT[name] captura e referência as saídas das subtarefas.

Sintaxe de Return Chain

---
subtask: true
return:
- /comando-1
- /comando-2
- /comando-3
---

Comandos

Com o subtask2, consigo adicionar comandos ao fluxo, e isso abre muitas possibilidades. Mas, por enquanto, estou com os pés no chão e vou fazer um fluxo simples com alguns novos comandos.

Eu criei esses comandos com o único intuito de usar na pipeline.

Comando Principal

O comando que vai dar inicio a todo o fluxo, vai ser o /generate-plan ao executar, ele da inicio a pipeline de planejamento.

Você é livre para escolher qualquer nome para o comando, para escolher o nome desse aqui eu só segui as vozes da minha cabeça.

Caso queira saber mais sobre como criar e configurar comandos no opencode, a doc é legalzinha.

/generate-plan refatorar sistema de autenticação
/generate-plan "adicionar suporte a múltiplos gateways de pagamento"

As aspas são opcionais: tudo após o comando é passado como $ARGUMENTS.

---
description: Pipeline completo de planejamento 
agent: octto
subtask: true
return:
- /refine-plan
- /review-plan
---

prompt aqui, e lembre de usar o $ARGUMENTS

Caso você queira ver como deixei o meu prompt usado no comando generate-plan é só ir no gist.

Todos os comandos podem ser usados individualmente/isolado no OpenCode, a unica diferença ao usar um comando com o subtask é que ele vai ser executado em um contexto diferente.

Refinamento Técnico

O /refine-plan tem como objetivo expandir um plano existente com detalhes arquiteturais.

/refine-plan # usa plano mais recente
/refine-plan docs/plans/meu-plano.md # plano específico

refine-plan:

---
description: Expande e refina tecnicamente um plano existente com arquitetura e diagramas
subtask: true
---

Mesma coisa que o anterior, aqui você consegue adicionar a instrução que você quiser.

No meu caso, o prompt que estou sando tá no gist 'refine-plan.md'.

Revisão Visual

Por último vem o comando /review-plan com o objetivo de mandar o plano para revisão interativa via Plannotator.

/review-plan # usa plano mais recente
/review-plan docs/plans/meu-plano.md # plano específico

Importante: Este comando não usa subtask: true. Ele roda na sessão primária para que a ferramenta submit_plan possa abrir a interface do Plannotator no browser corretamente. Comandos rodando como subtarefa não conseguem inicializar a UI do browser.

Fluxo Completo de Execução:

Considerações

O mais importante de tudo: funcionou? Sim. É uma bazuca? Sim, hahahaha. Esse projeto acabou saindo porque entrei em hiperfoco ao me fazer a pergunta “será que funciona?”. No fim, tive minha resposta.

Olhando para a usabilidade no dia a dia, acredito que os melhores momentos para utilizar algo assim são em novas features, refatoração de projeto e até mesmo para estruturar estudos, quem sabe. Só não use para algo como “quero trocar a cor de um botão”, aí você acaba complicando.

O ponto que mais curti foi o Octto, com as perguntas geradas de forma dinâmica. Aquilo ali, ao meu ver, auxilia na contextualização de uma baita maneira. Fora que é possível dar instruções para as branches dele, especificar qual tipo de input você quer ou não quer, entre outras coisas (vale ler a documentação).

Já o subtask2 abre portas para muita coisa. Como eu tinha dito antes, acabei indo pelo simples, mas alguém com a mente mais aberta provavelmente vai conseguir extrair o melhor da ferramenta.

Eu pretendo criar novos comandos, refinar mais os prompts e ver o que acontece. É isso, obrigado por ler até aqui e tente brincar com isso ai.

Como meu Tech Lead fala:

Faça codigo inútil e quebre alguma coisa.

Referências

Seu código é Orientado a Objetos

Bruno Freschi — Thu, 05 Mar 2026 17:19:48 +0000

🚀 O seu código é Orientado a Objetos ou apenas um "Procedural Disfarçado"?

Vamos tocar na ferida: o que mais existe por aí é o famoso "Código de Estimação". Aquele código empacotado em classes, cheio de getters e setters para todo lado, mas sem um pingo de inteligência ou comportamento real.

Se o código procedural resolve o problema e entrega o software, por que se dar ao trabalho de modelar objetos? A resposta não está na execução, mas na sustentabilidade.

Por que a OO (bem feita) salva o seu projeto?

Controle da Complexidade (O fim do Espaguete): No procedural, os dados são passivos e as funções globais. Conforme o sistema cresce, mexer em um ponto quebra cinco outros lugares imprevisíveis. A OO propõe o Encapsulamento: cada objeto é uma "caixa preta" que cuida da própria vida.
Flexibilidade sem Cirurgia (Polimorfismo): Precisa adicionar um novo meio de pagamento (ex: Cripto)? Em vez de espalhar if/else por todo o sistema, você apenas cria um novo objeto que sabe "Processar". Você adiciona funções sem tocar no que já está funcionando.

🏛️ Os 4 Pilares na Prática

Pilar	O que resolve na vida real?
Abstração	Esconde a complexidade. Você dirige o carro sem precisar entender a explosão interna do motor.
Encapsulamento	Protege os dados. Ninguém altera o "Saldo" sem passar pelas regras de negócio.
Herança	Compartilha características comuns, evitando redundância (mas cuidado para não virar um pesadelo!).
Polimorfismo	Permite que diferentes objetos respondam à mesma mensagem de formas específicas.

💡 O Veredito

Usamos Orientação a Objetos para que o código seja legível para humanos, e não apenas compreensível para máquinas. O custo de manutenção de um software é, em média, 80% do seu ciclo de vida.

A OO bem aplicada é um investimento para que o desenvolvedor do futuro (que pode ser você daqui a seis meses) não queira deletar tudo e começar do zero.

E aí, o seu código atual passaria em um teste de pureza de OO? 🧐

#programação #softwareDevelopment #cleanCode #OOP #devLife #brazilianDevs

API vs Event Streaming: O Que Muda Para Quem Testa?

Alicia Marianne 🇧🇷 — Thu, 12 Feb 2026 20:50:04 +0000

✨ Oi, gente!

Recentemente, tenho pensado bastante em como contribuir para a comunidade de QA e ajudar aqueles que estão começando ou que já estão há algum tempo na área. Também quero relatar mais sobre os desafios de ser uma brasileira morando em terras lusitanas 🇵🇹.

O que me levou a querer voltar — na verdade, começar — a escrever na minha língua materna?

Bom, se eu fosse dizer de bate-pronto: saudade. 💛

Sim, aqui em Portugal fala-se português também, porém, como boa mineira que sou, sinto falta do nosso jeitinho de falar e escrever as coisas. Acredito que falar sobre o que sei na minha língua materna me deixa mais próxima de casa.

Outra razão que me fez querer começar a escrever em português foi voltar a ser mais ativa em comunidades de desenvolvimento (He4rt 💜). Tenho visto muitas mulheres entrando para a área, e algumas não são fluentes em inglês ou não confiam no que sabem para se arriscar em conteúdos em outros idiomas.

Com isso, eu pensei: por que não focar por um tempo em escrever em português? E cá estamos! ✍️

E, para que isso não seja apenas um comunicado, mas algo útil, já vou começar falando sobre serviços de mensageria (Event Streaming) e por que é importante que um QA (ou aspirante a QA) entenda pelo menos o básico sobre isso.

📡 Em termos técnicos

Event Streaming (Transmissão de Eventos) é a prática de capturar dados em tempo real a partir de fontes como bancos de dados, sensores, dispositivos móveis, serviços na nuvem e aplicações de software, na forma de fluxos de eventos; armazenar esses fluxos de forma duradoura para recuperação posterior; manipular, processar e reagir a esses eventos tanto em tempo real quanto retrospectivamente; e encaminhá-los para diferentes destinos, conforme necessário.

Lindo, né? 😅

Mas como podemos entender isso na prática?

🧠 Vamos imaginar o seu corpo

Sim, ele mesmo!

Você sente aquela dor no estômago 🍽️, que é um sinal de que está com fome. Esse sinal “fala” para o seu cérebro:

— Querido, estou precisando de nutrientes. Quando eles chegam?

Normalmente, você para o que está fazendo e vai comer algo. Mas perceba: seu estômago precisa esperar até o momento certo. Ainda assim, seu corpo continua funcionando normalmente. Ele não para.

No mundo do software, isso significa que, sempre que existir um sinal ou uma modificação, essa informação será interpretada sem que outras funcionalidades do sistema sejam interrompidas.

🛒 Exemplo prático: compras online

Você faz o seu pedido
Realiza o pagamento
O sistema de pagamento processa esse pagamento
Ele publica um evento informando que o pagamento foi aprovado
O sistema de notificação consome esse evento
E o cliente recebe a confirmação de que a compra será entregue 📦

Tudo isso pode acontecer sem que um sistema precise “esperar parado” pelo outro.

🔧 Algumas ferramentas de Event Streaming

Hoje, existem várias ferramentas no mercado que trabalham com esse modelo de comunicação baseada em eventos. Algumas das mais conhecidas são:

Apache Kafka 🐘 (uma das mais populares no mercado)
RabbitMQ 🐰
AWS Kinesis

Cada uma tem suas particularidades, mas todas trabalham com o conceito de produtores, consumidores e eventos trafegando por tópicos ou filas.

E aqui começa a parte interessante para nós, QAs. 👀

🔄 Event Streaming vs API

Você pode se perguntar:

“Alicia, mas qual a diferença disso para uma API? Eu consigo fazer o mesmo apenas chamando uma API.”

Conseguir, você consegue. Mas será que é a melhor opção? 🤔

Depende.

Normalmente, sistemas que utilizam apenas APIs (geralmente síncronas) funcionam assim: fazem uma requisição, esperam a resposta, e só depois continuam o processamento. Isso pode deixar o sistema mais acoplado e dependente.

Já em um sistema de Event Streaming (assíncrono), não é necessário esperar uma resposta para continuar o fluxo. O sistema segue funcionando enquanto os eventos são processados em paralelo.

E, principalmente, não queremos que o usuário fique esperando uma resposta para continuar usando o software ⏳.

🧪 E onde o QA e automação entram nisso?

Quando falamos de sistemas orientados a eventos, surgem novas perguntas de teste:

O evento foi realmente publicado?
O formato (schema) está correto?
O consumidor está processando corretamente?
O que acontece se o consumidor falhar?
Existe retry?

Percebe como o nível de complexidade aumenta?

Testar Event Streaming não é só validar payload. Envolve entender fluxo, consistência eventual, ordenação de mensagens, tolerância a falhas e comportamento assíncrono e partir dessa compreensão, é possível pensar em automações, do tipo:

Produzir eventos automatizados para testes
Validar consumo de mensagens
Testes de contrato (como com Schema Registry no Kafka)
Testes de integração ponta a ponta
Validação de mensagens em filas durante pipelines de CI/CD

✅ Conclusão

Entender mensageria e Event Streaming não é apenas “coisa de backend” — é conhecimento essencial para qualquer QA que queira testar sistemas modernos com mais profundidade. 💡

Quando compreendemos como os eventos trafegam, como os sistemas se comunicam de forma assíncrona e onde podem ocorrer falhas, ampliamos nossa capacidade de análise, criamos melhores cenários de teste e nos tornamos profissionais mais estratégicos.

Escrever sobre isso em português é, para mim, uma forma de compartilhar conhecimento, fortalecer a comunidade e também me sentir mais próxima de casa. 💛

E esse é só o começo. 🚀

Figma MCP: sou designer, o que eu tenho a ver?

vitoriazzp — Thu, 04 Dec 2025 16:41:05 +0000

Se você trabalha com produto, já percebeu que entre o “nosso design está pronto!” e o “isso está no ar!” existe um universo paralelo de desalinhamentos, ajustes de última hora e aquele eterno vai e volta entre Figma e código. Nada mais normal.

Mas agora temos um novo personagem nessa história: o Figma MCP (Model Context Protocol) — uma ponte direta entre seus arquivos Figma e ferramentas de IA que geram código.
E aí você pensa: “Beleza… mas eu sou designer. O que eu tenho a ver com isso?”

A resposta curta: tudo.
A resposta longa: vem comigo.

O MCP traduz seu design de forma fiel para o código

O Figma MCP cria um servidor que permite que agentes de IA — como Cursor, VS Code ou outros editores — acessem o contexto real do seu arquivo: componentes, variáveis, tokens, layouts, constraints.

Ou seja, quando você manda a IA implementar um card, ela não está só “vendo um retângulo bonito”, ela está entendendo:

spacing real do design system
layout grid
variantes
tokens aplicados
comportamento definido no Dev Mode

Isso transforma o handoff. Literalmente.

Benefícios que designers vão sentir na prática

1) Converter frames direto em código confiável

Você seleciona um frame, copia o link e a IA escreve o código já alinhado ao design system — sem “interpretações criativas”.
Pra quem já trabalhou estruturando DS (como eu), isso é ouro puro.

2) As variáveis entram automaticamente no prompt

Nada de prompts longos explicando spacing, grids ou tokens.
O MCP envia tudo isso sozinho, deixando a IA mais esperta que nunca.

3) Colaboração com devs melhora MUITO

O MCP até audita diferenças entre design e implementação, sugerindo ajustes ou avisando onde algo não bate.
É quase um mini Design QA automatizado.

Um exemplo real do meu dia a dia em que MCP teria salvado tempo

Quando eu trabalhava ajustando componentes do design system, muitas vezes criava layouts complexos — tabelas responsivas, modais com várias variantes, dropdowns cheios de estados.

Mas para validar tudo isso, eu dependia de um dev parar o que estava fazendo para montar uma versão funcional.

Com o MCP, teria sido assim:

copiar link → pedir no Cursor → “gera esse componente seguindo meu design system”

Eu teria uma implementação inicial em minutos, pronta para iterar e testar. Sem interrupções, sem esperar sprint, sem perder contexto.

Mas… e os desenvolvedores frontend?

Eles continuam absolutamente essenciais.

O MCP não substitui devs — ele substitui o retrabalho, a adivinhação e as idas e vindas desnecessárias.

O frontend ainda será responsável por:

lógica de negócio
performance
arquitetura de componentes
integrações reais
otimizações
acessibilidade avançada
padrões de engenharia
boas práticas que IA nenhuma domina sozinha

O que muda é o foco:
menos tempo reescrevendo interface e mais tempo criando soluções melhores.

O MCP não tira o espaço do dev — ele tira o peso do handoff manual e dá espaço para que o dev faça o que só ele sabe fazer.

Então… Figma MCP: sou designer, o que eu tenho a ver?

Tudo.
Você tem a ver porque o MCP coloca designers no centro do fluxo: seus componentes, suas variáveis, sua lógica visual passam a ser entendidas pelo código — sem intermediários distorcendo suas intenções.

Ele acelera protótipos, reduz ruído, aumenta fidelidade e melhora a colaboração.

É um daqueles raros momentos em que design, dev e IA entram em sintonia real.

Se você trabalha com UX, prototipagem, design system ou quer entregar mais rápido sem depender de dez etapas intermediárias…
o MCP é exatamente onde você deveria prestar atenção.

Quer aprender mais sobre? Te recomendo ver o vídeo do próprio Figma aplicando a funcionalidade a Design Systems aqui: https://www.youtube.com/watch?v=A4mqzgFbmjI

Compartilhando seu conhecimento com o mundo! Como escrever artigos

Cherry Ramatis — Mon, 13 Nov 2023 21:31:19 +0000

Compartilhar conhecimento escrito é uma ótima forma de dominar um assunto específico, além de ser uma excelente maneira de melhorar a organização das ideias, comunicação e obviamente se autopromover na comunidade. Essa produção de artigos tanto técnicos quanto sociais são muito importantes tanto para quem escreve quanto para quem está lendo, lembre-se sempre: Você sabe mais hoje do que quem começou ontem. Pensando nisso vamos discutir um pouco mais sobre como organizar as próprias ideias na produção de um artigo técnico para a plataforma dev.to!

Método de Feynman e por que produzir conteúdo
Coletando ideias e se motivando para escrever
Entendendo a plataforma e achando a propria linguagem
Aprendendo markdown e dicas gerais para uma boa formatação
A estrutura básica de um artigo técnico
Como revisar e melhorar a escrita
Conclusão e agradecimentos

Método de Feynman e por que produzir conteúdo

Primeiramente precisamos discutir o porquê devemos compartilhar conteúdo, seja em formato textual (o foco desse artigo) ou em qualquer outro formato. Para iniciar essa discussão é importante entender o que é o método de Feynman e como ele pode nos ajudar a aprender 10 vezes mais com confiança e domínio do assunto.

O método de Feynman foi criado por um físico muito importante chamado Richard Feynman visando desenvolver uma abordagem nova ao aprendizado, essa nova proposta assume uma verdade central: "Se você não consegue explicar algo de maneira clara e simples, então você ainda não entendeu completamente".

Essa frase nos ajuda muito a pensar em como nosso aprendizado deve ser estruturado, pois a partir do momento que começamos a pensar em ensinar o que estamos estudando focamos muito mais em dominar as bases essenciais do assunto e se preparar para dúvidas que te forçam a olhar o problema, por outro lado, completamente diferente.

Ao se preparar para situações como essas, o resultado claro é uma excelente confiança e domínio sobre o assunto em questão que estava sendo estudado.

Eu particularmente amo esse método, o único problema dele é que quando saímos do ambiente acadêmico fica muito difícil de achar pessoas que se interessam pelo mesmo assunto que você esta estudando no momento, seja por não ter pessoas de TI no ciclo de amizade ou simplesmente por ter interesse em assuntos específicos.

Para esse problema temos uma solução muito incrível chamada "Learning in public"! Essa prática consiste em compartilhar seu aprendizado online em comunidades de tecnologia, seja produzindo vídeos, fazendo live streams ou no objetivo desse artigo: escrevendo!

Plataformas como o dev.to (que você usando para ler agora :D) visam tornar a ideia de "Learning in public" cada vez mais simples e próxima de quem está consumindo, pois agora é possível produzir artigos que vão chegar em pessoas com os mesmos interesses que os nossos que podem: aprender, tirar dúvidas ou mesmo sugerir mudanças e corrigir pensamentos. Incrível né?

Coletando ideias e se motivando para escrever

O processo de inspiração é provavelmente uma das fases mais chatinhas antes de produzir um artigo online, muitas vezes ficamos presos em um loop infinito de técnicas mirabolantes para ter ideias incríveis quando, na verdade, a solução acaba sendo muito simples: aceite suas ideias e consuma o máximo de conteúdos possível.

A forma mais prática de encontrar ideias e de construir sua própria linguagem é ler o que as outras pessoas já produzem sobre os temas que lhe interessam, quer se trate de uma linguagem de programação, de um tema específico em TI, etc; esse consumo de conteúdo vem de diversas fontes diferentes como artigos técnicos, vídeos no YouTube, tweets da bolha Tech, discussões no Github e muitos outros locais possíveis.

Bom, sei que falando assim parece simplificar algo que não é tão simples assim e eu concordo com você! Não é só ler ou assistir tudo o que existe na internet que vai nos tornar capazes de produzir os mesmos conteúdos, a habilidade mais importante que vai destacar essas pessoas é organizar as ideias que chegam no cérebro.

Mantendo um segundo cérebro

Nosso cérebro é uma excelente maquina de absorção de informação, praticamente uma esponja que guarda todas as informações ao nosso redor. O grande problema dessa maquina é que ela se tornou péssima em organização com o tempo, isso aconteceu principalmente para poupar energia já que não precisamos lembrar de tudo o tempo todo, mas sabendo disso o que podemos fazer para guardar as informações que queremos de forma organizada? Well well well jovem gafanhoto, precisamos parar de confiar no nosso cérebro é claro!

Manter um segundo cérebro é uma prática muito famosa entre escritores e pesquisadores, consiste em um local físico ou virtual onde você copia pequenos pedaços de conteúdo que consumiu junto de uma observação utilizando suas próprias palavras sobre o assunto. Esse amontoado de anotações vai compor o seu segundo cérebro e vai te empoderar com a habilidade de achar qualquer conteúdo rapidamente e referenciar seus autores sem nunca esquecer nada!

Para resumir a história, consuma o máximo de conteúdo possível, armazene-o em um segundo cérebro que pode ser armazenado e pesquisado e finalmente se desafie a escrever! Seja sobre um assunto que quer aprender, sobre algo específico que aprendeu recentemente ou até mesmo algo que domina há muitos anos.

Entendendo a plataforma e achando a propria linguagem

Entender a plataforma e o público que vamos atingir escrevendo nossos conteúdos é muito importante para podermos filtrar como vamos estruturar os artigos de forma geral certo? Na minha opinião, o dev.to é uma plataforma bem informal que valoriza muito conteúdos no formato de tutoriais com um estilo conversacional e direto ao ponto, com essa informação podemos deduzir algumas formas de estruturar nossos artigos para que possamos ilustrar nossa ideia em um modelo conhecido pelos leitores.

Isso significa que tudo o que você vai produzir são tutoriais diretos e informais? De forma alguma! Só significa que você pode moldar o seu conteúdo para conter essa linguagem mais informal, conversacional e direta mesmo que o tema tratado seja super complexo, isso inclusive vira um desafio muito interessante de simplificar o complexo.

A habilidade de simplificar o complexo vai te acompanhar para o resto da sua vida profissional, é importantíssimo a criação de analogias e exemplos para que facilite o entendimento e a identificação com os problemas apresentados e as soluções propostas.

Aprendendo markdown e dicas gerais para uma boa formatação

A forma para produzirmos nossos artigos no dev.to é utilizando uma linguagem de marcação (exatamente, igual o HTML) chamada Markdown, apesar dela ser super simples é importante termos um domínio bem solido do que é possível fazer quando falamos sobre organizar e deixar nosso texto bonitinho, semelhante como vamos produzir uma estrutura complexa no Microsoft Word devemos ser capazes de produzir o mesmo com código Markdown.

É sempre importante ressaltar a importância de um material educacional bem estruturado (afinal você está lendo esse artigo justamente para isso certo?) e quando o assunto é excelência e qualidade não consigo recomendar o suficiente o projeto 4noobs que junta em um único repositório diversos cursos grátis e no formato de texto sobre diversos assuntos em TI, para o tema desse artigo recomendo o uso do markdown4noobs no aprendizado da linguagem de marcação Markdown.

O básico sobre manipulação de texto e blocos de código

Markdown nos permite marcar partes do nosso texto com estruturas super básicas e necessárias como negrito, itálico, highlight, níveis de título, etc. Abaixo vamos ver rapidamente como realizar cada uma das ações com a sintaxe correta.

# Primeiro titulo equivalente a um h1
## Segundo titulo equivalente a um h2
### Terceiro titulo equivalente a um h3
#### Quarto titulo equivalente a um h4

`Texto em highlight`
**Texto em negrito**
*Texto em itálico*

Esses artifícios da linguagem markdown nos permitem controlar a narrativa a nosso favor e deixar a leitura mais simples de seguir, utilizando bold no meio do texto para chamar a atenção, deixar explicito um termo técnico usando highlight ou até mesmo utilizando imagens ilustrativas que introduzem o ponto do parágrafo enquanto mantém o clima geral do texto muito mais gostoso de ler.

Outra coisa importante de se mencionar é o bloco especifico que usei acima, ele é extremamente útil quando vamos escrever artigos técnicos, tanto, pois ele permite um destaque maior a um bloco de texto quanto ele permite habilitar syntax highlighting caso esteja escrevendo um bloco de código, ele é utilizado da seguinte maneira:

Disclaimer: Como markdown não permite um bloco dentro de um bloco optei por mostrar com um screenshot:

Após os símbolos de backtick, podemos incluir o nome da linguagem (no meu caso ruby) para que o dev.to possa habilitar o syntax highlighting especifico para essa linguagem de programação.

Tabela de conteúdo

Caso o seu artigo esteja ultrapassando a margem das duas mil palavras ou esteja com pelo menos 4 títulos principais, eu recomendo fortemente que deixe definido um Table of contents, ou Tabela de conteúdo. Essa tabela de conteúdo serve para guiar a leitura durante os pontos principais que serão lidados durante o artigo, para a criação de um existem uns macetes que vou demonstrar abaixo:

Na plataforma dev.to, use listas não ordenadas ao invés de listas numeradas

Listas em Markdown são bem simples de serem usadas e elas possuem dois tipos principais: não ordenadas e numeradas.

- Uma lista
- Não
- Ordenada

1. Uma lista
2. Numerada
3. Aqui

O problema de usar as listas numeradas no dev.to é que elas ficam desalinhadas como podemos ver no exemplo abaixo, portanto não recomendo o uso delas de maneira geral, sempre tento utilizar as listas não ordenadas e se for necessário aplicar alguma ordem utilizar um número após o símbolo da lista não ordenada manualmente.

Como organizar os links para um título

Assumindo que você já descobriu como estruturar um link no Markdown (já que você leu o markdown4noobs né?) vamos aprender os macetes simples para indicar um link em um título e como estruturar nossa tabela de conteúdo.

Uma tabela de conteúdo de exemplo pode ser vista abaixo:

## Table of contents

- [What is metaprogramming anyway?](#what-is-metaprogramming-anyway)
- [In ruby everything is an object, what does that mean?](#in-ruby-everything-is-an-object-what-does-that-mean)
- [But what about rails? How this framework applies that concept for maximum developer experience](#but-what-about-rails-how-this-framework-applies-that-concept-for-maximum-developer-experience)
- [How to define methods dynamically](#how-to-define-methods-dynamically)
- [Using hooks to detect moments on the instantiation of the class](#using-hooks-to-detect-moments-on-the-instantiation-of-the-class)
- [Conclusion](#conclusion)

Como você pode ver, a ideia geral para definir a segunda parte do link é incluir uma hashtag # junto ao título em um formato especifico seguindo as regras:

Trocar todos os espaços em branco por hifens -
Deixar todo o título em minúsculo

E é isso! Títulos com acentos podem continuar igual sem nenhum problema, o Markdown compreende como texto padrão igual mostrado abaixo:

- [Um título com muitos acentos e çedilha](#um-título-com-muitos-acentos-e-çedilha)

A estrutura básica de um artigo técnico

Agora que temos uma noção interessante de como podemos marcar nosso texto para ficar legível e agradável de ler, vamos entender um pouco a estrutura de um artigo. É importante ressaltar que um modelo não vai servir para todo tipo de texto possível, a ideia é prover uma ideia geral que deve ser adaptada e mudada conforme o contexto.

Primeiro é muito importante definir o parágrafo inicial para chamar o leitor para o problema ou a situação que você vai dissecar ao longo do artigo, é importante fazer isso, pois esse primeiro paragrafo vai ser usado pelo dev.to para comunicações de marketing por e-mail ou por redes sociais. Um exemplo de parágrafo inicial pode ser achado nesse mesmo artigo que você esta lendo ou em alguns outros que deixo abaixo:

A ideia é sempre utilizar perguntas e pausas no texto para podermos alcançar uma comunicação direta e bem conversacional, sempre tentando apresentar a situação da maneira mais geral possível para que quem esteja lendo fique com bastante curiosidade e vontade de ler.

Após o primeiro parágrafo de apresentação, é muito importante definir a Tabela de conteúdo para guiar o usuário ao longo dos títulos principais do seu artigo, sobre isso inclusive eu particularmente não recomendo listar os subtítulos junto dos títulos por conta de deixar a tabela de conteúdo muito grande e pouco útil para quem estiver lendo, obviamente que se você considerar seus subtítulos muito importantes de serem listados é completamente valido incluir.

Passando para o corpo geral do artigo, entramos em uma área muito subjetiva, pois depende muito do assunto que está sendo abordado para entender a estrutura dos seus títulos e parágrafos. Vou assumir um artigo no modelo de tutorial simples para ser possível partir de algum lugar.

Recomendo sempre ter três títulos satélites que vão nortear o seu artigo e dar inspiração para aumentar o conteúdo com mais detalhes. Esses títulos satélites são os seguintes:

Introdução a tecnologia ou problema: Esse parágrafo vai servir para podermos detalhar o que foi falado no começo do artigo, respondendo às perguntas que criamos para atiçar a curiosidade e aprofundando mais no tema que vai ser discutido com os tópicos específicos.
Prós e contras: Nesse momento vamos deixar claro os prós e contras da solução que vai ser apresentada no artigo, seja ela uma arquitetura, um padrão de código, uma linguagem, framework, etc. A existência desse paragrafo pode ser bem situacional dependendo do seu tema, mas costuma ser bem útil caso esteja apresentando uma solução em forma de tutorial!
Conclusão: Esse ponto é mais uma opinião do que uma regra geral, mas eu acho muito importante ter um parágrafo onde vai ser indicado o final do processo de leitura, assim podemos deixar argumentos finais, agradecimentos, contato e qualquer outra mensagem interessante.

Ao redor desses três principais títulos, podemos desenvolver nosso artigo com uma escrita ilustrativa e que apresente exemplos práticos ou analogias, facilitando a visualização tanto do problema quanto da solução pelo leitor. É importante ressaltar também o cuidado ao aprofundar muito nas analogias, elas são extremamente uteis, mas podem ser um tiro no pé quando você abusa e nunca volta para o mundo real com uma solução e explicação clara.

Uma dica geral ao redor da estrutura do artigo é manter o sentimento geral da leitura leve, portanto é super aconselhável utilizar imagens (seja um meme para descontrair ou um gráfico para ilustrar melhor o ponto apresentado), como a plataforma do dev.to comporta artigos técnicos mais informais, abusar dessa linguagem mais próxima é uma estratégia muito certeira.

Como revisar e melhorar a escrita

Bom, agora que temos uma boa ideia de como estruturar nosso artigo, como mantê-lo bonito utilizando Markdown e como ponderar nossa linguagem para a plataforma especifica, o que falta? Bom, agora o que falta é entender que não somos perfeitos e erramos, portanto, precisamos de uma boa estratégia para revisar o artigo que acabamos de produzir com nossas técnicas aprendidas.

Para auxiliar na escrita, eu recomendo fortemente utilizar um editor que oferece visualização do Markdown em tempo real como VSCode ou o queridinho da comunidade Obsidian. Inclusive esse artigo foi escrito utilizando o Obsidian!

No que se entende por revisão temos algumas ferramentas bem interessantes que nos auxiliam em diversos aspectos da escrita:

LanguageTool: Essa ferramenta é meu xodózinho e ela cuida de toda correção de ortografia, a parte legal é que nessa ferramenta você pode ter dicas de contexto que vão melhorar a frase e também correção de termos específicos de programação como nomes de linguagens visto que o banco de dados deles é super atualizado.
Deepl: Entrando no mundo das inteligências artificiais, o Deepl utiliza deep learning para oferecer uma interface incrível de tradução, mas não só isso! Com ele podemos ter uma segunda opinião para refrasear nosso parágrafo de forma muito simples, você só precisa traduzir o texto para inglês e traduzir o texto em inglês para português de novo; normalmente no Google Translate isso destruiria o contexto, mas essa ferramenta mantém o contexto e melhora as expressões para que você possua uma segundo percepção de um mesmo paragrafo.
ChatGPT ou Bard: Bom, aqui eu confesso que não tenho muito domínio e não uso tanto, mas essas interfaces de chat com IA ajudam muito a ter visões diferentes para refrasear um parágrafo já existente ou até mesmo começar a escrever algum. Importante: Preciso ressaltar para usar essas ferramentas apenas para ter ideias ou ajudar a refrasear textos que você já escreveu, por favor não produza artigos inteiros utilizando inteligência artificial
Comunidade: Na comunidade He4rt Developers tentamos providenciar o máximo de auxílio para a escrita de artigos técnicos na plataforma dev.to. Fazemos isso providenciando um fórum onde você pode postar seu artigo ainda em progresso e ganhar feedback da comunidade até a publicação, após a publicação a gente ainda faz um trabalho de divulgação para pessoas ativas! Disclaimer: Obviamente estou citando a He4rt, pois temos um projeto voltado para isso, mas a lição geral é compartilhar seus progressos com a comunidade de maneira geral.

Conclusão e agradecimentos

Esse é o último artigo que estou postando seguindo o desafio 100 dias de código, foi um desafio muito intenso e com muito aprendizado onde eu descobri uma nova paixão: escrever e compartilhar conhecimento! Não tenho nem palavras para agradecer a comunidade da He4rt por ter me apoiado 100% nessa jornada imensa. Espero que esse artigo seja útil para quem esteja lendo e que inspire qualquer um a compartilhar conhecimento online para podermos criar uma internet mais segura e rica em informação.

Gostaria também de deixar um agradecimento especial aos revisores desse artigo:

May the force be with you! 🍒

Forem: He4rt Developers

DataAccess: ADO.net

Controle total e performance máxima

O que é?

Quando faz sentido usar?

Como funciona (essencial)

Segurança básica (obrigatório)

Performance: por que é tão rápido?

ETL? Aqui ele brilha

Comparação rápida

Regra prática

Insight final

Link para o repo.

BrunoSFreschi / DataAccess.Benchmark

DataAccess Benchmark é um laboratório de engenharia de software criado para analisar, o custo das diferentes abordagens de acesso a dados no ecossistema .NET.

DataAccess Benchmark

A História do Acesso a Dados no .NET

Por que eu começo 10 projetos e não termino nenhum?

Table of contents

O prazer de começar

O momento em que tudo desmorona

O objeto brilhante

A culpa que ninguém fala

Não é preguiça. É neurologia.

Conclusão

O que uma usina nuclear tem a ver com o seu processo de QA?

O que aconteceu em Chernobyl?

E o que isso tem a ver com software?

O maior problema: risco tratado de forma rasa

Ouça sua equipe

Analise antes de agir

Conclusão

De front-end para UX, e de volta ao código: o que significa ser Design Engineer em 2026

Minha trajetória: 5 anos de front-end, 5 anos de UX

O que é design engineer em 2026?

Como front-end e UX mudam sua forma de ver produto

Por que estou voltando ao código agora

Como estou usando IA no processo de aprendizado

Design Engineer não é um cargo. É uma forma de pensar

O que vem por aí: UX data-driven e componentes React

Você também está nesse meio-termo entre UX e código?

Construí um gerador de playlists no Spotify com Claude

TL;DR

Índice

A Ideia

A Stack

O Problema de Trabalhar com OAuth Localmente

O Spotify não aceita localhost

O NextRequest normaliza URLs pra localhost

Dois momentos onde o redirect URI importa

A solução: Auth() direto com Request nativo

Bônus: problema de domínio do cookie PKCE

Endpoints Deprecated do Spotify

Spotify em Produção

Fazendo o Claude Obedecer

One-shot prompting

Extração de JSON como fallback

Prompt Engineering Anti-Alucinação

O system prompt atual completo

Melhor resolução de busca no Spotify

Modo Related Artists

Construindo o Perfil Musical

Streaming com SSE

O Que Aprendi

Teste Você Mesmo

Engenharia de Prompt: Por Que a Forma Como Você Pergunta Muda Tudo(Um guia introdutório)

Prefácio

Antes de tudo, para lembrar, o que é uma LLM mesmo?

Fazendo Perguntas

Mas afinal, como perguntar de forma certa?

1 - Evite a Ambiguidade

2 - Delimite o Escopo

3 - Forneça Contexto Relevante

Considerações Finais

Do commit ao deploy: CI/CD de uma API na AWS usando GitHub Actions, ECS e Terraform

Sumário

Introdução

Pré-requisitos

Visão Geral da Arquitetura

Configurando o IAM para o Terraform

O Spotify não aceita `localhost`

O `NextRequest` normaliza URLs pra `localhost`

A solução: `Auth()` direto com `Request` nativo