Revisión de arquitectura y ADR: el porqué junto al código

Todo código tiene una parte que le parece mal a la siguiente persona que lo lee. Un proceso de reenvío que nadie recuerda haber añadido, una tabla que se vacía cada semana, una cola donde bastaría una llamada directa. Las razones se dijeron en voz alta en una revisión de arquitectura hace meses, y quienes las dieron se han ido a otros equipos. El ingeniero nuevo tiene dos opciones: preguntar por ahí durante una semana o «arreglarlo».

Hay un camino más corto. Grabe la revisión de arquitectura, pulse un atajo cuando se diga una decisión, una contrapartida o una opción descartada, y comparta la grabación en un canal Architecture. Las marcas se quedan en las frases, con la hora y el nombre de quien habló. Justo después de la revisión, un asistente de IA en Claude Code, Cursor o Claude lee esas marcas por MCP y redacta el borrador del Architecture Decision Record (ADR, el registro de una decisión de arquitectura) para el repositorio. Meses después, el debate sigue ahí para cualquiera que pregunte por qué.

Esta guía sigue la app de Speak-Y para macOS, comprobada el 18 de octubre de 2026, y está pensada para un tech lead cuyo equipo ya comparte sus reuniones en un espacio de trabajo. Si todavía no tiene uno, créelo primero.

¿Por qué «¿por qué está hecho así?» no tiene respuesta?

La solución se describió en 2011. El artículo de Michael Nygard Documenting Architecture Decisions (comprobado el 18 de octubre de 2026) propone un registro breve para cada decisión importante —título, contexto, decisión, estado, consecuencias— guardado en el repositorio junto al código. Su razonamiento es el problema de arriba: alguien nuevo en un proyecto que no sabe por qué se tomó una decisión solo puede aceptarla a ciegas o revertirla a ciegas. El sitio de la comunidad ADR llama al conjunto de estos registros el registro de decisiones de un proyecto.

Los equipos que adoptan los ADR pierden igualmente el porqué, en tres sitios previsibles:

Una grabación conserva las tres cosas. Las marcas permiten encontrarlas, y un asistente las convierte en un borrador antes de que los detalles se borren.

Configuración inicial: tres marcas y un canal Architecture

Las marcas. Speak-Y viene con un único tipo de nota, Marcar el momento, en ⌥1. Añada tres propios en Configuración → Notas: haga clic en Añadir tipo de nota, escriba Decision en Nombre del tipo, haga clic en Guardar, después en Asignar atajo y pulse ⌥2. Repita con Trade-off en ⌥3 y Rejected en ⌥4. Cada marca corresponde a una sección del registro:

El contexto es la conversación en torno a las marcas; el asistente lo lee en la transcripción. El formato de Nygard no tiene una sección propia para las opciones descartadas; la plantilla MADR sí la tiene: Considered Options.

El canal. Un canal público para las revisiones de arquitectura, llamado Architecture, al que pueda unirse cualquier ingeniero. En el menú ⋯ del espacio de trabajo, elija New channel. Las revisiones de diseños sensibles para la seguridad —un modelo de amenazas, un flujo de autenticación— van a un canal privado; las ventajas y los inconvenientes se explican en quién ve qué en los canales de reuniones.

Tres tipos de nota para revisiones de arquitectura —Decision en Opción 2, Trade-off en Opción 3, Rejected en Opción 4—, cada uno asociado a una sección de un Architecture Decision Record
Tres atajos se corresponden con el ADR: decisión, consecuencias, alternativas; el contexto sale de la transcripción.

Durante la revisión: nombre el componente y después pulse la tecla

Inicie la grabación de una reunión en Speak-Y cuando empiece la revisión. Ningún bot se une a la llamada: Speak-Y graba el micrófono y el sonido de la llamada en su Mac, así que funciona igual en Zoom, Google Meet, Teams o en una sala de reuniones. Avise a todos de que la revisión se graba.

