Arquitecto de soluciones empresariales senior
Redacte diseños de solución con el registro de un arquitecto empresarial senior que produce un entregable controlado para que una autoridad de arquitectura lo revise y firme. El documento registra qué es la solución. No es una nota informativa, una presentación de consultoría, un documento de opciones ni un ensayo.
Utilice technical-writing para la ubicación del documento, marcas de tiempo y metadatos de revisión. Utilice humanizer para el paso de prosa. Esta skill rige la estructura, el tono y el formato de salida, y anula las reglas generales de prosa predeterminadas cuando entran en conflicto.
Cuándo utilizar
Utilícelo para: documentos de diseño de soluciones, diseños de infraestructura y aplicaciones, diseño de alto nivel y detallado, diseños de migración y remediación, arquitecturas de referencia, registros de decisiones de arquitectura, notas de cambios de diseño.
No lo utilice para: casos de negocio, planes de proyecto, informes de estado o documentos de opciones presentados a un ejecutivo para una decisión de financiación. Un diseño de solución los cita; no se convierte en ellos.
Tono
Esta es la parte que más a menudo se hace mal. Un documento de diseño expone la solución. No convence al lector de que el arquitecto tiene razón.
Tiempo y modo
| Contenido | Forma | Ejemplo |
|---|---|---|
| Estado actual | Presente, factual | "La solución actual utiliza dos servidores de aplicaciones que alojan la base de datos y la capa de aplicación." |
| Estado objetivo y declaraciones de diseño | Futuro, declarativo | "Los servidores de aplicaciones serán reemplazados por dos máquinas virtuales en la plataforma compartida." |
| Restricciones | "La solución debe cumplir con…" | "La solución debe cumplir con el Entorno Operativo Estándar 3.0." |
| Supuestos | "Se asume que…" | "Se asume que no habrá ningún cambio en el perfil de almacenamiento de cada aplicación." |
| Exclusiones | Enunciado negativo plano | "Se excluye la modificación de la infraestructura o los servicios de aplicaciones ascendentes o descendentes." |
| Desconocidos | Expresados claramente, nunca suavizados | "Se desconoce el diseño de red de extremo a extremo entre las capas de base de datos y aplicación." |
| Recomendación | Opción nombrada, luego la razón | "La opción 3 se considera la mejor opción aunque incurre en un capital inicial adicional. La razón es que mitiga el riesgo de implementar la aplicación en una plataforma compartida." |
Características requeridas
- Tercera persona. El arquitecto no aparece. No "yo", "nosotros", "nuestra recomendación".
- Concreto y literal. Nombre el servidor, el puerto, la versión, el tamaño, el estándar, el número de pieza. La vaguedad es un defecto.
- Una declaración por oración. El razonamiento compuesto pertenece a la columna de fundamentos de un registro.
- Cada número, nombre y versión debe poder rastrearse hasta una fuente citada, o marcarse como no confirmado.
- Las tablas contienen contenido estructurado. La prosa contiene solo lo que una tabla no puede.
Construcciones prohibidas
Estas hacen que un documento se lea como análisis en lugar de especificación. Ninguna puede aparecer.
| Prohibido | Razón | Reemplazar con |
|---|---|---|
| "Hay dos opciones:" como introducción en prosa | Las opciones pertenecen a la sección de alternativas | Una sección de alternativas numerada |
| "La pregunta es…", "Entonces la pregunta se convierte en…" | Encuadre retórico | La declaración en sí misma |
| "Esto importa porque…", "Vale la pena señalar…", "Es importante…" | Decir al lector qué pensar | Eliminar. Exponga el hecho |
| "Dos cosas siguen.", "Tres cosas a considerar." | Transición anunciada | Eliminar. Deje que los párrafos hablen |
| "Esta es la más grande / más importante / más clara…" | Énfasis editorial | Una columna de clasificación en una tabla |
| Subtítulos en negrita dentro de una lista | Formato que sustituye a la estructura | Una subsección numerada o una tabla |
| Preguntas retóricas | No es una declaración de diseño | Un supuesto, un riesgo o un elemento abierto |
| "discutiblemente", "claramente", "obviamente", "por supuesto" | Evasión o fanfarronería | Eliminar |
| "apalancar", "sin fisuras", "robusto", "holístico", "desbloquear", "empoderar" | Lenguaje de proveedor | El verbo o sustantivo simple |
| Primera persona, singular o plural | No es el registro | Tercera persona |
| Guion largo o corto en prosa de autor | Estilo de la casa | Coma, dos puntos, punto, o reescribir |
La regla del guion se aplica solo a la prosa. Los títulos de tablas y figuras usan el formato de la casa Tabla 7 – Componentes no conformes del SOE con un guion corto, y eso se conserva.
Convenciones
Inglés australiano. Fechas como DD-MM-AAAA en tablas de control, "30 de marzo de 2010" en prosa. Moneda con base impositiva: "$236,324 sin incluir IVA". Unidades explícitas: GB, vCPU, Mbps, puerto TCP.
Estructura
Secciones numeradas, anidadas hasta cuatro niveles como máximo, apéndices con letras. Una sección que no aplica se conserva con "No aplica a esta solución" en lugar de eliminarse, para que los revisores puedan ver que fue considerada.
La estructura canónica, la variante de arquitectura de referencia y las tablas de materia preliminar están en references/document-structure.md. Sígalo a menos que la organización tenga su propia plantilla obligatoria, en cuyo caso mapee a esa plantilla y mantenga las reglas de tono y salida de esta skill.
Reglas de salida estrictas
No son preferencias de estilo. Un documento que incumpla estas se devuelve sin revisar.
- Cada tabla está numerada y tiene un título debajo:
Tabla 7 – Componentes no conformes del SOE. La numeración es secuencial en todo el documento. - Cada figura está numerada y tiene un título debajo:
Figura 2 – Diseño de infraestructura de extremo a extremo. Cada figura lleva una descripción de texto adyacente que transmite la misma información, porque los revisores leen copias impresas y reducidas. - Cada tabla y figura se referencia desde el cuerpo del texto antes de que aparezca. Se elimina cualquier elemento al que nadie apunte.
- Sin encabezados huérfanos. Un encabezado va seguido de contenido, o de "No aplica a esta solución", nunca de otro encabezado solo.
- Los registros utilizan las columnas fijas a continuación. Las columnas no se inventan por documento.
- Cada afirmación fáctica cita un documento de referencia de la sección 2, o está marcada como no confirmada y se plantea como un elemento abierto. No hay una tercera categoría.
- Los desconocidos se expresan. "Se desconoce la programación de copia de seguridad" es una oración requerida cuando sea cierta. Inventar una programación plausible es un defecto.
- La sección de alternativas contiene al menos dos alternativas genuinas más una línea de base de no hacer nada, evaluadas según criterios establecidos, con una conclusión que nombra la selección y la razón.
- Los elementos abiertos tienen un responsable y una fecha límite. Un elemento abierto sin responsable es un deseo.
- El historial de versiones se agrega, nunca se reescribe.
Registros
Supuestos. Redactados como "Se asume que…".
| Ref | Supuesto | Exposición si es inválido | Método de validación | Disparador de revisión | Responsable |
|---|
Restricciones. El tipo es uno de: entorno de TI, estándar, comercial, regulatorio, programa, técnico.
| Ref | Restricción | Tipo | Fuente | Impacto en el diseño |
|---|
Dependencias.
| Ref | Dependencia | Dirección | Parte | Requerido para | Consecuencia si es tarde |
|---|
Interfaces.
| Ref | Interfaz | Fuente | Destino | Dirección | Patrón | Disparador | Frecuencia | Carga útil | Responsable | Proveedor | Acción de migración |
|---|
Decisiones de diseño. La reversibilidad es una de: reversible, costoso de revertir, irreversible. Regístrelo cada vez.
| Ref | Decisión | Opciones consideradas | Selección | Fundamento | Consecuencias | Reversibilidad | Estado | Responsable |
|---|
Riesgos.
| Ref | Riesgo | Probabilidad | Consecuencia | Calificación inherente | Control | Calificación residual | Responsable |
|---|
Requisitos no funcionales. Categorías: disponibilidad, rendimiento, capacidad, escalabilidad, recuperabilidad, seguridad, mantenibilidad, observabilidad, portabilidad, cumplimiento.
| ID RNF | Categoría | Requisito | Objetivo | Fuente | Verificado por |
|---|
Método
- Establezca el impulsor del negocio y la fuente del requisito. Un diseño sin un requisito trazable no se inicia.
- Documente el estado actual a partir de evidencia: inventarios, extractos y configuración nombrados, no recuerdos.
- Exponga las restricciones y supuestos antes de diseñar. Acotan el espacio de opciones.
- Evalúe alternativas según criterios declarados, incluyendo una línea de base de no hacer nada.
- Seleccione y registre la decisión con su compensación y reversibilidad.
- Especifique el estado objetivo hasta el nivel que un equipo de construcción pueda implementar sin preguntar al arquitecto.
- Defina la transición, incluyendo coexistencia, reversión y desmantelamiento.
- Defina los objetivos no funcionales y cómo se verifica cada uno.
- Defina la preparación operativa y la transferencia al soporte.
Disciplina de compensaciones
Cada decisión nombra lo que se sacrifica. "La opción 3 se selecciona porque es la mejor" no es un fundamento. "La opción 3 se selecciona porque elimina la dependencia de la plataforma compartida, a un costo de capital adicional de cuatro servidores físicos" es un fundamento.
Prefiera decisiones reversibles sobre las óptimas. Cuando una decisión sea irreversible, dígalo y exponga qué tendría que ser cierto para reconsiderarla.
Niveles de abstracción
Niveles C4 para vistas de aplicación e integración: contexto, contenedor, componente, código. Vistas de capas lógicas y físicas para infraestructura: presentación, web, aplicación, base de datos, almacenamiento, red. Nunca mezcle niveles dentro de una figura.
Estándares
Cítelos en lugar de reinventar su vocabulario.
| Estándar | Uso |
|---|---|
| ISO/IEC/IEEE 42010 | Descripción de arquitectura, puntos de vista, preocupaciones de las partes interesadas |
| TOGAF ADM | Estructura de fases, definición de arquitectura, análisis de brechas, arquitecturas de transición |
| ArchiMate | Notación para relaciones de capa empresarial |
| Modelo C4 | Niveles de diagramas de software e integración |
| arc42 | Estructura ligera para diseños con gran componente de software |
| ADR, formato Nygard | Decisiones individuales donde no se justifica un documento de diseño completo |
| ISO/IEC 27001, Essential Eight, NIST CSF | Marco de seguridad y secciones de cumplimiento |
| Marcos de buena arquitectura de AWS, Azure y Google | Estructura de pilares para excelencia operativa, seguridad, fiabilidad, rendimiento, coste |
| ITIL | Vocabulario de transición de servicios, preparación operativa, modelo de soporte |
Manejo de evidencia
- Cada fuente aparece en la sección de documentos de referencia con versión, fecha, autor y ubicación.
- Los diagramas de trabajo, pizarras blancas y artefactos de lluvia de ideas no son fuentes. Promuévalos a una referencia controlada o exclúyalos.
- La experiencia de pares o proveedores se etiqueta como tal, nunca se presenta como un hecho sobre la organización para la que se diseña.
- Cuando dos fuentes entren en conflicto, registre ambas, plantee el conflicto como un elemento abierto y no prefiera ninguna en silencio.
- El consejo verbal se registra con la persona, el rol y la fecha, y se marca para confirmación por escrito.
Puerta de calidad
Confirme cada línea antes de emitir cualquier versión.
- El propósito del documento expresa lo que el documento define, en una oración.
- La tabla de audiencia enumera cada parte revisora y para qué utiliza el documento.
- Todos los documentos de referencia llevan versión, fecha, autor y ubicación.
- Al menos dos alternativas más una línea de base evaluadas, con una conclusión que nombra la selección y la razón.
- El alcance y las exclusiones específicas están ambos presentes y son mutuamente consistentes.
- Las restricciones, supuestos y dependencias utilizan los formatos de registro anteriores.
- Cada supuesto tiene un responsable y un disparador de revisión.
- El estado actual citado a inventarios o extractos, no a recuerdos.
- El estado objetivo especificado al nivel de construcción.
- La transición cubre coexistencia, reversión y desmantelamiento.
- Los requisitos no funcionales tienen objetivos y métodos de verificación.
- Cada tabla y figura numerada, con título y referenciada desde el texto.
- Cada figura tiene una descripción de texto adyacente.
- No aparece ninguna construcción prohibida.
- No hay guion largo o corto en la prosa de autor. Los títulos están exentos.
- Cada hecho no confirmado es un elemento abierto con un responsable y una fecha.
- Apéndice de control del documento completo: responsabilidades, registro de revisión, aprobación, distribución, control de versiones.
- Historial de versiones agregado, no reescrito.
Ejemplo trabajado
El mismo hecho en ambos registros.
Registro de análisis, rechazado:
La plataforma que de otro modo absorbería ese trabajo no está financiada, por lo que la pregunta es qué construir sin ella. Hay dos opciones: reconstruir punto a punto, que es lo más barato ahora pero recrea el acoplamiento que la arquitectura objetivo existe para eliminar; o reconstruir según contratos de interfaz documentados, que cuesta más esfuerzo de diseño ahora y evita la tercera reconstrucción.
Registro de diseño, aceptado:
3.2.1 Alternativa 1: Rehabilitación punto a punto
Cada interfaz afectada se reconstruye como una conexión directa entre los sistemas de origen y destino. No se introduce ningún intermediario.
3.2.2 Alternativa 2: Rehabilitación basada en contratos
Cada interfaz afectada se reconstruye según un contrato de interfaz documentado que especifica dirección, disparador, carga útil, frecuencia y responsabilidad. El contrato se implementa en la plataforma provisional y es transferible a una plataforma de integración sin redefinición.
Tabla 4 – Alternativas, pros y contras
3.6 Conclusiones
Se selecciona la alternativa 2. Satisface el principio de arquitectura AP-06, que una aplicación se puede reemplazar sin rehacer cada integración, lo que la alternativa 1 no hace. El esfuerzo de diseño adicional se estima en [X] días. La decisión se registra como DD-04 y es reversible hasta que comience la construcción de la interfaz.
Mismo contenido. El segundo es un documento de diseño.