CommunityRedacción y edicióngithub.com

explicador-de-pr

Explica un pull request, una corrección de errores o un cambio local a un compañero de equipo, dirigido a un ingeniero junior, como una página HTML autónoma (por defecto) o un traspaso en Markdown (--md).

¿Qué es explicador-de-pr?

Este skill para agentes de IA (como Claude Code, Cursor, Codex) genera un documento técnico profesional que explica un cambio de código a un desarrollador junior del equipo. Es útil para traspasos, revisiones de PR o para documentar correcciones de errores y nuevas funcionalidades. Soporta las plataformas de terminal y CLI (gh) y produce un documento autónomo en HTML (con soporte para modo oscuro, Mermaid y resaltado de sintaxis) o en Markdown. El agente analiza el diff y el código circundante, identifica el modo (característica o corrección de error) y construye una narrativa ordenada que incluye desde el problema y la causa raíz hasta el código clave, la verificación y las lecciones aprendidas. Usa argumentos como --local, --concise y --md para adaptar el formato y la profundidad del contenido.

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

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Explicador de PR

Genera un documento que enseña a un compañero de equipo un cambio: qué estaba mal o faltaba, cómo funciona el sistema a su alrededor, qué hace el cambio y cómo sabemos que funciona.

Argumentos

  • Objetivo: un número o URL de PR, o nada.
    • Con un PR y la CLI gh disponible, obtén los detalles con gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files y el diff con gh pr diff <url>. Lee el código circundante en el commit head del PR (git show <headRefOid>:<path>), no en el HEAD local.
    • Sin PR, o sin gh: explica el cambio local. Usa git diff <base>...HEAD para commits y git diff más git status para trabajo no commiteado, donde <base> es la rama por defecto o el primer commit.
  • --local: usa el checkout local incluso cuando existe un PR (trabajo no subido). Indica en la página que refleja cambios locales.
  • --concise: una versión corta que se lee en unos dos minutos. Como máximo un visual, 3 fragmentos, sin tabla de contenidos, 1–3 frases por sección.
  • --md: escribe Markdown en lugar de HTML (archivo por defecto HANDOVER.md en la raíz del repositorio, a menos que el usuario indique otro). Úsalo para traspasos y cuando no se tenga un navegador a mano.

Audiencia y voz

  • El lector es un ingeniero junior del equipo. Usa frases cortas, verbos sencillos, una idea por párrafo.
  • No definas conceptos básicos (REST, SQL, JWT, hooks de React) y no uses analogías no técnicas. Mantén el tono técnico, con nombres reales de módulos, funciones, rutas y campos, y números reales.
  • Haz que el lenguaje sea simple, no el contenido. Explica una llamada a una biblioteca o un patrón inusual donde aparezca por primera vez.
  • Escríbelo como un borrador final. Describe el estado actual directamente. Sin registro de cambios ni frases como "antes pensábamos".
  • Sé honesto sobre la certeza. Etiqueta las afirmaciones no comprobadas como "probable, aún no confirmado".

Alcance: explica el cambio, no el diff

  • Elige los archivos que cuentan la historia, y dentro de ellos solo las líneas importantes.
  • Usa de 1 a 3 fragmentos por archivo, cada uno de menos de ~25 líneas, con ... para partes omitidas. Indica la ruta del archivo y 2–4 frases sobre lo que hace y por qué.
  • Para una corrección, muestra el código que causó el error y el diff de la corrección.
  • Ordena el código por flujo de ejecución, no por orden del diff.
  • Omite cambios de infraestructura, renombrados y formato. Mencíonalos en una línea si un revisor los verá en el diff.

1. Comprender el cambio

  • Lee el diff y el código circundante. Decide el modo:
    • Característica: comportamiento nuevo o una refactorización grande.
    • Corrección de error: un síntoma, una causa raíz y una corrección.
  • Encuentra la ejecución de verificación más reciente: comando de prueba y recuentos, e idealmente la prueba de que una nueva prueba de regresión falla sin la corrección y pasa con ella. Si esa prueba no existe y es barata, prodúcela: git stash push -- <archivos fuente>, ejecuta la prueba, luego git stash pop. También busca una comprobación manual o de extremo a extremo (salida de CLI, una solicitud, una captura de pantalla). Muestra solo la ejecución más reciente de cada una.
  • Usa los hallazgos de la conversación (análisis de causa raíz, informe de QA, ticket) cuando existan.

