2

Pitch: Criei o Shishō, um sensei de linha de comando que revisa seu código e diz se a arquitetura é exagero. Quero levar para outras stacks.

Faz um tempo que eu reparo em duas coisas que me incomodam.

A primeira: quem está aprendendo recebe 300 warnings do linter e nenhuma explicação. O linter diz o que está errado, mas não diz por que importa, quanto custa e quando a regra não vale.

Ichigo, de Bleach, tomando suco de caixinha com cara de tédio

Você lendo 300 warnings sem nenhuma explicação.

A segunda: tem muito tutorial ensinando arquitetura hexagonal ou Clean Architecture para um CRUD de três campos, e nenhuma ferramenta pergunta se aquela arquitetura cabe no projeto.

Então eu fiz o Shishō (師匠, "mestre" em japonês): uma CLI open source que lê o seu projeto como um sensei lê o trabalho de um aluno. Aponta o erro, explica o porquê, mostra o antes/depois, diz se a arquitetura é exagero (ou se ficou pequena demais) e no fim te dá uma faixa, do 6º kyū ao 1º dan.

Comecei por Java 21+ / Spring Boot, que é a stack que eu conheço a fundo. Mas o motivo deste post é outro: quero que exista um Shishō para PHP, Python, JavaScript, Ruby, Go, C#... e não tenho como fazer isso sozinho. Explico no fim.

Repositório: https://github.com/mauricioandrade/shisho


Como ele é na prática

Gravação do terminal: shisho analyze aponta quatro lições, shisho fix --apply corrige três e a nova análise dá 1º dan

Um projeto com quatro lições: o Shishō aponta cada uma e explica o porquê, o fix --apply corrige três sozinho e a graduação sobe de 2º kyū para 1º dan.

Num projeto maior, a saída fica assim:

$ shisho analyze ./clareza-api

師匠 Shishō — análise de clareza-api  (Java 21)
Arquitetura: Camadas técnicas (Layered)  (83% da assinatura)

✗ GRAVE  [field-injection]  UsuarioController.java:14
         usuarioService é injetado direto no campo. Assim, new cria a classe sem a
         dependência, o erro só aparece como NullPointerException em uso e o teste
         precisa de Spring ou reflexão. Receba a dependência pelo construtor.

Veredito: subengenharia. O projeto já não cabe na arquitetura Layered:
  · PedidoService tem 31 métodos e 9 dependências no construtor.
Próximo passo natural: package-by-feature.

Graduação: 3º kyū  (8 lições: 1 grave, 4 médias, 3 leves)

O que ele faz

  • Katas: 17 regras de boas práticas (injeção em campo, @RequestBody sem @Valid, entidade JPA exposta no controller, DTO que não é record, System.out, dependência abandonada como Log4j 1...). Cada violação vira uma lição, em português ou em inglês.
  • Classificação de arquitetura: reconhece layered, package-by-feature, monolito modular, hexagonal, clean, onion, CQRS, event-driven e microsserviços, e confere as regras de dependência de cada uma.
  • Veredito de overengineering ou subengenharia: cruza o código com o contexto que você declara (time pequeno? MVP? domínio complexo?) e responde com fatos medidos, não com opinião.
  • --sensei: para cada kata, o porquê, quando o código acusado é uma escolha razoável, o antes/depois e as fontes (docs do Spring, JEPs, OWASP).
  • shisho fix: corrige sozinho o que é mecânico e seguro, mexendo só nas linhas da correção.
  • --shoshin: dá nome aos conceitos que já estão no seu código (record, transação, Repository, Strategy...) e explica cada um. Bom para quem está começando.
  • shisho crud: gera um CRUD na arquitetura do projeto, explicando o papel de cada arquivo.
  • Plugin para o Claude Code: confere cada arquivo que o Claude edita e devolve as lições para ele enquanto escreve.
  • HTML e SARIF: relatório para abrir no navegador ou para ver os alertas direto no PR via GitHub Actions.

E se você pedir um CRUD hexagonal para um projeto que não precisa, ele pergunta antes:

Gintoki, de Gintama, segurando uma caixinha de leite de morango com cara de descrença

Hexagonal. Para um CRUD de dois campos. Sério?


