CommunityEscrita e Ediçãogithub.com

pr-explainer

Gere uma explicação auto-contida de um pull request, correção de bug ou alteração local para um colega de equipe júnior, como uma página HTML (padrão) ou um documento Markdown de transição (--md).

O que é pr-explainer?

Esta skill, chamada 'pr-explainer', gera automaticamente uma documentação detalhada e auto-contida para explicar alterações de código a um colega de equipe júnior. Ela atende a três cenários principais: (1) um pull request específico, (2) uma correção de bug, ou (3) alterações locais (não commitadas ou não enviadas). A saída padrão é uma página HTML completa com suporte a temas claro/escuro e diagramas Mermaid, ou opcionalmente um arquivo Markdown (--md) para fácil integração com ferramentas como GitHub. A skill estrutura o documento em seções lógicas ('O que deu errado', 'Causa raiz', 'O código que causou', 'A correção', 'Como sabemos', etc.) para garantia de clareza e profundidade técnica, evitando analogias não técnicas e mantendo o foco em módulos, funções, rotas e valores reais. Também oferece modos concisos (--concise) para versões rápidas de dois minutos, e suporta a verificação de evidências de testes (antes/depois) através de comandos git stash. A skill funciona com qualquer plataforma que suporte a ferramenta de linha de comando 'gh' (GitHub CLI) e acesso a repositórios git.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

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

Documentação

PR explainer

Produza um documento que ensine a um colega de equipe uma alteração: o que estava errado ou faltando, como o sistema funciona ao redor dela, o que a alteração faz e como sabemos que funciona.

Argumentos

  • Alvo: um número ou URL de PR, ou nada.
    • Com um PR e a CLI gh disponível, obtenha os detalhes com gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files e o diff com gh pr diff <url>. Leia o código circundante no commit de cabeça do PR (git show <headRefOid>:<path>), não no HEAD local.
    • Sem um PR ou sem gh: explique a alteração local. Use git diff <base>...HEAD para commits e git diff mais git status para trabalho não commitado, onde <base> é o branch padrão ou o primeiro commit.
  • --local: use o checkout local mesmo quando um PR existir (trabalho não enviado). Anote na página que reflete alterações locais.
  • --concise: uma versão curta que leva cerca de dois minutos. No máximo um visual, no máximo 3 trechos de código, sem sumário, 1–3 frases por seção.
  • --md: escreva Markdown em vez de HTML (arquivo padrão HANDOVER.md na raiz do repositório, a menos que o usuário nomeie um). Use isso para transições e quando um navegador não estiver disponível.

Público e tom

  • O leitor é um engenheiro júnior da equipe. Use frases curtas, verbos simples, uma ideia por parágrafo.
  • Não defina conceitos básicos (REST, SQL, JWT, hooks React) e não use analogias não técnicas. Mantenha-o técnico, com nomes reais de módulos, funções, rotas e campos, e números reais.
  • Torne o texto simples, não o conteúdo. Explique uma chamada ou padrão de biblioteca incomum onde ele aparecer pela primeira vez.
  • Escreva como um rascunho final. Descreva o estado atual diretamente. Sem registro de alterações ou texto do tipo "pensamos anteriormente".
  • Seja honesto sobre a certeza. Rotule alegações não comprovadas como "provável, ainda não confirmado".

Escopo: explique a alteração, não o diff

  • Escolha os arquivos que contam a história e, dentro deles, apenas as linhas que importam.
  • Use 1–3 trechos por arquivo, cada um com menos de ~25 linhas, com ... para partes omitidas. Dê a cada um o caminho do arquivo e 2–4 frases sobre o que faz e por quê.
  • Para uma correção, mostre o código que causou o bug e o diff da correção.
  • Ordene o código pelo fluxo de execução, não pela ordem do diff.
  • Pule ajustes menores, renomeações e formatação. Mencione-os em uma linha se um revisor os vir no diff.

1. Entenda a alteração

  • Leia o diff e o código circundante. Decida o modo:
    • Funcionalidade: novo comportamento ou uma grande refatoração.
    • Correção de bug: um sintoma, uma causa raiz e uma correção.
  • Encontre a execução de verificação mais recente: comando de teste e contagens, e idealmente a prova de que um novo teste de regressão falha sem a correção e passa com ela. Se essa prova não existir e for barato, produza-a: git stash push -- <arquivos src>, execute o teste, depois git stash pop. Procure também por uma verificação manual ou de ponta a ponta (saída de CLI, uma requisição, uma captura de tela). Mostre apenas a execução mais recente de cada.
  • Use descobertas da conversa (análise de causa raiz, relatório de QA, ticket) onde existirem.