2. Esqueleto

Todo documento comienza con una línea de encabezado (repositorio · PR #n · ticket, o repositorio · cambios locales), un título en lenguaje sencillo y una introducción de 1–2 frases.

Corrección de error

  1. Qué salió mal: el síntoma, dónde se vio, qué se descartó.
  2. Causa raíz: el lugar exacto donde se rompe el dato o el flujo (archivo:línea), con un visual si ayuda.
  3. El código que lo causó: uno o dos fragmentos.
  4. La corrección: un fragmento de diff y por qué funciona. Menciona los efectos secundarios que también corrige.
  5. Cómo lo sabemos: una prueba de regresión que falla antes y pasa después, recuentos del conjunto completo, una comprobación manual.
  6. Conclusiones: 2–4 lecciones que un junior pueda reutilizar en otro lugar.

Característica

  1. Por qué: el problema o el objetivo, con evidencia.
  2. Dónde se sitúa: contexto de arquitectura o módulo (diagrama), más lo que queda intencionadamente sin cambios.
  3. Cómo fluye: pasos o un diagrama de flujo vinculado a las tarjetas de código.
  4. Recorrido por el código: una tarjeta por archivo importante, en orden de flujo.
  5. Comportamiento a conocer: casos límite, estados, modos de fallo (una tabla si hay más de 3).
  6. Verificación: solo la ejecución más reciente.
  7. Conclusión para el revisor: el modelo mental en 2–3 líneas, y dónde mirar con más atención en el diff.

Adiciones para traspaso (incluir siempre con --md; opcional en HTML):

  • Cómo ejecutar / probar: comandos exactos.
  • Suposiciones realizadas: decisiones tomadas donde la especificación era ambigua, y por qué.
  • Preguntas abiertas para el negocio: ordenadas por impacto.
  • Riesgos y reversión: qué podría salir mal en producción y cómo revertir.
  • Próximos pasos: qué harías con más tiempo.

Conciso: solo Qué salió mal / Qué y por qué, Causa raíz / Cómo funciona, La corrección / Código clave y Cómo lo sabemos.

3. Visuales: solo cuando explican algo que el texto no puede

ContenidoUso
Arquitectura de módulos o servicios, quién llama a quién, secuencia de solicitudesflowchart / sequenceDiagram de Mermaid (≤ ~12 nodos)
Una rama que se comporta diferente antes y despuésTabla antes/después o un pequeño SVG estático
Datos que pasan por etapas, valores descartados por un filtroUna tabla de ejemplos de entrada → salida, antes vs después
Estados, comandos, riesgos, contratosTablas

En Markdown, usa bloques de código con ```mermaid (GitHub los renderiza). Añade animaciones solo si el usuario lo pide.

4. Construcción

  • HTML: comienza desde references/page-template.html (autónomo, modo claro y oscuro, Mermaid y highlight.js desde una CDN). Guarda en .pr-review/<nombre>.html, nombrado según el ticket o PR, o local-<descripción-corta>. No lo incluyas en git: si git check-ignore -q .pr-review/ falla, añade .pr-review/ a .git/info/exclude. No edites .gitignore a menos que te lo pidan.
    • Fragmentos de código: <pre><code class="language-<idioma>">…</code></pre>, escapado para HTML. Para un diff de corrección, usa language-diff con líneas -/+.
    • Mermaid: <pre class="mermaid">…</pre>. Nunca uses colores fijos.
  • Markdown (--md): Markdown estándar de GitHub Flavored Markdown, mismo esqueleto, sin HTML.

5. Verificación única

  • HTML: si hay una herramienta de navegador disponible, abre la página una vez con ancho de escritorio y otra con ~400 px. Comprueba que Mermaid se renderiza y el código está resaltado, corrige lo que veas en una sola pasada y no repitas. De lo contrario, indica que no se previsualizó y da el comando para abrirlo (open en macOS, start en Windows, xdg-open en Linux).
  • Vuelve a leer cada archivo:línea, número y comando de la página contra el código. Los hechos deben ser exactos.

6. Informar

Responde con:

  • la ruta del archivo
  • el modo y las secciones cubiertas
  • los visuales usados y qué explica cada uno
  • qué ejecución de verificación muestra el documento
  • cualquier cosa etiquetada como "aún no confirmado"

Nunca edites el cuerpo de un PR, publiques un comentario ni subas nada sin preguntar antes.

Skills relacionados