Anotar Merge Request

Anota um merge request / pull request com explicações voltadas ao revisor sobre alterações feitas por IA - intenção, comportamento antes/depois e um gráfico de pontos de entrada verificado - como um comentário geral, um comentário por arquivo alterado e comentários inline em pontos genuinamente não óbvios, mantendo tudo sincronizado após cada push. Use esta habilidade sempre que o usuário quiser explicar, documentar, anotar ou "auto-descrever" um MR/PR para revisores, tornar um MR gerado por IA revisável sem idas e vindas de Q&A, comentar um diff no GitLab/GitHub/Bitbucket ou atualizar/verificar comentários de MR após enviar novos commits - incluindo frases como "explique este MR", "anote o diff", "comente o PR para revisores" ou "atualize meus comentários do MR".

O que é Anotar Merge Request?

Esta habilidade de agente de IA preenche uma lacuna crítica em fluxos de trabalho de desenvolvimento assistido por IA: a lacuna de conhecimento entre o autor do código (IA) e o revisor humano. Quando um engenheiro de software lê um diff gerado por IA, ele gasta a maior parte do tempo reconstruindo três coisas que o autor já sabia: por que a mudança existe, qual comportamento mudou e quem chama esse código. Essa habilidade escreve essas três coisas em linguagem simples, no nível do merge request—não como comentários no código-fonte—usando três camadas: um comentário geral mapeando toda a mudança, um comentário por arquivo explicando o que a mudança daquele arquivo significa e comentários inline apenas em pontos genuinamente não óbvios. Para qualquer plataforma de git—GitLab, GitHub ou Bitbucket—ela constrói o conjunto de anotações, o pré-visualiza e o publica após aprovação do usuário. Ela se mantém sincronizada automaticamente: após cada push para o branch do MR, ela verifica as anotações existentes contra o novo diff e atualiza, remove ou adiciona apenas o que mudou, garantindo que os revisores sempre vejam explicações precisas e atualizadas.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kirill-kolomin/self-descriptive-merge-requests/tree/main/skills/annotate-merge-request

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

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

Documentação

Anotar um merge request para revisores

Um revisor lendo um diff gerado por IA passa a maior parte do tempo reconstruindo três coisas que o autor já sabia: por que esta mudança existe, qual comportamento mudou e quem chama este código. Esta habilidade escreve essas três coisas, em linguagem simples, no nível do merge request - não como comentários de código-fonte.

As anotações vêm em três camadas, com regras diferentes:

CamadaCoberturaCarrega
Geral - um comentário no nível do MRsempreo mapa de toda a mudança
Arquivo - um comentário por arquivo alteradosempre, exceto arquivos autogeradoso que a mudança deste arquivo significa
Inline - ancorado a uma linha do diffapenas pontos genuinamente não óbvios, com orçamentopor que este código específico é assim

A cobertura de arquivos é incondicional: um revisor abrindo qualquer arquivo no diff deve encontrar uma explicação dele. A decisão de julgamento - o que vale a pena explicar e o que é óbvio - se aplica dentro de um arquivo, a métodos e hunks individuais, nunca a se o arquivo recebe cobertura ou não.

Modos de operação

ModoQuandoO que faz
annotatePrimeira execução em um MRConstrói o conjunto completo de anotações, pré-visualiza, publica após aprovação
syncApós cada push para o branch do MRVerifica as anotações existentes contra o novo diff; atualiza, remove ou adiciona apenas o que mudou

Se anotações desta habilidade já existirem no MR (detectar pelo marcador, veja §7), execute sync, não annotate - re-executar annotate duplica comentários.

1. Pré-voo

Estabeleça, antes de escrever qualquer coisa:

  1. Plataforma e identidade do MR. git remote -v → gitlab.com/GitLab auto-hospedado, github.com ou Bitbucket. Então encontre o MR aberto para o branch atual (glab mr view, gh pr view). Se não houver MR ainda, pare e diga isso - esta habilidade anota um MR existente; ela não cria um.
  2. Faixa do diff. Sempre git merge-base HEAD origin/<branch-alvo> → <base>..HEAD. Nunca compare com a ponta do branch alvo diretamente: commits não relacionados que caíram no alvo apareceriam como mudanças deste MR.
  3. Idioma. Escreva anotações no idioma que os MRs do projeto já usam (verifique descrições e comentários de MR/PR existentes). Padrão para o idioma que o usuário está falando com você.
  4. Autoridade para publicar. Publicar em um MR é visível para toda a equipe e notifica os revisores. Padrão para uma pré-visualização dry-run na conversa e publique apenas após o usuário aprovar. Pule a pré-visualização apenas se o usuário já disse para publicar sem perguntar.

