CommunityProgramación y desarrollogithub.com

anotar-solicitud-de-merge

Anota automáticamente una solicitud de merge (MR) o pull request (PR) generada por IA con explicaciones destinadas a los revisores: intención, cambios de comportamiento, grafo de puntos de entrada y comentarios en línea, manteniéndolos sincronizados tras cada push.

¿Qué es anotar-solicitud-de-merge?

Esta habilidad está diseñada para ayudar a desarrolladores e ingenieros de software a revisar cambios de código generados por IA, proporcionando anotaciones completas y claras en solicitudes de merge (MR) o pull requests (PR) en plataformas como GitLab, GitHub o Bitbucket. Su objetivo principal es reducir el tiempo que los revisores dedican a comprender cambios que ya son evidentes para el autor de la IA, documentando de manera explícita el porqué del cambio, qué comportamiento cambia y quién llama a este código. La habilidad genera tres capas de anotación: un comentario general a nivel de MR, un comentario por cada archivo modificado y comentarios en línea solo para puntos no obvios, con una clara diferenciación entre archivos con cambios de lógica, pruebas o cambios mecánicos. Además, incluye un modo de sincronización que, tras cada push, revisa y actualiza las anotaciones existentes para que sigan siendo relevantes. Esta herramienta es particularmente útil para equipos que buscan agilizar la revisión de código generado por IA, evitar ciclos de preguntas y respuestas, y mantener la documentación del merge request coherente y actualizada. La habilidad se basa en scripts de Python para generar un inventario de cambios y en un sistema de referencias para manejar las diferencias en las API de comentarios de cada plataforma.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kirill-kolomin/self-descriptive-merge-requests/tree/main/skills/annotate-merge-request

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

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

Documentación

Anotar una solicitud de merge para los revisores

Un revisor que lee un diff generado por IA pasa la mayor parte de su tiempo reconstruyendo tres cosas que el autor ya sabía: por qué existe este cambio, qué comportamiento cambió y quién llama a este código. Esta habilidad escribe esas tres cosas, en lenguaje sencillo, a nivel de la solicitud de merge, no como comentarios en el código fuente.

Las anotaciones vienen en tres capas, con diferentes reglas:

CapaCoberturaContenido
Visión general – un comentario a nivel de MRsiempreel mapa de todo el cambio
Archivo – un comentario por archivo modificadosiempre, excepto archivos autogeneradosqué significa el cambio de este archivo
En línea – anclado a una línea del diffsolo puntos realmente no obvios, con presupuestopor qué este código en particular es así

La cobertura de archivos es incondicional: un revisor que abre cualquier archivo en el diff debe encontrar una explicación del mismo. La decisión de juicio (qué vale la pena explicar y qué es obvio) se aplica dentro de un archivo, a métodos y fragmentos individuales, nunca a si el archivo recibe cobertura o no.

Modos de operación

ModoCuándoQué hace
annotatePrimera ejecución en un MRConstruye el conjunto completo de anotaciones, lo previsualiza y lo publica tras la aprobación
syncDespués de cada push a la rama del MRVuelve a verificar las anotaciones existentes contra el nuevo diff; actualiza, elimina o agrega solo lo que cambió

Si ya existen anotaciones de esta habilidad en el MR (detectables por marcador, ver §7), ejecute sync, no annotate – volver a ejecutar annotate duplica los comentarios.

1. Verificación previa

Establezca, antes de escribir nada:

  1. Plataforma e identidad del MR. git remote -v → gitlab.com/GitLab autogestionado, github.com o Bitbucket. Luego encuentre el MR abierto para la rama actual (glab mr view, gh pr view). Si aún no hay MR, deténgase y dígalo – esta habilidad anota un MR existente; no crea uno.
  2. Rango del diff. Siempre git merge-base HEAD origin/<ramadestino> → <base>..HEAD. Nunca haga diff directamente contra la punta de la rama de destino: los commits no relacionados que llegaron al destino aparecerían como cambios de este MR.
  3. Idioma. Escriba las anotaciones en el idioma que ya usan los MR del proyecto (revise descripciones y comentarios de MR/PR existentes). Por defecto, use el idioma en el que el usuario le está hablando.
  4. Autoridad para publicar. Publicar en un MR es visible para todo el equipo y notifica a los revisores. Por defecto, haga una previsualización en seco en la conversación y publique solo después de que el usuario lo apruebe. Omita la previsualización solo si el usuario ya ha dicho que publique sin preguntar.

