docs / beta

Notas al margenbeta

Comenta cualquier documento Markdown local como comentarías un pull request — salvo que los comentarios viven en el propio archivo, como simples comentarios HTML que no aparecen en la página renderizada. Está hecho para un ciclo en concreto: un agente te escribe un documento, lo lees en PullMark dejando notas sobre la marcha y le devuelves el archivo con un «atiende las notas y bórralas según las resuelvas». La página de agentes recorre ese ciclo entero, capturas incluidas.

Usarlas en PullMark

¿Lees esto en el Mac donde PullMark (0.28.1+) está instalado? Salta directo al interruptor de las notas al margen.

Vienen activadas — las notas al margen son una función experimental en beta que se publica activada (desde la 0.35). La primera vez que vas a por una — el globo al pasar el cursor, ⌥⌘M, o Editar / Eliminar sobre una nota que te dejaron — PullMark presenta la función: qué son las notas, un botón Copiar para enseñárselo a tu agente y un botón Desactivar por si no es para ti. El interruptor vive en Ajustes → Experimental y solo controla las herramientas de escritura; un documento que ya trae notas muestra sus globos en cualquier caso (en solo lectura), así que un archivo anotado por un compañero o por un agente nunca se renderiza vacío en silencio.
Añadir una nota — pasa el cursor por cualquier bloque de un documento local y haz clic en el globo del margen (el mismo gesto que para comentar un PR). Dentro de una lista el globo apunta al elemento que estés señalando, y dentro de una tabla, a la fila — un tinte sutil muestra exactamente a qué se va a enganchar la nota. Selecciona texto antes y la nota se abre con la selección citada — así es como señalas una frase en vez de un párrafo. ⌥⌘M anota el bloque que estás leyendo; Edición → Nota al margen del archivo… deja una nota sobre el documento entero, arriba del todo.
Escribe Markdown — negrita, código en línea, bloques de código, enlaces, listas; ⌘↩ guarda. Cada guardado es una edición del archivo (deshazla con Archivo → Revertir la última edición).
Editar / Eliminar — pasa el cursor por el globo de una nota para ver sus acciones. Borrar una nota es la forma de darla por resuelta: sin estados, sin archivo histórico — una nota atendida es una nota ausente.
El chip — las filas de Archivos abiertos llevan un chip con la cuenta de comentarios mientras el documento aún cargue notas. Está vivo: según el agente recorre el archivo borrando notas, la cuenta baja y los globos desaparecen delante de ti.
En todo lo demás — las notas se renderizan en solo lectura en los archivos de GitHub que navegas, no aparecen nunca al imprimir, ni al exportar a PDF/HTML, ni en Quick Look, y Visualización → Ocultar las notas al margen despeja la página cuando quieres leer limpio.
Tu firma — las notas van firmadas @tu-login-de-github por defecto; cámbialo bajo el interruptor de la propia función, en Ajustes → Experimental.

El formato

Una nota al margen es un comentario HTML con la palabra clave note y una marca de autor, puesto en su propia línea después del bloque del que habla:

Requests retry three times with exponential backoff.

<!-- note @josh: Section 2 says five times. Which is it? -->

Una nota sobre un solo elemento de lista vive dentro del elemento — sangrada hasta el contenido del elemento, bien pegada, para que la lista siga entera:

- First point
  <!-- note @josh: too vague — name the metric -->
- Second point

Las notas más largas ponen el marcador de cierre en su propia línea; el cuerpo es Markdown completo, líneas en blanco y bloques de código incluidos:

<!-- note @josh:
This contradicts the design doc. Either reconcile them or
drop this section.

```suggestion
Requests retry five times with exponential backoff.
```
-->

La gramática completa:

Regla	Detalle
Marcador	`<!-- note @` abre una nota; los comentarios HTML normales (directivas de lint, TODOs) se dejan en paz.
Autor	Todo lo que va entre `@` y los primeros dos puntos. Se admiten espacios; los alias cortos son los que mejor se leen.
Cuerpo	Markdown, desde los dos puntos hasta `-->` — en la misma línea para las notas cortas, en las líneas siguientes para las largas.
Escapes	Un `-->` literal dentro del cuerpo se escribe `--\>` (es la única secuencia reservada; PullMark la escapa y la desescapa por ti).
Colocación	En su propia línea, con líneas en blanco alrededor, justo después del bloque que anota. Por encima del primer encabezado = una nota sobre el documento entero.
Elementos de lista	Una nota sobre un elemento de lista va dentro del elemento: justo después de su última línea, sangrada hasta el contenido del elemento (3 espacios como mucho — más adentro se lee como código) y sin líneas en blanco alrededor. La sangría es lo que la ata al elemento.
Hilos	Las notas contiguas bajo el mismo bloque se leen como una conversación — responde añadiendo otra nota debajo.
Reservado	`@name (attrs):` — la ranura entre paréntesis está reservada para el futuro y se conserva tal cual; hoy nada la escribe ni la lee.
Bloques de código	Un comentario con forma de nota dentro de un bloque de código delimitado es código, no una nota.

Como los renderizadores de Markdown se saltan los comentarios HTML, un archivo con notas dentro se renderiza limpio en GitHub, en los editores y en cualquier otra herramienta — las notas viajan en el código fuente sin ensuciar la página. PullMark es el cliente bonito de un formato que funciona en todas partes.

Para agentes

El traspaso es de protocolo cero: los agentes leen archivos, y las notas están en el archivo, físicamente pegadas al texto del que hablan. Pega esto en tu CLAUDE.md / AGENTS.md — Ajustes → Experimental tiene un botón Copiar con el mismo texto (o simplemente díselo):

## Margin notes

Markdown files may contain review notes as HTML comments:
`<!-- note @name: comment -->` (possibly multi-line, closing
with `-->` on its own line). Each note sits directly after the
passage it's about; a note above the first heading is about the
whole document. `--\>` inside a note means a literal `-->`.

When asked to address notes: work through each one, apply or
answer it, and DELETE the note (with its surrounding blank line)
once addressed. To reply or ask instead, leave your own note in
the same format below the original, signed with your own @name.
Don't add notes to code examples inside fenced blocks.

A note about one list item sits inside that item — directly after
the item's last line, indented to the item's content, with no
blank lines around it. Keep (or delete) the whole indented
comment; its indentation is what ties it to the item.

El ciclo de convergencia sale del propio formato: los globos que quedan son el trabajo que queda, y un archivo vacío es una revisión terminada. Si las notas nunca deben llegar a un pull request, un check de CI es una sola línea — grep -rn '<!-- note @' docs/ && exit 1.

Por qué está en beta

La mecánica se ha ganado su sitio — el formato no ha necesitado ningún cambio incompatible desde que se publicó, y por eso se graduó del alfa. Según el contrato beta, ahora ponemos empeño de verdad en mantener compatibles la gramática y el comportamiento entre versiones, y lo más probable es que la función se gradúe del todo. Lo que sigue asentándose es la superficie que la rodea: los nombres, los gestos que la invocan y hasta dónde generaliza el flujo más allá del ciclo de revisión con agentes en el que se diseñó. Si algo cambia, las notas de la versión dirán exactamente qué. Se agradecen comentarios.