Discute la arquitectura donde vive

Alguien se da cuenta de que Billing escribe directamente en la base de datos del ledger, aunque ADR-12 dice que solo la Ledger API puede hacerlo. Lo pregunta en un hilo de Slack. Dos respuestas, un "buena observación, lo miro", y a la hora de comer el hilo ya se ha perdido de vista. Un mes después la flecha sigue en el diagrama, ADR-12 sigue leyéndose como si nadie lo hubiera cuestionado nunca, y la persona que dijo "lo miro" se ha cambiado de equipo. La pregunta se hizo y se respondió, en un lugar que la arquitectura no puede ver.

Ese es el hueco en el que trabajamos esta semana. El 18 de octubre lanzamos seis funcionalidades que llevan la conversación sobre la arquitectura al propio modelo: comentarios fijados en el diagrama, @menciones, citas con # y una lista "Citado en", previsualizaciones de enlaces en la app y en Slack, seguimiento y tareas. Cada una vincula una discusión al elemento, la decisión o la página de la que trata, y todas informan a la bandeja de entrada que añadimos el 10 de octubre.

La misma pregunta, hecha en el modelo

Aquí está de nuevo esa pregunta sobre el ledger, pasada por lo que acabamos de lanzar. Los nombres y el proyecto son ejemplos. El comportamiento es el del producto.

Marie la fija donde la ve. Está revisando el proyecto Checkout a nivel de container. Pulsa C, el cursor se convierte en una cruz, y hace clic en la flecha de Billing a Ledger DB. Se abre un cuadro de comentario a mitad de la relación, y escribe:

Billing writes to Ledger DB directly here. #ADR-12 says ledger writes
go through the Ledger API. @Sam, is this still intended?

Al escribir # se abrió una lista de los elementos, decisiones y páginas del proyecto, y ADR-12 se convirtió en un chip que abre la decisión. Al escribir @ aparecieron las personas que pueden abrir el proyecto, y Sam, responsable de Billing, también se convirtió en un chip. Pulsa ⌘ Enter. La burbuja recibe un número, #7, y todos los que abren esa vista del diagrama la ven.

Sam se entera. Su campana muestra que Marie lo ha mencionado, con el comentario de ella como extracto. No tiene que estar mirando el diagrama, ni el canal de Slack correcto, para saberlo.

La respuesta se convierte en una tarea. Sam responde que es un resto de la migración del ledger y que lo moverá detrás de la Ledger API. Marie, que inició la discusión, recibe su respuesta en la bandeja de entrada. Abre la discusión completa, hace clic en Tarea bajo la respuesta de Sam, se la asigna, elige el viernes como fecha de vencimiento y hace clic en Crear tarea. Aparece una casilla bajo la respuesta, y la tarea llega a la pestaña Por hacer de la bandeja de entrada de Sam.

La decisión recuerda que fue cuestionada. Abre ADR-12 y la parte inferior de su tarjeta expandida muestra ahora el comentario de Marie en Citado en, con el texto que rodea la cita. Quien lea la decisión después sabrá que en la base de datos que protege se seguía escribiendo, y podrá hacer clic para ir a la discusión.

La corrección se anuncia sola. Sam sustituye la flecha mediante una solicitud de cambio. Su descripción cita #ADR-12 y pega el enlace a la discusión #7, que aparece como una tarjeta de previsualización bajo el texto. Todos los que pueden editar el proyecto reciben el aviso de que se abrió una solicitud de cambio, como antes. Léa, del equipo de datos financieros, no puede revisarla, pero sigue el proyecto Checkout, así que también recibe una línea: una solicitud de cambio abierta en un proyecto seguido notifica a los seguidores que no pueden revisarla.

El ciclo se cierra. Sam marca la tarea. Marie, que la creó, recibe "Sam completó una tarea que creaste". Resuelve la #7 y la burbuja desaparece del diagrama. Cuando Sam pega el enlace de la solicitud de cambio en #payments, el bot de Archyl lo despliega con su título, su estado y su proyecto.

Cada pieza de ese intercambio está vinculada a algo del modelo: la relación, la decisión, el responsable, la solicitud de cambio. Nada depende de que alguien recuerde dónde estaba un hilo.

Qué hace cada funcionalidad

Comentarios en el diagrama

Pulsa C, o haz clic en Comentar en la barra inferior del diagrama, y luego haz clic donde corresponde el comentario:

  • en un espacio vacío, la burbuja se queda en ese punto;
  • en un elemento, queda vinculada y sigue al elemento cuando se mueve, y la discusión aparece también en el panel de detalles del elemento;
  • en una relación, se sitúa a mitad de ella.

