engenharia-de-arquitetura-de-software

Habilidade de codificação. Projete, implemente, refatore e revise software preservando continuamente a integridade arquitetural. Use para codificação assistida por IA, mudanças em repositórios, desenvolvimento de funcionalidades, mudanças em API/banco de dados, fronteiras de módulos, design de sistemas, migrações, escolhas de implantação, escalabilidade, confiabilidade e revisões de arquitetura. Analise a arquitetura existente antes de alterar o código; escolha trade-offs ponderados pelo contexto; verifique restrições arquiteturais após as alterações. Mantenha-se leve para edições isoladas de baixo risco.

O que é engenharia-de-arquitetura-de-software?

Esta habilidade de agente de IA garante que a integridade arquitetural seja preservada durante todo o processo de desenvolvimento de software, especialmente quando as alterações são feitas por agentes de IA. Ela se baseia nos princípios de 'Fundamentos de Arquitetura de Software' (Richards e Ford, 2025) e os estende com fluxos de trabalho contínuos para agentes. Não é uma ordem para redesenhar cada projeto, mas sim um conjunto operacional de leis e um loop de codificação que todo agente deve seguir: descobrir o sistema atual, avaliar o impacto antes de editar, preservar fronteiras, planejar incrementos seguros, implementar sem desvio arquitetural, verificar a arquitetura (não apenas a função) e registrar decisões importantes. A habilidade categoriza o esforço em três modos (Leve, Padrão, Profundo) com base no impacto da alteração, permitindo que o agente escolha o nível adequado de análise e documentação. Ela fornece salvaguardas não negociáveis contra fatos não verificáveis, falsos universais, acoplamento oculto e 'teatro de processo', e inclui referências e modelos para dar suporte a decisões arquiteturais, governança e verificação, independentemente de linguagem de programação, plataforma ou modelo de IA.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/iAmSerathion/Skills/tree/HEAD/software-architecture-engineering

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. Tudo é um trade-off. Avalie custos e benefícios, ponderados pelo contexto real; reavalie quando as condições mudarem.
  2. 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.
  3. 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

ModoGatilho típicoAção e saída esperada
LeveBug isolado, formatação, implementação local sem efeito de contrato/fronteiraInspecione 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ãoFuncionalidade entre módulos, nova integração, alteração de API/esquema, refatoração consequenteEstabeleça o contexto do projeto; inspecione dependências; compare opções realistas; implemente em incrementos; verifique fronteiras e contratos; registre decisões significativas.
ProfundoNova plataforma, divisão de serviço, migração importante, alteração de alto risco em dados/segurança/confiabilidade, revisão de arquiteturaAná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):

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.

Habilidades Relacionadas