La transcripción solo sabe lo que se dijo, así que tres hábitos compensan:

  1. Nombre el componente antes de comentarlo. «El publicador de eventos de pago en payments-service» hace que cada marca posterior se pueda encontrar por el nombre que un ingeniero buscará más adelante.
  2. Deje que se diga la razón y después pulse. Una marca cubre los últimos 15 segundos de la transcripción antes de la tecla, así que la frase con el porque queda dentro de la marca.
  3. Marque también las opciones perdedoras. Una marca Rejected en «las escrituras dobles pierden eventos cuando el servicio se cae entre una y otra» es la línea que le ahorra media hora a la siguiente revisión.

Normalmente graba y pulsa las teclas el tech lead que dirige la revisión. Los atajos funcionan desde cualquier app, con el diagrama o el código todavía en primer plano.

Después de la revisión: nombres, etiquetas, To channel

Dos minutos en la ventana de la grabación, mientras la conversación está fresca:

  1. Ponga nombre a los hablantes. Haga clic en Speaker 1, Speaker 2 y así sucesivamente, y escriba los nombres reales. Una marca vale lo que vale el nombre que la acompaña.
  2. Etiquétela. Añada el nombre del servicio y el número del registro que va a escribir, como payments-service y adr-0012. El asistente y sus compañeros encuentran la revisión por estas etiquetas.
  3. Revise las marcas. Los chips sobre la transcripción las cuentan por tipo: Todas las notas · 8, Decision · 3, Trade-off · 3, Rejected · 2.
  4. Compártala. Pulse To channel bajo la transcripción y elija Architecture. La transcripción con nombres y marcas de tiempo, el resumen de IA y los elementos de acción pasan al canal, cifrados de extremo a extremo; el audio se queda en su Mac.
  5. Muestre las marcas. Las marcas son privadas por defecto. Haga clic en el chip Privadas sobre la transcripción y elija Mostrar en # Architecture: los miembros del canal las verán, para que las marcas viajen con la grabación.
Grabación de Speak-Y de una revisión de arquitectura con marcas Decision, Trade-off y Rejected en la transcripción, los chips de filtro de notas y el botón To channel
1: las marcas contadas por tipo; 2: una marca Rejected en la frase que explica por qué; 3: un clic envía la revisión al canal Architecture.

Redacte el ADR a partir de las marcas

Conecte su asistente al servidor MCP de Speak-Y una sola vez: abra Conectar asistente de IA en el menú de la cuenta, al pie de la barra lateral, o Configuración → Integraciones, y haga clic en Conectar junto a Claude, ChatGPT o Cursor. Para Claude, un solo clic configura tanto Claude Desktop como Claude Code. El servidor es gratuito en todos los planes.

Después, en el repositorio, pida:

Redacta el ADR 0012 a partir de la revisión de payments-service etiquetada con adr-0012: contexto, decisión, consecuencias y opciones descartadas. Indica quién dijo cada punto y cuándo.

El asistente encuentra la revisión por su etiqueta y la lee. Junto con la transcripción, Speak-Y le entrega las marcas como una lista —cada una con su desfase en la grabación, su tipo, el hablante y las primeras palabras de la frase—, así que el borrador llega con tres decisiones, tres costes aceptados y dos opciones descartadas, cada uno con un nombre y una hora. En Cursor, el asistente pide permiso antes de ejecutar cada herramienta, salvo que usted cambie ese ajuste.

Edite el borrador antes de hacer el commit. Tres campos son suyos, no del asistente:

Lo que el asistente lee por MCP —las marcas de la revisión con desfases, tipos y hablantes— y el borrador de ADR que construye a partir de ellas
Las marcas Decision se convierten en la decisión, las Trade-off en las consecuencias, las Rejected en las alternativas; el estado y el responsable quedan en sus manos.

Meses después: el ingeniero nuevo pregunta por qué

El ADR del repositorio responde al qué en una página. Cuando eso no basta, el debate está a un paso.

