Melhorar Arquitetura de Código

Quando Usar

Use quando este fluxo de trabalho corresponder à solicitação do usuário: Analise um codebase em busca de oportunidades de aprofundamento, apresente-as como um relatório HTML visual e, em seguida, analise qualquer uma que você escolher.

Fonte: mattpocock/skills (MIT).

Exponha o atrito arquitetônico e proponha oportunidades de aprofundamento — refatorações que transformam módulos rasos em profundos. O objetivo é a testabilidade e a navegabilidade por IA.

Este comando é informado pelo modelo de domínio do projeto e construído sobre um vocabulário de design compartilhado:

• Execute a habilidade /codebase-design para o vocabulário de arquitetura (módulo, interface, profundidade, costura, adaptador, alavancagem, localidade) e seus princípios (o teste de exclusão, "a interface é a superfície de teste", "um adaptador = costura hipotética, dois = real"). Use esses termos exatamente em cada sugestão — não se desvie para "componente", "serviço", "API" ou "limite".
• A linguagem de domínio em CONTEXT.md dá nomes a boas costuras; ADRs em docs/adr/ registram decisões que este comando não deve reabrir.

Processo

1. Explorar

Leia o glossário de domínio do projeto (CONTEXT.md) e quaisquer ADRs na área que você está abordando primeiro.

Em seguida, use a ferramenta Agente com subagent_type=Explore para percorrer o codebase. Não siga heurísticas rígidas — explore organicamente e observe onde você experimenta atrito:

• Onde a compreensão de um conceito exige saltar entre muitos módulos pequenos?
• Onde os módulos são rasos — a interface quase tão complexa quanto a implementação?
• Onde funções puras foram extraídas apenas para testabilidade, mas os bugs reais se escondem em como elas são chamadas (sem localidade)?
• Onde módulos acoplados de forma rígida vazam através de suas costuras?
• Quais partes do codebase não são testadas ou são difíceis de testar através de sua interface atual?

Aplique o teste de exclusão a qualquer coisa que você suspeite ser rasa: excluí-la concentraria a complexidade ou apenas a moveria? Um "sim, concentra" é o sinal que você deseja.

2. Apresentar candidatos como um relatório HTML

Escreva um arquivo HTML autônomo no diretório temporário do sistema operacional para que nada seja gravado no repositório. Resolva o diretório temporário de $TMPDIR, recorrendo a /tmp (ou %TEMP% no Windows) e escreva para <tmpdir>/architecture-review-<timestamp>.html para que cada execução obtenha um arquivo novo. Abra-o para o usuário — xdg-open <path> no Linux, open <path> no macOS, start <path> no Windows — e diga a ele o caminho absoluto.

O relatório usa Tailwind via CDN para layout e estilo, e Mermaid via CDN para diagramas onde um gráfico/fluxo/sequência comunica de forma confiável a estrutura. Misture Mermaid com CSS/SVG feitos à mão — use Mermaid quando as relações tiverem formato de gráfico (gráficos de chamada, dependências, sequências) e divs/SVG feitos à mão quando você quiser algo mais editorial (diagramas de massa, seções transversais, animações de colapso). Cada candidato recebe uma visualização antes/depois. Seja visual.

Para cada candidato, renderize um cartão com:

• Arquivos — quais arquivos/módulos estão envolvidos
• Problema — por que a arquitetura atual está causando atrito
• Solução — descrição em inglês simples do que mudaria
• Benefícios — explicados em termos de localidade e alavancagem, e como os testes melhorariam
• Diagrama Antes / Depois — lado a lado, desenhado personalizado, ilustrando a superficialidade e o aprofundamento
• Força da recomendação — um de Strong, Worth exploring, Speculative, renderizado como um selo

Termine o relatório com uma seção Recomendação Principal: qual candidato você abordaria primeiro e por quê.

Use o vocabulário CONTEXT.md para o domínio e o vocabulário /codebase-design para a arquitetura. Se CONTEXT.md define "Pedido", fale sobre "o módulo de entrada de Pedido" — não "o FooBarHandler", e não "o serviço de Pedido".

Conflitos de ADR: se um candidato contradisser um ADR existente, apresente-o apenas quando o atrito for real o suficiente para justificar a revisão do ADR. Marque-o claramente no cartão (por exemplo, um aviso: "contradiz o ADR-0007 — mas vale a pena reabrir porque…"). Não liste todos os refatores teóricos que um ADR proíbe.

Veja HTML-REPORT.md para o scaffold HTML completo, padrões de diagramas e orientação de estilo.

NÃO proponha interfaces ainda. Após a escrita do arquivo, pergunte ao usuário: "Quais destes você gostaria de explorar?"

3. Loop de Análise

…