Help us improve
Share bugs, ideas, or general feedback.
From leandrocfe-skills
Analyzes codebase architecture to find refactoring opportunities, consolidate tightly-coupled modules, and improve testability and AI-navigability using domain language and ADRs.
npx claudepluginhub leandrocfe/skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/leandrocfe-skills:improve-codebase-architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Traga à tona fricção arquitetural e proponha **deepening opportunities** — refactors que transformam shallow modules em deep modules. O alvo é testability e AI-navigability.
Finds deepening opportunities in a codebase by analyzing domain language and ADRs, suggesting refactors to consolidate tightly-coupled modules and improve testability.
Identifies shallow modules and architectural friction in a codebase, using domain language from CONTEXT.md and ADR decisions, to propose refactoring opportunities for testability and AI-navigability.
Analyzes codebase architecture, identifies shallow modules, and proposes deepening refactors to improve testability and AI-navigability using precise vocabulary (Module, Interface, Depth, Seam, Adapter).
Share bugs, ideas, or general feedback.
Traga à tona fricção arquitetural e proponha deepening opportunities — refactors que transformam shallow modules em deep modules. O alvo é testability e AI-navigability.
Use estes termos exatamente em cada sugestão. Linguagem consistente é o ponto — não derive para "component", "service", "API" ou "boundary". Definições completas em LANGUAGE.md.
Princípios-chave (veja LANGUAGE.md para a lista completa):
Esta skill é informada pelo domain model do projeto. A linguagem de domínio dá nomes a bons seams; ADRs registram decisões que a skill não deve re-litigar.
Leia o glossário de domínio do projeto e quaisquer ADRs na área que está tocando primeiro.
Depois use a ferramenta Agent com subagent_type=Explore para caminhar pela codebase. Não siga heurísticas rígidas — explore organicamente e anote onde você experimenta fricção:
Aplique o deletion test a qualquer coisa que você suspeita ser shallow: deletar concentraria complexidade ou só moveria? Um "sim, concentra" é o sinal que você quer.
Escreva um arquivo HTML self-contained no diretório temp do OS para que nada caia no repo. Resolva o temp dir a partir de $TMPDIR, com fallback para /tmp (ou %TEMP% no Windows), e escreva em <tmpdir>/architecture-review-<timestamp>.html para que cada execução tenha um arquivo novo. Abra para o usuário — xdg-open <path> no Linux, open <path> no macOS, start <path> no Windows — e informe o path absoluto.
O relatório usa Tailwind via CDN para layout e estilo, e Mermaid via CDN para diagramas onde um graph/flow/sequence comunica a estrutura de forma confiável. Misture Mermaid com visuais CSS/SVG artesanais — use Mermaid quando as relações têm forma de grafo (call graphs, dependências, sequences), e divs/SVG manuais quando quiser algo mais editorial (mass diagrams, cross-sections, collapse animations). Cada candidato ganha uma visualização before/after. Seja visual.
Para cada candidato, o mesmo template de antes, mas renderizado como card:
Strong, Worth exploring, Speculative, renderizado como badgeEncerre o relatório com uma seção Top recommendation: qual candidato você atacaria primeiro e por quê.
Use vocabulário do CONTEXT.md para o domínio, e vocabulário do LANGUAGE.md para arquitetura. Se CONTEXT.md define "Order", fale sobre "o módulo de Order intake" — não sobre "o FooBarHandler", e não "o Order service".
Conflitos com ADR: se um candidato contradiz um ADR existente, só traga à tona quando a fricção for real o suficiente para justificar revisitar o ADR. Marque claramente no card (ex.: callout em amber: "contradiz ADR-0007 — mas vale reabrir porque…"). Não liste todo refactor teórico que um ADR proíbe.
Veja HTML-REPORT.md para o scaffold HTML completo, padrões de diagrama e guia de estilo.
NÃO proponha interfaces ainda. Após escrever o arquivo, pergunte ao usuário: "Qual destes você quer explorar?"
Quando o usuário escolher um candidato, entre numa conversa de sabatina. Caminhe pela design tree com ele — constraints, dependências, o shape do módulo aprofundado, o que fica atrás do seam, que testes sobrevivem.
Efeitos colaterais acontecem inline conforme as decisões cristalizam:
CONTEXT.md? Adicione o termo ao CONTEXT.md — mesma disciplina do /grill-with-docs (veja CONTEXT-FORMAT.md). Crie o arquivo com preguiça se não existir.CONTEXT.md ali mesmo.