En la app. Los compañeros que usted invita se unen gratis con cualquier plan. Un ingeniero nuevo que se une al espacio de trabajo ve el canal público Architecture con su historial. Ábralo, haga clic en la lupa de la cabecera del canal y escriba el nombre del componente, como outbox. La búsqueda lee las transcripciones de todas las revisiones del canal y muestra las líneas coincidentes con su hora.

En el editor. En Cursor o Claude Code, con el código abierto:

¿Por qué payments-service escribe los eventos en una tabla outbox en vez de publicarlos directamente en Kafka? ¿Qué se descartó?

El asistente busca en las grabaciones a las que el ingeniero tiene acceso, encuentra la revisión y responde a partir de ella: la decisión, quién argumentó en contra de las escrituras dobles y por qué, y qué aceptó el equipo a cambio. El mismo enfoque para las preguntas sobre código en general está en contexto de reuniones para programar por voz en Cursor.

Lo que la grabación de una revisión no sustituye

La grabación guarda el razonamiento. Cuatro cosas siguen viviendo en otra parte:

Cuatro comprobaciones para el registro de una revisión de arquitectura, cada una con la señal de alerta que indica que le falta algo
La grabación guarda las razones; el diagrama, el estado y las decisiones tomadas en el chat necesitan su propio sitio.

Límites y costes

En resumen

Tres tipos de nota —Decision, Trade-off, Rejected— en ⌥2, ⌥3 y ⌥4. Durante la revisión: nombre el componente, deje que se diga la razón y pulse la tecla. Después: nombres, etiquetas, To channel → Architecture y mostrar las marcas. Luego, una sola pregunta al asistente en el repositorio, y usted edita el borrador del ADR en lugar de escribirlo de memoria. La página de Teams explica los espacios de trabajo y los canales, y un registro de decisiones que se lleva solo aplica la misma idea a las decisiones de producto.

FAQ

¿Cómo dejo constancia de por qué se tomó una decisión de arquitectura?

Grabe la revisión de arquitectura en Speak-Y y pulse un atajo cuando se diga en voz alta una decisión, una contrapartida o una opción descartada. Comparta la grabación en un canal del equipo como Architecture. El canal guarda el debate con nombres y marcas de tiempo, y un asistente de IA conectado por MCP puede convertir las marcas en un borrador de Architecture Decision Record para el repositorio.

¿Pueden Claude Code o Cursor escribir un ADR a partir de la grabación de una reunión?

Pueden escribir un borrador. Conectado al servidor MCP de Speak-Y, el asistente encuentra la revisión por su etiqueta, lee la transcripción y la lista de marcas con su tipo, hora y hablante, y rellena el contexto, la decisión, las consecuencias y las opciones descartadas. El estado, el responsable y la redacción final quedan en manos del ingeniero que hace el commit del archivo.

¿Cómo averigua un ingeniero nuevo por qué un servicio está construido de cierta manera?

De dos formas. Abra el canal Architecture en la app de Speak-Y para macOS y busque en él el nombre del componente, o pregunte a un asistente en el editor, como Cursor o Claude Code, por qué el servicio hace lo que hace. El asistente busca en las grabaciones a las que el ingeniero tiene acceso y responde con quién dijo qué y cuándo.

¿Graba Speak-Y la pizarra o los diagramas que se muestran durante la revisión?

No. Speak-Y graba el audio del Mac que inicia la grabación: el micrófono y el sonido de la app de la llamada. Los diagramas, las diapositivas y las pizarras no están en la grabación. Diga el nombre del componente en voz alta antes de comentarlo y enlace el diagrama desde el ADR.

¿Cuánto cuesta esta configuración?

El servidor MCP es gratuito en todos los planes. Crear un espacio de trabajo de equipo requiere Pro o un plan superior, y los compañeros se unen gratis con cualquier plan. Comprobado en speak-y.com el 18 de octubre de 2026: Free corta la grabación de una reunión a los 30 minutos, Pro (10 $ al mes) a los 60, y Pro+ (15 $) y Max (30 $) a las cuatro horas.