Auto-Reparo (Motor de Regras Autocorretivo)
Um motor de memória e aprendizado autocorretivo que registra correções, convenções de projeto e correções de bugs em um arquivo de regras persistente (autofix.json). Ele garante que o agente se adapte continuamente, elimine erros repetidos entre sessões e siga rigidamente as preferências do usuário.
Por que isso funciona: Agentes de IA tendem a repetir as mesmas suposições padrão ou erros estilísticos em novas sessões. Ao externalizar o conhecimento aprendido em um conjunto de regras JSON imperativo e versionado, com precedência estrita (regras mais novas vencem), o agente retém limites rígidos adaptados ao usuário e repositório específicos.
Armazenamento e Configuração
O skill procura o arquivo de regras em um dos seguintes locais (em ordem de prioridade):
.agents/autofix.jsonautofix.json(na raiz do workspace).rules/autofix.json
Se nenhum existir quando uma nova regra precisar ser adicionada, ele cria .agents/autofix.json (ou autofix.json na raiz, dependendo da convenção do projeto).
Esquema de Regra
Cada regra é armazenada dentro de um array JSON com o seguinte esquema:
[
{
"Rule_number": 1,
"Category": "CODE",
"Instruction": "Nunca use exportações padrão para componentes React - sempre use exportações nomeadas.",
"Why": "Garante consistência com a base de código e simplifica a refatoração."
}
]
Categorias Permitidas
| Categoria | Descrição | Exemplos |
|---|---|---|
[STYLE] | Formatação de código, convenções de nomenclatura, ordenação de imports, comentários | "Sempre use camelCase para funções auxiliares" |
[CODE] | Padrões de linguagem, escolhas de bibliotecas, definições de tipo, tratamento de erros | "Nunca use any em TypeScript; use unknown com guards de tipo" |
[ARCH] | Estrutura de diretórios, limites de módulos, camadas arquiteturais | "Rotas de API ficam em src/server/routes/, não em src/api/" |
[TOOL] | Comandos CLI, ferramentas de build, gerenciadores de pacotes, frameworks de teste | "Sempre use pnpm em vez de npm ou yarn" |
[PROCESS] | Fluxo de trabalho Git, mensagens de commit, requisitos de PR, portas de teste | "Nunca adicione emojis a mensagens de commit" |
[DATA] | Esquemas de banco de dados, migrações, estratégias de cache, formatos de estado | "Sempre inclua timestamps created_at e updated_at nas tabelas" |
[UX] | Comportamentos de UI, convenções de texto, padrões de acessibilidade | "Sempre forneça um aria-label explícito para botões apenas com ícone" |
[OTHER] | Preferências gerais ou específicas de domínio do projeto | "Sempre documente endpoints de API pública em formato de tabela markdown" |
Fluxo de Trabalho Operacional
[Início da Sessão / Tarefa Recebida]
│
▼
┌─────────────────────────────────┐
│ 1. Varredura Pré-Tarefa │ ◄── Ler autofix.json
│ - Carregar todas as regras │
│ - Resolver conflitos (nova>antiga)
│ - Construir restrições ativas│
└────────────┬────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 2. Execução da Tarefa │
│ - Aplicar restrições │
│ - Executar código/edições │
└────────────┬────────────────────┘
│
├───────────────────────────────────────────┐
│ │
[Sem Correções] [Gatilho Detectado]
│ │
▼ ▼
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Tarefa Concluída │ │ 3. Auto-Reparo e Captura │
│ Entregar saída ao usuário │ │ - Formular regra imperativa │
└─────────────────────────────────┘ │ - Anexar ao autofix.json │
│ - Reconhecer aprendizado │
└──────────────┬──────────────────┘
│
▼
┌─────────────────────────────────┐
│ 4. Reexecutar e Corrigir │
│ Corrigir saída atual da tarefa │
└─────────────────────────────────┘
Execução Detalhada Passo a Passo
1. Varredura Pré-Tarefa (Antes de Fazer Qualquer Coisa)
Antes de planejar ou modificar arquivos em qualquer tarefa:
- Localizar e carregar
autofix.json. - Examinar as regras:
- Verificar se alguma regra se aplica diretamente aos arquivos, ferramentas ou padrões envolvidos no prompt atual.
- Resolver conflitos:
- Se duas regras fornecerem orientação conflitante, a regra de número mais alto (mais nova) vence.
- Manter restrições ativas:
- Tratar todas as regras ativas como restrições rígidas (equivalente a
CONSTRAINTSdo contrato de prompt).
- Tratar todas as regras ativas como restrições rígidas (equivalente a
2. Quando Adicionar uma Regra (Condições de Gatilho)
Disparar imediatamente a captura de regra quando qualquer um dos seguintes ocorrer:
- Usuário corrige explicitamente a saída: por exemplo, "Não, não use X, faça com Y", "Não usamos componentes de classe aqui".
- Usuário rejeita um arquivo, abordagem ou padrão: por exemplo, "Não coloque arquivos de teste ao lado do código fonte".
- Usuário declara uma preferência pessoal/de equipe: por exemplo, "Sempre formate mensagens de commit como Conventional Commits", "Nunca use emojis em documentação".
- Um bug foi causado por suposições erradas: O agente assumiu uma biblioteca ou localização de arquivo que causou uma falha.
- Usuário executa
/learnou pede para lembrar de uma regra.
3. Anexando uma Nova Regra
Quando um gatilho ocorre, execute a seguinte atualização atômica:
- Ler o array
autofix.jsonexistente. - Determinar o próximo
Rule_numbersequencial:- Se o número de regra mais alto existente for $N$, a nova regra é $N + 1$.
- Se o arquivo estiver vazio ou for novo, começar em
1.
- Formatar o novo objeto de regra:
- Rule_number: Inteiro sequencial.
- Category: Uma das categorias padrão (
STYLE,CODE,ARCH,TOOL,PROCESS,DATA,UX,OTHER). - Instruction: Escrita em formato imperativo estrito:
"Nunca/Sempre faça X - porque Y." - Why: Razão breve (por exemplo, "preferência do usuário", "padrão da base de código", "limitação do framework").
- Anexar a regra ao array JSON e salvar o arquivo formatado com indentação de 2 espaços.
- Nunca deletar regras existentes. Se uma regra antiga for substituída, escrever a nova regra para que seu número mais alto tenha precedência.
- Notificar brevemente o usuário:
"Regra #
<N>aprendida ([CATEGORIA]):<Instrução>— registrada emautofix.json."
4. Exemplo de Arquivo de Regras (autofix.json)
[
{
"Rule_number": 1,
"Category": "PROCESS",
"Instruction": "Nunca adicione emojis a mensagens de commit - mantenha títulos de commit como Conventional Commits simples.",
"Why": "preferência do usuário"
},
{
"Rule_number": 2,
"Category": "ARCH",
"Instruction": "Sempre coloque manipuladores de rota de API em 'src/server/routes/', nunca em 'src/api/' - mantenha arquitetura de backend consistente.",
"Why": "padrão existente da base de código"
},
{
"Rule_number": 3,
"Category": "CODE",
"Instruction": "Sempre use esquemas Zod para validação de entrada em todos os pontos de entrada externos - evite entradas de runtime sem tipo.",
"Why": "previne erros de runtime e impõe tipos"
}
]
Melhores Práticas e Casos de Borda
- Escrita JSON Atômica: Sempre analisar o array JSON existente, anexar o novo objeto e salvar de volta um JSON válido. Nunca corrompa o arquivo com texto sem escape.
- Concreto e Imperativo: Escreva regras que outra IA possa seguir sem ambiguidade. Evite conselhos vagos como "Escreva código limpo"; prefira "Sempre exporte tipos junto com implementações de componentes em arquivos
.types.ts". - Evite Loops Infinitos: Ao registrar uma regra, não dispare um loop de auto-reparo separado para o próprio arquivo de regras.
- Substituindo Regras: Se a Regra 1 disser "Use Axios" e o usuário depois instruir "Migre tudo para Fetch", adicione a Regra 4 "Sempre use Fetch nativo em vez de Axios" com
Why: "usuário solicitou migração para Fetch nativo (substitui a Regra 1)".