CommunityImagemgithub.com

pr-diagram

Desenha um diagrama Mermaid (.mmd) das alterações de um pull request, permitindo que revisores vejam o fluxo antes de ler o diff.

O que é pr-diagram?

Essa skill gera diagramas Mermaid que resumem visualmente as mudanças de um Pull Request, ideal para repositórios no GitHub. Ela analisa o diff, identifica o fluxo lógico (etapas, conexões e estado) e escolhe automaticamente o tipo de diagrama mais adequado: fluxograma top-down ou left-right, diagrama de sequência, diagrama de estado ou diagrama entidade-relacionamento. As cores (verde para novo, amarelo para alterado, cinza para inalterado) facilitam a leitura em temas claro e escuro. A skill funciona com qualquer PR (número, URL ou branch atual) e, com aprovação do usuário, pode inserir o bloco do diagrama diretamente na descrição do PR, preservando o conteúdo original. Não modifica código, faz commits ou executa revisões. É compatível com ferramentas como Claude Code, Cursor e Codex que executem comandos `gh` e `git`.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/amihali1/claude-skills/tree/HEAD/plugins/pr-diagram/skills/pr-diagram

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

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

Documentação

pr-diagram: diagramar um pull request

Objetivo: um diagrama que mostre ao revisor o que a mudança faz e como flui, em 10 segundos. Não é um mapa de todo o código.

Diretrizes (absolutas)

  1. Nunca modifique código. Não edite, crie ou exclua arquivos no repositório, e não faça commit, push ou checkout de branches. O arquivo .mmd vai para um diretório temporário ou de rascunho, nunca no repositório.
  2. Nunca aprove, solicite alterações ou faça merge. Não execute gh pr review, gh pr merge ou gh pr close, e não publique comentários no PR. A única escrita que esta skill faz é gh pr edit --body-file na descrição.
  3. Uma única etapa de aprovação: mostre a nova descrição completa e pergunte se deve publicá-la na mesma mensagem. Não pergunte "quer que eu publique?" e depois mostre a descrição. Isso cria duas rodadas de aprovação. Mostre o corpo inteiro, não apenas a seção adicionada, e termine a mensagem com a pergunta. "Ok", "publica" ou "sim" para essa mensagem conta como aprovação. Silêncio, uma pergunta ou um pedido de ajuste não. Após um ajuste, mostre novamente o corpo completo e a pergunta juntos.
  4. Assine tudo que adicionar com esta linha exata como última linha do bloco adicionado: - Gerado por Claude Code

Argumentos

  • /pr-diagram usa o PR da branch atual, ou o diff da branch local se não existir PR.
  • /pr-diagram 123 ou uma URL de PR segmenta aquele PR (funciona para outros repositórios via URL).
  • type=td|lr|sequence|state|er força um tipo de diagrama.

Passo 1: coletar o diff

Com um PR (tudo somente leitura):

gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>

Sem PR: encontre a base (gh repo view --json defaultBranchRef -q .defaultBranchRef.name), então git diff --stat $(git merge-base origin/<base> HEAD) e git diff $(git merge-base origin/<base> HEAD).

Diffs grandes (>1500 linhas alteradas ou >30 arquivos): leia --stat e o corpo do PR primeiro, depois leia apenas os arquivos que carregam a lógica. Ignore lockfiles, código gerado, snapshots e renomeações puras.

Passo 2: identificar o fluxo

Um diff mostra linhas, não relacionamentos. Leia a versão atual de cada arquivo tocado (somente leitura) e descubra:

  • O fluxo: o que o aciona (requisição, job, evento, ação do usuário), o que roda em que ordem, e onde termina (resposta, escrita no banco, mensagem, chamada externa).
  • O status de cada etapa: nova (adicionada por este PR), alterada (existente, modificada) ou inalterada (contexto que o revisor precisa para situar a mudança).
  • O resumo de uma frase que o revisor precisa ("adiciona uma etapa de retry antes da chamada de pagamento").

Use o título e o corpo do PR como intenção, mas confie no código onde eles divergirem. Cada nó e aresta deve ter origem no código que você leu. Nunca invente uma etapa para tornar a figura mais limpa. Se algo for incerto, omita e diga isso.

