Communitygithub.com

renatoxm/leanagentkit

Uma alternativa mais enxuta ao GitHub Spec Kit

O que é leanagentkit?

Este skill fornece um framework de Arquitetura Limpa (Clean Architecture) para estruturar software de forma disciplinada, garantindo que as regras de negócio permaneçam independentes de frameworks, bancos de dados e mecanismos de entrega. Ele é útil para desenvolvedores que desejam projetar sistemas testáveis, resilientes e de fácil manutenção, onde decisões sobre tecnologia podem ser adiadas e implementações podem ser trocadas sem impactar a lógica central do negócio. O skill é baseado nos princípios de Clean Architecture de Robert C. Martin e cobre desde a Regra de Dependência (Dependency Rule) e círculos concêntricos, até Entidades, Casos de Uso, Adaptadores de Interface, Componentes e os princípios SOLID. Ele também fornece um diagnóstico rápido (Quick Diagnostic) de 7 perguntas para avaliar a adesão à arquitetura, com pontuação de 0 a 10. O skill está disponível para ser usado em assistentes de codificação como Claude Code, Cursor e Codex, e inclui referências a arquivos detalhados para aprofundamento em cada tópico.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add renatoxm/leanagentkit

Perguntar na sua IA favorita

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

Documentação

Framework de Arquitetura Limpa

Uma abordagem disciplinada para estruturar software de modo que as regras de negócio permaneçam independentes de frameworks, bancos de dados e mecanismos de entrega. Aplique estes princípios ao projetar arquitetura de sistema, revisar limites de módulos ou aconselhar sobre gerenciamento de dependências.

Princípio Central

As dependências do código-fonte devem apontar para dentro — em direção às políticas de mais alto nível. Nada em um círculo interno pode saber sobre qualquer coisa de um círculo externo. Esta única regra produz sistemas que são testáveis e independentes de frameworks, UI, banco de dados e qualquer agência externa. As regras de negócio são o que importa; bancos de dados, frameworks web e mecanismos de entrega são detalhes — quando os detalhes dependem das políticas, você pode adiar decisões, trocar implementações e testar a lógica de negócio de forma isolada.

Pontuação

Meta: 10/10. Atribua um ponto para cada uma das sete linhas do Diagnóstico Rápido que a arquitetura satisfizer (0-7) e, em seguida, mapeie para uma faixa de 0 a 10: 6-7 satisfeitos = 9-10 (a Regra de Dependência é mantida, a lógica de negócio é independente de framework e banco de dados); 4-5 = 6-8 (o núcleo é testável, mas alguns detalhes vazam para dentro); 2-3 = 3-5 (o framework ou a persistência ditam a estrutura); 0-1 = 0-2 (sem limites — as regras de negócio vivem em controladores e modelos ORM). Relate a pontuação, as linhas do diagnóstico que falharam e a inversão específica necessária para corrigir cada uma.

1. Regra de Dependência e Círculos Concêntricos

Conceito central: Organize a arquitetura como círculos concêntricos — Entidades (regras de negócio corporativas) no centro, depois Casos de Uso (regras de negócio da aplicação), depois Adaptadores de Interface, com Frameworks e Drivers na camada mais externa. As dependências do código-fonte sempre apontam para dentro.

Por que funciona: Quando as políticas de alto nível não dependem de detalhes de baixo nível, você pode trocar o banco de dados, o framework web ou o estilo de API sem tocar na lógica de negócio — o sistema se torna resiliente às partes mais voláteis da pilha.

Insights principais:

  • Círculos internos não podem mencionar nomes de círculos externos — sem classes, funções, variáveis ou formatos de dados de fora
  • Os dados que cruzam um limite devem estar na forma mais conveniente para o círculo interno, nunca ditada pelo externo
  • A Inversão de Dependência (interfaces definidas internamente, implementadas externamente) é o mecanismo que impõe a regra
  • O número de círculos não é fixo — quatro é típico; a regra permanece a mesma
  • Frameworks são detalhes, não arquitetura — eles pertencem ao círculo mais externo

Aplicações de código:

