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)
- 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
.mmdvai para um diretório temporário ou de rascunho, nunca no repositório. - Nunca aprove, solicite alterações ou faça merge. Não execute
gh pr review,gh pr mergeough pr close, e não publique comentários no PR. A única escrita que esta skill faz égh pr edit --body-filena descrição. - 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.
- Assine tudo que adicionar com esta linha exata como última linha do bloco adicionado:
- Gerado por Claude Code
Argumentos
/pr-diagramusa o PR da branch atual, ou o diff da branch local se não existir PR./pr-diagram 123ou uma URL de PR segmenta aquele PR (funciona para outros repositórios via URL).type=td|lr|sequence|state|erforç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ão | flowchart TD (de cima para baixo) |
| componentes ou serviços se conectando, ou um pipeline | flowchart LR (esquerda para direita) |
| uma requisição ou mensagem passando entre 3+ participantes ao longo do tempo | sequenceDiagram |
| 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ãoCardValidator.validateExpiry(). Quando o nome ajudar, use uma forma curta:PaymentReconciliationServiceviraPayment reconciler. - Encurte URLs para o caminho:
api.example.com/v2/orders/{id}/refundsviraPOST /orders/:id/refunds. - Nós retângulo
A["..."]: máximo 35 caracteres por linha. - Nós estádio
A(["..."])e arredondadosA("..."): 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), cilindroA[("...")]= armazenamento de dados. - Máximo de 15 nós. Use
subgraphpara 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, eopt, e texto deNoteno 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), porqueA---oBé analisado como uma borda circular. subgraph Id["Label"]…end. Cada subgraph precisa de seu próprioend.- Participantes de sequência:
participant API as Orders API(o ID não tem espaços). - Tipos de atributos em
erDiagramdevem ser palavras únicas (varchar, nãovarchar(255)). - Sem blocos de tema
%%{init}%%. As coresclassDeflidam 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:
-
Busque o corpo atual para um arquivo temporário:
gh pr view <N> --json body -q .body > <tmp>/body-old.md -
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. -
Verifique se o novo corpo começa com o corpo original completo. Ele deve ser preservado byte por byte.
-
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)
gh pr edit <N> --body-file <tmp>/body-new.md. Nunca use--bodycom texto inline, pois as aspas do shell deformam crases e$.- Verifique com
gh pr view <N> --json body -q .bodyse corresponde abody-new.md, então forneça a URL do PR. Ignore espaços em branco à direita ao comparar, porque-qadiciona 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.