md-review

Visão geral da skill md-review

O que a md-review faz

md-review é uma skill de apresentação para Code Review que transforma um texto de PR em markdown em uma revisão HTML de arquivo único, com duas colunas. Ela espera um markdown de revisão com blocos cercados de diff no formato unified diff e comentários marcados por severidade, como > [!BLOCKER], > [!MAJOR], > [!MINOR] ou > [!NIT]. A saída coloca o diff renderizado à esquerda, cards de anotação à direita, uma navegação superior para pular entre achados e um rodapé obrigatório com o nome do revisor.

Usuários e fluxos de trabalho mais indicados

A skill md-review funciona melhor para equipes que já escrevem notas estruturadas de code review em markdown e querem um artefato HTML portátil para compartilhar, arquivar ou repassar fora de uma plataforma de PR. Ela se encaixa bem para leads de engenharia, revisores, mantenedores de documentação e fluxos com agentes que convertem análise de PR em uma página de revisão mais polida. É especialmente útil quando severidade da revisão, ancoragem por linha e acessibilidade são mais importantes do que um resumo simples em markdown.

O que diferencia a md-review

Ao contrário de um prompt genérico do tipo “deixe esta revisão mais bonita”, md-review tem um pipeline definido: diff_parser.py extrai hunks de unified diff, annotation_extractor.py vincula callouts de severidade ao bloco de diff anterior mais próximo, e review_html_renderer.py produz o HTML final. O repositório também documenta decisões de renderização em references/diff_rendering_canon.md, references/pr_annotation_ux.md e references/severity_coding.md, o que torna a saída mais previsível do que uma formatação ad hoc feita por LLM.

Principais restrições de adoção

O principal bloqueio é o formato da entrada. md-review não serve para páginas markdown comuns, notas de release ou relatórios narrativos sem hunks de diff. Ela se recusa a renderizar sem um nome explícito de revisor e foi projetada para não codificar severidade apenas por cor; os badges incluem ícones e texto aria-label para atender à WCAG 1.4.1. Se a sua fonte não contém diffs unified reais, encaminhe a tarefa para uma skill de renderização de documentos.

Como usar a skill md-review

Instalação da md-review e arquivos do repositório para inspecionar

Para gerenciadores de skills compatíveis com Claude, instale a partir do caminho do repositório no GitHub, por exemplo:

npx skills add alirezarezvani/claude-skills --skill md-review

Depois da instalação, leia primeiro SKILL.md para entender as regras de invocação. Em seguida, inspecione estes arquivos antes de depender da skill em produção:

• scripts/diff_parser.py para formatos aceitos de blocos de diff e --infer-diff
• scripts/annotation_extractor.py para entender o parsing de callouts e o comportamento de vinculação
• scripts/review_html_renderer.py para flags obrigatórias do renderizador, como --reviewer
• assets/md_review_template.html para a estrutura final da página
• references/severity_coding.md para níveis de severidade padrão e personalizados

Prepare uma entrada que a md-review consiga interpretar

Um bom padrão de uso da md-review começa com um markdown que mantém cada achado próximo do diff que ele descreve:

# Review: payment retry change

```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
-    attempts = 1
+    attempts = 5
+    timeout = None

[!BLOCKER]
This can retry indefinitely if the provider never returns. Add a bounded timeout.

Use blocos cercados de `diff` sempre que possível. O parser consegue inferir alguns blocos sem tag apenas quando `--infer-diff` é usado, mas blocos explícitos reduzem ambiguidade. Coloque comentários gerais antes de qualquer diff somente se você quiser que eles sejam renderizados como comentários sem ancoragem.

### Acione a md-review em um fluxo com agente

A skill pode ser acionada quando um orquestrador markdown-html classifica a entrada como `REVIEW`, ou diretamente com `/cs:md-review`. Um prompt completo deve fornecer o markdown de origem, o nome do revisor e qualquer mudança na convenção de severidade:

```text
/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]

