minions-ai-agents/src/knowledge/standards/code_hygiene_standards.md

🧹 Higiene de Código e Padrões (O Protocolo "KonMari")

Público: Agentes Criativos e de Auditoria (Gordon Ramsay, Marie Kondo, Linus Torvalds). Objetivo: Código limpo, legível e que traz alegria.

[!CRITICAL] O Mandato Ramsay: "Este código está CRU! Se eu vir uma função com 50 linhas e sem docstring, vou desligar o container!"

1. 🧼 A Regra "Spark Joy" (Refatoração)

Código Morto

Mandato: Se está comentado, DELETE.

• Por que: O Git lembra a história. Não precisamos de // codigo_antigo_v1 poluindo a tela.
• Ação do Agente: Agentes de auditoria devem deletar agressivamente blocos de código inalcançáveis.

O Princípio da "Responsabilidade Única"

• Limite: Funções > 30 linhas são suspeitas. Classes > 200 linhas são um "Code Smell".
• Ação: Quebre. Extraia métodos. Torne modular.

2. 🐍 Estilo Pythonico (O Padrão Linus)

Formatação

Adesão Estrita: Seguimos PEP 8, impondo:

1. Snake_case para funções/variáveis (calcular_total).
2. CamelCase para classes (GerenciadorUsuario).
3. UPPER_CASE para constantes (TENTATIVAS_MAX).

Imports

• Agrupamento: Standard Lib -> Third Party -> Local.
• Ordenação: Alfabética.

  import os
  import sys
  
  import requests
  
  from meu_modulo import utils
  

Dicas de Tipo (A Zona "Sem Any")

• Regra: Toda assinatura de função DEVE ter dicas de tipo.
• Proibido: def processar(dados): (O que são dados??)
• Exigido: def processar(dados: Dict[str, Any]) -> bool: (Pelo menos sabemos que é um dict).

3. 📂 Estrutura de Diretórios (Um Lugar para Cada Coisa)

Agentes devem respeitar o Mapa do Projeto. Não invente novas pastas raiz.

• src/: Lógica da Aplicação.
• tests/: Testes espelhando a estrutura src.
• docs/: Documentação humana.
• scripts/: Scripts de DevOps/Manutenção.

Proibido: Criar temp/, stuff/, ou utils.py (Seja específico: string_utils.py, date_utils.py).

4. 📝 Nomenclatura Semântica (A Checagem "Gordon")

Nomes devem explicar a Intenção.

• ❌ RUIM: d = obter_dados() (Espere, o que é 'd'? Que dados?)
• ✅ BOM: usuarios_ativos = buscar_lista_usuarios_ativos()

5. 🗑️ O Ciclo de Vida de Descontinuação

Ao substituir uma funcionalidade:

1. Marcar: Adicione o decorador @deprecated("Use nova_funcao em vez disso").
2. Avisar: Registre um evento WARN (Veja observability_standards.md).
3. Matar: Remova na próxima limpeza de versão principal.

6. 🧑‍🍳 O Checklist de Auditoria Ramsay

Antes de fazer o merge:

• Linting: Rodei black ou flake8?
• Nomenclatura: As variáveis são distintas? (Nada de temp, dados, obj).
• Docstrings: Todo método público tem uma docstring estilo Google?
• Complexidade: Existe algum if/else aninhado com mais de 3 níveis? (Achate!).
• Alegria: Ler este código me deixa calmo ou em pânico?