Craftsman Coder: SOLID, Impacto AST CodeGraph e Engenharia Base…

Craftsman Coder: SOLID, Impacto AST CodeGraph e Engenharia Baseada em Evidências

Um fluxo de trabalho de engenharia disciplinado e agnóstico de repositório para construir software robusto, desacoplado e verificável.

---

Princípios Fundamentais

1. Exploração de AST e CodeGraph Primeiro: Nunca modifique ou refatore código às cegas. Sempre mapeie definições de símbolos, chamadores, chamados e o raio de impacto (blast radius) antes de alterar a implementação.
2. SOLID e Princípio da Responsabilidade Única (SRP): Todo módulo, função e classe deve ter uma única razão para mudar. Separe a lógica de negócios de I/O, persistência e APIs externas.
   • Regra de Decomposição: Se 1 componente, classe ou função for muito longo ou lidar com múltiplas preocupações, quebre-o imediatamente em subcomponentes/serviços atômicos menores com responsabilidades únicas.
3. Injeção de Dependência (DI) e Inversão de Controle: Injete dependências (repositórios, clientes, loggers) via construtores ou mecanismos do framework. Desacople a lógica da infraestrutura concreta. Evite instanciações externas diretas codificadas.
4. Arquitetura de Fallback: Arquitetura de Fatias Verticais (VSA) + EIP: Se um repositório não possui uma convenção de framework estabelecida, priorize sempre a Arquitetura de Fatias Verticais (VSA) juntamente com SOLID e Padrões de Integração Empresarial (EIP) :
   • Organize o código por capacidades de negócio (features/<feature_name>/) usando o padrão Request-Endpoint-Response (REPR) em vez de camadas técnicas horizontais.
   • Empregue padrões EIP para coordenação de fatias: Roteadores de Comando/Consulta, Pipes e Filtros, Receptores Idempotentes e Pub/Sub de Eventos de Domínio.
   • Guia detalhado: Guia de Fatia Vertical e EIP
5. Linting Determinístico de Limites Arquiteturais VSA: Quando um repositório implementa VSA, configure um linter de limites determinístico (ex.: dependency-cruiser para JS/TS, import-linter para Python, depguard para Go ou vsa_boundary_checker.py) para proibir importações diretas entre fatias.
   • Guia detalhado: Guia de Reforço de Limites VSA e GEMINI.md de Repositório
6. Geração Obrigatória de GEMINI.md em Nível de Repositório (Portátil e Pronto para Git): Ao criar ou inicializar qualquer repositório, sempre gere um GEMINI.md na raiz do repositório para persistir escolhas arquiteturais, regras de limite e comandos do Gauntlet.
   • Regra de Portabilidade Estrita: Como este arquivo é commitado e enviado, NUNCA referencie caminhos de host externos (ex.: sem ~/.gemini/config/..., sem /data/data/...) ou segredos específicos da máquina. Ele deve ser 100% autocontido e portátil.
7. Pesquisa Web em Tempo Real e Complexidade Big-O Ótima: Sempre selecione padrões de algoritmo e estrutura de dados com a complexidade de tempo e espaço Big-O mais ótima (consultas $O(1)$, ordenação $O(N \log N)$, memória $O(1)$ de streaming).
   • Pesquisa Web Obrigatória: Nunca confie apenas em suposições pré-treinadas, pois o conhecimento pode estar desatualizado. Sempre pesquise na web com base no mês e ano atuais para descobrir padrões algorítmicos de ponta, estruturas de dados ótimas e implementações de bibliotecas de alto desempenho mais recentes.
8. Bibliotecas de Alto Desempenho e Baixo Consumo de RAM e Conformidade com Licenças Empresariais:
   • Máximo Desempenho e Baixa Memória: Prefira bibliotecas modernas, cache-friendly, zero-copy e aceleradas por SIMD (ex.: orjson/msgspec, polars, sonic, zerolog, simd-json, fast-json-stringify).
   • Conformidade com Licenças Empresariais: Selecione licenças open-source permissivas (MIT, Apache 2.0, BSD-2/3, ISC). Evite estritamente copyleft virais (GPL, AGPL, SSPL) para garantir a aprovação em auditorias empresariais sem obrigações de divulgação de código-fonte.
   • Guia detalhado: Guia de Bibliotecas de Alto Desempenho e Licenciamento
9. Análise Estática Determinística para SRP e Abstrações: Sempre priorize ferramentas de análise estática determinística para auditar o código quanto a violações de SRP (ex.: comprimento excessivo, responsabilidades excessivas) e desvios de abstração (ex.: chamadas SQL brutas ou HTTP diretas dentro da lógica de apresentação/negócios).
10. Injeção Centralizada de Segredos (Infisical): Nunca codifique segredos ou armazene credenciais brutas em arquivos git/locais de ambiente. Trate segredos como dependências injetadas em tempo de execução via Infisical (infisical run -- ...).
    • Guia detalhado: Guia de Gerenciamento de Segredos Infisical
