LLM12 – Un visor de Markdown diferente

En el artículo anterior hablábamos de cómo podíamos dar ojos y oídos a un agente para verificar su propio trabajo, y en LLM10 sobre cómo podemos usar las anotaciones de Markdown para comunicarnos con el agente. En el artículo de hoy vamos a combinar estas dos ideas y hablar de una pequeña utilidad que llevo usando durante el último mes, un visor web un tanto particular de Markdown.

La herramienta en acción

Mi flujo de trabajo últimamente se parece bastante a esta imagen, una pantalla dividida, por una parte el chat y por otra parte «algo», ya sea un documento, una web, o una revisión de código. En este ejemplo es un documento de requisitos que he creado usando EARS y RFC2119 para una herramienta de Kanban como ejemplo.

Este es un visor, es decir, no permite la edición directa, pero permite generar anotaciones sobre el contenido del documento. Estas anotaciones se persisten en el fichero Markdown.

¿Y qué podemos hacer con las anotaciones? Pues pedir a Claude que lea y aplique los comentarios con el contexto necesario de donde se han generado. El LLM leerá el documento, nuestras notas y finalmente generará una nueva versión del mismo, que se actualiza automáticamente.

Para qué tipo de documentos merece la pena?

Desde que empecé con el proyecto, he trabajado sobre todo con documentos de contexto: el resultado de una investigación, el progreso de una tarea, o diferentes ideas relacionadas con el proyecto.

En cuanto a la formalidad, estoy trabajando en un espectro amplio. Por una parte, una serie de ideas en texto libre; por otra, estoy experimentando documentos más formales como los que hemos visto en las imágenes usando dos tipos de nomenclatura: RFC 2119 para requisitos definiendo palabras clave como MUST, SHOULD o MAY y EARS, que define requisitos como: «cuando ocurre X, el sistema debe hacer Y».

Por qué otra herramienta?

Escribo estas líneas desde Obsidian que me parece un editor de texto fabuloso, y tanto Visual Studio Code como Zed tienen visores de Markdown muy potentes, sin embargo, últimamente paso mucho más tiempo leyendo (y comentando) que escribiendo documentos, y me pareció una idea interesante crearme mi pequeña herramienta web que me permitiera lo siguiente: Renderizar markdown, escribir comentarios en el mismo, y recargar de disco cuando hubiera cambios.

Cómo se hizo?

Dejando la obviedad de que el 100% del código de esta utilidad está hecha por claude code, la parte más interesante es que casi todas las características las he ido implementando usando la app, ya sea la app móvil como la app de escritorio o la web de claude.ai.

Crear cambios desde el móvil que tienen como resultado una PR de github es un ejemplo «de libro» de la importancia de cerrar el bucle, con lo cual yo puedo pedir un cambio (por ejemplo modo oscuro) y asegurarme que los tests existentes encontrarán cualquier regresión antes de hacer el merge a main.

Dejando de lado la estructura inicial, he agregado algunas características peculiares, como un botón para copiar el markdown en el portapapeles para poder pegarlo en otras herramientas o historial de recientes, y algunos otros cambios que veremos al final del artículo.

De verdad, solo desde el móvil?

Como he dicho antes, casi todas las características están hechas desde el movil, pero la semana pasada estuve echando un vistazo al código en la pantalla grande como el señor mayor que soy, y tuve la oportunidad de limpiar y hacer algunos refactors del código, como extraer el código de las vistas a ejs, trocear en multiples ficheros y dividir en módulos, y más tareas de limpieza que de vez en cuando hacen falta.

Este refactor fue un buen recordatorio de la necesidad de leer el código que producen los agentes, y de priorizar límites a la hora de cerrar los bucles. En este caso uno de los límites que no estaban puestos al principio, eran reglas de linter para mantener el tamaño de los ficheros, las funciones o la complejidad ciclomática.

Los agentes pueden ser testarudos, y nada impide realmente que el agente deshabilite las reglas de linter y genere un desastre, pero dejando de lado excepciones, cualquier restricción que sea determinista (reglas de linter, pruebas unitarias, límites de rendimiento) ayudan al agente a tener feedback de la tarea realizada.

Conclusiones

Los LLM nos brindan la oportunidad de adaptar el entorno a nuestra manera de trabajar con cierta facilidad. A lo largo de este proceso, me he ido adaptando a las ventajas y limitaciones de modelos y herramientas, leyendo las experiencias de otros, y enriqueciendo mi caja de herramientas con pequeñas utilidades como esta, usando documentos como mecanismo de sincronización, y comunicación dentro de los mismos.

A pesar de que el modelo de Kanban está creado para el artículo, la herramienta es real, la uso diariamente y la sigo evolucionando. Un ejemplo es el soporte para diagramas de Mermaid que agregué mientras escribía este artículo.

Ser una herramienta real significa dar cariño y mantenimiento, preocuparse por los tests, por automatizar reglas en el linter, y tener specs detalladas de qué se supone que hace la aplicación, como por ejemplo el soporte que podemos dar al formato CommonMark.

Estas herramientas funcionan de manera muy personal, así que mi recomendación es que le eches un vistazo al repositorio y crees la tuya propia.

¿Y tú, has creado herramientas personalizadas para este nuevo mundo?