Ensinando o agente a revisar MR como gente

Agente de código já escreve código razoável. O que ele faz mal é o resto do trabalho: explicar uma coisa pra quem não tem contexto, escrever um comentário que não pareça gerado, revisar o MR de um colega sem afogar o achado importante em vinte preferências pessoais.

O repositório skills é onde eu guardo as instruções que uso pra isso. Cada skill é um arquivo SKILL.md com um frontmatter e um procedimento. Elas rodam no Claude Code, no Codex, no Cursor e em qualquer agente que o skills CLI suporte:

npx skills@latest add joaomarcostg/skills --skill review-mr

No Claude Code, cada uma vira um slash command: /explain, /concise, /review-mr !1226.

O que tem lá

Hoje são nove, em quatro grupos:

• Escrita: explain e concise.
• Frontend: frontend-development.
• Merge requests: review-mr, review-deck, address-mr-feedback e record-demo.
• Ticket de ponta a ponta: feature e oncall.

O primeiro commit, em setembro de 2026, já trouxe sete delas. Depois vieram uma reescrita grande do review-mr, a skill de frontend e a review-deck.

Escrever pra humano tem regra

A concise é a mais curta e talvez a que eu mais uso. Ela parte de três perguntas que toda frase precisa sobreviver:

1. O leitor já sabe disso? Corta.
2. Dá pra ver isso no código ou na thread? Corta.
3. Se o leitor agir com base nessa frase, o que ele faz de diferente? Sem resposta, corta.

Depois vem uma lista de coisas banidas. Travessão longo, “leverage”, “robust”, “seamless”, aberturas como “It’s worth noting that”, fechamentos como “In summary”. E o hábito da tríade, aquela mania de listar tudo de três em três, que a skill chama de o sinal mais forte de texto feito por IA.

A explain vai pelo outro lado. Ela assume que o leitor tem zero contexto. Antes de explicar, o agente lista todo termo que vai usar e decide: define na primeira vez ou troca por palavra comum. Se o código nunca expande uma sigla, a skill manda dizer isso em vez de inventar uma expansão. E toda afirmação sobre o código vem com arquivo:linha.

Revisar é refutar

A review-mr é a mais elaborada. Ela foi reescrita uma vez, e a versão atual se organiza em torno de três perguntas que um revisor humano faz, nessa ordem:

1. Faz o que se propõe? Se é um fix, o bug sumiu mesmo, e pela causa certa?
2. O que mais isso toca? Outros chamadores, caminhos irmãos, estado em cache.
3. O código está decente?

As duas primeiras bloqueiam aprovação. A terceira não, a não ser que o código esteja ruim de verdade. O texto da skill diz isso sem rodeio: a maior parte dos achados de qualidade é gosto, e gosto não pertence ao MR dos outros.

A ideia de usar perguntas em vez de técnicas tem um motivo prático. Uma pergunta termina quando é respondida. Uma técnica como “procure code smells” não tem ponto de parada, e o agente segue até acabar o orçamento, reportando tudo que viu no caminho.

A fase que eu considero o coração da skill é a de refutação. Achado de revisão é plausível por construção, e é isso que o torna perigoso. Então, pra cada achado, a skill sobe um subagente novo, sem saber dos outros achados nem da revisão que gerou aquele. A tarefa dele é provar que o achado está errado. Só o que sobrevive vira comentário, e só depois de eu aprovar um por um.

Tem também um detalhe operacional que só aparece quando você roda isso todo dia. Se uma execução é interrompida, sobra um worktree pra trás, e o próximo git fetch falha. A skill manda limpar antes de começar, não só no fim. E manda conferir se o arquivo de diff começa com diff --git, porque alguns proxies de terminal reescrevem a saída do git e entregam um resumo truncado no lugar do diff.

Ticket do começo ao fim

A feature e a oncall encadeiam as outras. A oncall tem uma ordem fixa e duas travas:

0 Intake + route -> 1 Explain (stop) -> 2 Reproduce -> 3 Red test -> 4 Fix

Na fase 1 ela para e espera eu corrigir a hipótese, porque quem está no plantão sabe coisas que o ticket não diz. Na fase 3, sem teste falhando, não tem fix. Nas palavras da skill: um fix escrito antes de reproduzir o bug é um chute.

A feature congela os critérios de aceite antes de construir e começa por uma fatia vertical. As duas terminam com uma revisão feita por um agente novo, que não escreveu o código.

Prova em vídeo

A record-demo grava um MP4 da mudança numa janela real do Chrome: tela de título, estado quebrado, estado consertado e um comparativo lado a lado. Junto vem o review-clip.sh, que reprova vídeo chato antes de ele ir pro MR. Ele usa o filtro freezedetect do ffmpeg pra medir quanto tempo a tela fica parada:

ffmpeg -i "$clip" -vf "freezedetect=n=-60dB:d=1.5" -f null - 2>&1 \
  | grep -oE "freeze_duration: [0-9.]+"

Os limites padrão são 45 segundos no total, no máximo 40% do vídeo congelado e nenhum trecho parado por mais de 5 segundos. O script também gera uma folha de contato com um quadro a cada 3 segundos, pra você bater o olho e ver onde está o tempo morto.

A review-deck, mais recente, transforma uma revisão em slides com gravações e cenas animadas do mecanismo: a parte com defeito fica vermelha e o conserto fica verde.

O que ainda depende de mim

As skills de MR falam com o GitLab pelo glab. A address-mr-feedback também lida com PR do GitHub pelo gh. A record-demo precisa de Chrome com janela de verdade, ffmpeg e uma tela de pelo menos 1920x1080. E feature e oncall chamam as outras pelo nome, então é melhor instalar o conjunto.

O repositório é MIT e está no GitHub.