Leia references/platform-gitlab.md, references/platform-github.md ou references/platform-bitbucket.md para os comandos exatos - as APIs de comentário diferem de maneiras que importam (ancoragem no nível do arquivo, capacidade de resolução, semântica de atualização).

2. Construir o inventário de mudanças

Os dois scripts ficam ao lado deste arquivo, em scripts/. Invoque-os pelo caminho absoluto, construído a partir do próprio diretório desta habilidade - o diretório de trabalho durante uma execução é o repositório do usuário, não a habilidade, então um caminho simples scripts/... falha. Abaixo, $SKILL representa o diretório contendo este SKILL.md (ex.: ~/.claude/skills/annotate-merge-request para uma instalação no nível do usuário, ou skills/annotate-merge-request do plugin quando carregado de um plugin).

python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json

Por arquivo alterado, isso fornece: tipo de mudança (adicionado/modificado/excluído/renomeado), requires_file_comment (falso apenas para arquivos autogerados/vendored), uma file_fingerprint e os hunks do arquivo com números de linha do lado novo (ao que os comentários inline devem ancorar), símbolo envolvente mais próximo e sinais de trivialidade. Para arquivos de especificação e teste, também emite test_cases - cada caso no arquivo com seu status (unchanged / adapted / added / removed), calculado comparando corpos de caso entre as duas revisões em vez de lido do diff. É um mapa heurístico para sua leitura, não um substituto para ela - leia o diff real para qualquer coisa que você vá descrever.

A anchor de cada hunk é uma sugestão (sua primeira linha adicionada); added_lines lista cada linha naquele hunk na qual você poderia ancorar em vez disso. Escolha a linha sobre a qual a explicação realmente é.

Restrição rígida: um comentário inline só pode ancorar a uma linha que aparece no diff. Nem GitLab nem GitHub permitem comentar em código não tocado longe de um hunk. Qualquer coisa que você queira dizer sobre código que o MR não tocou vai no comentário de arquivo ou geral, nunca inline.

3. Camada 1 - cobrir cada arquivo alterado

Cada arquivo que o inventário marca requires_file_comment: true recebe exatamente um comentário no nível do arquivo. Sem exceções, sem orçamento, sem julgamento sobre se é "interessante o suficiente".

A única isenção é saída autogerada e vendored - lockfiles, dist/, snapshots, codegen, bundles minificados, vendor/. O inventário sinaliza estes; se ele perder um que seu projeto gera, isente-o também e diga ao usuário qual padrão adicionar.

O que varia é forma e comprimento, não existência:

  • Um arquivo com mudanças reais de lógica recebe o modelo completo (references/annotation-format.md): função, por que mudou, antes → depois, alcançado a partir de.
  • Um arquivo de especificação ou teste recebe uma lista de casos de teste em vez disso - cada caso que agora contém, cada um com um status (unchanged / adapted / added / removed) e, para os alterados, uma descrição curta. O modelo padrão está errado para especificações: nada os chama, então a seção de ponto de entrada está vazia por construção. O inventário calcula os status para você (test_cases por arquivo); casos adapted são os que um revisor mais precisa, então eles vêm primeiro e devem dizer se a forma da chamada ou a expectativa mudou. Regras completas em references/annotation-format.md.
  • Um arquivo mecânico recebe uma linha que permite ao revisor pulá-lo com confiança: Apenas caminhos de importação - segue a renomeação de PricingService; nenhuma mudança de comportamento.
  • Um arquivo excluído recebe uma linha sobre por que foi removido e o que o substituiu - muitas vezes a anotação mais útil em um MR.

