MR Guided Review

ANÁLISE EDITORIAL

MR Guided Review é uma Skill oficial do GitLab para revisar merge requests em duas etapas. Primeiro ela ajuda o revisor a entender o problema, a mudança e o mecanismo. Só depois de uma confirmação explícita passa à revisão técnica. A proposta é atuar como companhia de raciocínio, sem publicar comentários, aprovar o MR ou alterar qualquer estado no GitLab.

A versão auditada está no repositório gitlab-org/ai/skills, fixada no commit 27cf0dc8a0874e77c67063611f4d359f0e28dd9f. O projeto tinha 39 estrelas na consulta de 16 de agosto de 2026. A contagem é apenas um sinal público de adoção. O que importa para esta curadoria é o conteúdo do arquivo, a licença MIT e os limites explícitos de somente leitura.

O download local contém somente SKILL.md, LICENSE e ORIGEM.md. Nenhum comando glab ou git foi executado. Não há script, runtime, dependência, token, cookie, credencial nem conteúdo de merge request privado.

Imagem editorial exclusiva do Bastidores da IA. Não é captura do GitLab, interface real nem evidência de revisão executada.

O que esta Skill faz

A primeira fase cria um modelo mental da mudança. A instrução pede título, descrição, autor, branch de destino, issues relacionadas e a forma geral do diff. Em seguida organiza a explicação em problema, mudança, funcionamento, exemplo concreto e escopo. Esse exemplo é obrigatório porque uma descrição abstrata pode esconder a diferença entre intenção e comportamento.

Ao terminar a explicação, a Skill interrompe o fluxo e pergunta se o revisor está pronto para examinar o código. Essa pausa reduz um erro frequente: começar a procurar defeitos antes de compreender qual problema a mudança deveria resolver. Se o usuário ainda tiver dúvidas, o agente deve permanecer na primeira fase.

A segunda fase prioriza correção, regressões, segurança, desempenho, cobertura e aderência à arquitetura. Cada achado material precisa citar arquivo e linha, explicar o impacto e apresentar um cenário de falha ou correção concreta. Preferências de estilo, nomes e micro-otimizações ficam de fora, salvo quando realmente impedem compreensão ou causam comportamento incorreto.

O limite mais importante: ela não fala pelo revisor

A regra central proíbe postar notas, comentários, respostas, aprovações, sugestões, resoluções de threads, rótulos ou alterações de status. Mesmo quando o usuário pede um texto de comentário, a saída deve ficar na conversa para copiar. Isso mantém a decisão pública e a responsabilidade com a pessoa que recebeu o pedido de revisão.

Esse limite é especialmente útil em repositórios corporativos. Um comentário automático pode ser interpretado como posição do revisor, acionar discussões, atrasar um merge ou expor uma hipótese que ainda não foi confirmada. A Skill transforma a IA em uma camada privada de preparação, não em um participante autônomo do processo.

Somente leitura, porém, não significa risco zero. O agente pode ler código proprietário, descrições internas, issues, logs e contexto do repositório. O token do GitLab continua determinando o alcance real. Um ambiente seguro deve usar o menor escopo possível e nunca colar segredos ou dados pessoais na conversa.

Para quem serve

Ela serve para desenvolvedores que receberam um MR complexo, pessoas em onboarding e revisores que precisam separar entendimento de crítica. Também pode ajudar líderes técnicos a preparar perguntas para uma mudança que atravessa vários componentes, desde que o agente tenha acesso autorizado aos arquivos necessários.

O fluxo é menos adequado quando a equipe quer um bot que publique comentários automaticamente, faça triagem em massa ou aprove mudanças. A Skill rejeita deliberadamente essas ações. Também não substitui testes, análise de segurança especializada, validação de migração ou conhecimento do domínio.

Compatibilidade e ferramentas

O arquivo declara compatibilidade com OpenCode e lista comandos de leitura para glab mr view, glab mr diff, glab api, git diff, git log, git show, git merge-base e git fetch. Outros clientes que implementem Agent Skills podem carregar o texto, mas precisam traduzir ferramentas, confirmações e permissões para sua própria arquitetura.

A presença de glab api merece revisão. A ferramenta pode fazer operações de escrita quando usada com métodos e endpoints inadequados, embora a Skill proíba isso em linguagem explícita. A política do cliente deve reforçar a restrição, permitindo apenas chamadas GET ou endpoints de leitura durante esse fluxo.

O git fetch também altera referências locais, apesar de não mudar o MR remoto. Se o projeto exige leitura estrita, trabalhe com um clone descartável ou obtenha aprovação antes de atualizar referências. O ZIP do Bastidores é documental e não concede essas permissões.

Instalação controlada

