CommunityImagemgithub.com

antes-depois

Gera uma imagem com uma tabela de capturas de tela 'antes e depois' mostrando cada mudança visual que o branch atual faz em relação a um branch base — cada tela, componente e estado alterado é capturado a partir de uma compilação local da base e do branch, sob os mesmos dados, viewport e tema, com uma verificação de pixel garantindo que cada par realmente difere. Use quando o usuário solicitar capturas de tela antes/depois, uma tabela de comparação, um diff visual, uma comparação de screenshots ou imagens das alterações visuais para um pull request, revisão ou designer. Apenas captura e compõe imagens; não edita o código do projeto.

O que é antes-depois?

O skill 'antes-depois' é uma ferramenta de automação para desenvolvedores que precisam documentar visualmente as alterações introduzidas por um branch em relação a um branch base (como main ou a base de um PR). Ele constrói ambos os branches localmente, captura screenshots emparelhadas de cada mudança visual — incluindo diferentes estados de dados (carregamento, vazio, erro), interações (hover, foco, popover) e temas (claro/escuro) — e compõe uma única imagem PNG com uma tabela lado a lado ou empilhada. O skill verifica pixel a pixel que cada par realmente difere, evitando falsos positivos causados por dados dinâmicos ou cache. É especialmente útil para revisões de código, pull requests e comunicação com designers, pois produz evidências visuais claras e repetíveis sem modificar o código do projeto. Suporta projetos com catálogos de componentes (Storybook) e testes E2E, e pode ser usado com ferramentas CLI como Claude Code, Cursor e Codex, sendo executado localmente com Node.js e Playwright.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MagnusBrogie/agent-skills/tree/HEAD/before-after

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Antes e depois

Produz um PNG: uma tabela com uma linha por mudança visual, e em cada linha o nome da mudança, uma nota de uma linha, a captura de tela da base e a captura de tela do branch. Um leitor que não viu o código deve ser capaz de identificar pela imagem o que mudou visualmente e onde.

A imagem é tão boa quanto sua lista de mudanças. Uma tabela que mostra três de cinco mudanças, ou que mostra uma diferença causada por dados diferentes em vez do código, engana o leitor. A maior parte do trabalho é encontrar cada mudança visual e capturar cada par de modo que o código seja a única coisa que difere.

Onde as imagens vão. Tudo que este skill produz é armazenado na pasta Documentos do usuário, em ~/Documents/antes-depois/<repositorio>/<branch>/: as capturas, o manifesto, uma cópia de shots.mjs e o antes-depois.png final. Os scripts escolhem esta pasta sozinhos e não recebem caminho de saída; um usuário que queira outra raiz que não ~/Documents/antes-depois define a variável de ambiente BEFORE_AFTER_DIR, que é dele, não sua. Não escreva as imagens em nenhum outro lugar, e não as mova nem copie depois; o scratchpad é apenas para a worktree base e para rascunhar shots.mjs. Uma execução posterior para o mesmo branch reutiliza a pasta.

Dois scripts estão em scripts/ ao lado deste arquivo: capture.mjs tira as capturas, e compose.mjs monta e verifica a tabela. Cada um documenta seu formato de entrada em seu cabeçalho. Leia ambos os cabeçalhos antes de começar.

Notas locais. Se um arquivo chamado LOCAL.md estiver ao lado deste arquivo, leia-o antes de começar. Ele contém os padrões do próprio usuário para os projetos em que trabalha (comandos, hosts, contas, caminhos) e não faz parte do skill publicado. Onde ele cobrir o projeto em questão, conta como parte das instruções do projeto; onde não cobrir, ignore-o.

1. Reunir as mudanças

Sem um branch base informado, use a base do pull request (gh pr view --json baseRefName --jq .baseRefName), senão o branch padrão (git symbolic-ref --short refs/remotes/origin/HEAD), senão origin/main. Prefira a ref remota de rastreamento. Inclua trabalho não commitado:

base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short   # leia também arquivos não rastreados
git log --oneline "$base"..HEAD

Leia também a descrição do pull request e a issue, se houver. Eles frequentemente dizem quais telas a mudança afeta e incluem capturas de tela que as pessoas esperam ver.

