[{"data":1,"prerenderedAt":106},["ShallowReactive",2],{"content-/blog/markdown-review-merge-hell-e-a-spec":3},{"id":4,"title":5,"body":6,"date":94,"description":16,"extension":95,"image":96,"language":96,"meta":97,"navigation":98,"path":102,"seo":103,"stem":104,"__hash__":105},"blog/blog/markdown-review-merge-hell-e-a-spec.md","Markdown review, merge hell e a spec de 1 milhão de linhas",{"type":7,"value":8,"toc":87},"minimark",[9,13,17,23,28,31,34,37,43,46,50,53,56,59,62,65,68,71,75,78,81,84],[10,11,5],"h1",{"id":12},"markdown-review-merge-hell-e-a-spec-de-1-milhão-de-linhas",[14,15,16],"p",{},"Nas últimas semanas tenho trabalhado com Spec Driven Development (SDD) usando a lógica de AI-First com o Claude Code automatizando vários passos do processo interno, ou como temos dito na equipe: do Jira ao PR. Se trata de um projeto greenfield e sem nenhuma ferramenta de SDD específica como Kiro, spec-kit ou Tesl, e sim plugins internos para o Claude os quais vou omitir quaisquer detalhes. Meu objetivo aqui é compartilhar as minhas impressões e opiniões sobre esse salto que estamos vivendo no desenvolvimento de software a partir de uma experiência real.",[18,19],"img",{"src":20,"alt":21,"width":22},"/images/voce-vai-trabalhar-menos-ne.jpeg","Isso significa que vamos trabalhar menos, né?",64,[24,25,27],"h2",{"id":26},"a-experiência","A experiência",[14,29,30],{},"Ao usar o Claude Code com um processo mais organizado produzimos mais código e mais rápido, mas o código ainda precisa passar pela curadoria humana, porque no fim não é a spec que vai pra produção e até mesmo os melhores modelos de geração de código ainda podem propagar erros, bugs, subotimizações, alucinar ou não ter contexto suficientemente completos para algumas tarefas específicas de uma aplicação. E assim, nós programadores nos tornamos curadores de qualidade de código e orquestradores de agentes de codificação. Em muitas situações nos tornamos o “gargalo”, pois é mais fácil produzir código e o tempo para abrir um Pull Request diminuiu muito, mas o tempo de Code Review continua o mesmo, ou maior já que é necessário mais atenção nessa etapa e com mais PRs vêm mais conflitos de merge.",[14,32,33],{},"Com AI-First o processo está sendo automatizado usando IA desde a criação das user stories no Jira a partir de PRDs. Isso cria mais dos chamados pontos de inspeção, etapas do processo onde é necessária a atuação humana e, onde geralmente existem os gargalos. O Code Review é um exemplo de ponto de inspeção. No contexto da esteira de processo como um todo passam a existir também a revisão das user stories e das specs. Isso mesmo, não escrevemos as specs manualmente e sim usando IA. Com os plugins e skills de SDD internos da empresa o Claude escreve os arquivos de spec e revisamos e iteramos sobre o markdown (Vibe Spec?).",[14,35,36],{},"O que posso dizer é que com relação a entrega tem sido uma boa experiência. Comparada com experiências anteriores, muitos aspectos foram otimizados ou se tornaram menos massantes. O tempo de desenvolvimento está bom, bem melhor do que se tivéssemos que escrever todo o código. No entanto, para desenvolver casos de uso mais complexos é necessária mais atenção aos detalhes de implemetação, pois muito contexto está na nossa cabeça e pode não estar nem no PRD, user story ou na spec, e muito do nosso conhecimento e experiência é necessária para antever problemas e bugs, que geralmente existem no menores detalhes, durante o desenvolvimento.",[38,39,40],"blockquote",{},[14,41,42],{},"“Crucially, your role isn’t just to steer. It’s to verify. At each phase, you reflect and refine.”",[14,44,45],{},"Essa citação do Github sobre o spec-kit descreve bem a experiência até aqui. Acredito que isso seja independente da ferramenta que se esteja usando para SDD.",[24,47,49],{"id":48},"nem-tudo-é-um-campo-verde","Nem tudo é um campo verde",[14,51,52],{},"Até agora parece uma propaganda tipo “Use AI, não fique para trás” né? Mas não tô escrevendo isso pra vender curso. Desculpe despontar, mas não vou te ensinar a criar software sem conhecimento de programação. Por se tratar de uma experiência nova, talvez hajam mais questões sem respostas e problemas que ainda não foram identificados do que soluções mágicas para os problemas de processos de desenvolvimento.",[14,54,55],{},"A começar com as specs. É difícil definir precisamente o que é ou o que deve ser uma spec. Tenho buscado estudar sobre o assunto mas percebi que ainda não existe um consenso sobre a definição de uma spec. Na forma mais abstrata e resumida é um artefato que descreve e linguagem natural uma feature a nível de produto e pode ser usado como guia para agentes de IA (mas podem ter muitas variações dessa definição). Além disso, existem diferentes abordagens para SDD, recomendo o artigo da Birgitta Böckeler sobre o assunto pra mais detalhes.",[14,57,58],{},"Ao adotar AI-First, delegamos aos agentes a tarefa de escrever as specs, mas se pensarmos no PRD como um artefato que pode ser considerado uma spec macro (várias features) então nosso cenário é mais Spec-First? E isso faz alguma diferença? Bom, para melhorar um processo o primeiro passo é entendê-lo. Se excluimos a definição e escrita dos PRDs do processo e a IA produz tarefas mal segmentadas, pouco paralelizáveis ou sem resolver bem as dependências entre elas, e isso prejudica a produtividade desde o início, como sabemos onde melhorar para otimizar ainda mais?",[14,60,61],{},"Um outro ponto é que quando as tarefas desenvolvimento são hiper-paralelizadas, isso não necessariamente leva ao melhor dos mundos. Mais código chegando ao estado de “pronto para revisão” mais rápido implica em mais code reviews e mais testes em ambiente de dev que precisam ser feitos, de novo, os gargalos dos pontos de inspeção. Essa experiência inicial em um projeto greenfield me mostrou que tarefas menores são mergeadas mais rápido e em muitas situações podem prejudicar as tarefas maiores que estão em paralelo pois existem mais conflitos de merge sendo gerados e isso aumenta o tempo e trabalho necessário nos pontos de inspeção humana.",[14,63,64],{},"Uma lição que aprendemos é melhorar o design de projeto tendo arquivos mais especializados, basicamente levar a lógica de Single Responsibility para os arquivos do projeto, visando minimizar conflitos de merge em tarefas paralelizadas. Usamos Go, e o fato de a linguagem ser bem orientada por packages é uma vantagem pois torna possível separar até mesmo funções de uma mesma struct em arquivos diferentes. Uma decisão positiva para isso também foi a de usar a abordagem de Contract-First (ou API-First) desde o início do projeto, e assim desenvolver contratos de API e interfaces internas antes das tarefas em paralelo.",[14,66,67],{},"Ainda sobre pontos de inspeção, penso que melhorias em outras partes do processo como melhor priorização das tarefas e funcionalidades, acordos internos entre a equipe em relação aos code reviews e até mesmo a criação de novas skills customizadas para ajudar com os pontos de inspeção. Tenho trabalhado em algumas dessas ações, mas ainda analisando o efeito delas.",[14,69,70],{},"Um ponto importante que merece atenção é a evolução dos arquivos de contexto agêntico. Além do CLAUDE.md, usamos arquivos mais específicos como PROJECT.md para informações com uma linguagem mais de produto, PATTERNS.md com padrões de projeto comuns dentro do código bem como o uso de bibliotecas externas para vários fins. Depois de algumas primeiras iterações, percebemos que mesmo tarefas muito parecidas, quando executadas de forma independente produziam resultados um tanto diferentes, a partir disso criamos o ARCHITECTURE.md, que descreve com mais detalhes os diretórios do projeto, o objetivo de cada camada da aplicação e isso trouxe uma melhora significativa.",[24,72,74],{"id":73},"o-que-tirei-disso-em-poucas-linhas","O que tirei disso (em poucas linhas)",[14,76,77],{},"Depois dessa experiência, minha principal conclusão é que estamos trocando o papel de escrever código pelo de cuidar do processo. E isso não é necessariamente um problema — é uma evolução. O gargalo deixou de ser \"quantos arquivos eu consigo implementar por dia\" e passou a ser \"quantas decisões importantes eu consigo revisar com qualidade\". E olha, revisar spec escrita por IA não é mais fácil do que revisar código; é diferente, mas igualmente crítico. Aprendi também que spec ainda é um conceito mal resolvido na indústria, e jogar IA nesse território nebuloso sem definir bem o que esperamos dela pode ser receita para ruído. Outro aprendizado que levo: paralelizar tarefas cegamente não acelera entrega, na verdade tende a acelerar o acúmulo de trabalho. No entanto, um bom planejamento de projeto e contexto, isso sim faz diferença, é algo em que vale a pena investir tempo.",[14,79,80],{},"No fim, SDD com IA não é um atalho mágico, mas um novo tipo de disciplina. Não vai extinguir os desenvolvedores mas mudar a forma como eles trabalham. O uso de IA na programação é realidade, não é mais futuro e sim presente. É indiscutível que LLMs generativas como ferramentas para produzir código é um grande salto industrial no setor de desenvolimento de software. Mas abordagens como SDD devem ser vistas como tentativas de organizar o processo com a adição dessa nova ferramenta.",[14,82,83],{},"Não existe nada escrito em pedra, assim como temos muitas outras contribuições na história da engenharia de software desde waterfall a métodos ágeis, com abordagens diferentes que podem ser melhor ou pior aplicáveis a depender do contexto empresarial e equipe. Penso que SDD é isso, e parte de nosso papel na indústria de software é busca contribuir para o debate sobre o uso de IA, destacar problemas, propor soluções, apresentar idéias a partir de contextos concretos específicos pra depois caminhar em busca de generalização, soluções mais amplas.",[14,85,86],{},"E bom, é isso que estou tentando fazer. Me segue e se inscreve aí. Quem sabe vem uma Parte 2 depois de mais algumas iterações do projeto. Tô tentando consolidar um espaço de compartilhamento por aqui pra vários assuntos relacionados a tecnologia.",{"title":88,"searchDepth":89,"depth":89,"links":90},"",2,[91,92,93],{"id":26,"depth":89,"text":27},{"id":48,"depth":89,"text":49},{"id":73,"depth":89,"text":74},"2026-04-28T00:00:00.000Z","md",null,{},{"title":5,"description":99,"image":20,"language":100,"date":101},"Impressões sobre spec driven development com AI-first em um projeto real pra que você não fique refém de postagens no LinkedIn","pt","2026-04-28","/blog/markdown-review-merge-hell-e-a-spec",{"title":5,"description":16},"blog/markdown-review-merge-hell-e-a-spec","UFW5Nhw6_b3hwoxaKMXz6LKgGs9ydq4vtyFYwTwYqDA",1777417652928]