As decisões que guiam o projeto

  • Determinístico primeiro. Toda lição, classificação e veredito sai de código reprodutível. Mesma entrada, mesma saída, e por isso dá para rodar em CI.
  • O LLM explica, não julga. Tem um shisho ask opcional que usa um modelo local via Ollama. Ele recebe os fatos e o veredito prontos e só escreve a explicação. Modelo pequeno escreve bem quando recebe fatos e alucina quando precisa deduzi-los, então ele nunca decide nada. Vem desligado, e o seu código não sai da máquina.
  • O conhecimento vive em Markdown. Arquiteturas, guias das katas, conceitos, dependências abandonadas e templates de CRUD ficam em catalog/, em Markdown com frontmatter YAML. Ensinar uma arquitetura nova ao Shishō é escrever um .md.
  • Dogfooding. O Shishō passa nas próprias katas. Se uma kata nova acusa o próprio código, ou eu corrijo o código ou questiono a kata.
  • Simplicidade. A ferramenta que aponta overengineering não pode ser um. É uma CLI em Java 25 com picocli, JavaParser e SnakeYAML, sem Spring e sem Lombok.

Cada decisão grande virou um ADR em docs/adr/, com uma seção explicando o conceito para quem está aprendendo. São 11 até agora, do parser escolhido até o motivo de eu ter desistido do template de Clean Architecture no gerador de CRUD.


O convite: um Shishō para a sua linguagem

Naruto fazendo o selo de mão do Kage Bunshin no Jutsu

Um dev sozinho não cobre todas as linguagens. Precisamos de clones.

A ideia do Shishō não é Java. É ter um mestre que ensina o porquê e pergunta se a arquitetura cabe no problema. Isso faz o mesmo sentido em qualquer stack, e cada uma tem os seus "@Autowired em campo", aquele erro que todo mundo comete e que o linter aponta sem explicar. Só para puxar a conversa:

  • PHP / Laravel: regra de negócio inteira no controller, model do Eloquent devolvido direto na API, validação esquecida no request.
  • Python / Django / FastAPI: print no lugar de logging, except: engolindo tudo, model do ORM exposto como resposta da API.
  • JavaScript / TypeScript / Node / NestJS: console.log em produção, any espalhado, promise sem await nem tratamento de erro.
  • Ruby / Rails: controller gordo, callbacks do ActiveRecord escondendo regra de negócio, N+1 nas views.

Você que manja dessas stacks sabe listar coisa muito melhor que essa. É exatamente isso que eu quero.

E metade do caminho já não depende de Java:

  • O catálogo de arquiteturas descreve layered, hexagonal, clean etc. por padrões de pasta, regras de dependência e sinais de overengineering. Um projeto Laravel em camadas ou um NestJS hexagonal cabem no mesmo catálogo.
  • O domínio (kata, lição, graduação, veredito) não tem nenhum termo de Java ou Spring. O parser entra por uma porta própria, e o que é específico do Spring fica nas katas.

Eu não construí um "sistema de plugins de linguagem" de propósito. Prefiro desenhar isso com quem vai usar do que inventar uma abstração no escuro. Então dá para colaborar de dois jeitos:

  1. Trazer a sua linguagem para dentro do Shishō. Abra uma issue com o nome da stack e as primeiras 3 ou 4 katas que você colocaria, cada uma com o porquê. A partir daí a gente decide junto como parsear (o ast do Python? o compilador do TypeScript? tree-sitter?) e como o projeto se organiza (módulos e package.json/composer.json/pyproject.toml em vez de classes e pom.xml).
  2. Criar o Shishō da sua linguagem, na sua linguagem. Se fizer mais sentido escrever um Shishō para PHP em PHP ou para Python em Python, vai fundo: os princípios estão nos ADRs, e o catálogo de arquiteturas é Markdown, então pode ser compartilhado. Me chama que eu linko no README e a gente mantém o mesmo espírito (e as mesmas faixas).

E se você não quer escrever código nenhum, também dá para ajudar: uma arquitetura que faltou, um sinal de overengineering, uma explicação mais clara, uma tradução... tudo isso é um PR em Markdown no catalog/.


Para testar

Você só precisa do Java 25. O instalador baixa o jar da última release, confere o checksum e pergunta o idioma:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/mauricioandrade/shisho/main/install.sh)"
shisho analyze --sensei ./seu-projeto

Roda num projeto Spring Boot seu e me conta a graduação que tirou. Se o veredito estiver errado, quero saber mais ainda: lição injusta, explicação confusa ou arquitetura mal classificada, tudo isso vira issue e melhora o catálogo.

Jiraiya, de Naruto, partindo um picolé ao meio e oferecendo metade ao Naruto

Zero lições graves. O mestre divide o picolé.

https://github.com/mauricioandrade/shisho

Carregando publicação patrocinada...