11. Convenção do Framework Primeiro: Respeite as convenções idiomáticas do framework existente (ex.: Depends do FastAPI, @Injectable do NestJS, hooks React, interfaces Go) em vez de inventar abstrações ad-hoc.
12. Testes Paralelizáveis e Herméticos: Todos os testes devem ser sem estado, isolados e prontos para paralelização (ex.: pytest -n auto, go test -parallel). Sem estado mutável compartilhado ou efeitos colaterais de singleton estático.
13. A Disciplina do "Old Coder" Baseada em Evidências: Revise evidências, não código. Siga o loop Spec -> RED -> GREEN -> REFACTOR e verifique por meio de verificações automatizadas no terminal antes de relatar a conclusão.
14. Engenharia de Ferramentas e Habilidades Prontas para Agentes de IA: Ao extrair padrões repetitivos em ferramentas e habilidades: garanta saída --json, execução não interativa (zero prompts), segurança --dry-run, verbos previsíveis de substantivo-ação e códigos de saída tipados.
    • Guia detalhado: Guia de Design de CLI Pronto para Agentes de IA

---

Fluxo de Trabalho Passo a Passo

Passo 1: Análise de Raio de Impacto Pré-Alteração (CodeGraph AST)

Antes de modificar uma função, classe ou serviço, inspecione o raio de impacto para determinar o impacto downstream:

python3 ~/.gemini/config/skills/craftsman-coder/scripts/codegraph_impact.py <caminho_para_repositorio> --symbol <SimboloAlvo>

• Revise Chamadores Diretos e Arquivos de Referência.
• Revise Suítes de Teste Afetadas: Se nenhum teste cobrir este símbolo, você deve criar um antes de refatorar.

Passo 2: Arquitetura, Big-O Algorítmico e GEMINI.md em Nível de Repositório

• Formule uma especificação e design claros:
  • Se estiver criando/inicializando um repositório, crie um GEMINI.md autocontido na raiz do repositório (zero caminhos externos, zero segredos).
  • Se não existir convenção de framework, organize em Fatias Verticais (features/<nome>/) com padrões REPR e EIP.
  • Configure ou verifique linter de limites arquiteturais (ex.: dependency-cruiser, import-linter ou vsa_boundary_checker.py).
  • A classe/função/componente está fazendo mais de uma coisa ou excedendo os limites de comprimento? Decomponha-a em subcomponentes focados (SRP).
  • Os sistemas externos estão fortemente acoplados? Defina uma interface/protocolo e use Injeção de Dependência.
  • Complexidade Algorítmica e Pesquisa Web: Avalie a complexidade Big-O de tempo/espaço. Pesquise ativamente na web de acordo com o mês e ano atuais em busca de otimizações algorítmicas modernas.
  • Auditoria de Dependências: Escolha bibliotecas de baixo consumo de RAM e alta taxa de transferência com licenças seguras para empresas (MIT / Apache 2.0 / BSD). Garanta zero dependências transitórias copyleft/AGPL.
• Referência detalhada: Guia de Padrões SOLID e DI
• Referência detalhada: Guia de Fatia Vertical e EIP
• Referência detalhada: Guia de Reforço de Limites VSA e GEMINI.md de Repositório
• Referência detalhada: Guia de Bibliotecas de Alto Desempenho e Licenciamento

Passo 3: Escrever Testes Paralelizáveis (RED)

• Escreva um teste unitário ou de integração isolado e hermético que verifique o comportamento esperado ou a correção de bug.
• Garanta que o teste use recursos temporários independentes ou mocks em memória.
• Execute o teste para confirmar que ele falha (RED).
• Referência detalhada: Guia de Teste Paralelo e Old Coder

Passo 4: Implementar Solução Mínima e Limpa (GREEN)

• Implemente apenas o necessário para satisfazer o teste.
• Mantenha os componentes coesos e com um único propósito.
• Injete dependências de forma limpa.

Passo 5: Refatorar e o Gauntlet (REFACTOR e EVIDÊNCIA)

• Limpe o código enquanto os testes permanecem verdes.
• Execute O Gauntlet (toda verificação deve ser automatizada e determinística):
  1. Verificação de Limites VSA: Execute a verificação de limites arquiteturais (ex.: npx depcruise --config .dependency-cruiser.js src ou python3 ~/.gemini/config/skills/craftsman-coder/scripts/vsa_boundary_checker.py <caminho_para_repositorio>).
  2. Análise Determinística Estática de SRP e Abstração:

     python3 ~/.gemini/config/skills/craftsman-coder/scripts/static_srp_analyzer.py <caminho_para_repositorio> --strict
     

  3. Linter e Análise Estática (ex.: ruff check ., eslint, golangci-lint)
  4. Verificação de Tipos (ex.: mypy, tsc --noEmit)
  5. Suíte de Testes Completa executada em paralelo (ex.: pytest -n auto, go test -parallel 4 ./...)
• Forneça evidências de terminal (códigos de saída, resumo de testes aprovados) em sua resposta final.

---

Scripts e Ferramentas Incorporados

• Analisador de Impacto AST CodeGraph: scripts/codegraph_impact.py

  • Inspeciona AST e referências cruzadas em Python, JS/TS, Go, Rust, Java.
  • Calcula o nível de risco do raio de impacto (Baixo, Médio, Alto, Crítico).
  • Identifica chamadores diretos e suítes de teste afetadas.

• Analisador Determinístico Estático de SRP e Abstração: scripts/static_srp_analyzer.py

  • Avalia o código quanto a violações de comprimento/complexidade SRP.
  • Sinaliza desvios de abstração (chamadas SQL/HTTP brutas fora de repositórios/adaptadores).
  • Emite --json legível por máquina e códigos de saída determinísticos para verificação CI/Old Coder.

• Verificador de Limites Arquiteturais VSA: scripts/vsa_boundary_checker.py

  • Impõe o isolamento de fatias, impedindo importações ilegais entre fatias.
  • Configurável via .vsa-boundaries.json. Sem dependências, agnóstico de repositório (MIT).