223 lines
7.1 KiB
Markdown
Executable File
223 lines
7.1 KiB
Markdown
Executable File
# 🧠 Política de Memórias Core
|
|
|
|
Este documento define a política de uso das memórias core da IA coder no projeto SysCMS.
|
|
|
|
---
|
|
|
|
## 📋 Objetivo
|
|
|
|
As memórias core são **atalhos rápidos** para informações que a IA precisa acessar frequentemente, sem precisar realizar buscas demoras na codebase. Elas **NÃO DEVEM** substituir a documentação formal.
|
|
|
|
---
|
|
|
|
## ⚠️ Regra Fundamental
|
|
|
|
### Fonte da Verdade
|
|
|
|
**OS ARQUIVOS DE REGRAS SÃO A FONTE DA VERDADE.**
|
|
|
|
Em caso de conflito entre uma memória core e um arquivo de regras:
|
|
- ❌ **Nunca** confie na memória core
|
|
- ✅ **Sempre** consulte o arquivo de regras correspondente
|
|
|
|
### Prioridade de Consulta
|
|
|
|
1. **Primeiro**: Consulte RULES.md, CONTEXT.md, DECISIONS.md
|
|
2. **Segundo**: Consulte arquivos específicos em /rules/
|
|
3. **Terceiro**: Use memórias core como atalhos para informações estáticas
|
|
|
|
---
|
|
|
|
## 📊 O que Pode Estar nas Memórias Core
|
|
|
|
### ✅ Permitido (Informações Estáticas)
|
|
|
|
| Tipo | Exemplo | Justificativa |
|
|
|------|---------|---------------|
|
|
| **Credenciais** | Banco de dados (user=root, pass=root) | Informação que não muda com frequência e usada em muitas operações |
|
|
| **URLs de API** | Endpoints de API REST | Atalho rápido para chamadas de API frequentes |
|
|
| **Comandos CLI** | `php syscli migrate` | Padrões de comandos usados frequentemente |
|
|
| **Paths Fixos** | `storage/uploads/{modulo}` | Caminhos que não mudam no projeto |
|
|
| **Configs Estáticas** | Timeout de sessão, limites de upload | Configurações que são constantes |
|
|
|
|
### ❌ Proibido (Informações Dinâmicas ou de Regras)
|
|
|
|
| Tipo | Exemplo | Motivo |
|
|
|------|---------|--------|
|
|
| **Regras de desenvolvimento** | "Use DataTables para tabelas" | Duplicação de RULES.md |
|
|
| **Padrões de código** | "Classes em PascalCase" | Duplicação de 05_PADROES_CODIGO.md |
|
|
| **Estrutura de módulos** | "module.json deve ter X campos" | Duplicação de 03_MODULOS.md |
|
|
| **Frontend patterns** | "Usar Bootstrap Icons" | Duplicação de 04_TECNOLOGIAS.md |
|
|
| **Compatibilidade ERP Legado** | "Precedência do legado" | Duplicação de CONTEXT.md |
|
|
| **Padrões de uploads** | "Usar storage/uploads" | Duplicação de 51_UPLOADS_STORAGE.md |
|
|
| **Padrões de layouts** | "Usar layouts/dashboard.twig" | Duplicação de 50_LAYOUTS_CORRETOS.md |
|
|
| **Padrões de UX** | "Evitar confirm() nativo" | Duplicação de RULES.md |
|
|
|
|
---
|
|
|
|
## 🔍 Quando Criar uma Nova Memória Core
|
|
|
|
### Critérios de Aceitação
|
|
|
|
Crie uma nova memória core **APENAS** se atender a **TODOS** estes critérios:
|
|
|
|
1. ✅ A informação é **estática** (não muda com frequência)
|
|
2. ✅ A informação é **usada frequentemente** (3+ vezes em tarefas diferentes)
|
|
3. ✅ A informação **não está documentada formalmente** em /rules/
|
|
4. ✅ A informação **economiza tempo significativo** (evita 3+ tool calls)
|
|
|
|
### Exemplos de Memórias Apropriadas
|
|
|
|
**Credenciais de Banco de Dados:**
|
|
```
|
|
Banco de Dados (dev): user=root, pass=root, db=syscms, host=dockersyscms.
|
|
Execução direta via `docker exec dockersyscms mysql -u root -proot -D syscms -e 'QUERY'`
|
|
```
|
|
✅ Aceito: Informação estática, usada frequentemente, não está em /rules/
|
|
|
|
**URLs de API de GlobalLists:**
|
|
```
|
|
API Routes: `/api/globallists/states/{countryId}` e `/api/globallists/cities/{stateId}`.
|
|
Response JSON: `[{ "id": 1, "name": "..." }]`.
|
|
```
|
|
✅ Aceito: Informação estática, usada frequentemente, economiza tool calls
|
|
|
|
---
|
|
|
|
## 🚫 Quando NÃO Criar Memórias Core
|
|
|
|
### Exemplos de Memórias Inapropriadas
|
|
|
|
**Regras de DataTables:**
|
|
```
|
|
DataTables Obrigatório: Todas as tabelas de listagem DEVEM usar DataTables.
|
|
```
|
|
❌ Rejeitado: Duplicação de RULES.md - usar arquivos de regras
|
|
|
|
**Padrão de Uploads:**
|
|
```
|
|
Uploads no SysCMS: Arquivos em 'storage/uploads'. BD armazena caminho relativo.
|
|
```
|
|
❌ Rejeitado: Duplicação de 51_UPLOADS_STORAGE.md - usar arquivos de regras
|
|
|
|
**Layouts Twig:**
|
|
```
|
|
Layouts Twig: O layout principal é `layouts/dashboard.twig`. NUNCA usar `layout.twig`.
|
|
```
|
|
❌ Rejeitado: Duplicação de 50_LAYOUTS_CORRETOS.md - usar arquivos de regras
|
|
|
|
---
|
|
|
|
## 🧹 Manutenção de Memórias Core
|
|
|
|
### Limpeza Automática
|
|
|
|
Remova imediatamente memórias core que:
|
|
1. ❌ Duplicam informações dos arquivos de regras
|
|
2. ❌ Se tornaram obsoletas
|
|
3. ❌ Não são mais usadas (não acessadas em 10+ tarefas)
|
|
4. ❌ Contêm informações dinâmicas que mudam com frequência
|
|
|
|
### Validação Periódica
|
|
|
|
A cada 20 tarefas, a IA deve:
|
|
1. Listar todas as memórias core
|
|
2. Verificar se ainda há redundância com /rules/
|
|
3. Remover memórias desnecessárias
|
|
4. Documentar quais memórias foram removidas no contexto
|
|
|
|
---
|
|
|
|
## 📚 Documentação Formal vs Memórias Core
|
|
|
|
### Quando Usar Cada Fonte
|
|
|
|
| Situação | Fonte | Motivo |
|
|
|----------|-------|--------|
|
|
| Preciso de uma regra de desenvolvimento | RULES.md, /rules/ | Fonte da verdade, detalhada |
|
|
| Preciso entender a arquitetura | CONTEXT.md, 02_ARQUITETURA.md | Documentação oficial |
|
|
| Preciso de um padrão de código | 05_PADROES_CODIGO.md | Documentação oficial |
|
|
| Preciso de credenciais do BD | Memória Core | Atalho rápido para informação estática |
|
|
| Preciso de URLs de API | Memória Core | Atalho rápido para endpoints estáticos |
|
|
| Preciso entender módulos | 03_MODULOS.md | Documentação oficial |
|
|
| Preciso implementar um padrão específico | Arquivo específico em /rules/ | Documentação detalhada |
|
|
|
|
---
|
|
|
|
## 🎯 Checklist para IA Coder
|
|
|
|
### Antes de Consultar Memória Core
|
|
|
|
- [ ] A informação é estática?
|
|
- [ ] A informação não está em RULES.md?
|
|
- [ ] A informação não está em /rules/?
|
|
- [ ] A informação é usada frequentemente?
|
|
|
|
### Após Criar Memória Core
|
|
|
|
- [ ] Verifiquei que não duplica /rules/?
|
|
- [ ] A informação é realmente estática?
|
|
- [ ] A informação será usada frequentemente?
|
|
|
|
### Antes de Seguir Memória Core
|
|
|
|
- [ ] Verifiquei se há conflito com RULES.md?
|
|
- [ ] Verifiquei se há conflito com /rules/?
|
|
- [ ] Consultei a documentação oficial?
|
|
|
|
---
|
|
|
|
## 📖 Exemplos Práticos
|
|
|
|
### Caso 1: Implementar Tabela de Listagem
|
|
|
|
**❌ INCORRETO:**
|
|
```
|
|
Memória: "Use DataTables para tabelas de listagem"
|
|
→ Seguir memória sem consultar RULES.md
|
|
```
|
|
|
|
**✅ CORRETO:**
|
|
```
|
|
Consultar RULES.md → Encontrar seção sobre DataTables
|
|
→ Implementar seguindo documentação oficial
|
|
```
|
|
|
|
### Caso 2: Conectar ao Banco de Dados
|
|
|
|
**✅ CORRETO:**
|
|
```
|
|
Memória: "Banco de Dados (dev): user=root, pass=root"
|
|
→ Usar credenciais da memória (informação estática)
|
|
```
|
|
|
|
### Caso 3: Implementar Upload de Arquivo
|
|
|
|
**❌ INCORRETO:**
|
|
```
|
|
Memória: "Usar storage/uploads para uploads"
|
|
→ Seguir memória sem consultar 51_UPLOADS_STORAGE.md
|
|
```
|
|
|
|
**✅ CORRETO:**
|
|
```
|
|
Consultar 51_UPLOADS_STORAGE.md → Implementar seguindo documentação oficial
|
|
→ Usar memória apenas para paths específicos se existirem
|
|
```
|
|
|
|
---
|
|
|
|
## 📌 Resumo
|
|
|
|
1. **Arquivos de regras são a fonte da verdade**
|
|
2. **Memórias core são apenas atalhos rápidos**
|
|
3. **Nunca duplicar informações de /rules/ nas memórias**
|
|
4. **Em conflito: arquivos de regras sempre prevalecem**
|
|
5. **Memórias devem ser usadas para informações estáticas frequentes**
|
|
6. **Limpar memórias obsoletas ou redundantes regularmente**
|
|
|
|
---
|
|
|
|
**Última Atualização**: 2025-01-19
|
|
**Versão**: 1.0.0
|