Engenharia de Arquitetura de Software
Propósito
Manter a arquitetura coerente enquanto o software está sendo alterado, incluindo alterações escritas por agentes de IA. Esta é uma habilidade operacional, não uma ordem para redesenhar todo projeto. Seus princípios reutilizáveis vêm de Fundamentos de Arquitetura de Software, 2ª ed. (Richards e Ford, 2025); fluxos de trabalho contínuos de agentes e artefatos são extensões originais. Nenhum modelo, linguagem de programação, hospedeiro de repositório, ferramenta de CI ou framework específico é necessário.
Aplique três leis em todo momento:
- Tudo é um trade-off. Avalie custos e benefícios, ponderados pelo contexto real; reavalie quando as condições mudarem.
- O porquê importa mais do que o como. Preserve a justificativa, opções rejeitadas, riscos e donos das decisões, não apenas diagramas e código.
- As decisões estão em um espectro. Rejeite falsos binários, regras gerais de microsserviços e modismo arquitetural.
Escolha o esforço pelo impacto
| Modo | Gatilho típico | Ação e saída esperada |
|---|---|---|
| Leve | Bug isolado, formatação, implementação local sem efeito de contrato/fronteira | Inspecione o código e as restrições relevantes; faça a alteração mínima; execute verificações relevantes; reporte apenas problemas materiais. Nenhum ADR obrigatório. |
| Padrão | Funcionalidade entre módulos, nova integração, alteração de API/esquema, refatoração consequente | Estabeleça o contexto do projeto; inspecione dependências; compare opções realistas; implemente em incrementos; verifique fronteiras e contratos; registre decisões significativas. |
| Profundo | Nova plataforma, divisão de serviço, migração importante, alteração de alto risco em dados/segurança/confiabilidade, revisão de arquitetura | Análise completa de contexto e arquitetura, alternativas, modos explícitos de falha/dados, migração e rollback, funções de adequação mensuráveis, ADR(s), risco e limites de aprovação. |
Escale quando uma edição supostamente pequena cruzar fronteiras de propriedade, alterar contratos públicos, modificar persistência, introduzir novos componentes de runtime/implantação, ampliar o impacto de falha ou revelar desvio arquitetural. Desescalone se a investigação mostrar que não há impacto arquitetural significativo. Instruções do usuário/projeto/segurança têm precedência. Nunca force relatórios pesados para tarefas triviais.
Loop obrigatório para agentes de codificação
Para trabalho em um repositório existente, execute este loop. Consulte governança de implementação de agentes para procedimentos precisos, tratamento de falhas e regras de agentes paralelos.
0. Descubra o sistema atual — não o invente
- Inspecione código relevante, testes, arquivos de pacote/build, infraestrutura, configuração, documentação, ADRs, layout de diretório e caminhos reais de dependência quando acessíveis.
- Localize qualquer contrato de arquitetura do projeto, por exemplo
docs/architecture/CONTRACT.md, e ADRs aceitos; trate-os como restrições do projeto, não verdades imutáveis. - Registre observado / fornecido / assumido / desconhecido separadamente. Se não houver acesso a código/ferramentas, diga que o resultado é uma proposta, não uma análise verificada do repositório.
- Não substitua silenciosamente a arquitetura já em uso por um estilo favorito.
1. Avalie o impacto antes de editar
- Defina o escopo da mudança, capacidades de negócio afetadas, módulos proprietários, APIs/contratos, responsabilidades de dados, dependências, fronteiras de segurança, unidades de implantação e caminhos de falha.
- Classifique a tarefa como Leve / Padrão / Profundo e escolha a menor revisão adequada.
- Para decisões materiais, derive algumas características arquiteturais priorizadas (ex.: segurança, latência, disponibilidade, escalabilidade, elasticidade, manutenibilidade, testabilidade, implantabilidade, recuperabilidade, custo) com escopo, alvo e medição. Separe requisitos explícitos de implícitos e não confirmados.
- Escolha padrões mínimos e reversíveis para incógnitas de baixo risco; não prossiga com suposições de alto risco não suportadas como se fossem confirmadas.
2. Preserve fronteiras e compare alternativas quando justificado
- Favoreça alta coesão e baixo acoplamento. Mantenha a responsabilidade de negócio, direção da dependência, acoplamento temporal e propriedade de dados explícitos. Distinga módulos lógicos de serviços implantados independentemente.
- Verifique implicações para a arquitetura operacional e de dados, não apenas a estrutura de diretórios. Um banco de dados compartilhado, fronteira de transação ou chamada síncrona pode desfazer a modularidade aparente.
- Para mudanças consequentes, compare pelo menos duas opções viáveis usando trade-offs ponderados pelo contexto. Candidatos podem incluir camadas, monólito modular, pipeline, microkernel, baseado em serviços, orientado a eventos, baseado em espaço, SOA orquestrada, microsserviços ou híbridos. Nenhum estilo arquitetural é o padrão universal.
- Projetos distribuídos devem abordar falha/latência de rede, disponibilidade, consistência, fronteiras de transação, retentativas, idempotência, observabilidade, segurança e custo operacional conforme aplicável.
- Nomeie condições que reverteriam a decisão. Use estilos, design distribuído e fundamentos seletivamente.
3. Planeje a implementação em incrementos seguros
- Identifique mudanças esperadas em arquivos/módulos, contratos que devem permanecer estáveis, ordem de migração e estratégia de rollback quando necessário.
- Declare invariantes arquiteturais (regras que devem permanecer verdadeiras): direção permitida de dependência, propriedade de API interna, autoridade de escrita de dados, fronteiras de locação/autenticação, compatibilidade reversa, tratamento de erros, etc.
- Escolha verificações objetivas para esses invariantes antes de implementar. Onde útil, copie/adapte contrato de arquitetura do projeto e modelo de impacto de mudança; não crie arquivos de projeto sem permissão ou escopo claro de tarefa.
- Solicite ou adie decisões irreversíveis/de alto impacto que exigem autoridade humana/de negócio. Não falsifique aprovações.
4. Implemente sem desvio arquitetural
- Faça a menor mudança coerente consistente com a arquitetura atual. Não divida serviços, introduza brokers, abstrações globais ou novos frameworks sem necessidade demonstrada.
- Mantenha interfaces e propriedade de dados explícitas. Não crie atalhos através de internos de outro módulo, ignore autenticação/validação, altere silenciosamente esquemas de eventos ou misture mudanças não relacionadas.
- Se a implementação revelar uma falha material no plano, pare e reavalie a decisão afetada em vez de ocultá-la com código de contorno. Atualize ADR/contrato apenas quando justificado.
- Em trabalho multiagente, defina propriedade de componente/arquivo, contratos estáveis e um proprietário de integração. Mudanças paralelas não sobrepõem restrições arquiteturais compartilhadas.
5. Verifique a arquitetura, não apenas a função
- Execute testes existentes de unidade/integração/contrato e verificações de build quando disponíveis e autorizados.
- Verifique funções de adequação específicas da arquitetura: dependências proibidas, ciclos, propriedade de módulo, compatibilidade de API, migração de esquema, idempotência, orçamentos de desempenho, observabilidade, resiliência, segurança, implantação/rollback, conforme aplicável.
- Compare a estrutura de dependências antes/depois e invariantes afetados. Um verificador de fronteiras de importação opcional da stdlib com configuração de exemplo pode reforçar regras de importação selecionadas em Python/JS/TS; é intencionalmente limitado e não prova correção arquitetural completa.
- Rotule evidências como APROVADO / REPROVADO / NÃO EXECUTADO / NÃO APLICÁVEL. Não afirme que testes, escalabilidade, prontidão para produção, segurança ou implantações foram verificados sem execução/evidência real.
- Se alguma verificação obrigatória falhar, corrija/reverta, ou identifique explicitamente o problema não resolvido e o dono da decisão. Nunca apresente uma verificação reprovada como trabalho concluído.
6. Registre e comunique decisões consequentes
- Crie ou atualize um ADR conciso apenas para mudanças com significado arquitetural: título, status, contexto, solução escolhida, porquê, alternativas, trade-offs, consequências, aplicação e gatilho de revisão. Use modelo de ADR.
- Preserve decisões históricas quando substituídas. Trate diagramas como auxílios de comunicação, não evidência de implementação ou validação.
- No relatório final, declare: o que mudou; impacto arquitetural; verificações aprovadas, reprovadas ou não executadas; riscos pendentes; e qualquer decisão humana necessária. Para mudanças Leves, um parágrafo conciso geralmente é suficiente.
Tarefas apenas de design e auditoria
Quando não estiver editando um repositório, aplique os passos 0–3 e 6 proporcionalmente; produza um design, análise de trade-off, resumo arquitetural ou revisão sem fingir que algo foi implementado ou testado. Para uma auditoria completa de arquitetura, inventarie componentes, propriedade de dados, fronteiras, implantação e restrições de equipe/infraestrutura; classifique riscos concretos com evidências; proponha remediações incrementais e funções de adequação antes de recomendar reescritas completas.
Salvaguardas não negociáveis
- Sem fatos não verificáveis: Nenhuma inspeção inventada de repositório, saída de teste, níveis de carga, status de conformidade, custos, aprovações de stakeholders ou medições.
- Sem universais falsos: Nem microsserviços, nem monólitos, nem sistemas orientados a eventos são intrinsecamente melhores. Não divida serviços por tabela/entidade sozinha.
- Sem confusão de escopo: Módulos lógicos, unidades implantadas, propriedade de dados e escopo de característica arquitetural são conceitos diferentes.
- Sem acoplamento oculto: Examine esquemas compartilhados, bibliotecas compartilhadas, acoplamento temporal, chamadas entre serviços e contratos de eventos; reutilizar lógica de domínio volátil pode aumentar o acoplamento.
- Sem apagamento de risco: Consistência distribuída, tratamento de transações, mudanças de esquema, recuperação de falhas e rollback exigem pensamento explícito quando relevantes.
- Sem teatro de processo: Uma lista de verificação ou autoavaliação concluída não é prova. Priorize verificações reais e evidências de código.
- Sem mudanças arquiteturais silenciosas: Sinalize desvios importantes, documente razões e mantenha a responsabilidade com o dono humano/do projeto da decisão.
- Sem distribuição de livro com direitos autorais: Esta habilidade é uma síntese original. Não copie o livro ou seus diagramas para repositórios downstream.
Arquivos de referência sob demanda
Leia apenas os arquivos necessários para a tarefa (caminhos relativos a este diretório de habilidade):
- Codificação IA e governança contínua de arquitetura — necessário para edições substanciais em repositórios, revisões de PR, agentes paralelos e diagnóstico de desvio arquitetural.
- Fundamentos e características arquiteturais — requisitos, acoplamento, coesão, componentes, escopo de característica.
- Estilos arquiteturais — nove estilos e condições de seleção.
- Sistemas distribuídos e padrões — realidade de rede, eventos, transações, consistência, orquestração, CQRS.
- Decisões, funções de adequação e riscos — ADRs, governança, risk storming, diagramas.
- Pessoas, dados, infraestrutura e IA — equipes e restrições operacionais.
- Mapa de fontes — todos os 27 capítulos do livro e distinção entre ideias do livro e extensões específicas de agente.
- Rubrica de verificação — critérios de qualidade para grandes decisões de design e revisão de implementação.
Artefatos: resumo arquitetural, contrato de arquitetura, impacto de mudança, ADR, matriz de trade-off, registro de risco, revisão de arquitetura, exemplo de política de fronteira. Cenário trabalhado: Codificação IA sem desvio de fronteira. Outras instruções de modelo/runtime são opcionais; consulte portabilidade.