ContextoPadrãoExemplo
Direção da camadaCírculos internos definem interfaces; externos implementamInterface UserRepository nos Casos de Uso; PostgresUserRepository nos Adaptadores
Cruzamento de dadosDTOs cruzam limites, não entidades ORMCaso de Uso retorna DTO UserResponse, não um modelo ActiveRecord
Direção da dependênciaSetas de importação sempre apontam para dentroController importa Caso de Uso; Caso de Uso nunca importa Controller

Veja references/dependency-rule.md quando uma importação do círculo interno apontar para fora e você precisar da explicação detalhada dos quatro círculos, das regras de cruzamento de dados e do procedimento de inversão de dependência em quatro etapas para corrigi-la.

2. Entidades e Casos de Uso

Conceito central: Entidades encapsulam regras de negócio de toda a empresa — regras que existiriam mesmo sem software. Casos de Uso contêm regras específicas da aplicação que orquestram o fluxo de dados de e para as Entidades.

Por que funciona: Separar o que o negócio faz (Entidades) de como a aplicação orquestra (Casos de Uso) permite reutilizar Entidades entre aplicações e alterar o comportamento da aplicação sem modificar as regras centrais de negócio.

Insights principais:

  • Entidades não são linhas de banco de dados — são objetos ou funções puras que encapsulam regras de negócio críticas
  • Casos de Uso aceitam Modelos de Requisição e retornam Modelos de Resposta — nunca objetos de framework
  • Cada Caso de Uso é uma única operação da aplicação (CriarPedido, AprovarDespesa)
  • O padrão Interactor: uma classe de Caso de Uso implementa uma interface de limite de entrada e chama uma interface de limite de saída
  • Mudanças em um Caso de Uso nunca devem afetar uma Entidade; alterações em Entidades podem se propagar para Casos de Uso

Aplicações de código:

ContextoPadrãoExemplo
Design de EntidadeRegras de negócio críticas, zero dependências de frameworkPedido.calcularTotal() aplica regras de imposto; não sabe nada sobre HTTP
Requisição/RespostaEstruturas de dados simples cruzam o limiteCriarPedidoRequest { itens, clienteId } — sem modelos ORM
Responsabilidade únicaUm Caso de Uso por operaçãoColocarPedido, CancelarPedido, ReembolsarPedido como classes separadas
InteractorImplementa Porta de Entrada, chama Porta de SaídaColocarPedidoInteractor implements ColocarPedidoInput

Veja references/entities-use-cases.md ao projetar um Interactor ou decidir o que pertence a uma Entidade versus um Caso de Uso — tratamento completo de Regras de Negócio Corporativas vs. de Aplicação com exemplos de modelos de requisição/resposta.

3. Adaptadores de Interface e Frameworks

Conceito central: Adaptadores de Interface convertem dados entre a forma conveniente para Casos de Uso/Entidades e a forma exigida por agências externas. Frameworks e Drivers são a camada mais externa — código de cola para o mundo exterior.

Por que funciona: Quando o framework web, ORM ou fila de mensagens está confinado aos círculos externos, substituir qualquer um deles é uma mudança localizada. O banco de dados é um detalhe; a web é um detalhe; detalhes devem ser plugins para suas regras de negócio, não o esqueleto da aplicação.

Insights principais:

  • Controladores traduzem HTTP em entrada de Caso de Uso; Apresentadores traduzem saída de Caso de Uso em modelos de visão
  • Gateways implementam interfaces de repositório definidas pelos Casos de Uso — o círculo interno define o contrato, o externo o cumpre
  • Regras de negócio nunca sabem se os dados vivem em SQL, NoSQL ou arquivos planos, ou que a entrega é HTTP
  • Trate frameworks com desconfiança — eles querem que você se acople a eles; mantenha-os à distância

Aplicações de código:

ContextoPadrãoExemplo
ControladorMecanismo de entrega → entrada de Caso de UsoPedidoController.criar(req) constrói CriarPedidoRequest, chama Interactor
ApresentadorSaída de Caso de Uso → modelo de visãoPedidoApresentador.apresentar(resposta) formata para JSON/HTML
GatewayInterface de repositório implementada por DBSqlPedidoRepository implements PedidoRepository
Limite do frameworkFramework chama para dentro, nunca o contrárioManipulador de rota do Express chama Controller; Controller nunca importa Express

