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:
| Capa | Cobertura | Contenido |
|---|---|---|
| Visión general – un comentario a nivel de MR | siempre | el mapa de todo el cambio |
| Archivo – un comentario por archivo modificado | siempre, excepto archivos autogenerados | qué significa el cambio de este archivo |
| En línea – anclado a una línea del diff | solo puntos realmente no obvios, con presupuesto | por 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
| Modo | Cuándo | Qué hace |
|---|---|---|
annotate | Primera ejecución en un MR | Construye el conjunto completo de anotaciones, lo previsualiza y lo publica tras la aprobación |
sync | Después de cada push a la rama del MR | Vuelve 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:
- 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. - 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. - 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.
- 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_casespor archivo); los casosadaptedson 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 enreferences/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:
- Publique cada comentario con un token de marcador de posición (
[[ref:<slug>]]) donde pertenezca un enlace a otra anotación. - 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.