Ancore estes como comentários no nível do arquivo (subject_type=file no GitHub, position_type=file no GitLab), não em uma linha. Eles se anexam ao cabeçalho do arquivo, então não se intercalam com o código e o revisor encontra um ao abrir cada arquivo. Onde uma instância não suporta ancoragem no nível do arquivo, recorra à primeira linha alterada do arquivo - as referências da plataforma fornecem a recaída exata.

Escrever one-liners bem é toda a habilidade aqui. O volume agora escala com a contagem de arquivos, então um arquivo mecânico descrito em três parágrafos é um defeito, não minúcia.

4. Camada 2 - o comentário geral

Um comentário no nível do MR, o ponto de entrada para toda a revisão, estruturado exatamente como references/annotation-format.md especifica:

  • Intenção - que problema este MR resolve, em duas ou três frases, em linguagem simples. Sem reafirmar o diff.
  • Comportamento antes → depois - o que um observador do sistema em execução notaria. Para um novo componente, diga "novo" em vez de inventar um "antes".
  • Gráfico de pontos de entrada - como um leitor alcança o código alterado a partir de um ponto de entrada real (rota HTTP, comando CLI, manipulador de evento, cron, API exportada). Limitado a 3 níveis; uma linha por área alterada, não por arquivo.
  • Ordem de leitura - qual arquivo abrir primeiro, quais são acompanhamentos mecânicos.
  • Índice de comentários inline - links para cada anotação inline.

O geral tem seus próprios limites de volume (máximo 7 entradas de ordem de leitura, máximo 5 linhas de comportamento, nenhuma enumeração por arquivo - os comentários de arquivo fazem isso). Eles estão em references/annotation-format.md; respeite-os, ou o geral se torna a parede de texto que os comentários de arquivo deveriam prevenir.

Verificando o gráfico de pontos de entrada

Nunca adivinhe um grafo de chamada. Uma lista de chamadores fabricada é pior do que nenhuma anotação: está confiantemente errada e o revisor confiará nela. Para cada aresta reivindicada, encontre o chamador com uma pesquisa real (rg -n 'symbolName' em todo o repositório, incluindo testes e configuração), e siga-o para cima até alcançar um ponto de entrada ou 3 níveis, o que vier primeiro. Se os chamadores de um símbolo não puderem ser resolvidos - despacho dinâmico, contêiner DI, reflexão, um registro com chave de string - escreva ponto de entrada não resolvido (<motivo>) em vez de uma cadeia plausível.

5. Camada 3 - comentários inline, apenas onde o código não é óbvio

Esta é a única camada com uma decisão de julgamento. Execute o teste de significância de references/significance-test.md em cada método e hunk. A versão curta:

Anote quando o leitor poderia razoavelmente perguntar "por que isso é assim?" - intenção não óbvia, uma mudança comportamental que não é visível no diff, uma consequência não local, uma troca deliberada, um algoritmo incomum, uma solução alternativa, uma restrição de fora do arquivo ou uma interação com outra mudança neste mesmo MR.

Pule quando o código se explica para um leitor competente deste codebase: um helper de 5-10 linhas que capitaliza o título de uma string, uma constante DEBOUNCE_MS = 300, uma verificação nula óbvia, uma atualização de teste mecânica. O comentário do arquivo já cobre o arquivo; um comentário inline aqui o repetiria com menor valor.

O tamanho do código não é o teste - sua distância inferencial é. Um helper de 6 linhas dentro de um esquema de codificação personalizado precisa de um comentário; um arquivo de snapshot gerado de 200 linhas não precisa.

Orçamentos (padrões; o usuário pode aumentá-los explicitamente):

  • No máximo 3 comentários inline por arquivo, no máximo 12 por MR.
  • Estes são tetos, não cotas. Um arquivo cuja história é totalmente contada por seu comentário de arquivo recebe zero comentários inline, e esse é o caso normal.
  • Exceder um orçamento é um sinal, não uma licença: se mais de 12 pontos em um MR são genuinamente não óbvios, o MR é grande demais, ou a explicação pertence ao geral onde pode ser contada como uma história. Diga isso ao usuário.

Cada anotação inline usa as mesmas seções que o comentário do arquivo, com escopo naquele hunk, e permanece curta - 3 a 6 linhas, lida dentro de uma visão de diff apertada.