2. Estrutura

Todo documento começa com uma linha de destaque (repositório · PR #n · ticket, ou repositório · alterações locais), um título em linguagem simples e uma introdução de 1–2 frases.

Correção de bug

  1. O que deu errado: o sintoma, onde foi visto, o que foi descartado.
  2. Causa raiz: o local exato onde os dados ou o fluxo quebram (arquivo:linha), com um visual se ajudar.
  3. O código que causou: um ou dois trechos.
  4. A correção: um trecho de diff e por que funciona. Nomeie efeitos colaterais que também corrige.
  5. Como sabemos: um teste de regressão que falha antes e passa depois, contagens da suíte completa, uma verificação manual.
  6. Conclusões: 2–4 lições que um júnior pode reutilizar em outro lugar.

Funcionalidade

  1. Por quê: o problema ou objetivo, com evidências.
  2. Onde se encaixa: contexto de arquitetura ou módulo (diagrama), mais o que intencionalmente não foi alterado.
  3. Como flui: passos ou um fluxograma vinculado aos cartões de código.
  4. Explicação do código: um cartão por arquivo importante, na ordem do fluxo.
  5. Comportamento a conhecer: casos limite, estados, modos de falha (uma tabela se houver mais de 3).
  6. Verificação: apenas a execução mais recente.
  7. Conclusão para o revisor: o modelo mental em 2–3 linhas e onde olhar com mais atenção no diff.

Acréscimos para transição (sempre incluídos com --md; opcionais em HTML):

  • Como executar / testar: comandos exatos.
  • Suposições feitas: decisões tomadas onde a especificação era omissa e por quê.
  • Perguntas em aberto para o negócio: ordenadas por impacto.
  • Riscos e reversão: o que poderia dar errado em produção e como reverter.
  • Próximos passos: o que você faria com mais tempo.

Conciso: apenas O que deu errado / O que e por quê, Causa raiz / Como funciona, A correção / Código-chave e Como sabemos.

3. Visuais: apenas quando explicam algo que o texto não consegue

ConteúdoUso
Arquitetura de módulo ou serviço, quem chama quem, sequência de requisiçãoflowchart / sequenceDiagram Mermaid (≤ ~12 nós)
Um branch que se comporta de forma diferente antes e depoisTabela antes/depois ou um SVG estático pequeno
Dados passando por estágios, valores descartados por um filtroUma tabela de exemplos de entrada → saída, antes vs. depois
Estados, comandos, riscos, contratosTabelas

Em Markdown, use blocos ```mermaid cercados (GitHub os renderiza). Adicione animações apenas se o usuário pedir.

4. Construção

  • HTML: comece de references/page-template.html (autocontido, modos claro e escuro, Mermaid e highlight.js de uma CDN). Salve em .pr-review/<nome>.html, nomeado pelo ticket ou PR, ou local-<desc-curta>. Mantenha fora do git: se git check-ignore -q .pr-review/ falhar, anexe .pr-review/ a .git/info/exclude. Não edite .gitignore a menos que solicitado.
    • Trechos de código: <pre><code class="language-<idioma>">…</code></pre>, escapados para HTML. Para um diff de correção, use language-diff com linhas -/+.
    • Mermaid: <pre class="mermaid">…</pre>. Nunca codifique cores diretamente.
  • Markdown (--md): Markdown simples no estilo GitHub, mesma estrutura, sem HTML.

5. Verificação única

  • HTML: se uma ferramenta de navegador estiver disponível, abra a página uma vez na largura de desktop e uma vez em ~400px. Verifique se o Mermaid renderiza e o código está destacado, corrija o que viu em uma passada e não repita. Caso contrário, diga que não foi pré-visualizado e dê o comando para abri-lo (open no macOS, start no Windows, xdg-open no Linux).
  • Releia cada arquivo:linha, número e comando na página contra o código. Fatos devem ser exatos.

6. Relate

Responda com:

  • o caminho do arquivo
  • o modo, e as seções cobertas
  • os visuais usados e o que cada um explica
  • qual execução de verificação o documento mostra
  • qualquer coisa rotulada como "ainda não confirmado"

Nunca edite o corpo de um PR, publique um comentário ou faça push sem perguntar primeiro.

Habilidades Relacionadas