Abra o diretório oficial fixado no commit auditado e compare o SKILL.md original com o pacote local. Depois copie a pasta para o diretório de Skills reconhecido pelo cliente.

Antes do primeiro uso, confirme que glab aponta para a instância correta, que a conta possui apenas o acesso necessário e que nenhum comando de escrita está autorizado. Em projetos sensíveis, prefira uma conta técnica somente de leitura e um clone sem arquivos de ambiente.

A documentação de revisão do GitLab continua sendo a referência para o processo do produto. A Skill organiza o raciocínio, mas não redefine regras de aprovação, proteção de branch ou responsabilidade do revisor.

Primeiro uso seguro

1. Escolha um MR pequeno, não confidencial e já conhecido pela equipe.
2. Informe o identificador e peça somente a fase de entendimento.
3. Compare problema, mudança, exemplo e escopo com a descrição e o diff.
4. Corrija qualquer interpretação errada antes de liberar a segunda fase.
5. Na revisão, exija arquivo, linha, impacto e cenário de falha para cada achado.
6. Confirme manualmente o contexto ao redor da linha citada.
7. Execute testes autorizados em etapa separada, se necessário.
8. Publique você mesmo apenas os comentários que sobreviverem à revisão humana.

Resultado esperado

Uma boa primeira fase cabe em poucos parágrafos e deixa o revisor capaz de explicar o MR a outra pessoa. Uma boa segunda fase contém poucos achados materiais, ordenados por gravidade, e termina com um veredito curto sobre bloqueios. Quantidade de observações não é métrica de qualidade.

Quando a intenção do autor não está documentada, a Skill deve registrar a lacuna em vez de inventar motivação. Quando um possível defeito depende de uma premissa não verificada, o resultado deve virar pergunta ou hipótese, não acusação.

Cenário prático de revisão

Imagine um merge request que altera a renovação de sessão e adiciona um novo tratamento para tokens expirados. Na fase de entendimento, o agente deve localizar o comportamento anterior, explicar qual condição dispara a renovação, identificar os consumidores afetados e montar um exemplo com uma sessão válida e outra vencida. O revisor confirma essa leitura com a descrição do MR e com o código adjacente antes de procurar falhas.

Na fase técnica, uma observação útil não seria apenas dizer que existe uma condição de corrida. Ela precisaria indicar o arquivo, a linha, as duas operações que podem acontecer fora de ordem e o efeito observável, como duas renovações simultâneas invalidando o token recém emitido. O revisor então verifica se há bloqueio, idempotência ou teste concorrente em outro ponto do projeto.

Antes de transformar a análise em comentário público, faça uma checagem final: confirme que a linha ainda existe na versão mais recente, reproduza o cenário quando houver ambiente autorizado, procure testes que contradigam a hipótese e ajuste o tom para uma pergunta quando faltar evidência. Essa etapa protege o autor e o revisor de um diagnóstico convincente, porém incorreto. A contribuição da Skill termina na preparação; a decisão de comentar, solicitar mudança ou aprovar continua humana.

Riscos e erros comuns

• Pular a confirmação: mistura entendimento e julgamento antes de o modelo mental estar correto.
• Confiar apenas no diff: comportamento pode depender de código adjacente, configuração, migração ou contrato externo.
• Publicar automaticamente: viola o limite principal da Skill e atribui opinião ao revisor.
• Tratar hipótese como bug: todo achado precisa de evidência e cenário reproduzível.
• Ignorar permissões: leitura do MR pode expor código e dados internos.
• Confundir aprovação com ausência de achados: testes, segurança e domínio ainda exigem responsáveis próprios.

Versão, licença e download local

A curadoria fixou o commit 27cf0dc8a0874e77c67063611f4d359f0e28dd9f. O repositório é mantido pelo GitLab e o arquivo declara versão 0.1.0. O pacote preserva a licença MIT e a atribuição.

O ZIP local tem SHA-256 94e53269960a7172335ad8b639b1a98b8ceb6d79872e1f06fa68a92fe8c7e9cb e três arquivos de texto. Ele não instala glab, não conecta uma conta e não executa o fluxo. Use-o para leitura, comparação e arquivo da versão auditada.

Limite final

MR Guided Review melhora a disciplina da revisão, mas não conhece automaticamente a regra de negócio, a urgência, o histórico nem os acordos da equipe. O revisor continua responsável por validar fatos, escolher comentários e decidir se o MR está pronto.

O melhor uso é conservador: entender, confirmar, revisar, verificar e só então comunicar. A Skill deve economizar tempo sem transferir autoria ou autoridade para o agente.

Fontes primárias

• Diretório oficial no commit auditado
• SKILL.md oficial
• Licença MIT
• GitLab Docs, revisão de merge requests
• Especificação Agent Skills