Diretrizes Operacionais para Uso de Inteligência Artificial — Projeto EBDbe
Finalidade
Este documento estabelece as regras de utilização de ferramentas de Inteligência Artificial (IA) no projeto EBDbe.
A IA é assistente técnica.
A decisão final é sempre humana.
Todas as decisões arquiteturais devem respeitar os ADRs vigentes.
1. Regras Gerais
- A IA deve sempre considerar os ADRs antes de propor alterações estruturais.
- Nenhuma alteração pode violar a separação arquitetural definida no ADR-0007.
- O backend é a autoridade final das regras de negócio.
- O frontend não deve conter validações críticas de negócio.
- Toda entidade deve respeitar o escopo organizacional (ministry_id e unit_id).
2. Respeito à Arquitetura
A IA deve preservar:
- Clean Architecture simplificada
- Domínio isolado de infraestrutura
- Infraestrutura implementando interfaces do domínio
- Camada de apresentação sem regra de negócio
- Acesso ao Firestore apenas na camada infrastructure
Padrões proibidos:
- Chamadas diretas ao Firestore na camada presentation
- Validação organizacional apenas no frontend
- Lógica de negócio embutida em widgets Flutter
3. Regras do Backend
A IA deve:
- Validar RBAC em toda Cloud Function
- Validar escopo organizacional (ministry_id + unit_id)
- Não confiar em dados de escopo enviados pelo cliente
- Centralizar validação no backend
A IA não deve:
- Alterar regras de segurança do Firestore sem autorização explícita
- Modificar fluxo de autenticação sem revisão
- Armazenar dados sensíveis desnecessários
4. Estratégia de Presença
Ao implementar presença:
- QR Code é o método principal
- WIFI e GEO apenas sugerem presença
- Nunca armazenar localização contínua
- Registrar apenas o evento de presença
A IA deve respeitar integralmente ADR-0004 e ADR-0006.
5. Diretrizes de Geração de Código
A IA deve:
- Criar arquivos pequenos e modulares
- Evitar arquivos monolíticos
- Utilizar tipagem explícita no TypeScript (modo strict)
- Usar nomes claros e sem abreviações excessivas
- Evitar valores mágicos
6. Versionamento e Git
A IA pode:
- Sugerir mensagens de commit
- Organizar commits por responsabilidade
A IA não pode:
- Realizar push automático
- Realizar merge automático
- Forçar push
Padrão de commit:
- feat:
- fix:
- refactor:
- chore:
- docs:
- test:
7. Testes
A IA deve:
- Criar testes unitários para o domínio
- Criar testes de casos de uso
- Utilizar Firebase Emulator para backend
A IA não deve:
- Omitir validações críticas nos testes
- Criar testes superficiais sem cobertura real
8. Refatoração
A IA pode refatorar se:
- Não houver conflito com ADRs
- A separação de camadas for mantida
- A alteração for explicada antes da execução
Refatorações estruturais exigem novo ADR.
9. Uso de Terminal
A IA pode sugerir comandos como:
- flutter run
- flutter build web
- firebase emulators:start
- npm install
- git add / commit
A IA deve solicitar confirmação antes de executar qualquer comando.
10. Documentação
A IA pode:
- Atualizar README
- Melhorar comentários
- Sugerir melhorias em ADRs
Regra geral para documentação de páginas (ui): sempre que possível, incluir um screenshot da página (frontend) como parte da documentação.
A IA não pode modificar decisões arquiteturais existentes sem criação de novo ADR.
11. Princípio de Segurança
Em caso de dúvida, a IA deve:
- Solicitar esclarecimento
- Evitar alterações estruturais
- Preferir implementação mínima segura
12. Objetivo do Uso de IA
A IA deve:
- Aumentar produtividade
- Reduzir trabalho repetitivo
- Preservar consistência arquitetural
- Apoiar documentação
- Não substituir governança humana