el momento
Acaba de aterrizar un plan de 400 líneas. ¿Y ahora qué?
Ya conoces la rutina: el agente termina un plan y el siguiente movimiento es tuyo. Leer el Markdown crudo en un editor esconde lo que vería un lector — las tablas, la estructura, la forma del argumento. Pegar fragmentos de vuelta en el chat separa cada comentario del lugar al que se refiere, y el agente tiene que adivinar a dónde apunta tu «esta parte está mal». Y la única herramienta hecha para comentar documentos — un pull request — exige antes hacer commit del borrador, subirlo y revisarlo en un navegador.
No todo documento merece un commit, y no toda versión de trabajo de un doc debería subirse.
Un borrador de trabajo necesita el mismo ciclo de feedback que le darías a un colega frente a una pizarra: señalar el párrafo, decir qué falla, devolvérselo. Eso son las notas al margen.
el ciclo
Lee renderizado. Anota en el sitio. Devuélvelo.
Abre el borrador en PullMark — o simplemente pullmark plan.md desde
la terminal donde corre tu agente. Las tablas son tablas, los diagramas son
diagramas y la página se vuelve a renderizar cada vez que el archivo cambia.
Pasa el cursor por el bloque que falla, haz clic en el globo de nota y escribe lo que le dirías a un colega. Las notas van firmadas con tu @nombre y ancladas al pasaje exacto — una nota encima del título cubre el documento entero.
Dile a tu agente: «atiende mis notas en plan.md». Las notas viven en el archivo como simples comentarios HTML, así que el agente lee cada una exactamente donde la dejaste — la aplica, la responde, la borra.
Sin ataduras, por construcción. Una nota al margen es
<!-- note @you: … --> en el Markdown — un comentario que
no aparece en la página renderizada. Tus archivos siguen siendo texto plano,
tus notas viajan con el documento y cualquier cosa capaz de leer el archivo
puede leer los comentarios. Los docs
de notas al margen explican la mecánica; la función está en beta y activada
por defecto.
A los agentes les sale mejor la convención con un párrafo de contexto.
Este es el mismo texto que hay detrás del botón Copiar en
Ajustes → Experimental — pégalo en el archivo de instrucciones
de tu agente (CLAUDE.md, AGENTS.md) o en la
conversación:
## 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.
documentos largos
Notas que saben esperarte.
Una revisión a fondo de un documento largo — un informe de investigación, un doc de diseño complejo — puede llevar una hora. Las notas al margen están hechas para esa hora. El documento se queda quieto mientras trabajas: escribe la idea donde te asalta y sigue leyendo. Cuando la página treinta te haga cambiar de opinión sobre la nota que dejaste en la página tres, vuelve y afínala — o bórrala. Nada llega a tu agente hasta que la pasada termina y tus notas concuerdan entre sí, así que el feedback aterriza como un conjunto coherente y no como un goteo de correcciones.
También rinde con documentos que acabarán en un commit. Haz la primera pasada en bruto con notas al margen antes del primer commit, y el pull request se abre limpio — los revisores ven la conversación que importa, no el andamiaje que hizo falta para llegar.
la revisión
Mira aterrizar los cambios.
Mientras el agente trabaja con tus notas, PullMark le sigue el ritmo. La
página se vuelve a renderizar con cada guardado, y Comparar
muestra la nueva versión como un diff renderizado — las ediciones
del agente resaltadas palabra por palabra, en vivo a medida que aterrizan. Un
clic compara el archivo de trabajo con cualquier commit o rama reciente;
pullmark --diff plan.md lo hace desde la terminal. Es la
respuesta más rápida a «¿qué acaba de cambiar el agente en mi
doc?» — y cuando las notas quedan atendidas, sencillamente
desaparecen del archivo.
cuando sí es un PR
Y cuando el doc sí sube a revisión…
Algunos documentos sí merecen un commit — y los repos con mucho agente llenan los pull requests de Markdown: planes, ADRs, definiciones de agentes, runbooks. PullMark muestra esos PR como diffs renderizados con solo las palabras que cambiaron resaltadas, te deja comentar y sugerir sobre los bloques exactos y envía tu revisión a GitHub. El resumen sabe en qué punto está el PR: la decisión, los veredictos de los revisores, los checks y la conversación como una cronología legible.
Cierra el ciclo con tu agente.
Gratis, de código abierto, firmada y notarizada. macOS 13+.
$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmarkEl DMG más reciente — ábrelo y arrástralo a Aplicaciones (PullMark se encarga de la limpieza). Todas las versiones →
Vayas por donde vayas, PullMark busca actualizaciones y las instala con un clic.