Veja references/adapters-frameworks.md ao conectar controladores, apresentadores ou gateways, ou ao argumentar que o banco de dados/web é um detalhe — cobre arquitetura de plugins e como confinar um framework às bordas.

4. Princípios de Componentes

Conceito central: Componentes são as unidades de implantação. Três princípios de coesão governam o que vai dentro de um componente; três princípios de acoplamento governam as relações entre componentes.

Por que funciona: Componentes mal compostos criam efeitos cascata onde uma mudança força a reimplantação de código não relacionado; os princípios mantêm as mudanças localizadas e os lançamentos independentes.

Insights principais:

  • REP (Equivalência de Reúso/Lançamento): classes em um componente devem ser versionáveis e lançáveis como uma unidade
  • CCP (Fechamento Comum): classes que mudam pela mesma razão ao mesmo tempo pertencem juntas — SRP para componentes
  • CRP (Reúso Comum): não force os usuários a depender de classes que não usam
  • ADP (Dependências Acíclicas): o grafo de componentes não deve ter ciclos — quebre-os com DIP ou um novo componente
  • SDP (Dependências Estáveis): dependa na direção da estabilidade
  • SAP (Abstrações Estáveis): componentes estáveis devem ser abstratos; instáveis, concretos

Aplicações de código:

ContextoPadrãoExemplo
Agrupamento de componentesAgrupe classes que mudam juntas (CCP)Todos os Casos de Uso relacionados a pedidos em um componente
Quebra de ciclosAplique DIP para inverter uma aresta de dependênciaExtraia uma interface para um novo componente para quebrar o ciclo
Métricas de estabilidadeInstabilidade I = Ce / (Ca + Ce)Muitas dependências de entrada, nenhuma de saída → I próximo de 0 (estável)

Veja references/component-principles.md ao agrupar classes em componentes implantáveis ou quebrar um ciclo de dependência — cada um de REP, CCP, CRP, ADP, SDP, SAP trabalhados com a métrica de instabilidade.

5. Princípios SOLID

Conceito central: Cinco princípios em nível de classe e módulo — Responsabilidade Única, Aberto-Fechado, Substituição de Liskov, Segregação de Interface, Inversão de Dependência — os blocos de construção de nível médio que tornam a Regra de Dependência possível.

Por que funciona: Cada princípio aborda uma maneira específica pela qual as dependências dão errado, prevenindo a rigidez, fragilidade e imobilidade que transformam bases de código em pesadelos legados.

Insights principais:

  • SRP: um módulo tem uma razão para mudar — ele serve a um ator (não "faz uma coisa")
  • OCP: estenda o comportamento adicionando novo código, não modificando o existente — padrões de estratégia e plugin
  • LSP: subtipos devem ser utilizáveis através da interface base sem que o cliente saiba — violado por exceções inesperadas ou métodos ignorados
  • ISP: clientes não devem depender de métodos que não usam — interfaces gordas criam acoplamento desnecessário
  • DIP: módulos de alto nível e módulos de baixo nível dependem de abstrações definidas pelo módulo de alto nível

Aplicações de código:

ContextoPadrãoExemplo
Violação de SRPClasse serve a múltiplos atoresFuncionario lida com pagamento (CFO), relatórios (COO), persistência (CTO)
OCP via estratégiaNovo comportamento através de novas classesAdicione EntregaExpressa implementando EstrategiaEntrega; Pedido inalterado
Violação de LSPSubtipo altera comportamento esperadoQuadrado extends Retangulo quebra o contrato de setLargura()/setAltura()
Aplicação de ISPDivida interfaces gordas em interfaces de papelImpressora, Scanner, Fax em vez de um DispositivoMultiFuncao
Conexão com DIPAlto nível define interface; baixo nível implementaServicoPedido depende de GatewayPagamento, não de ClienteStripe

Veja references/solid-principles.md ao aplicar SRP/OCP/LSP/ISP/DIP a uma classe específica ou diagnosticar uma violação — cada princípio trabalhado com exemplos de código e o cheiro que ele previne.

6. Limites e Anatomia de Limites