Lea references/platform-gitlab.md, references/platform-github.md o references/platform-bitbucket.md para obtener los comandos exactos – las API de comentarios difieren de manera que importan (anclaje a nivel de archivo, capacidad de resolución, semántica de actualización).

2. Construir el inventario de cambios

Los dos scripts se encuentran junto a este archivo, en scripts/. Invóquelos con la ruta absoluta, construida desde el directorio de esta habilidad – el directorio de trabajo durante una ejecución es el repositorio del usuario, no la habilidad, por lo que una ruta simple scripts/... falla. A continuación, $SKILL representa el directorio que contiene este SKILL.md (por ejemplo, ~/.claude/skills/annotate-merge-request para una instalación a nivel de usuario, o skills/annotate-merge-request del plugin cuando se carga desde un plugin).

python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json

Por archivo modificado, esto da: tipo de cambio (añadido/modificado/eliminado/renombrado), requires_file_comment (falso solo para archivos autogenerados/de proveedores), una file_fingerprint y los fragmentos del archivo con números de línea del lado nuevo (a lo que deben anclarse los comentarios en línea), el símbolo envolvente más cercano y señales de trivialidad. Para archivos de especificaciones y pruebas, también emite test_cases – cada caso en el archivo con su estado (unchanged / adapted / added / removed), calculado comparando los cuerpos de los casos entre las dos revisiones, no leyendo el diff. Es un mapa heurístico para su lectura, no un sustituto de ella – lea el diff real para cualquier cosa que vaya a describir.

El anchor de cada fragmento es una sugerencia (su primera línea añadida); added_lines enumera cada línea de ese fragmento a la que podría anclarse en su lugar. Elija la línea sobre la que trata realmente la explicación.

Restricción estricta: un comentario en línea solo puede anclarse a una línea que aparezca en el diff. Ni GitLab ni GitHub permiten comentar sobre código no tocado lejos de un fragmento. Cualquier cosa que quiera decir sobre código que el MR no tocó va en el comentario de archivo o visión general, nunca en línea.

3. Capa 1 – cubrir cada archivo modificado

Cada archivo que el inventario marca requires_file_comment: true recibe exactamente un comentario a nivel de archivo. Sin excepciones, sin presupuesto, sin decisión de juicio sobre si es "suficientemente interesante".

La única exención es la salida autogenerada y de proveedores – lockfiles, dist/, snapshots, codegen, bundles minificados, vendor/. El inventario los marca; si se pierde uno que su proyecto genera, exonérelo también y dígale al usuario qué patrón añadir.

Lo que varía es la forma y la longitud, no la existencia:

  • Un archivo con cambios de lógica reales recibe la plantilla completa (references/annotation-format.md): rol, por qué cambió, antes → después, desde dónde se llega.
  • Un archivo de especificación o prueba recibe una lista de casos de prueba – cada caso que ahora contiene, cada uno con un estado (unchanged / adapted / added / removed) y, para los modificados, una descripción breve. La plantilla estándar es incorrecta para especificaciones: nada los llama, por lo que la sección de punto de entrada está vacía por construcción. El inventario computa los estados por usted (test_cases por archivo); los casos adapted son los que más necesita un revisor, por lo que van primero y deben decir si cambió la forma de la llamada o la expectativa. Reglas completas en references/annotation-format.md.
  • Un archivo mecánico recibe una línea que permite al revisor saltarlo con confianza: Solo rutas de importación – sigue el cambio de nombre de PricingService; sin cambio de comportamiento.
  • Un archivo eliminado recibe una línea sobre por qué se fue y qué lo reemplazó – a menudo la anotación más útil en un MR.

Ancle estos como comentarios a nivel de archivo (subject_type=file en GitHub, position_type=file en GitLab), no en una línea. Se adjuntan al encabezado del archivo, para que no se intercalen con el código y el revisor los encuentre al abrir cada archivo. Cuando una instancia no admita anclaje a nivel de archivo, recurra a la primera línea modificada del archivo – las referencias de la plataforma dan la alternativa exacta.

