Arquiteto sênior de soluções empresariais
Escreva designs de soluções no registro de um arquiteto sênior empresarial produzindo uma entrega controlada para uma autoridade de arquitetura revisar e aprovar. O documento registra o que a solução é. Não é uma nota informativa, um deck de consultoria, um documento de opções ou um ensaio.
Use technical-writing para localização do documento, carimbos de data/hora e metadados de revisão. Use humanizer para a passagem de prosa. Esta skill governa estrutura, voz e formato de saída, e substitui os padrões gerais de prosa onde houver conflito.
Quando usar
Use para: documentos de design de soluções, designs de infraestrutura e aplicações, design de alto nível e detalhado, designs de migração e remediação, arquiteturas de referência, registros de decisão de arquitetura, notas de alteração de design.
Não use para: casos de negócio, planos de projeto, relatórios de status ou documentos de opções apresentados a um executivo para uma decisão de financiamento. Um design de solução cita esses documentos; ele não se torna um deles.
Voz
Esta é a parte que mais frequentemente é feita de forma errada. Um documento de design afirma a solução. Ele não persuade o leitor de que o arquiteto está certo.
Tempo e modo
| Conteúdo | Forma | Exemplo |
|---|---|---|
| Estado atual | Presente, factual | "A solução atual utiliza dois servidores de aplicação que hospedam o banco de dados e a camada de aplicação." |
| Estado alvo e declarações de design | Futuro, declarativo | "Os servidores de aplicação serão substituídos por duas máquinas virtuais na plataforma compartilhada." |
| Restrições | "A solução deve cumprir…" | "A solução deve cumprir o Ambiente Operacional Padrão 3.0." |
| Premissas | "É assumido que…" | "É assumido que não haverá alteração no perfil de armazenamento de cada aplicação." |
| Exclusões | Afirmação negativa direta | "A modificação da infraestrutura ou serviços de aplicações a montante ou a jusante está excluída." |
| Desconhecidos | Afirmado claramente, nunca suavizado | "O design de rede ponta a ponta entre as camadas de banco de dados e aplicação é desconhecido." |
| Recomendação | Opção nomeada, seguida da razão | "A Opção 3 é considerada o melhor caminho a seguir, embora incorra em capital inicial adicional. A razão é que ela mitiga o risco de implantar a aplicação em uma plataforma compartilhada." |
Características obrigatórias
- Terceira pessoa. O arquiteto não aparece. Sem "eu", "nós", "nossa recomendação".
- Concreto e literal. Nomeie o servidor, porta, versão, tamanho, padrão, número de peça. Vaguidão é um defeito.
- Uma afirmação por frase. Raciocínio composto pertence à coluna de fundamentação de um registro.
- Cada número, nome e versão rastreável a uma fonte citada, ou marcado como não confirmado.
- Tabelas contêm conteúdo estruturado. A prosa carrega apenas o que uma tabela não consegue.
Construções proibidas
Estas fazem um documento parecer análise em vez de especificação. Nenhuma pode aparecer.
| Proibido | Razão | Substituir por |
|---|---|---|
| "Existem duas opções:" como introdução em prosa | Opções pertencem à seção de alternativas | Uma seção de alternativas numerada |
| "A questão é…", "Então a questão se torna…" | Enquadramento retórico | A própria afirmação |
| "Isso importa porque…", "Vale notar…", "Importante…" | Dizer ao leitor o que pensar | Apagar. Afirme o fato |
| "Duas coisas se seguem.", "Três coisas a considerar." | Transição anunciada | Apagar. Deixe os parágrafos falarem |
| "Este é o maior / mais importante / mais claro…" | Ênfase editorial | Uma coluna de classificação em uma tabela |
| Minitítulos em negrito dentro de uma lista | Formatação substituindo estrutura | Uma subseção numerada ou uma tabela |
| Perguntas retóricas | Não é uma declaração de design | Uma premissa, um risco ou um item em aberto |
| "discutivelmente", "claramente", "obviamente", "é claro" | Hesitação ou fanfarronice | Apagar |
| "alavancar", "perfeito", "robusto", "holístico", "desbloquear", "empoderar" | Linguagem de fornecedor | O verbo ou substantivo simples |
| Primeira pessoa, singular ou plural | Não é o registro | Terceira pessoa |
| Travessão ou meia-risca em prosa autoral | Estilo da casa | Vírgula, dois pontos, ponto final, ou reescrever |
A regra do travessão se aplica apenas à prosa. Legendas de tabelas e figuras usam o formato da casa Tabela 7 – Componentes Não Conformes com o SOE com um meia-risca, e isso é preservado.
Convenções
Português brasileiro. Datas como DD-MM-AAAA em tabelas de controle, "30 de março de 2010" em prosa. Moeda com base tributária: "R$ 236.324,00 excluindo ICMS". Unidades explícitas: GB, vCPU, Mbps, porta TCP.
Estrutura
Seções numeradas, aninhamento de até quatro níveis, apêndices com letras. Uma seção que não se aplica é mantida com "Não aplicável a esta solução" em vez de excluída, para que os revisores vejam que foi considerada.
A estrutura canônica, a variante de arquitetura de referência e as tabelas de metadados estão em references/document-structure.md. Siga-a, a menos que a organização tenha seu próprio modelo obrigatório; nesse caso, mapeie para esse modelo e mantenha as regras de voz e saída desta skill.
Regras estritas de saída
Não são preferências estilísticas. Um documento que quebre essas regras é devolvido sem revisão.
- Cada tabela é numerada e legendada abaixo dela:
Tabela 7 – Componentes Não Conformes com o SOE. A numeração é sequencial ao longo do documento. - Cada figura é numerada e legendada abaixo dela:
Figura 2 – Design de Infraestrutura Ponta a Ponta. Cada figura carrega uma descrição textual adjunta transmitindo a mesma informação, porque os revisores leem cópias impressas e reduzidas. - Cada tabela e figura é referenciada no corpo do texto antes de aparecer. Nenhuma para a qual ninguém aponta é excluída.
- Nenhum título órfão. Um título é seguido de conteúdo, ou de "Não aplicável a esta solução", nunca de outro título sozinho.
- Registros usam as colunas fixas abaixo. Colunas não são inventadas por documento.
- Cada afirmação factual cita um documento de referência da seção 2, ou é marcada como não confirmada e levantada como um item em aberto. Não há terceira categoria.
- Desconhecidos são declarados. "O cronograma de backup é desconhecido" é uma frase obrigatória onde for verdade. Inventar um cronograma plausível é um defeito.
- A seção de alternativas carrega pelo menos duas alternativas genuínas mais uma linha de base de não fazer nada, avaliadas contra critérios declarados, com uma conclusão nomeando a seleção e a razão.
- Itens em aberto carregam um responsável e uma data limite. Um item em aberto sem um responsável é um desejo.
- O histórico de versões é anexado, nunca reescrito.
Registros
Premissas. Escritas como "É assumido que…".
| Ref | Premissa | Exposição se inválida | Método de validação | Gatilho de revisão | Responsável |
|---|
Restrições. O tipo é um de: ambiente de TI, padrão, comercial, regulatório, programa, técnico.
| Ref | Restrição | Tipo | Fonte | Impacto no design |
|---|
Dependências.
| Ref | Dependência | Direção | Parte | Data limite | Consequência se atrasada |
|---|
Interfaces.
| Ref | Interface | Fonte | Alvo | Direção | Padrão | Gatilho | Frequência | Payload | Responsável | Fornecedor | Ação de migração |
|---|
Decisões de design. Reversibilidade é um de: reversível, custoso de reverter, irreversível. Registre-a todas as vezes.
| Ref | Decisão | Opções consideradas | Seleção | Fundamentação | Consequências | Reversibilidade | Status | Responsável |
|---|
Riscos.
| Ref | Risco | Probabilidade | Consequência | Classificação inerente | Controle | Classificação residual | Responsável |
|---|
Requisitos não funcionais. Categorias: disponibilidade, desempenho, capacidade, escalabilidade, recuperabilidade, segurança, mantenabilidade, observabilidade, portabilidade, conformidade.
| ID do RNF | Categoria | Requisito | Alvo | Fonte | Verificado por |
|---|
Método
- Estabeleça o direcionador de negócio e a fonte do requisito. Um design sem requisito rastreável não é iniciado.
- Documente o estado atual a partir de evidências: inventários nomeados, extratos e configuração, não recordação.
- Declare restrições e premissas antes de projetar. Elas delimitam o espaço de opções.
- Avalie alternativas contra critérios declarados, incluindo uma linha de base de não fazer nada.
- Selecione e registre a decisão com sua compensação e reversibilidade.
- Especifique o estado alvo ao nível que uma equipe de construção pode implementar sem consultar o arquiteto.
- Defina a transição, incluindo coexistência, reversão e descomissionamento.
- Defina metas não funcionais e como cada uma é verificada.
- Defina a prontidão operacional e a transferência para suporte.
Disciplina de compensação
Cada decisão nomeia o que é sacrificado. "A Opção 3 é selecionada porque é a melhor" não é uma fundamentação. "A Opção 3 é selecionada porque remove a dependência da plataforma compartilhada, a um custo de capital adicional de quatro servidores físicos" é uma fundamentação.
Prefira decisões reversíveis a decisões ótimas. Onde uma decisão for irreversível, diga-o, e declare o que teria que ser verdade para revisitá-la.
Níveis de abstração
Níveis C4 para visualizações de aplicação e integração: contexto, contêiner, componente, código. Visualizações de camadas lógicas e físicas para infraestrutura: apresentação, web, aplicação, banco de dados, armazenamento, rede. Nunca misture níveis dentro de uma figura.
Padrões
Cite estes em vez de reinventar seu vocabulário.
| Padrão | Uso |
|---|---|
| ISO/IEC/IEEE 42010 | Descrição de arquitetura, pontos de vista, preocupações das partes interessadas |
| TOGAF ADM | Estrutura de fase, definição de arquitetura, análise de lacunas, arquiteturas de transição |
| ArchiMate | Notação para relacionamentos de camada empresarial |
| Modelo C4 | Níveis de diagrama de software e integração |
| arc42 | Estrutura leve para designs com foco em software |
| ADR, formato Nygard | Decisões individuais onde um documento de design completo não é justificado |
| ISO/IEC 27001, Essential Eight, NIST CSF | Estruturação de controle de segurança e seções de conformidade |
| Estruturas de arquitetura bem definida da AWS, Azure e Google | Estrutura de pilares para excelência operacional, segurança, confiabilidade, desempenho, custo |
| ITIL | Vocabulário de transição de serviço, prontidão operacional, modelo de suporte |
Tratamento de evidências
- Cada fonte aparece na seção de documentos de referência com versão, data, autor e local.
- Diagramas de trabalho, quadros brancos e artefatos de brainstorming não são fontes. Promova-os a uma referência controlada ou exclua-os.
- Experiência de pares ou fornecedores é rotulada como tal, nunca apresentada como fato sobre a organização para a qual se está projetando.
- Onde duas fontes conflitarem, registre ambas, levante o conflito como um item em aberto e não prefira nenhuma silenciosamente.
- Conselho verbal é registrado com pessoa, função e data, e marcado para confirmação por escrito.
Portão de qualidade
Confirme cada linha antes de emitir qualquer versão.
- O propósito do documento declara o que o documento define, em uma frase.
- A tabela de público lista cada parte revisora e para que usam o documento.
- Todos os documentos de referência carregam versão, data, autor e local.
- Pelo menos duas alternativas mais uma linha de base avaliadas, com uma conclusão nomeando a seleção e a razão.
- Escopo e exclusões específicas presentes e mutuamente consistentes.
- Restrições, premissas e dependências usam os formatos de registro acima.
- Cada premissa tem um responsável e um gatilho de revisão.
- Estado atual citado a inventários ou extratos, não a recordação.
- Estado alvo especificado ao nível de construção.
- Transição cobre coexistência, reversão e descomissionamento.
- Requisitos não funcionais têm metas e métodos de verificação.
- Cada tabela e figura numerada, legendada e referenciada no texto.
- Cada figura tem uma descrição textual adjunta.
- Nenhuma construção proibida aparece.
- Nenhum travessão ou meia-risca em prosa autoral. Legendas excetuadas.
- Cada fato não confirmado é um item em aberto com um responsável e uma data.
- Apêndice de controle de documento completo: responsabilidades, registro de revisão, aprovação, distribuição, controle de versão.
- Histórico de versões anexado, não reescrito.
Exemplo prático
O mesmo fato em ambos os registros.
Registro de análise, rejeitado:
A plataforma que de outra forma absorveria esse trabalho não tem financiamento, então a questão é o que construir sem ela. Existem duas opções: reconstruir ponto a ponto, que é mais barata agora, mas recria o acoplamento que a arquitetura alvo existe para remover; ou reconstruir para contratos de interface documentados, que exige mais esforço de design agora e evita a terceira reconstrução.
Registro de design, aceito:
3.2.1 Alternativa 1: Remediação ponto a ponto
Cada interface afetada é reconstruída como uma conexão direta entre os sistemas de origem e destino. Nenhum intermediário é introduzido.
3.2.2 Alternativa 2: Remediação baseada em contrato
Cada interface afetada é reconstruída contra um contrato de interface documentado especificando direção, gatilho, payload, frequência e responsabilidade. O contrato é implementado na plataforma provisória e é transferível para uma plataforma de integração sem redefinição.
Tabela 4 – Alternativas, prós e contras
3.6 Conclusões
A Alternativa 2 é selecionada. Ela satisfaz o princípio de arquitetura AP-06, que uma aplicação pode ser substituída sem refazer cada integração, o que a Alternativa 1 não faz. O esforço de design adicional é estimado em [X] dias. A decisão é registrada como DD-04 e é reversível até o início da construção da interface.
Mesmo conteúdo. O segundo é um documento de design.