Conceito central: Um limite é uma linha entre coisas que importam e coisas que são detalhes, implementado através de polimorfismo: dependências cruzam apontando para dentro, enquanto o fluxo de controle pode cruzar em qualquer direção.

Por que funciona: Cada limite compra a opção de adiar uma decisão ou trocar uma implementação; o posicionamento estratégico de limites determina se um sistema é uma alegria ou uma dor de manter ao longo dos anos.

Insights principais:

  • Limites completos usam interfaces recíprocas em ambos os lados; limites parciais usam uma estratégia ou fachada mais simples
  • Padrão Objeto Humilde: divida o código do limite em uma parte difícil de testar (próxima ao limite) e uma parte fácil de testar (a lógica)
  • Serviços não são automaticamente limites arquiteturais — um microsserviço com um modelo de dados compartilhado gordo é um monólito com chamadas de rede
  • Testes são o componente mais isolado: eles dependem para dentro, nada depende deles
  • Limites prematuros são caros, mas limites ausentes também — desenhe-os em pontos de provável volatilidade

Aplicações de código:

ContextoPadrãoExemplo
Limite completo vs. parcialPortas recíprocas, ou uma única estratégiaCaso de Uso define ColocarPedidoInput/ColocarPedidoOutput; casos mais simples usam uma EstrategiaEntrega
Objeto HumildeSepare a lógica testável da infraestruturaLogicaApresentador (testável) produz ModeloVisao; Visao (humilde) renderiza
Main como pluginRaiz de composição monta o sistemamain() conecta todas as implementações concretas e inicia a aplicação

Veja references/boundaries.md ao decidir onde desenhar um limite, escolher entre completo vs. parcial ou aplicar o padrão Objeto Humilde — também cobre serviços como limites, limites de teste e Main como o plugin definitivo.

Erros Comuns

ErroPor que FalhaCorreção
ORM vazando para a lógica de negócioEntidades acopladas ao esquema; mudanças no BD reescrevem regras de negócioSepare entidades de domínio de modelos de persistência; mapeie na camada de adaptador
Regras de negócio em controladoresNão testável sem HTTP; duplicado entre endpointsMova a lógica para Interactors de Caso de Uso; controladores apenas traduzem e delegam
Arquitetura orientada a frameworkFramework dita a estrutura; trocá-lo significa reescreverTrate o framework como um plugin; estruture o código por capacidade de negócio
Dependências circulares entre componentesMudanças se propagam imprevisivelmente; sem lançamentos independentesAplique DIP ou extraia um componente de abstração compartilhada
Um Caso de Uso gigante por funcionalidadeOrquestradores inchados de milhares de linhasDivida em Casos de Uso focados de operação única
Pular limites "porque é simples"Acoplamento se acumula silenciosamente até que o custo seja enormeDesenhe limites proativamente em pontos de provável volatilidade
Microsserviços como arquitetura boa automáticaUm monólito distribuído é pior que um monólito limpoAplique a Regra de Dependência dentro e entre serviços; serviços são limites de implantação, não arquiteturais

Diagnóstico Rápido

PerguntaSe NãoAção
Você pode testar regras de negócio sem BD, servidor web ou framework?Regras acopladas à infraestruturaExtraia entidades e casos de uso por trás de interfaces; simule camadas externas
Todas as dependências de código-fonte apontam para dentro?Dependências invertidas observadasAplique DIP: defina interface no círculo interno, implemente no externo
Nenhum modelo de framework/BD aparece em Entidades ou Casos de Uso?Detalhes vazaram para dentroSubstitua por tipos definidos internamente; mapeie no adaptador
Os Casos de Uso são focados em uma única operação cada?Casos de Uso fazem muitas coisasDivida em classes separadas de operação única
Os controladores traduzem HTTP para entrada de Caso de Uso (não contêm lógica)?Controladores contêm lógica de negócioMova a lógica para Interactors de Caso de Uso
O grafo de componentes não tem ciclos?Ciclos no grafo de dependênciaExtraia uma abstração compartilhada ou aplique DIP para quebrar o ciclo
A alteração de um detalhe (BD, framework web) não força mudanças nas regras de negócio?Detalhes vazam através dos limitesConfirme que todos os detalhes estão atrás de interfaces definidas pelo interior

Habilidades Relacionadas