Las burbujas se numeran por proyecto y mantienen el mismo tamaño con cualquier zoom. Cada una pertenece al nivel y la vista donde se colocó, así que un comentario en el system context no aparece dentro de un sistema. Las burbujas resueltas están ocultas; marca Mostrar resueltos en modo comentario para verlas en gris. Por lo demás, una discusión fijada es una discusión normal: aparece en la lista de discusiones del proyecto, y sus respuestas notifican a las personas que participan en ella. Docs: Comentarios en el diagrama.

@menciones

Escribe @ en un comentario o una respuesta, en el contexto, la decisión o las consecuencias de un ADR, en una página de documentación, o en la descripción, un comentario o una revisión de una solicitud de cambio. La lista muestra las personas que pueden abrir el proyecto y los equipos que tienen al menos una de ellas. Mencionar a un equipo llega a sus miembros que pueden abrir el proyecto.

A cada persona se le avisa una vez: volver a editar el texto no notifica a nadie que ya estuviera mencionado. Las menciones en un título no se detectan, así que escríbelas en el cuerpo. Cuando lanzamos la bandeja de entrada, las menciones eran lo primero de su lista de "lo que aún no hace". Ya están. Docs: Menciones, citas y enlaces.

Citas con # y "Citado en"

Escribe # en los mismos lugares para citar un sistema, container, component o elemento de código (cada uno mostrado con su padre), una decisión (listada como ADR-3 con su título) o una página de documentación. Al hacer clic en el chip se abre lo que cita. Un elemento se abre en el diagrama en su propio nivel, ya seleccionado.

La otra mitad es el backlink. Cada elemento, decisión y página lista dónde se cita, lo más reciente primero, con el extracto alrededor de cada cita: en la sección Citado en del panel de detalles de un elemento, en la parte inferior de la tarjeta expandida de una decisión, al final de una página. Esta es la parte que un hilo de Slack no puede darte. La conversación apunta al ADR, y el ADR apunta de vuelta.

Previsualizaciones de enlaces, en Archyl y en Slack

Copiar enlace está en el panel de detalles de un elemento, en cada tarjeta de decisión y en la parte superior de cada página de documentación. Un enlace a un elemento abre el elemento en su nivel, seleccionado. Las solicitudes de cambio y las discusiones se comparten desde la barra de direcciones.

Pega un enlace de Archyl en un comentario, en la descripción de una solicitud de cambio o en una revisión y aparecerá como una tarjeta bajo el texto: título, tipo y estado, proyecto y un extracto. Se previsualizan hasta tres enlaces por mensaje, y solo para las personas que pueden abrir el proyecto. Los demás ven un enlace simple.

En Slack, el bot ahora despliega los enlaces a un proyecto, un elemento, una decisión, una página de documentación, una solicitud de cambio o una discusión en esa misma previsualización. Sigue las reglas que el bot ya tenía. La previsualización se construye con los permisos del admin que conectó el workspace, solo para proyectos de la organización a la que está conectado el workspace, y en un canal acotado un enlace a un proyecto fuera del alcance se queda como enlace simple. Un enlace a algo que no existe, o que el bot no puede ver, también se queda simple, así que una previsualización nunca confirma que una página existe. Docs: Previsualizaciones de enlaces en Slack.

Seguimiento

Sigue un elemento, una decisión o un proyecto entero con la campana del panel de detalles del elemento, de la tarjeta de la decisión o de la barra de herramientas del diagrama. Una campana rellena significa que lo sigues. Los responsables de un elemento lo siguen sin hacer nada, y también los miembros de un equipo responsable de él. Haz clic en la campana para darte de baja y Archyl lo recuerda, aunque sigas siendo responsable del elemento.

Los seguidores se enteran cuando lo que siguen se modifica o se elimina (la notificación lista los campos que cambiaron), cuando un elemento seguido recibe un comentario y cuando una solicitud de cambio toca un elemento seguido. Los seguidores de un proyecto se enteran además cuando se añade un elemento, una decisión o una página. Seguir no da acceso: si pierdes el acceso al proyecto, las notificaciones se detienen. Docs: Seguimiento.

Tareas

Bajo cualquier comentario o respuesta de un proyecto, haz clic en Tarea, elige un responsable entre las personas que pueden abrir el proyecto (tú, por defecto), opcionalmente una fecha de vencimiento, y haz clic en Crear tarea. Un comentario lleva como máximo una tarea. La tarea aparece bajo su comentario con una casilla, el responsable y la fecha de vencimiento, que se vuelve roja una vez pasada. Quitar la tarea conserva el comentario.

