Cómo escribir un documento de arquitectura con IA: plantilla de seis secciones, dónde ayuda la IA y dónde inventa restricciones
Plantilla de documento de arquitectura (contexto, restricciones, componentes, flujo de datos, decisiones.
En esta página
Un documento de arquitectura tiene seis secciones: contexto, restricciones, componentes, flujo de datos, decisiones y riesgos. La IA es útil para el primer borrador de componentes y flujo de datos a partir de un PRD, para listar alternativas bajo cada decisión y para una lista de riesgos que después podas; es dañina cuando rellena la sección de restricciones, porque inventa límites que nunca tuviste y luego diseña alrededor de ellos. Escribe tú las restricciones y las decisiones, deja que el agente redacte el resto y mantén el conjunto por debajo de dos páginas.
Esta es la plantilla que usamos en Atrix para cada funcionalidad mayor que un ciclo, con el reparto de trabajo entre el agente y el ingeniero al que hemos llegado tras un año usando ambos.
Para qué sirve un documento de arquitectura
Responde una pregunta para la siguiente persona: ¿por qué el sistema tiene esta forma? No cómo operarlo (eso es el runbook), ni qué hace para los usuarios (eso es el PRD), sino qué piezas existen, cómo se mueven los datos entre ellas y qué elecciones se hicieron a propósito y no por accidente.
El lector es un ingeniero que se incorpora dentro de seis meses, o tú después de una pausa larga. Si el documento no se lee en diez minutos, no se leerá. Dos páginas, un diagrama, una tabla de decisiones.
La plantilla de seis secciones
| Sección | Qué contiene | Quién la redacta |
|---|---|---|
| Contexto | La funcionalidad en dos frases; enlace al PRD; qué existe hoy | El agente, desde el PRD |
| Restricciones | Límites duros: residencia de datos, latencia, presupuesto, contratos existentes, tamaño del equipo | Solo personas |
| Componentes | Las piezas tocadas y las piezas que deliberadamente no se tocan | El agente redacta, la persona recorta |
| Flujo de datos | Cómo una petición o un registro se mueve por los componentes, en orden | El agente redacta, la persona verifica contra el código |
| Decisiones | Cada elección significativa: opciones consideradas, la elegida, por qué | La persona decide; el agente lista alternativas |
| Riesgos | Qué puede salir mal, probabilidad, qué haríamos | El agente lista, la persona poda a cinco |
La columna "quién la redacta" es el sentido de este artículo. La plantilla en sí es corriente; el reparto es lo que hace a la IA útil en vez de peligrosa.
Contexto
Dos frases y un enlace. El agente lo hace bien porque resume un documento que se le dio. Haz que nombre lo que existe hoy: "Los recordatorios no existen; la sincronización del calendario y el envío de correo sí".
Restricciones
Los límites duros que el diseño debe respetar. "Los datos de clientes se quedan en la región de la UE". "El proveedor de correo limita a 100 por minuto". "Dos ingenieros, un ciclo". "No se debe cambiar la capa de sincronización, que se sustituye el próximo trimestre".
Escribe esta sección tú, antes de que el agente vea el documento. Un agente al que se le pide redactar restricciones producirá unas plausibles: "debe soportar 10.000 usuarios concurrentes", "debe escalar horizontalmente", "debe soportar failover multirregión". Ninguna es tuya. Una vez que están en el documento, la sección de componentes diseña para ellas, y acabas con una cola, una caché y una región de respaldo para una funcionalidad que envía cuarenta correos al día.
Componentes
El primer borrador del agente suele ser una lista razonable de piezas tocadas. Tu trabajo es recortar: quita los componentes que añadió para satisfacer restricciones inventadas y añade la línea "no se toca: X, Y" para las partes que dejas deliberadamente en paz. La lista de "no se toca" es más útil para un revisor que la de tocados.
Flujo de datos
Una secuencia numerada: "1. El cron se dispara en punto. 2. Consultar reservas en las próximas 24 h sin marca de enviado. 3. Renderizar plantilla. 4. Enviar por el proveedor. 5. Marcar como enviado". El agente lo redacta desde el PRD y los componentes; tú verificas cada paso contra el código existente. El paso 2 es donde viven la mayoría de los bugs, y el agente no sabrá que la tabla de reservas tiene una columna de borrado lógico.
Decisiones
Una fila por elección que alguien pueda cuestionar después: opciones, elegida, por qué. El agente es bueno listando opciones en las que no pensaste; es malo eligiendo, porque no conoce a tu equipo ni tu historia. Pídele alternativas y escribe tú las celdas "elegida" y "por qué". Lo normal son de tres a seis filas. Si tienes doce, el documento es de dos funcionalidades.
Riesgos
El agente listará quince. Quédate con cinco, cada uno con una mitigación de una línea. Un riesgo sin mitigación es una preocupación, no un riesgo.
Dónde ayuda la IA y dónde perjudica
Ayuda:
- Primer borrador de contexto, componentes y flujo de datos a partir de un PRD. Está leyendo un documento y reformulándolo de forma estructurada, cosa que hace bien.
- Alternativas bajo cada decisión. "¿Qué más podríamos hacer aquí?" produce con fiabilidad una opción que no habías considerado.
- Comprobaciones de coherencia. "¿Aparece cada componente del flujo de datos en la sección de componentes?" atrapa las omisiones que comete una persona cansada.
- Lluvia de riesgos, siempre que podes.
Perjudica:
- Restricciones. Inventadas, plausibles y estructurales. Tratado arriba.
- Elegir entre opciones. Escoge la respuesta de manual, no la que encaja con un equipo de dos personas con fecha límite.
- Afirmaciones sobre el estado actual. "La capa de sincronización existente expone un webhook" cuando no es así. Todo lo que el agente diga sobre el sistema de hoy debe comprobarse contra el código.
- Escala. Si se le deja solo, diseña para la escala de sus datos de entrenamiento, no para la tuya.
La regla que usamos: el agente puede escribir cualquier cosa que reformule un insumo que se le dio; una persona escribe todo lo que sea un hecho sobre el mundo o una elección.
Hacerlo en Atrix
Nuestro propio agente de IA produce un documento de arquitectura como una de las tres salidas de una ejecución Develop, junto con los requisitos y las incidencias planificadas, a partir del brief y el PRD que le das. Sigue el reparto de arriba porque así lo instruimos: el brief de la ejecución nombra las restricciones como insumo y al agente se le dice que no las amplíe. El documento aterriza como una página en Docs, donde tiene historial de versiones, comentarios y coedición en vivo, así que las ediciones del ingeniero en componentes y decisiones se ven como un diff frente al borrador del agente.
El diagrama de bloques se dibuja en la pizarra dentro de la página. Las pizarras en Atrix son tableros Excalidraw: dibujas las cajas y flechas a mano, y el dibujo queda editable junto al texto. No hay generación de diagramas a partir de texto; si quieres que el agente produzca un diagrama, pídele un flujo de datos numerado y dibuja a partir de él, lo que lleva unos diez minutos para una funcionalidad de seis componentes. Las herramientas que sí generan diagramas desde texto, como la IA de Miro y DiagramGPT de Eraser, se tratan en otro artículo.
Un ejemplo real, abreviado
Contexto: recordatorios de reservas; PRD v3; hoy no hay recordatorios, la sincronización del calendario y el envío de correo existen.
Restricciones (persona): sin cambios en la capa de sincronización; límite del proveedor de 100 correos por minuto; un ingeniero, un ciclo; solo datos en la UE.
Componentes (redactados por el agente, recortados por la persona): programador de recordatorios (nuevo), plantilla de recordatorio (nueva), consulta de reservas (existente, solo lectura), envío de correo (existente). No se toca: capa de sincronización, interfaz del calendario.
Flujo de datos: los cinco pasos listados antes, con el paso 2 corregido para excluir reservas con borrado lógico tras revisar la tabla.
Decisiones: cron frente a cola (cron; el volumen es de cuarenta al día y una cola es un segundo sistema que operar); envío por reserva frente a por lotes (por lotes, para quedar bajo el límite del proveedor); almacenamiento de la plantilla (página en Docs, no una tabla nueva).
Riesgos: envíos duplicados por solapamiento del cron (mitigación: marca de enviado escrita antes del envío); caída del proveedor (mitigación: reintento a la hora siguiente, sin alerta por debajo de una hora); errores de zona horaria (mitigación: almacenar y comparar en UTC, renderizar en la zona de la reserva).
El borrador del agente había añadido una cola Redis y un "servicio de notificaciones" para satisfacer una restricción de escalabilidad que había escrito él mismo. Ambos se recortaron, y el documento cabe en página y media.
Preguntas frecuentes
¿Qué debe incluir un documento de arquitectura?
Seis secciones: contexto, restricciones, componentes (tocados y no tocados), flujo de datos como secuencia numerada, una tabla de decisiones con opciones y razones, y cinco riesgos con mitigaciones. El objetivo son dos páginas y un diagrama.
¿Puede la IA escribir un documento de arquitectura de software?
Puede redactar contexto, componentes, flujo de datos y alternativas a partir de un PRD, y lo hace bien. No debería escribir restricciones ni tomar decisiones, porque inventa restricciones y escoge opciones de manual. Trátala como herramienta de borrador con una persona responsable de cada hecho y cada elección.
¿Cuál es la diferencia entre un documento de arquitectura y un ADR?
Un registro de decisión de arquitectura cubre una decisión: contexto, opciones, elección, consecuencias. El documento de arquitectura de una funcionalidad contiene varias decisiones en una tabla más los componentes y el flujo de datos a su alrededor. Los equipos pequeños suelen mantener la tabla en el documento y promover una fila a su propio ADR solo cuando afecta a más de una funcionalidad.
¿Cuánto debe ocupar un documento de arquitectura?
Dos páginas, leídas en diez minutos. Si es más largo, describe dos funcionalidades o ha absorbido el runbook. Saca el detalle operativo.
¿Debe incluir un diagrama el documento de arquitectura?
Sí, un diagrama de bloques de los componentes con flechas para el flujo principal de datos. Dibújalo a mano desde el flujo numerado; lleva diez minutos y el acto de dibujar encuentra flechas que faltan.
¿Cuándo debe escribirse el documento de arquitectura?
Después de congelar el PRD y antes de crear las incidencias, porque la sección de componentes determina cómo se divide el trabajo. Escribirlo cuando ya existen las incidencias lo convierte en una descripción de lo que se hizo, que es un documento distinto.
Siguiente paso
Toma tu funcionalidad actual, escribe a mano la sección de restricciones en cinco minutos y entrega el PRD y esas restricciones al agente que uses pidiéndole las otras cinco secciones. La plantilla de PRD da al agente los requisitos numerados que necesita, y en Atrix una ejecución Develop del agente de IA devuelve el documento de arquitectura como una página que puedes editar con el equipo.