2. Listar cada mudança visual

Trace cada hunk para fora até o que o usuário vê:

  • Visualizar código, estilos, tokens, ícones, cópia, traduções. Cada um destes é um candidato. Para código compartilhado (um componente de UI, um helper de formatação, um token CSS), procure por seus chamadores e liste cada tela que o renderiza. Uma mudança em código compartilhado geralmente é vista em mais lugares do que o branch pretendia.
  • Estados de dados. Para cada tela, leia quais ramos do código alterado são percorridos: carregado, carregando, vazio, erro, valor ausente, zero e negativo, texto longo, um item e muitos, cada modo ou configuração. Mantenha apenas os estados cuja renderização o diff altera.
  • Estados de interação. Hover, foco, pressionado, desabilitado, selecionado; um popover, menu, folha ou diálogo aberto; um campo mostrando erro de validação. Estes precisam de passos antes da captura (etapa 4).
  • Telas que o branch adiciona ou remove. Estas têm apenas um lado; a linha mostra um placeholder para o outro.
  • Ambientes que o projeto suporta, onde a mudança pode parecer diferente: tema escuro, larguras mobile e desktop, outra localidade.

Classifique os candidatos em três listas:

  1. Visual: algo na tela difere. Estes se tornam linhas.
  2. Não visual: a mudança afeta apenas a árvore de acessibilidade, atributos, texto somente para leitor de tela, comportamento ou estrutura de código. Estes não são linhas. Nomeie-os no relatório, para que o leitor saiba que foram considerados e não esquecidos. Se o usuário quiser que sejam mostrados mesmo assim, uma linha pode conter um trecho da árvore de acessibilidade capturado como imagem, rotulado como tal.
  3. Incerteza: mudanças de marcação ou classes que deveriam ser invisíveis, mas podem mover ou recolorir algo (um novo elemento wrapper, uma classe de posicionamento, um helper trocado). Capture estes e deixe que a verificação de pixel decida.

Uma mudança em movimento (uma animação, uma transição, seu tempo) não pode ser mostrada em uma imagem estática. Coloque-a em "Não mostrado" no relatório e diga como vê-la.

Agrupe as linhas de forma sensata: uma linha por aparência distinta, não por local de chamada. Se dez telas usam a célula alterada da mesma forma, mostre uma ou duas delas e nomeie as demais na nota. Busque uma tabela que alguém realmente lerá; acima de cerca de doze linhas, faça uma segunda imagem por área e informe.

Se as listas visual e de incerteza estiverem ambas vazias, pare aqui. Diga ao usuário que o branch não tem mudanças visuais, liste o que foi considerado e por que cada item não é visual, e não produza imagem. Se apenas itens de incerteza existirem e cada par for idêntico, o resultado é o mesmo, e os pares idênticos são a evidência: relate-os como verificados e inalterados.

3. Compilar a base e o branch localmente

Capture ambos os lados a partir de compilações locais, nunca de uma implantação: uma implantação está atrasada em relação à árvore de trabalho e não pode mostrar trabalho não commitado.

  • Branch: a árvore de trabalho atual, compilada após a última alteração.

  • Base: uma worktree separada no merge base, para que a árvore de trabalho do usuário nunca seja tocada. Nunca mude de branch ou faça stash no checkout do usuário.

    git worktree add --detach <scratchpad>/before-after-base "$base"
    

    Instale as dependências lá. Sincronizar o diretório de dependências do checkout principal é aceitável apenas quando o diff não toca o lockfile. Remova a worktree quando terminar (git worktree remove).

Use os comandos documentados do projeto (leia seu README, AGENTS.md, CLAUDE.md, documentos de desenvolvimento e qualquer skill run). Ambos os lados devem falar com o mesmo backend de staging ou teste, nunca produção. Se não estiver claro qual comando direciona para qual backend, leia a configuração de compilação e, se ainda restar dúvida, pare e pergunte. Antes de capturar qualquer coisa, verifique o host de uma requisição API real de cada lado.