Tus tareas abiertas están en la pestaña Por hacer de la bandeja de entrada, primero las que vencen antes, con un contador en la pestaña. El panel de detalles de cada elemento tiene una sección Por hacer que lista las tareas de todas sus discusiones. Al responsable se le avisa cuando se crea una tarea para él o se le reasigna, y al creador cuando otra persona la completa. Docs: Tareas.

Los agentes también pueden etiquetar

Los agentes de código conectados a través del servidor MCP escriben en el mismo modelo: abren solicitudes de cambio, registran decisiones, dejan comentarios. Hasta ahora, un agente que escribía "@Sam, ¿puedes confirmarlo?" producía texto plano que no avisaba a nadie.

Ahora el servidor lee lo que escribe un agente igual que lo hacen los selectores en la app. En un comentario, un ADR, una página de documentación o una solicitud de cambio:

  • @Name menciona a una persona o a un equipo, que recibe el aviso en su bandeja de entrada como con cualquier otra mención. El agente puede llamar a list_mentionables para obtener los nombres exactos.
  • #Label cita un elemento C4, una decisión (#ADR-12) o una página, que entonces lista el texto del agente en Citado en.

Un comentario publicado por un agente también llega a las personas que ya participan en la discusión y a los seguidores del elemento, igual que uno publicado por una persona. Cada escritura le dice al agente qué se ha vinculado, para que pueda comprobar que @Sam llegó de verdad a Sam.

Los agentes también pueden leer los enlaces de vuelta. get_backlinks devuelve dónde se cita un elemento, una decisión o una página. Antes de tocar Ledger DB, un agente puede encontrar el comentario #7 de Marie y la solicitud de cambio que citó ADR-12, en lugar de redescubrir la pregunta.

Seguir sin ahogarse

Seguir va en contra de la regla que fijamos para la bandeja de entrada: solo contiene lo que te espera o lo que responde a algo que hiciste. Que un elemento seguido cambie no te espera. Lo dejamos entrar porque tú lo pediste, al hacer clic en la campana o al ser responsable del elemento, y pusimos límites a cuánto ruido puede hacer:

  • Mover un elemento o cambiar su estilo no notifica a nadie.
  • Varias ediciones sobre lo mismo en una hora generan una sola notificación, mientras no la hayas leído.
  • Si sigues un proyecto pero no el elemento, recibes como máximo una notificación de cada tipo por hora para ese proyecto. Aprobar un AI discovery que crea cientos de elementos es una línea, no cientos.
  • No se te avisa dos veces. Un comentario que te menciona, o una respuesta en una discusión de la que formas parte, te llega solo a través de esa notificación.
  • Nunca se te avisa de tus propias acciones.

Si quieres cada cambio de toda la organización, las notificaciones por correo y la página Historial siguen siendo el lugar para ello.

Lo que aún no hace

  • Solo bandeja de entrada. Las menciones, los seguimientos y las tareas no envían correo.
  • Sin recordatorio de vencimientos. Una tarea vencida se vuelve roja, y nada te avisa.
  • Sin lista de lo que sigues. Lo gestionas desde cada elemento, decisión o proyecto. Una página de documentación no se puede seguir por sí sola; sigue su proyecto en su lugar.
  • Las burbujas se quedan donde las pones. No puedes mover una una vez colocada. La burbuja de una relación se sitúa en el punto medio entre sus dos elementos, no sobre la curva de la línea. Las burbujas se ocultan mientras Viaje en el tiempo está abierto.
  • Sin previsualizaciones en Microsoft Teams. Solo Slack, por ahora. Los workspaces de Slack conectados antes del 18 de octubre deben volver a conectarse desde Organización → Bot para conceder los dos permisos nuevos, links:read y links:write.
  • Los agentes no ven las tareas, los seguimientos ni los comentarios fijados. A través del servidor MCP pueden mencionar y citar, pero aún no leer ni completar tareas, seguir un elemento ni fijar un comentario en el diagrama.
  • Sin tareas fuera de un proyecto. Las discusiones de organización no pueden llevar una.

Pruébalo

Abre un diagrama, pulsa C y haz clic en esa relación sobre la que llevas tiempo queriendo preguntar. Menciona a quien sea responsable del otro extremo y cita la decisión que se supone que debe seguir. La documentación cubre cada pieza en detalle:

Lecturas relacionadas: una bandeja de entrada para lo que te espera, para las reglas que sigue cada notificación anterior, y acotar el bot por canal, para lo que un canal de Slack puede previsualizar.