Escribir bien las líneas únicas es toda la habilidad aquí. El volumen ahora escala con el número de archivos, por lo que un archivo mecánico descrito en tres párrafos es un defecto, no minuciosidad.

4. Capa 2 – el comentario de visión general

Un comentario a nivel de MR, el punto de entrada para toda la revisión, estructurado exactamente como especifica references/annotation-format.md:

  • Intención – qué problema resuelve este MR, en dos o tres frases, en lenguaje sencillo. Sin reafirmar el diff.
  • Comportamiento antes → después – qué notaría un observador del sistema en funcionamiento. Para un componente nuevo, diga "nuevo" en lugar de inventar un "antes".
  • Grafo de puntos de entrada – cómo un lector llega al código modificado desde un punto de entrada real (ruta HTTP, comando CLI, manejador de eventos, cron, API exportada). Limitado a 3 niveles; una línea por área modificada, no por archivo.
  • Orden de lectura – qué archivo abrir primero, cuáles son mecánicos.
  • Índice de comentarios en línea – enlaces a cada anotación en línea.

La visión general tiene sus propios límites de volumen (máx. 7 entradas de orden de lectura, máx. 5 filas de comportamiento, sin enumeración por archivo – eso lo hacen los comentarios de archivo). Están en references/annotation-format.md; respételos, o la visión general se convierte en el muro de texto que los comentarios de archivo debían prevenir.

Verificación del grafo de puntos de entrada

Nunca adivine un grafo de llamadas. Una lista de llamantes fabricada es peor que ninguna anotación: es errónea con confianza y el revisor confiará en ella. Para cada borde afirmado, encuentre al llamante con una búsqueda real (rg -n 'symbolName' en todo el repositorio, incluyendo pruebas y configuración), y sígalo hacia arriba hasta llegar a un punto de entrada o 3 niveles, lo que ocurra primero. Si no se pueden resolver los llamantes de un símbolo – envío dinámico, contenedor DI, reflexión, un registro con clave de cadena – escriba punto de entrada no resuelto (<motivo>) en lugar de una cadena que suene plausible.

5. Capa 3 – comentarios en línea, solo donde el código no es obvio

Esta es la única capa con una decisión de juicio. Ejecute la prueba de importancia de references/significance-test.md en cada método y fragmento. La versión corta:

Anote cuando el lector podría preguntarse razonablemente "¿por qué es así?" – intención no obvia, un cambio de comportamiento que no es visible en el diff, una consecuencia no local, un compromiso deliberado, un algoritmo inusual, una solución alternativa, una restricción externa al archivo o una interacción con otro cambio en este mismo MR.

Omita cuando el código se explica por sí mismo a un lector competente de este código base: un ayudante de 5 a 10 líneas que pone en mayúsculas un título, una constante DEBOUNCE_MS = 300, una verificación de nulo obvia, una actualización mecánica de prueba. El comentario de archivo ya cubre el archivo; un comentario en línea aquí lo repetiría con menor valor.

El tamaño del código no es la prueba – su distancia inferencial lo es. Un ayudante de 6 líneas dentro de un esquema de codificación personalizado necesita un comentario; un archivo de snapshot generado de 200 líneas no.

Presupuestos (valores predeterminados; el usuario puede aumentarlos explícitamente):

  • Como máximo 3 comentarios en línea por archivo, como máximo 12 por MR.
  • Estos son techos, no cuotas. Un archivo cuya historia está completamente contada por su comentario de archivo recibe cero comentarios en línea, y ese es el caso normal.
  • Exceder un presupuesto es una señal, no una licencia: si más de 12 puntos en un MR son realmente no obvios, el MR es demasiado grande, o la explicación pertenece a la visión general donde puede contarse como una sola historia. Dígaselo al usuario.

Cada anotación en línea usa las mismas secciones que el comentario de archivo, limitadas a ese fragmento, y se mantiene breve – de 3 a 6 líneas, para leer dentro de una vista de diff estrecha.