Prefira a compilação de produção do projeto servida estaticamente (um build seguido de um preview ou qualquer servidor estático) em vez do servidor de desenvolvimento. Um servidor de desenvolvimento adiciona clientes de hot-reload e overlays, pode precisar de um processo watcher por worktree e pode renderizar de forma diferente do que vai para produção. Se você compilar com uma ferramenta que não é o comando de build do projeto, verifique se a página renderiza: um projeto pode pós-processar seu bundle. Uma compilação também pode esvaziar ou sobrescrever um diretório de saída na árvore de trabalho do usuário. Esses são arquivos gerados, mas diga no relatório o que você recompilou e coloque de volta o que a configuração de desenvolvimento espera, se a compilação o removeu.

Antes de confiar em qualquer captura, confirme que as duas compilações diferem: leia o elemento alterado no markup de cada lado e veja a mudança do diff nele. Dois servidores que servem o mesmo código produzem pares idênticos que não provam nada.

Escolha como servir as duas compilações:

  • Ambas ao mesmo tempo, em duas portas livres. Esta é a mais simples, e as duas capturas de um par são tiradas com segundos de diferença. Funciona quando as telas não precisam de login, ou quando o login sobrevive a uma mudança de porta. Cookies são compartilhados entre portas no mesmo host, mas o armazenamento local não é, e um backend pode aceitar apenas certas origens. Verifique se uma tela logada realmente carrega na segunda porta antes de confiar nela.
  • Uma após a outra, na mesma porta. Sirva a base na porta usual do projeto, capture com --side=before, pare-a, sirva o branch nessa porta e capture com --side=after. O estado de login salvo e as origens permitidas se aplicam a ambos. As capturas têm minutos de diferença, então os dados devem ser simulados (mocked) ou conhecidos por serem estáveis.

Se o projeto tiver um catálogo de componentes (Storybook, um app "workshop" ou similar) e a mudança estiver em um componente compartilhado, capturá-lo lá é mais barato e mais estável do que no aplicativo completo, e geralmente não precisa de login. Ainda assim, capture pelo menos uma tela real por mudança onde puder, para que a imagem a mostre em contexto. Se uma tela real não puder ser acessada (sem credenciais de teste, por exemplo), informe em "Não mostrado".

4. Capturar cada par sob condições idênticas

Escreva um shots.mjs no scratchpad, no formato dado no cabeçalho de scripts/capture.mjs, e execute-o a partir da raiz do projeto, para que o Playwright resolva e a pasta de saída receba o nome correto do repositório e branch:

node <this skill>/scripts/capture.mjs <scratchpad>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>

O script executa os mesmos passos contra ambas as URLs. Ele usa o Chrome instalado, um fator de escala de dispositivo de 2 e movimento reduzido. Ele desliga transições, redefine animações infinitas (um brilho, um spinner) para seu primeiro quadro e finaliza as finitas, espera por fontes e pela rede estabilizar, e congela o relógio se você fornecer uma hora. Ele escreve shots/<slug>.before.png, shots/<slug>.after.png e o manifest.json para a etapa 5 na pasta Documentos descrita acima, copia shots.mjs para lá e imprime o caminho da pasta como sua última linha. --only=<slug> recaptura uma linha. Uma captura com falha deixa um <slug>.<side>.FAILED.png da viewport inteira, que mostra como a página estava.

Se a configuração de teste E2E do projeto tiver um estado de login salvo, passe-o como storageState (leia a documentação do projeto sobre como ele é criado). No Orca, o navegador embutido (skill orca-cli) também funciona para um ou dois pares, mas um script torna os pares repetíveis.

