melhoria de ia
This commit is contained in:
parent
a3cbd154f5
commit
b188f28ad4
20 changed files with 1060 additions and 61 deletions
121
global/rules/diagnostico-antes-correcao
Normal file
121
global/rules/diagnostico-antes-correcao
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
type: rule
|
||||
name: diagnostico-antes-correcao
|
||||
description: Todo agente DEVE realizar diagnóstico antes de implementar qualquer correção ou mudança
|
||||
scope: global
|
||||
trigger: always_on
|
||||
priority: alta
|
||||
updatedAt: "2026-07-09"
|
||||
---
|
||||
|
||||
# Regra: Diagnóstico Obrigatório Antes de Correção
|
||||
|
||||
## Contexto
|
||||
|
||||
Corrigir sem diagnosticar é tratar sintomas sem entender a causa. Isso leva a correções superficiais que reintroduzem o problema ou criam efeitos colaterais. Todo agente deve primeiro **entender** o problema para depois **resolver**.
|
||||
|
||||
## Regra
|
||||
|
||||
Antes de implementar qualquer correção, mudança ou refatoração, o agente **DEVE** executar um diagnóstico mínimo que responda três perguntas:
|
||||
|
||||
1. **O que está errado?** — Identificar o problema concreto (erro, smell, inconsistência)
|
||||
2. **Por que está errado?** — Entender a causa raiz, não apenas o sintoma
|
||||
3. **Qual o impacto?** — Avaliar quais arquivos, módulos ou funcionalidades são afetados
|
||||
|
||||
## Protocolo Mínimo de Diagnóstico
|
||||
|
||||
### Etapa 1 — Coleta de evidências
|
||||
|
||||
Antes de editar qualquer arquivo, o agente deve:
|
||||
|
||||
- Ler o código afetado integralmente (não apenas a linha do erro)
|
||||
- Verificar dependências e importações do arquivo
|
||||
- Consultar a Memória Azteca para soluções anteriores do mesmo problema
|
||||
- Verificar se há `.regras-negocio.md` relevante
|
||||
|
||||
### Etapa 2 — Análise de causa raiz
|
||||
|
||||
O agente deve diferenciar:
|
||||
|
||||
| Tipo | Exemplo | Abordagem |
|
||||
|------|---------|-----------|
|
||||
| **Sintoma** | "Campo X não aparece na tela" | NÃO corrigir direto |
|
||||
| **Causa intermediária** | "O tipo não inclui o campo X" | Investigar mais |
|
||||
| **Causa raiz** | "A migração não adicionou a coluna X no banco" | ESTA é a correção |
|
||||
|
||||
### Etapa 3 — Plano de correção
|
||||
|
||||
Antes de implementar, declarar ao operador:
|
||||
|
||||
```
|
||||
DIAGNÓSTICO:
|
||||
- Problema: [descrição objetiva]
|
||||
- Causa raiz: [identificação da causa]
|
||||
- Arquivos afetados: [lista]
|
||||
- Plano de correção: [passos]
|
||||
- Riscos: [efeitos colaterais possíveis]
|
||||
```
|
||||
|
||||
## Diagnóstico por Domínio
|
||||
|
||||
Cada agente aplica o protocolo mínimo acima com foco no seu domínio:
|
||||
|
||||
| Agente | Diagnóstico Específico |
|
||||
|--------|----------------------|
|
||||
| `@ag-back` | Verificar rotas, queries, schemas Zod, filas, logs de erro |
|
||||
| `@ag-front` | Verificar componente, composable, props/emits, estados de UI, console do navegador |
|
||||
| `@ag-refatorar` | Executar skill `diagnosticar-code-smells` antes de qualquer refatoração |
|
||||
| `@ag-testes` | Mapear cobertura existente, identificar cenários ausentes |
|
||||
| `@ag-deploy` | Verificar logs, healthchecks, variáveis de ambiente, estado dos containers |
|
||||
| `@ag-arquiteto` | Verificar fronteiras de módulo, dependências, contratos de API |
|
||||
| `@ag-ux` | Verificar fluxo de uso completo, estados de interface, mensagens ao usuário |
|
||||
| `@ag-documentacao` | Verificar JSDoc existente, `.regras-negocio.md`, dessincronia código/docs |
|
||||
| `@ag-agente` | Executar `auditar-agentes.sh`, verificar contradições entre personas |
|
||||
|
||||
## Exceções
|
||||
|
||||
A etapa de diagnóstico pode ser **simplificada** (não eliminada) quando:
|
||||
|
||||
- O erro é trivial e isolado (typo, import faltando, formatação)
|
||||
- O operador fornece diagnóstico completo junto com a solicitação
|
||||
- É uma continuação de correção já diagnosticada na mesma conversa
|
||||
|
||||
Mesmo nesses casos, o agente deve confirmar a compreensão do problema antes de agir.
|
||||
|
||||
## Exemplos
|
||||
|
||||
### ✅ Correto
|
||||
|
||||
```
|
||||
Operador: "O campo email não está salvando"
|
||||
Agente:
|
||||
1. Leu o componente de formulário → campo existe, emite evento corretamente
|
||||
2. Leu a rota da API → recebe o campo, mas o schema Zod não inclui 'email'
|
||||
3. Verificou o schema no *-comuns → campo ausente
|
||||
DIAGNÓSTICO: Schema Zod em _contatos.ts não inclui o campo 'email'.
|
||||
Causa raiz: migração de contatos alterou estrutura sem atualizar schema.
|
||||
PLANO: Adicionar campo ao schema → rodar build → verificar front.
|
||||
```
|
||||
|
||||
### ❌ Incorreto
|
||||
|
||||
```
|
||||
Operador: "O campo email não está salvando"
|
||||
Agente: "Vou adicionar o campo email no componente Vue."
|
||||
→ Não investigou a causa. Pode ser problema no schema, na API ou no banco.
|
||||
```
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem esta regra:
|
||||
- Agentes corrigem sintomas ao invés de causas raiz
|
||||
- Correções criam novos bugs em cascata
|
||||
- O operador perde tempo revisando correções superficiais
|
||||
- A mesma classe de problema reaparece repetidamente
|
||||
|
||||
## Referências
|
||||
|
||||
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
|
||||
- Skill: `global/skills/diagnosticar-erros-build/SKILL`
|
||||
- Skill: `agents/ag-refatorar/skills/diagnosticar-code-smells/SKILL`
|
||||
- Rule: `global/rules/autonomia-agente`
|
||||
192
global/skills/diagnosticar-antes-corrigir/SKILL
Normal file
192
global/skills/diagnosticar-antes-corrigir/SKILL
Normal file
|
|
@ -0,0 +1,192 @@
|
|||
---
|
||||
name: diagnosticar-antes-corrigir
|
||||
scope: global
|
||||
updatedAt: "2026-07-09"
|
||||
description: >
|
||||
Protocolo universal de diagnóstico que todo agente deve seguir antes de implementar
|
||||
correções, mudanças ou refatorações. Define etapas, ferramentas e formato de saída.
|
||||
---
|
||||
|
||||
# Skill: Diagnosticar Antes de Corrigir
|
||||
|
||||
Use esta skill **sempre** que receber uma solicitação de correção, ajuste ou mudança. Ela é a implementação operacional da rule `diagnostico-antes-correcao`.
|
||||
|
||||
---
|
||||
|
||||
## PASSO 1 — Compreender a Solicitação
|
||||
|
||||
Antes de qualquer ação, responder internamente:
|
||||
|
||||
| Pergunta | Resposta esperada |
|
||||
|----------|-------------------|
|
||||
| O que o operador reportou? | Descrição objetiva do problema |
|
||||
| É um erro de build, runtime, lógica ou visual? | Classificação |
|
||||
| Qual módulo/pacote é afetado? | `*-back`, `*-front`, `*-comuns`, `*-migracao` |
|
||||
| O operador já forneceu diagnóstico? | Se sim, validar antes de aceitar |
|
||||
|
||||
---
|
||||
|
||||
## PASSO 2 — Coletar Evidências
|
||||
|
||||
### 2.1. Ler o código afetado (completo)
|
||||
|
||||
```sh
|
||||
# Não ler apenas a linha do erro — ler o arquivo inteiro para contexto
|
||||
view_file <arquivo_afetado>
|
||||
|
||||
# Verificar imports e dependências
|
||||
rg "import.*from" <arquivo_afetado>
|
||||
|
||||
# Verificar quem usa este arquivo
|
||||
rg "<nome_do_export>" --include='*.ts' --include='*.vue' -l
|
||||
```
|
||||
|
||||
### 2.2. Verificar erros de build (se aplicável)
|
||||
|
||||
```sh
|
||||
# Verificar se o build passa
|
||||
pnpm --filter <pacote> build 2>&1 | head -50
|
||||
|
||||
# Ou checagem de tipos isolada
|
||||
npx tsc --noEmit -p <caminho>/tsconfig.json 2>&1 | head -30
|
||||
```
|
||||
|
||||
### 2.3. Consultar memória (obrigatório)
|
||||
|
||||
```sh
|
||||
# Buscar problemas semelhantes já resolvidos
|
||||
curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H "CHAVE: banana" \
|
||||
-d '{"termo": "PALAVRAS_CHAVE_DO_PROBLEMA"}' | jq '.items[] | {codigo, titulo, resumo}'
|
||||
```
|
||||
|
||||
### 2.4. Verificar regras de negócio documentadas
|
||||
|
||||
```sh
|
||||
# Buscar .regras-negocio.md no diretório afetado
|
||||
fd ".regras-negocio.md" <diretorio_do_modulo>
|
||||
|
||||
# Buscar comentários explicativos no código
|
||||
rg "HACK|FIXME|TODO|NOTA|IMPORTANTE|REGRA" <arquivo_afetado>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Análise de Causa Raiz
|
||||
|
||||
### 3.1. Técnica dos 5 Porquês
|
||||
|
||||
Aplicar progressivamente até chegar à causa raiz:
|
||||
|
||||
```
|
||||
Por que o campo não salva?
|
||||
→ Porque a API retorna 400.
|
||||
Por que a API retorna 400?
|
||||
→ Porque a validação Zod rejeita o campo.
|
||||
Por que o Zod rejeita?
|
||||
→ Porque o schema não inclui esse campo.
|
||||
Por que o schema não inclui?
|
||||
→ Porque a migração adicionou a coluna mas o schema não foi atualizado.
|
||||
CAUSA RAIZ: Schema Zod desatualizado após migração.
|
||||
```
|
||||
|
||||
### 3.2. Classificar a causa
|
||||
|
||||
| Categoria | Exemplos |
|
||||
|-----------|----------|
|
||||
| **Schema/Tipo** | Zod schema desatualizado, tipo TypeScript incorreto |
|
||||
| **Banco de dados** | Coluna ausente, migração não executada |
|
||||
| **Lógica de negócio** | Condição errada, regra não implementada |
|
||||
| **Integração** | API fora do contrato, fila não processando |
|
||||
| **Interface** | Componente não reativo, estado inconsistente |
|
||||
| **Configuração** | Variável de ambiente, tsconfig, dependência |
|
||||
| **Infraestrutura** | Container, deploy, proxy, certificado |
|
||||
|
||||
---
|
||||
|
||||
## PASSO 4 — Avaliar Impacto
|
||||
|
||||
```sh
|
||||
# Quais arquivos usam o código afetado?
|
||||
rg "<simbolo_afetado>" --include='*.ts' --include='*.vue' --include='*.tsx' -l
|
||||
|
||||
# Quantos módulos são impactados?
|
||||
rg "<simbolo_afetado>" --include='*.ts' -l | xargs -I{} dirname {} | sort -u
|
||||
```
|
||||
|
||||
Classificar o impacto:
|
||||
|
||||
| Severidade | Critério |
|
||||
|------------|----------|
|
||||
| 🔴 Alto | Afeta 3+ módulos, pode causar regressão |
|
||||
| 🟡 Médio | Afeta 1-2 arquivos, impacto limitado |
|
||||
| 🟢 Baixo | Isolado, sem dependentes |
|
||||
|
||||
---
|
||||
|
||||
## PASSO 5 — Declarar Diagnóstico
|
||||
|
||||
**OBRIGATÓRIO:** Antes de editar qualquer arquivo, apresentar ao operador:
|
||||
|
||||
```markdown
|
||||
## 🔍 Diagnóstico
|
||||
|
||||
**Problema:** [descrição objetiva do problema observado]
|
||||
**Causa raiz:** [identificação precisa da causa]
|
||||
**Categoria:** [Schema/Tipo | Banco | Lógica | Integração | Interface | Config | Infra]
|
||||
**Severidade:** [🔴 Alto | 🟡 Médio | 🟢 Baixo]
|
||||
|
||||
### Arquivos afetados
|
||||
- `caminho/arquivo1.ts` — [o que precisa mudar]
|
||||
- `caminho/arquivo2.vue` — [o que precisa mudar]
|
||||
|
||||
### Plano de correção
|
||||
1. [Primeiro passo]
|
||||
2. [Segundo passo]
|
||||
3. [Verificação]
|
||||
|
||||
### Riscos
|
||||
- [Efeito colateral possível, se houver]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 6 — Executar Correção
|
||||
|
||||
Somente após o diagnóstico declarado:
|
||||
|
||||
1. Aplicar as mudanças conforme o plano
|
||||
2. Verificar build após cada mudança significativa
|
||||
3. Confirmar que o problema original foi resolvido
|
||||
4. Verificar se não houve regressão nos arquivos afetados
|
||||
|
||||
---
|
||||
|
||||
## Atalho para Problemas Triviais
|
||||
|
||||
Quando o problema é **evidentemente trivial** (typo, import faltando, formatação), o diagnóstico pode ser condensado em uma linha:
|
||||
|
||||
```
|
||||
DIAGNÓSTICO: Import ausente de `zContato` em `_contatos.ts` (linha 5). Adicionando.
|
||||
```
|
||||
|
||||
A etapa de diagnóstico **nunca é eliminada** — apenas simplificada proporcionalmente à complexidade.
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] O código afetado foi lido integralmente (não apenas a linha do erro)?
|
||||
- [ ] A Memória Azteca foi consultada para soluções anteriores?
|
||||
- [ ] A causa raiz foi identificada (não apenas o sintoma)?
|
||||
- [ ] O impacto foi avaliado (arquivos e módulos afetados)?
|
||||
- [ ] O diagnóstico foi declarado ao operador antes da correção?
|
||||
- [ ] A correção resolve a causa raiz, não apenas o sintoma?
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/diagnostico-antes-correcao`
|
||||
- Skill: `global/skills/diagnosticar-erros-build/SKILL`
|
||||
- Skill: `agents/ag-refatorar/skills/diagnosticar-code-smells/SKILL`
|
||||
- Rule: `global/rules/autonomia-agente`
|
||||
Loading…
Add table
Add a link
Reference in a new issue