Se você usar os scripts diretamente, o fluxo prático é: converter os blocos de diff em JSON, extrair as anotações em relação a esses hunks e então renderizar o HTML com --reviewer. Os scripts usam apenas a Python stdlib, o que facilita a execução em CI restrito ou em automação local.

Dicas práticas para melhorar a qualidade da saída

Para melhorar a ancoragem, coloque cada callout imediatamente após o bloco de diff relevante. Para facilitar a triagem, reserve BLOCKER para problemas que precisam ser corrigidos obrigatoriamente e evite classificar toda preocupação como MAJOR. Para melhorar a escaneabilidade, escreva a primeira frase de cada anotação como o ponto de decisão, porque a navegação superior usa prévias curtas. Se a sua equipe usa rótulos diferentes, passe uma convenção personalizada de quatro níveis, do mais severo ao menos severo, como critical,important,suggestion,nit.

FAQ da skill md-review

A md-review é apenas para Code Review?

Sim. md-review para Code Review é intencionalmente específica: ela converte revisões de PR em markdown, com hunks de diff e anotações de severidade, em uma página HTML de revisão. Ela não é um gerador genérico de sites em markdown, não gera diffs de PR e não substitui a escrita da revisão em si.

O que acontece se meu markdown não tiver blocos de diff?

É um caso pouco adequado. O layout central da skill depende de hunks de unified diff, números de linha, adições, remoções e vinculação de anotações. Sem blocos de diff, o resultado seria enganoso; por isso, o comportamento esperado é recusar a tarefa ou encaminhá-la para uma skill de markdown para HTML orientada a documentos.

Como a md-review é melhor do que um prompt comum?

Um prompt comum pode produzir um HTML visualmente atraente, mas muitas vezes inventa regras de layout, erra convenções de numeração de linha ou depende apenas de cor para indicar severidade. md-review usa scripts concretos de parsing e renderização, uma UX documentada de revisão em duas colunas e restrições explícitas de acessibilidade. Isso a torna melhor quando consistência e semântica de revisão importam.

A md-review é amigável para iniciantes?

Ela é amigável para iniciantes se você já entende blocos de código em markdown e unified diffs. Iniciantes que têm apenas comentários em prosa talvez precisem primeiro gerar ou colar um diff real de PR. O ponto de partida mais simples é executar os modos de exemplo nos scripts e depois adaptar a estrutura do markdown de exemplo para a sua própria revisão.

Como melhorar a skill md-review

Melhore as entradas da md-review antes de renderizar

A forma mais rápida de melhorar a saída da md-review é melhorar a revisão de origem. Inclua caminhos de arquivo nos cabeçalhos padrão de unified diff, preserve os cabeçalhos de hunk @@ e mantenha linhas de contexto suficientes para que os revisores entendam a alteração. Use um achado por callout sempre que possível; combinar problemas não relacionados em um único card MAJOR torna a navegação superior menos útil.

Evite modos de falha comuns

Falhas comuns incluem ausência de --reviewer, blocos de diff malformados, rótulos de severidade fora da convenção configurada e anotações posicionadas longe demais do diff a que se referem. Outro problema mais sutil é usar severidade como tom, em vez de prioridade. Uma preferência de estilo escrita de forma dura ainda deve ser NIT; um problema de correção escrito de forma calma pode ser BLOCKER.

Itere depois da primeira saída em HTML

Depois da primeira renderização, verifique três pontos: se todos os achados aparecem na navegação superior, se as anotações foram vinculadas aos hunks pretendidos e se os comentários sem ancoragem são realmente comentários gerais. Se uma anotação cair no lugar errado, mova-a para mais perto do bloco de diff relevante em vez de tentar corrigir o HTML manualmente.

Personalize sem quebrar o modelo de revisão

Use personalização para convenções da equipe, não para enfraquecer a estrutura. Uma lista personalizada de severidade faz sentido se a sua organização usa rótulos como critical, important, suggestion e nit. Transformar a saída em um relatório em prosa, esconder ícones de severidade ou remover o rodapé do revisor enfraquece aquilo que a md-review foi projetada para garantir: uma saída de revisão responsável, acessível e centrada em diff.