Skill
Improve Codebase Architecture
Crédito: mattpocock no GitHub (mattpocock/skills) · 0 cópias
Indicada na UseIA por Cristiano Rochenbach Abreu em 5 de out. de 2026
277 mil estrelas no GitHubVer no GitHub
Tradução feita por IA. Em caso de dúvida, vale o texto original (aba “Original”).
---
name: improve-codebase-architecture
description: Varre uma base de código em busca de oportunidades de aprofundamento, apresenta-as em um relatório visual em HTML e depois faz uma sabatina sobre aquela que você escolher.
disable-model-invocation: true
---
# Improve Codebase Architecture
Evidencie atritos de arquitetura e proponha **oportunidades de aprofundamento**: refatorações que transformam módulos rasos em módulos profundos. O objetivo é a testabilidade e a facilidade de navegação por IA.
Este comando é _informado_ pelo modelo de domínio do projeto e construído sobre um vocabulário de design compartilhado:
- Chame a ferramenta Skill com "codebase-design" para obter o vocabulário de arquitetura (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) e seus princípios (o teste da exclusão, "a interface é a superfície de teste", "um adapter = costura hipotética, dois = costura real"). Use esses termos exatamente assim em cada sugestão e não derive para "componente", "serviço", "API" ou "fronteira".
- A linguagem de domínio em `GLOSSARY.md` dá nomes às boas costuras; os ADRs em `docs/adr/` registram decisões que este comando não deve rediscutir.
## Processo
### 1. Explore
**Delimite o escopo antes de varrer: YAGNI.** Aprofundar um módulo compensa porque facilita mudanças futuras nele, então dê peso extra às partes da base de código que mudaram recentemente. Decida *onde* olhar antes de olhar:
- Se o usuário indicou uma direção (um módulo, um subsistema, uma dor), siga-a e pule a inferência abaixo.
- Caso contrário, volte um bom trecho do histórico de commits (`git log --oneline`) para encontrar os pontos quentes da base de código, os arquivos e áreas que aparecem sempre, e deixe esses caminhos atraírem sua atenção primeiro. Se as mudanças estiverem espalhadas, sem um ponto quente claro, amplie a rede.
Leia primeiro o glossário de domínio do projeto (`GLOSSARY.md`) e quaisquer ADRs da área em que você vai mexer.
Depois, acione um subagente para percorrer a base de código. Não siga heurísticas rígidas; explore de forma orgânica e anote onde você sentir atrito:
- Onde entender um conceito exige pular entre muitos módulos pequenos?
- Onde os módulos são **rasos**, com uma interface quase tão complexa quanto a implementação?
- Onde funções puras foram extraídas apenas por testabilidade, mas os bugs reais se escondem na forma como elas são chamadas (sem **locality**)?
- Onde módulos fortemente acoplados vazam através de suas costuras?
- Quais partes da base de código não têm testes, ou são difíceis de testar pela interface atual?
Aplique o **teste da exclusão** a tudo o que você suspeitar que seja raso: excluir concentraria a complexidade ou apenas a moveria de lugar? Um "sim, concentra" é o sinal que você quer.
### 2. Apresente os candidatos em um relatório HTML
Escreva um arquivo HTML autocontido no diretório temporário do sistema, para que nada vá parar no repositório. Resolva o diretório temporário a partir de `$TMPDIR`, usando `/tmp` como alternativa (ou `%TEMP%` no Windows), e escreva em `<tmpdir>/architecture-review-<timestamp>.html`, para que cada execução gere um arquivo novo. Abra-o para o usuário (`xdg-open <path>` no Linux, `open <path>` no macOS, `start <path>` no Windows) e informe o caminho absoluto.
O relatório usa **Tailwind via CDN** para layout e estilo, e **Mermaid via CDN** para diagramas quando um grafo/fluxo/sequência comunica a estrutura de forma confiável. Misture o Mermaid com visuais feitos à mão em CSS/SVG: use o Mermaid quando as relações têm forma de grafo (grafos de chamadas, dependências, sequências) e divs/SVG feitos à mão quando quiser algo mais editorial (diagramas de massa, cortes 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 causa atrito
- **Solução**: descrição em linguagem simples do que mudaria
- **Benefícios**: explicados em termos de locality e leverage, e como os testes melhorariam
- **Diagrama antes / depois**: lado a lado, desenhado sob medida, ilustrando a rasidão e o aprofundamento
- **Força da recomendação**: uma entre `Strong`, `Worth exploring`, `Speculative`, exibida como um selo
Termine o relatório com uma seção de **Recomendação principal**: qual candidato você atacaria primeiro e por quê.
**Use o vocabulário do GLOSSARY.md para o domínio e o vocabulário do `/codebase-design` para a arquitetura.** Se o `GLOSSARY.md` define "Order", fale em "o módulo de entrada de Order" e não em "o FooBarHandler" nem em "o serviço de Order".
**Conflitos com ADRs**: se um candidato contradiz um ADR existente, só o apresente quando o atrito for real o bastante para justificar rever o ADR. Marque isso claramente no cartão (por exemplo, um destaque de alerta: _"contradiz o ADR-0007, mas vale reabrir porque…"_). Não liste toda refatoração teórica que um ADR proíbe.
Veja [HTML-REPORT.md](HTML-REPORT.md) para o esqueleto HTML completo, os padrões de diagrama e as orientações de estilo.
NÃO proponha interfaces ainda. Depois que o arquivo for escrito, pergunte ao usuário: "Qual destes você gostaria de explorar?"
### 3. Ciclo de sabatina
Quando o usuário escolher um candidato, chame a ferramenta Skill com "grilling" para percorrer com ele a árvore de decisão: restrições, dependências, o formato do módulo aprofundado, o que fica atrás da costura, quais testes sobrevivem.
Os efeitos colaterais acontecem na hora, à medida que as decisões se cristalizam; chame a ferramenta Skill com "domain-modeling" para manter o modelo de domínio atualizado ao longo do caminho:
- **Vai nomear um módulo aprofundado com um conceito que não está no `GLOSSARY.md`?** Adicione o termo ao `GLOSSARY.md`. Crie o arquivo sob demanda, se ele não existir.
- **Está afinando um termo vago durante a conversa?** Atualize o `GLOSSARY.md` ali mesmo.
- **O usuário rejeita o candidato com um motivo que sustenta a decisão?** Ofereça um ADR, formulado assim: _"Quer que eu registre isto como um ADR para que revisões de arquitetura futuras não sugiram de novo?"_ Ofereça apenas quando o motivo for realmente necessário para um futuro explorador evitar sugerir a mesma coisa; pule os motivos efêmeros ("não vale a pena agora") e os autoevidentes.
- **Quer explorar interfaces alternativas para o módulo aprofundado?** Chame a ferramenta Skill com "codebase-design" e use seu padrão de subagentes paralelos de design-it-twice.Funciona com:Claude

