pr-diagram: diagramar un pull request
Objetivo: un diagrama que le muestre a un revisor qué hace el cambio y cómo fluye, en 10 segundos. No es un mapa de todo el código base.
Barreras de seguridad (absolutas)
- Nunca modifiques código. No edites, crees ni elimines archivos en el repositorio, y no hagas commit,
push ni cambies de rama. El archivo
.mmdva en un directorio temporal o de borrador, nunca en el repositorio. - Nunca apruebes, solicites cambios ni fusiones. No ejecutes
gh pr review,gh pr mergenigh pr close, y no publiques comentarios en el PR. La única escritura que hace esta habilidad esgh pr edit --body-fileen la descripción. - Un solo paso de aprobación: muestra la nueva descripción completa y pregunta si publicarla en el mismo mensaje. No preguntes "¿quieres que lo publique?" y luego muestres la descripción después. Eso serían dos rondas de aprobación. Muestra el cuerpo completo, no solo la sección añadida, y termina el mensaje con la pregunta. "Se ve bien", "publícalo" o "sí" a ese mensaje cuenta como aprobación. El silencio, una pregunta o un ajuste solicitado no. Después de un ajuste, muestra el cuerpo completo y la pregunta de nuevo juntos.
- Firma todo lo que añadas con esta línea exacta como la última línea del bloque añadido:
- Generado por Claude Code
Argumentos
/pr-diagramusa el PR para la rama actual, o el diff de la rama local si no existe un PR./pr-diagram 123o una URL de PR apunta a ese PR (funciona para otros repositorios mediante URL).type=td|lr|sequence|state|erfuerza un tipo de diagrama.
Paso 1: recopilar el diff
Con un PR (todo solo lectura):
gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>
Sin PR: encuentra la base (gh repo view --json defaultBranchRef -q .defaultBranchRef.name), luego
git diff --stat $(git merge-base origin/<base> HEAD) y git diff $(git merge-base origin/<base> HEAD).
Diffs grandes (>1500 líneas cambiadas o >30 archivos): lee --stat y el cuerpo del PR primero, luego lee
solo los archivos que contienen la lógica. Omite archivos de bloqueo, código generado, instantáneas y cambios de nombre puros.
Paso 2: identificar el flujo
Un diff muestra líneas, no relaciones. Lee la versión actual de cada archivo tocado (solo lectura) y determina:
- El flujo: qué lo desencadena (solicitud, trabajo, evento, acción del usuario), qué se ejecuta en qué orden y dónde termina (respuesta, escritura en BD, mensaje, llamada externa).
- El estado de cada paso: nuevo (añadido por este PR), cambiado (existente, modificado) o sin cambios (contexto que el revisor necesita para ubicar el cambio).
- El resumen de una oración que necesita un revisor ("añade un paso de reintento antes de la llamada de pago").
Usa el título y el cuerpo del PR como intención, pero confía en el código donde discrepen. Cada nodo y arista se debe poder rastrear hasta el código que leíste. Nunca inventes un paso para que la imagen quede más ordenada. Si algo es incierto, déjalo fuera y dilo.
Código eliminado: si un paso eliminado es importante para los revisores, muéstralo como un nodo gris etiquetado "(eliminado)" con una arista punteada. De lo contrario, déjalo fuera.
Paso 3: elegir el tipo de diagrama
La salida siempre es Mermaid en un archivo .mmd. Elige el tipo que coincida con el flujo:
| El cambio es principalmente... | Diagrama |
|---|---|
| un proceso paso a paso o lógica de decisión | flowchart TD (de arriba abajo) |
| componentes o servicios que se conectan, o un pipeline | flowchart LR (de izquierda a derecha) |
| una solicitud o mensaje que pasa entre 3+ participantes a lo largo del tiempo | sequenceDiagram |
| un cambio de estado o ciclo de vida (pendiente → aprobado → ...) | stateDiagram-v2 |
| tablas, columnas o relaciones (migraciones) | erDiagram |
Usa un diagrama. Usa dos solo si el PR cambia claramente tanto la estructura como el flujo en tiempo de ejecución. Si el PR es demasiado pequeño para necesitar una imagen (1–2 archivos, sin flujo nuevo), dilo y detente.
Paso 4: construir el diagrama
Etiquetas: inglés sencillo, corto.
- Escribe lo que hace un paso, no identificadores de código:
Check card is not expired, noCardValidator.validateExpiry(). Cuando el nombre ayude, usa una forma abreviada:PaymentReconciliationServicese convierte enPayment reconciler. - Acorta las URLs a la ruta:
api.example.com/v2/orders/{id}/refundsse convierte enPOST /orders/:id/refunds. - Nodos rectangulares
A["..."]: máximo 35 caracteres por línea. - Nodos de estadio
A(["..."])y redondeadosA("..."): máximo 25 caracteres por línea. - Si un nodo necesita más detalle, divídelo en líneas con
<br/>(cada línea dentro de su límite). Usa 3 líneas como máximo. - Significado de las formas: rectángulo = paso o componente, estadio = inicio o fin (desencadenante, respuesta),
redondeado = sistema externo, diamante
A{"..."}= decisión (25 caracteres máximo), cilindroA[("...")]= almacén de datos. - Máximo 15 nodos. Usa
subgraphpara agrupar por servicio o área cuando haya más de unos 8. - Etiqueta las aristas brevemente en inglés sencillo (
sends,on failure,saves), 20 caracteres máximo. - Diagramas de secuencia: nombres de participantes y actores máximo 25 caracteres. Mensajes, etiquetas de
loop,altyopt, y texto deNotemáximo 35 caracteres por línea (divide con<br/>, 3 líneas como máximo). No uses;ni#en el texto del mensaje, porque rompen el análisis sintáctico.
Colores (legibles tanto en modo claro como oscuro de GitHub). Usa rellenos claros con texto oscuro y un borde fuerte:
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 nodo recibe exactamente una clase. En stateDiagram-v2, usa classDef más class StateName new.
Diagramas de secuencia: las clases no aplican. Un rect establece solo el fondo, y el color del texto
proviene del tema de GitHub (gris claro en modo oscuro). Un relleno claro opaco hace que el texto sea
ilegible en modo oscuro, por lo que siempre usa tintes translúcidos:
- nuevo:
rect rgba(46,160,67,0.18) - cambiado:
rect rgba(210,153,34,0.22) - sin cambios: sin
rect
Nunca uses rect rgb(...) opaco. Añade Note over para el cambio clave.
PRs completamente nuevos (nada cambiado o sin cambios): mantén el tinte verde, y también di "Todo en este diagrama es código nuevo" en el resumen, ya que no hay nada con qué contrastarlo.
Trampas de sintaxis (rompen la representación de GitHub). Verifica cada una:
- Los IDs de nodo deben ser alfanuméricos simples (
ChkCard). Las etiquetas siempre deben estar entre comillas:ChkCard["Check card"]. - Usa
#quot;para una"literal dentro de una etiqueta.<br/>es el único HTML permitido en las etiquetas. - Nunca uses
end(minúsculas) como ID. Siempre pon espacios alrededor de las flechas (A --> B), porqueA---oBse analiza como un borde circular. subgraph Id["Label"]…end. Cada subgrafo necesita su propioend.- Participantes de secuencia:
participant API as Orders API(el ID no tiene espacios). - Los tipos de atributos de
erDiagramdeben ser palabras individuales (varchar, novarchar(255)). - Sin bloques de tema
%%{init}%%. Los coloresclassDefmanejan ambos modos.
Guarda el diagrama como pr-<N>-diagram.mmd (o branch-<nombre>-diagram.mmd) en un directorio temporal o
de borrador. Proporciona la ruta completa.
Paso 5: autoverificación antes de presentar
- Cuenta los caracteres de cada línea de etiqueta con respecto a su límite (35 para rectángulos, 25 para nodos de estadio, redondeados y diamante, 20 para etiquetas de arista; en diagramas de secuencia, 25 para participantes y 35 para mensajes, bloques y notas). Corrige los que estén por encima.
- Asegúrate de que ninguna etiqueta contenga un identificador de código sin procesar (camelCase,
Foo.bar(), snake_case) donde el inglés sencillo funcione. - Verifica el color de cada nodo: ¿es realmente nuevo, cambiado o sin cambios en el diff?
- Verificación de renderizado opcional:
npx -y @mermaid-js/mermaid-cli -i <archivo>.mmd -o <archivo>.svg. La primera ejecución descarga Chromium (~150 MB), así que pregunta antes de ejecutarlo.
Paso 6: presentar
Usa este formato en el chat:
**<resumen de una oración de lo que hace el PR>**
<2–3 oraciones: el flujo en palabras, dónde se sitúa el cambio en él, cualquier cosa omitida o incierta>
```mermaid
...
Leyenda: verde = código nuevo · amarillo = código cambiado · gris (o sin tinte) = contexto sin cambios
Guardado: <ruta completa al .mmd>
## Paso 7: mostrar la descripción completa y preguntar si publicar (mismo mensaje que el Paso 6)
Haz esto antes de responder, para que el diagrama, la nueva descripción completa y la pregunta salgan todos
juntos:
1. Obtén el cuerpo actual a un archivo temporal: `gh pr view <N> --json body -q .body > <tmp>/body-old.md`
2. Construye el nuevo cuerpo en `<tmp>/body-new.md`. Pon el bloque entre marcadores para que las reejecuciones lo reemplacen en lugar de apilarlo:
Diagrama de cambios
<oración de resumen>
...
Leyenda: verde = nuevo · amarillo = cambiado · gris (o sin tinte) = sin cambios (Usa palabras, no emoji de color. Los emojis se renderizan con diferentes colores en cada SO, p. ej., ⬜ se muestra como lavanda en Windows.)
- Generado por Claude Code
Si los marcadores ya existen, reemplaza solo el texto entre ellos. De lo contrario, añade el
bloque después de una línea en blanco. Mantén todos los demás bytes del cuerpo original sin cambios.
3. Verifica que el nuevo cuerpo comienza con el cuerpo original completo. Debe conservarse byte por byte.
4. Termina el mensaje con la nueva descripción completa en un bloque delimitado, la URL del PR y la
pregunta: **"¿Publicar esto en <URL del PR>?"** Luego detente y espera (Barrera de seguridad 3).
## Paso 8: publicar (solo después de un sí al mensaje del Paso 7)
1. `gh pr edit <N> --body-file <tmp>/body-new.md`. Nunca uses `--body` con texto en línea,
porque el quoting del shell estropea los backticks y `$`.
2. Verifica con `gh pr view <N> --json body -q .body` que coincida con `body-new.md`, luego da
la URL del PR. Ignora los espacios en blanco al final al comparar, porque `-q` añade una nueva línea. Por
ejemplo, compara `.rstrip()` de ambos en Python.
¿Aún no hay PR (solo rama local)? Ofrece el bloque para pegar cuando el usuario abra el PR. No crees el PR.
## Lo que no debes hacer
- No diagrames todos los archivos. Un diagrama de todo no muestra nada.
- No pongas secretos, nombres de host internos, URLs completas con tokens o cadenas de consulta, ni datos de clientes en las etiquetas.