O que você precisa acertar em shots.mjs:

  • Mesmos dados em ambos os lados. Dados ao vivo variam entre duas capturas: preços mudam e listas reordenam. Prefira simular (mock) as respostas das quais a tela depende no mock da captura: capture um payload real do staging e atenda ambos os lados com ele. Dois limites:
    • Se o branch altera a requisição ou a forma da resposta (um novo endpoint, um novo campo, um decoder alterado), um payload não pode servir ambos os lados. Dê a cada lado o payload que seu código espera, construído a partir dos mesmos valores subjacentes, e informe na legenda.
    • Dados que chegam por WebSocket ou server-sent events não são afetados por page.route. Use page.routeWebSocket, ou escolha uma tela ou um momento em que o fluxo está quieto, ou oculte o elemento ao vivo se não for o assunto.
  • Alcance o estado deliberadamente. Estados de carregamento, erro e valor ausente raramente ocorrem em contas de teste: produza-os em mock (atrase uma resposta, falhe-a, anule um campo). Derive os caminhos de requisição e nomes de campo do código, não por palpites. Alcance estados de interação em steps (hover, foco, clique para abrir).
  • Corte a mudança com contexto. Defina target para o menor elemento que mostra a mudança e ainda é reconhecível como parte de sua tela: o card, a tabela, a folha, não a página inteira. Busque um corte de no máximo cerca de 650 CSS px de largura: é o que cabe lado a lado em tamanho real. Um corte mais largo é empilhado (antes sobre depois), e um mais largo que cerca de 1300 CSS px é reduzido, tornando o texto mais difícil de ler. Use o mesmo target em ambos os lados para que os cortes se alinhem.
  • Oculte o que não é o assunto e continua se movendo (um ticker, um relógio, um avatar que carrega tarde) com uma tag de estilo em steps, em ambos os lados.

5. Compor e verificar

node <this skill>/scripts/compose.mjs <pasta>/manifest.json [--diff] [--stack]

A imagem é escrita ao lado do manifesto como antes-depois.png, e seu caminho é a última linha da saída. --diff adiciona uma imagem por linha com os pixels alterados em magenta. Use quando a mudança for pequena ou sutil (espaçamento, uma cor, um glifo); deixe de fora quando a mudança for óbvia. Quando as duas capturas de uma linha diferem em tamanho, a comparação é alinhada no canto superior esquerdo, então tudo após o deslocamento conta como alterado; a linha informa isso, e a imagem de diff é então apenas um guia aproximado.

O script desenha ambas as capturas de uma linha na mesma escala. Ele imprime a proporção de pixels alterados por linha e como cada linha foi disposta, e sai com código 3 se algum par for idêntico. Então:

  1. Um par idêntico significa que a captura perdeu a mudança (estado errado, tela errada, um cache, uma compilação base que não é realmente a base) ou a mudança não é visual. Descubra qual. Corrija a captura, ou remova a linha do manifesto e mova o item para a lista não visual como "verificado, nenhum pixel difere". Nunca publique uma linha com um par idêntico.
  2. Olhe para a imagem (leia o PNG) e verifique cada linha: a diferença que você vê é a que a nota descreve, e nada mais difere. Uma diferença que não é explicada pelo diff (um preço diferente, uma linha faltando, layout deslocado em outro lugar) é deriva de dados ou uma regressão inesperada. Recapture, ou relate ao usuário como uma possível regressão. Não esconda.
  3. Verifique se o texto em cada captura pode ser lido. Aja sobre qualquer aviso "texto pode estar ilegível" do script: corte mais estreito e recapture essa linha com --only.
  4. Se a imagem for muito longa, divida-a por área: crie uma subpasta por área dentro da pasta do branch, cada uma com seu próprio manifest.json cujos caminhos apontam para ../shots/..., e componha cada um.

6. Relatar

Dê ao usuário:

  • O caminho absoluto completo para o PNG.
  • As linhas, uma por linha.
  • Não mostrado: as mudanças não visuais, os itens de incerteza que a verificação de pixel achou inalterados, mudanças de movimento, as mudanças visuais que você não conseguiu capturar (e por quê), e os locais de chamada deixados de fora como duplicatas de uma linha que é mostrada.
  • Qualquer coisa inesperada que a verificação de pixel ou seu próprio olhar revelou.
  • Como os pares foram produzidos (dados reais de staging, ou quais respostas foram simuladas; um catálogo ou o aplicativo real), para que o leitor saiba o que as imagens provam.

Pare os servidores de desenvolvimento que você iniciou e remova a worktree base. As capturas, a cópia de shots.mjs e o manifesto permanecem na pasta de saída, para que uma execução posterior possa recapturar uma única linha com --only.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas