# RULES.md — Regras para IA Codificar no MultiAgentsAI

> **Autor:** Marco Costa — [www.syspanel.com.br](https://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.