Código removido: se uma etapa removida for importante para os revisores, mostre-a como um nó cinza com rótulo "(removido)" e uma borda pontilhada. Caso contrário, omita.

Passo 3: escolher o tipo de diagrama

A saída é sempre Mermaid em um arquivo .mmd. Escolha o tipo que corresponde ao fluxo:

A mudança é principalmente...Diagrama
um processo passo a passo ou lógica de decisãoflowchart TD (de cima para baixo)
componentes ou serviços se conectando, ou um pipelineflowchart LR (esquerda para direita)
uma requisição ou mensagem passando entre 3+ participantes ao longo do temposequenceDiagram
uma mudança de status ou ciclo de vida (pendente → aprovado → …)stateDiagram-v2
tabelas, colunas ou relações (migrações)erDiagram

Use um diagrama. Use dois apenas se o PR claramente mudar tanto a estrutura quanto o fluxo em execução. Se o PR for muito pequeno para precisar de uma figura (1–2 arquivos, sem fluxo novo), diga isso e pare.

Passo 4: construir o diagrama

Rótulos: inglês claro, curtos.

  • Escreva o que uma etapa faz, não identificadores de código: Check card is not expired, não CardValidator.validateExpiry(). Quando o nome ajudar, use uma forma curta: PaymentReconciliationService vira Payment reconciler.
  • Encurte URLs para o caminho: api.example.com/v2/orders/{id}/refunds vira POST /orders/:id/refunds.
  • Nós retângulo A["..."]: máximo 35 caracteres por linha.
  • Nós estádio A(["..."]) e arredondados A("..."): máximo 25 caracteres por linha.
  • Se um nó precisar de mais detalhes, divida-o em linhas com <br/> (cada linha dentro do seu limite). Use no máximo 3 linhas.
  • Significado das formas: retângulo = etapa ou componente, estádio = início ou fim (gatilho, resposta), arredondado = sistema externo, diamante A{"..."} = decisão (máximo 25 caracteres), cilindro A[("...")] = armazenamento de dados.
  • Máximo de 15 nós. Use subgraph para agrupar por serviço ou área quando houver mais de cerca de 8.
  • Rotule arestas brevemente em inglês claro (sends, on failure, saves), máximo 20 caracteres.
  • Diagramas de sequência: nomes de participantes e atores no máximo 25 caracteres. Mensagens, rótulos de loop, alt, e opt, e texto de Note no máximo 35 caracteres por linha (divida com <br/>, no máximo 3 linhas). Não use ; ou # no texto da mensagem, pois quebram a análise.

Cores (legíveis tanto no modo claro quanto escuro do GitHub). Use preenchimentos claros com texto escuro e uma borda forte:

classDef new fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#0b3d17
classDef changed fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#4a2b00
classDef unchanged fill:#e9ecef,stroke:#868e96,stroke-width:1px,color:#343a40
class StepA,StepB new
class StepC changed
class StepD unchanged

Cada nó recebe exatamente uma classe. Em stateDiagram-v2, use classDef mais class StateName new.

Diagramas de sequência: classes não se aplicam. Um rect define apenas o fundo, e a cor do texto vem do tema do GitHub (cinza claro no modo escuro). Um preenchimento claro opaco torna o texto ilegível no modo escuro, portanto sempre use tons translúcidos:

  • novo: rect rgba(46,160,67,0.18)
  • alterado: rect rgba(210,153,34,0.22)
  • inalterado: sem rect

Nunca use rect rgb(...) opaco. Adicione Note over para a mudança principal.

PRs totalmente novos (nada alterado ou inalterado): mantenha o tom verde e também diga "Tudo neste diagrama é código novo" no resumo, já que não há nada com o que contrastar.