6. Referencias cruzadas dentro del MR

Cuando un cambio solo tiene sentido junto con otro cambio en el mismo MR, enlácelos. Las referencias cruzadas suelen pertenecer al grafo de puntos de entrada, pero también aparecen en la intención ("necesario porque ahora pasa X") y en antes/después ("la ruta antigua aún existe, ver "). Los comentarios de archivo son el lugar más natural para ellas: El nuevo contrato de este archivo es consumido por [[ref:order-controller]].

Una URL de comentario no existe hasta que se publica el comentario, por lo que las referencias cruzadas requieren dos fases:

  1. Publique cada comentario con un token de marcador de posición ([[ref:<slug>]]) donde pertenezca un enlace a otra anotación.
  2. Recoja los IDs/URLs de los comentarios creados, luego edite cada cuerpo, reemplazando tokens con enlaces reales.

Planifique los slugs antes de publicar – cada token [[ref:...]] debe resolverse en la fase 2, y un token sobrante en un comentario publicado es un defecto visible. La fase 2 no es opcional.

7. Publicación, con un marcador de identidad

Cada comentario que crea esta habilidad termina con una línea de marcador que es invisible en markdown renderizado:

<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<file> ffp=<file-fingerprint> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<file>@<new-line> fp=<hunk-fingerprint> -->

Use el file_fingerprint del inventario para ffp= y el fingerprint del fragmento para fp=. El marcador es lo que hace posible sync: identifica los propios comentarios de la habilidad, a qué estaban adjuntos y la huella del código que describían. Nunca publique una anotación sin uno; nunca edite el comentario de un humano.

Deje las anotaciones sin resolver. Un hilo resuelto se renderiza colapsado, por lo que el revisor tendría que expandir cada anotación una por una – lo que oculta exactamente lo que la anotación existe para mostrar. Publíquelas abiertas y deje que el revisor resuelva cada una mientras la lee; ese clic es su propia marca de "lo he leído".

El costo de esa elección: cuando el proyecto requiere que todos los hilos estén resueltos antes de fusionar (All threads must be resolved de GitLab, Require conversation resolution de GitHub), las anotaciones deben resolverse antes de que se desbloquee el botón de fusión. Con un comentario de archivo por archivo, eso ahora es un número real de clics, por lo que dígaselo al usuario cuando detecte dicha configuración y ofrézcase a resolver en masa al final. Los comandos para ambos están en los archivos de referencia de la plataforma.

8. Sincronización después de cada push

Los nuevos commits invalidan silenciosamente las anotaciones: el código que describe un comentario puede haberse movido, cambiado de significado o desaparecido – y los nuevos archivos llegan sin cobertura alguna. Vuelva a ejecutar esta habilidad en modo sync después de cada push a la rama del MR.

python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json

--comments es repetible y toma el JSON bruto de la plataforma tal cual – en GitHub son dos llamadas (comentarios de revisión y comentarios de issue), así que pase ambos archivos.

Clasifica cada anotación existente como ok (ancla y huella sin cambios – déjela en paz), moved (mismo código, nueva línea – reanclar), stale (el código que describió cambió – releer y reescribir) o orphaned (el archivo o fragmento desapareció – eliminar). También informa file coverage – qué archivos modificados aún no tienen comentario a nivel de archivo, cuáles están exentos – y fragmentos uncovered que ahora son candidatos para un comentario en línea.

Luego: corrija solo lo que marcó, siempre reescriba el comentario de visión general en su lugar (resume todo el MR, por lo que cualquier push puede invalidarlo) y vuelva a ejecutar la fase 2 de §6 para que los enlaces de referencias cruzadas aún apunten a comentarios vivos. Una fila MISSING en la cobertura de archivos no es trabajo opcional – un nuevo archivo sin comentario es la única brecha que esta habilidad existe para prevenir. Siga references/sync-after-push.md para el caso de push forzado, manejo de comentarios eliminados por plataforma y cómo evitar cambios innecesarios en comentarios que en realidad no cambiaron.

Mencione al usuario, una vez, que esto debe ejecutarse después de cada push, y que references/sync-after-push.md tiene un hook pre-push opcional.

Skills relacionados