6. Referências cruzadas dentro do MR

Quando uma mudança só faz sentido junto com outra mudança no mesmo MR, vincule-as. Referências cruzadas geralmente pertencem ao gráfico de pontos de entrada, mas também aparecem na intenção ("necessário porque agora passa X") e no antes/depois ("o caminho antigo ainda existe, veja <outro comentário>"). Comentários de arquivo são o lugar mais natural para elas: Este novo contrato do arquivo é consumido por [[ref:order-controller]].

Um URL de comentário não existe até que o comentário seja publicado, então a vinculação cruzada leva duas fases:

  1. Publique cada comentário com um token marcador ([[ref:<slug>]]) onde um link para outra anotação pertence.
  2. Colete os IDs/URLs dos comentários criados, então edite cada corpo, substituindo tokens por links reais.

Planeje os slugs antes de publicar - cada token [[ref:...]] deve resolver na fase 2, e um token restante em um comentário publicado é um defeito visível. A fase 2 não é opcional.

7. Publicar, com um marcador de identidade

Cada comentário que esta habilidade cria termina com uma linha de marcador que é invisível na renderização de markdown:

<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<file> ffp=<file-fingerprint> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<file>@<new-line> fp=<hunk-fingerprint> -->

Use o file_fingerprint do inventário para ffp= e o fingerprint do hunk para fp=. O marcador é o que torna sync possível: ele identifica os próprios comentários da habilidade, a que cada um estava anexado e a impressão digital do código que descreveu. Nunca publique uma anotação sem um; nunca edite o comentário de um humano.

Deixe as anotações não resolvidas. Um thread resolvido é renderizado recolhido, então o revisor teria que expandir cada anotação uma por uma - o que esconde exatamente o que a anotação existe para mostrar. Publique-as abertas e deixe o revisor resolver cada uma enquanto a lê; aquele clique é o próprio marcador de "li" do revisor.

O custo dessa escolha: onde o projeto exige que todos os threads sejam resolvidos antes de mesclar (o Todos os threads devem ser resolvidos do GitLab, o Exigir resolução de conversa do GitHub), as anotações devem ser resolvidas antes que o botão de mesclar desbloqueie. Com um comentário de arquivo por arquivo, isso agora é um número real de cliques, então avise o usuário quando você detectar tal configuração e ofereça-se para resolver em massa no final. Comandos para ambos estão nos arquivos de referência da plataforma.

8. Sincronizar após cada push

Novos commits invalidam anotações silenciosamente: o código que um comentário descreve pode ter se movido, mudado de significado ou desaparecido - e novos arquivos chegam sem cobertura alguma. Re-execute esta habilidade no modo sync após cada push para o branch do MR.

python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json

--comments é repetível e aceita o JSON bruto da plataforma como está - no GitHub são duas chamadas (comentários de revisão e comentários de issue), então passe ambos os arquivos.

Ele classifica cada anotação existente como ok (ancora e impressão digital inalterados - deixe-a em paz), moved (mesmo código, nova linha - re-ancore), stale (o código que descreveu mudou - releia e reescreva) ou orphaned (arquivo ou hunk sumiu - exclua). Ele também relata file coverage - quais arquivos alterados ainda não têm comentário no nível do arquivo, quais são isentos - e hunks uncovered que agora são candidatos para um comentário inline.

Então: corrija apenas o que ele sinalizou, sempre reescreva o comentário geral no lugar (ele resume todo o MR, então qualquer push pode invalidá-lo), e re-execute a fase 2 da §6 para que links de referência cruzada ainda apontem para comentários vivos. Uma linha MISSING na cobertura de arquivos não é trabalho opcional - um novo arquivo sem comentário é a lacuna que esta habilidade existe para prevenir. Siga references/sync-after-push.md para o caso de force-push, tratamento de comentário excluído por plataforma e como evitar agitação de comentários que não mudaram realmente.

Mencione ao usuário, uma vez, que isso precisa ser executado após cada push, e que references/sync-after-push.md tem um gancho pre-push opcional que pode automatizá-lo - mas não assuma que está configurado e não o configure sem permissão.

Habilidades Relacionadas