Armadilhas de sintaxe (quebram a renderização do GitHub). Verifique cada uma:

  • IDs de nós devem ser alfanuméricos simples (ChkCard). Rótulos devem sempre estar entre aspas: ChkCard["Check card"].
  • Use #quot; para uma " literal dentro de um rótulo. <br/> é o único HTML permitido em rótulos.
  • Nunca use end (minúsculo) como ID. Sempre coloque espaços ao redor das setas (A --> B), porque A---oB é analisado como uma borda circular.
  • subgraph Id["Label"] … end. Cada subgraph precisa de seu próprio end.
  • Participantes de sequência: participant API as Orders API (o ID não tem espaços).
  • Tipos de atributos em erDiagram devem ser palavras únicas (varchar, não varchar(255)).
  • Sem blocos de tema %%{init}%%. As cores classDef lidam com ambos os modos.

Salve o diagrama como pr-<N>-diagram.mmd (ou branch-<nome>-diagram.mmd) em um diretório temporário ou de rascunho. Forneça o caminho completo.

Passo 5: auto-verificação antes de apresentar

  • Conte os caracteres em cada linha de rótulo em relação ao seu limite (35 para retângulos, 25 para estádio, arredondados e diamantes, 20 para rótulos de aresta; em diagramas de sequência, 25 para participantes e 35 para mensagens, blocos e notas). Corrija os que estiverem acima.
  • Certifique-se de que nenhum rótulo contenha um identificador de código bruto (camelCase, Foo.bar(), snake_case) onde o inglês claro funcione.
  • Verifique a cor de cada nó: ele é realmente novo, alterado ou inalterado no diff?
  • Verificação de renderização opcional: npx -y @mermaid-js/mermaid-cli -i <arquivo>.mmd -o <arquivo>.svg. A primeira execução baixa o Chromium (~150 MB), portanto pergunte antes de executá-lo.

Passo 6: apresentar

Use este formato no chat:

**<resumo de uma frase do que o PR faz>**

<2–3 frases: o fluxo em palavras, onde a mudança se encaixa nele, o que foi omitido ou incerto>

```mermaid
...
```
**Legenda:** verde = código novo · amarelo = código alterado · cinza (ou sem tom) = contexto inalterado

Salvo em: <caminho completo para .mmd>

Passo 7: mostrar a descrição completa e perguntar se deve publicar (mesma mensagem do Passo 6)

Faça isso antes de responder, para que o diagrama, a nova descrição completa e a pergunta saiam juntos:

  1. Busque o corpo atual para um arquivo temporário: gh pr view <N> --json body -q .body > <tmp>/body-old.md

  2. Construa o novo corpo em <tmp>/body-new.md. Coloque o bloco entre marcadores para que execuções repetidas o substituam em vez de empilhar:

    <!-- pr-diagram:start -->
    ## Diagrama da mudança
    <frase de resumo>
    
    ```mermaid
    ...
    

    Legenda: verde = novo · amarelo = alterado · cinza (ou sem tom) = inalterado (Use palavras, não emoji de cor. Emoji são renderizados com cores diferentes em cada sistema operacional, ex. ⬜ aparece como lavanda no Windows.)

    • Gerado por Claude Code
    Se os marcadores já existirem, substitua apenas o texto entre eles. Caso contrário, anexe o
    bloco após uma linha em branco. Mantenha todos os outros bytes do corpo original inalterados.
    
  3. Verifique se o novo corpo começa com o corpo original completo. Ele deve ser preservado byte por byte.

  4. Termine a mensagem com a nova descrição completa em um bloco cercado, a URL do PR e a pergunta: "Publicar em ?" Então pare e aguarde (Diretriz 3).

Passo 8: publicar (apenas após um sim para a mensagem do Passo 7)

  1. gh pr edit <N> --body-file <tmp>/body-new.md. Nunca use --body com texto inline, pois as aspas do shell deformam crases e $.
  2. Verifique com gh pr view <N> --json body -q .body se corresponde a body-new.md, então forneça a URL do PR. Ignore espaços em branco à direita ao comparar, porque -q adiciona uma nova linha. Por exemplo, compare .rstrip() de ambos em Python.

Ainda não há PR (apenas branch local)? Ofereça o bloco para colar quando o usuário abrir o PR. Não crie o PR.

Não faça

  • Não diagrame todos os arquivos. Um diagrama de tudo não mostra nada.
  • Não coloque segredos, nomes de host internos, URLs completas com tokens ou strings de consulta, ou dados do cliente nos rótulos.

Habilidades Relacionadas