Documentar una decisión de arquitectura

1. Define la entrega

Para quién: Consultores de tecnología y responsables de proyecto que necesitan dejar una decisión comprensible para negocio y desarrollo.

Tarea: Preparar un ADR, un registro de decisión de arquitectura, para una propuesta aún pendiente de aprobación.

Consulta la ficha, el acceso y los requisitos del recurso antes de elegir el entorno. El archivo gratuito no incluye un motor de IA; el servicio elegido puede tener cuotas o coste.

2. Prepara la entrada ficticia

CASO FICTICIO — portal interno de informes.
Contexto: equipo de dos personas; debe trabajar sobre una única versión de cada informe. Se conserva la aplicación existente.
Propuesta: guardar los informes en la base de datos actual, para reutilizar su control de acceso.
Alternativas: carpeta compartida; servicio documental separado.
Motivos propuestos para descartarlas: la carpeta exigiría conciliar permisos con la aplicación; el servicio separado añadiría una integración.
Participantes: responsable de operaciones y responsable técnico (roles ficticios).
Faltan volumen, presupuesto y mediciones de rendimiento. No se aporta repositorio ni inventario de ADR.

En un caso real, utiliza solo materiales que puedas compartir con el asistente elegido y retira datos confidenciales o personales innecesarios.

3. Prepara el Markdown y el entorno

1. Descarga el paquete desde la ficha y localiza source/adr-generator.agent.md. Léelo antes de facilitar documentación de un proyecto.
2. El perfil está destinado a un entorno que interprete .agent.md, como VS Code con GitHub Copilot; su carga nativa no está probada aquí. Un asistente que acepte texto puede usar el Markdown como referencia para un borrador.
3. Para guardar un ADR real, el entorno necesita acceso autorizado al repositorio y a docs/adr. Primero comprueba numeración y convenciones existentes. En este ejercicio pide solo texto; no deduzcas un número si no has visto los archivos.

4. Pide un borrador en español

Usa el caso ficticio para un borrador de ADR en español. Estado: Proposed. Conserva contexto, propuesta con motivos, alternativas y participantes. Incluye consecuencias positivas y negativas como hipótesis y preguntas sobre volumen, presupuesto y rendimiento. No inventes métricas, aprobaciones, fecha de aprobación ni número secuencial. Señala que el número se asignará al consultar docs/adr. No escribas archivos. Si falta una entrada obligatoria, pregúntala antes de cerrar el documento.

El botón copia la solicitud y la entrada completa del paso 2. Conserva la respuesta íntegra si haces un intento propio.

5. Revisa antes de usar el resultado

• El estado debe ser Proposed; ninguna alternativa queda rechazada por una autoridad real.
• Mantén las dos alternativas y sus motivos como parte del caso. No añadas comparaciones de coste o rendimiento sin datos.
• Una consecuencia posible es reutilizar permisos; un riesgo posible es aumentar carga o acoplamiento. Ambos necesitan validación, no son resultados observados.
• El ADR debe conservar los roles y las incógnitas. Antes de guardarlo, revisa numeración, nombre, fecha y referencias contra el repositorio real.

Si falla un criterio, conserva la diferencia y corrige el borrador. Si falta evidencia, déjala pendiente; superar este ejercicio no demuestra eficacia general.

Límites y procedencia

Documentar una decisión no valida la arquitectura. El original pide estructura y escritura en docs/adr; este ejercicio prepara un borrador sin acceso a repositorios. El coste y la disponibilidad de Copilot, modelos y herramientas dependen del entorno; no se ha probado aquí una ruta integral gratuita.

Fuente: ADR Generator, de github / awesome-copilot. Revisión consultada: 613efc8c21d9b3ce642dff361d17006cd9967e28. Licencia original: MIT.

Las funciones y requisitos descritos proceden de ese original; el caso, la solicitud y los criterios son aportación editorial de peopleofthe.ai. Consulta la metodología y la distinción entre documentación, ejemplo y ensayo.

Volver a la ficha del recurso · Elegir otro recorrido para consultorías