SyspanelMultiAgentsAI/RULES.md

RULES.md — Regras para IA Codificar no MultiAgentsAI

Autor: Marco Costa — www.syspanel.com.br
Criado em: Setembro de 2026

Este arquivo define as regras que qualquer IA (incluindo agentes do próprio sistema) deve seguir ao modificar ou criar código dentro deste projeto.

---

1. Propriedade do Código

• Todo arquivo .py criado por uma IA deve conter o comentário # Gerado por IA na primeira linha, após o docstring ou shebang se houver.
• Nunca apagar comentários existentes sem justificativa explícita no commit.

2. Estrutura de Pastas

• Código fonte fica em app/.
• Scripts de shell ficam na raiz de app/.
• Dados gerados (SQLite, JSONs) ficam em app/Contexts/ ou na raiz de app/.
• Nunca coloque arquivos .env ou com credenciais no versionamento.
• Nunca crie pastas novas sem necessidade explícita.

3. Convenções de Código Python

• Python 3.10+ mínimo.
• Type hints obrigatórios em funções públicas e métodos de classe.
• Docstrings em todas as classes e funções públicas (formato Google ou reStructuredText).
• Sem comentários inline desnecessários.
• Sem prints de debug deixados no código final.
• Tratamento de exceções explícito; nunca usar except: pass genérico.
• Constantes em UPPER_SNAKE_CASE, variáveis em snake_case, classes em PascalCase.
• Importações agrupadas: stdlib → terceiros → locais, separadas por uma linha em branco.

4. Configuração e Variáveis de Ambiente

• Toda configuração deve vir do arquivo .env carregado por python-dotenv.
• NUNCA hardcodar chaves de API, tokens ou credenciais.
• Variáveis novas no .env devem ser documentadas no README.md na tabela de variáveis.

5. Banco de Dados (SQLite)

• Usar sqlite3.Row como row_factory para acessar colunas por nome.
• Toda query parametrizada com ? — nunca concatenar strings em SQL.
• Migrações de schema: se alterar a estrutura do banco, adicionar uma função migrate_db() em database.py chamada por init_db().
• Nunca usar DROP TABLE sem backup explícito.

6. Manipulação de Contexto

• O arquivo JSON diário em Contexts/ é a fonte da verdade para o contexto dos agentes.
• Toda mensagem de agente deve ser salva via append_to_context() (que grava no JSON e no SQLite simultaneamente).
• Nunca ler o JSON diretamente — sempre usar as funções de context_manager.py.
• O nome do arquivo JSON deve seguir o padrão conversas_YYYY-MM-DD.json.

7. API OpenRouter

• Toda chamada à API OpenRouter deve passar por AIAgent.generate_response() em ai_agent.py.
• Headers obrigatórios: Authorization, Content-Type, HTTP-Referer, X-Title.
• Timeout mínimo de 60 segundos.
• Respostas com erro devem retornar [Erro ao gerar resposta por {nome}: {erro}] — nunca lançar exceção para o caller.

8. Telegram Bot

• Toda resposta ao usuário no Telegram deve usar _send_telegram() de telegram_bot.py.
• Nunca chamar python-telegram-bot diretamente em outros módulos.
• Novos comandos devem ser adicionados como funções assíncronas com prefixo cmd_ e registrados em build_bot().

9. Orquestrador

• O loop principal está em Orchestrator.run() em orchestrator.py.
• O delay entre mensagens é controlado por settings.CONVERSATION_DELAY (segundos).
• A referência global _orchestrator_ref em orchestrator_shared.py é usada para pausar/retomar via comandos Telegram — nunca removê-la sem substituir por mecanismo equivalente.
• O sistema só para com KeyboardInterrupt (Ctrl+C) ou self._running = False.

10. Arquivos Gerados

Nunca commitar:

• .env (credenciais)
• venv/ (ambiente virtual)
• agents.db (banco de dados local)
• Arquivos em Contexts/ com dados reais de conversas

Esses arquivos devem estar listados no .gitignore.

11. Segurança

• Nunca logar chaves de API, tokens ou senhas.
• Validar entradas de usuário antes de enviar para a API.
• Limitar max_tokens em chamadas à API para evitar custos excessivos.
• Sanitizar texto antes de exibir no Telegram (evitar injeção de HTML malicioso).

12. Testes

• Qualquer nova função pública deve ter ao menos um teste básico.
• Testes ficam em tests/ (criar a pasta se necessário).
• Usar pytest como framework de testes.

13. Commits

• Mensagens de commit em português, imperativo, curtas.
• Formato: tipo: descrição curta
  • feat: nova funcionalidade
  • fix: correção de bug
  • refactor: refatoração sem mudança de comportamento
  • docs: alteração em documentação
  • chore: alterações de configuração, dependências
• Nunca commitar com --amend sem antes verificar o diff.