Agente Arquista de Loop (Engenharia de Loop)

Visão Geral

Agente Arquista de Loop é um padrão de execução e um padrão de design para orquestrar fluxos de trabalho multiagente complexos e de múltiplos estágios através de iterações de ciclo fechado com memória persistente e rastreamento de estado.

Em vez de tratar as execuções de agente como prompts únicos ou pipelines lineares, o Agente Loop impõe um ciclo de vida iterativo onde subagentes se especializam, verificam seu trabalho através de portões objetivos e aprendem sistematicamente entre execuções.

As Duas Regras de Ouro do Loop

Nenhuma Execução Sem Aprendizado Prévio: Antes de propor ou implementar qualquer solução, os agentes devem executar a fase Aprender consultando padrões positivos e negativos existentes na memória.
Nenhuma Conclusão Sem Compressão: Um ciclo não é concluído quando o código ou conteúdo é escrito; ele termina somente após a fase Comprimir destilar o resultado na memória e atualizar o estado.

flowchart TD
    Start([Tarefa Iniciada]) --> Learn[1. APRENDER: Ingerir .loop-memory/]
    Learn --> Plan[2. PLANEJAR: Decomposição em Estágios & etapas.json]
    Plan --> Exec[3. EXECUTAR: Subagentes Especializados Enviados]
    Exec --> Verify{4. VERIFICAR: Portões Objetivos Aprovados?}
    Verify -- Não: Regredir / Pivotar --> Learn
    Verify -- Sim --> Compress[5. COMPRIMIR: Destilar Memória & Atualizar Estado]
    Compress --> Done([Loop Concluído])

As 5 Fases do Loop

Cada ciclo de loop avança estritamente por cinco fases:

Fase 1: Aprender (Ingestão Pré-Voo)

Verificação obrigatória: Subagentes devem ler:
- .loop-memory/positive-cases/ (padrões vencedores, correções validadas, ângulos de copy de alta conversão, templates de prompt ideais).
- .loop-memory/negative-cases/ (antipadrões, hipóteses falhas, regressões de borda, abordagens proibidas).
Objetivo: Impedir que agentes repitam erros previamente documentados e forçar a reutilização de padrões comprovados.

Fase 2: Planejar e Orquestrar (Inicialização de Estado)

Decompor o objetivo em estágios discretos e ordenados.
Inicializar ou atualizar etapas.json com status do estágio, subagentes atribuídos, entradas, saídas e critérios de aceitação.
Atribuir funções de subagente dedicadas que correspondam aos requisitos do domínio.

Fase 3: Executar (Envio de Subagentes Especializados)

Executar subagentes sequencialmente ou em paralelo com base nas dependências dos estágios.
Subagentes trabalham em contexto isolado, passando artefatos concisos ou diffs em vez de bagagem conversacional completa.

Fase 4: Verificar e Avaliar (Portões de Aceitação Objetivos)

Validar a saída da execução contra critérios explícitos, automatizados ou determinísticos (ex.: resultados de testes unitários/integração, linting, verificação de citações factuais, conformidade de tom).
Se a verificação falhar:
- Documentar a falha como um padrão negativo intermediário.
- Retornar para Aprender/Planejar com o feedback da falha.
Se a verificação passar: prosseguir para Comprimir.

Fase 5: Comprimir (Destilação de Memória Pós-Voo)

Destilação Positiva: Extrair o padrão exato, template, fragmento de prompt ou correção de código que teve sucesso e escrevê-lo em .loop-memory/positive-cases/CASE-<ID>.md.
Destilação Negativa: Documentar becos sem saída, hipóteses rejeitadas e regressões em .loop-memory/negative-cases/CASE-<ID>.md.
Finalização de Estado: Atualizar etapas.json com timestamps de conclusão, artefatos finais e métricas de execução.

Estrutura de Diretórios e Arquitetura de Memória

Cada projeto operando com o padrão Loop adere à seguinte estrutura raiz ou de workspace:

<raiz-do-projeto>/
├── .loop-memory/
│   ├── positive-cases/
│   │   ├── CASE-001-fixar-condicao-corrida-auth.md
│   │   └── CASE-002-gatilho-frio-alta-conversao.md
│   └── negative-cases/
│       ├── CASE-001-falha-jwt-no-localstorage.md
│       └── CASE-002-gatilho-clickbait-rejeicao.md
├── etapas.json
├── references/
│   └── exemplos-de-dominio.md
└── SKILL.md

Esquema de Caso de Memória (`.loop-memory//CASE-.md`)

Cada arquivo de caso deve seguir este template markdown padronizado:

# Caso: [Título Descritivo Curto]
- **Data:** AAAA-MM-DD
- **Domínio:** [Engenharia | Copywriting | Vendas | Pesquisa]
- **Tipo:** [Positivo | Negativo]
- **Gatilho / Contexto:** [Situação exata, mensagem de erro ou objetivo do prompt]

## Padrão / Técnica
[Descrição detalhada do que funcionou ou por que falhou]

## Artefato Concreto / Fragmento de Código / Prompt
```[linguagem]
[Cole o fragmento concreto, template ou diff aqui]

Lição e Heurística

Faça: [Regra acionável para agentes futuros]
Não Faça: [O que deve ser evitado]


### Esquema de `etapas.json`

O arquivo `etapas.json` rastreia a progressão do ciclo de vida atual:

```json
{
  "project": "projeto-loop-agente",
  "loop_version": "2.0.0",
  "updated_at": "2026-11-06T21:00:00Z",
  "current_stage": "corrigir",
  "stages": [
    {
      "id": "reproduzir",
      "role": "Subagente Reprodução QA",
      "status": "completo",
      "input": "Relatório de bug #402",
      "output": "tests/repro_spec.ts",
      "memory_consulted": ["CASE-001-fixar-condicao-corrida-auth.md"]
    },
    {
      "id": "corrigir",
      "role": "Subagente Engenheiro de Correção Principal",
      "status": "em_andamento",
      "input": "tests/repro_spec.ts",
      "output": null,
      "memory_consulted": []
    }
  ],
  "metrics": {
    "total_cycles": 1,
    "positive_patterns_harvested": 0,
    "negative_patterns_avoided": 1
  }
}

Arquétipos de Domínio Integrados

O Agente Arquista de Loop inclui 4 pipelines de domínio testados em batalha. Para instruções passo a passo completas e prompts para cada arquétipo, veja exemplos-de-dominio.md (em inglês).

1. Correção de Bugs e Engenharia

Pipeline: Reproduzir -> Causa Raiz -> Corrigir -> Testar -> Documentar
Verificação de Aprendizado: Ingerir correções anteriores para subsistemas relacionados; evitar regressões passadas.
Portão de Verificação: Teste de reprodução muda de VERMELHO para VERDE; sem quebras colaterais em testes.
Comprimir: Armazenar a explicação da causa raiz e o diff mínimo de correção em .loop-memory/positive-cases/.

2. Conteúdo e Copywriting

Pipeline: Pesquisa de Público e Ângulo -> Rascunho de Gancho e Narrativa -> Crítica e Polimento de Tom -> Prova e Verificação de Fatos -> Empacotamento de Distribuição
Verificação de Aprendizado: Ler os ganchos de maior desempenho e palavras-chave/clichês proibidos.
Portão de Verificação: Nível de leitura alvo, pontuação de rubrica de voz da marca ≥ 8,5/10, alegações factuais verificadas.
Comprimir: Colher ângulos de alto desempenho e fórmulas de gancho na memória.

3. Vendas

Pipeline: Inteligência de ICP -> Hipótese de Valor -> Sequenciamento Personalizado -> Contra-Argumentação de Objeções -> Preparação de Envio
Verificação de Aprendizado: Consultar taxas de resposta em propostas de valor, padrões de objeção e suposições inválidas.
Portão de Verificação: Checklist de especificidade (sem linhas genéricas de mala direta), conformidade com diretrizes de spam.
Comprimir: Salvar ganchos de personalização bem-sucedidos e registrar ângulos de baixa resposta em casos negativos.

4. Análise de Pesquisa, Financeira e Jurídica

Pipeline: Descoberta e Ingestão de Fontes -> Verificação de Fatos e Matriz de Risco -> Síntese Quantitativa/Jurídica -> Teste de Estresse de Cenário -> Briefing Executivo
Verificação de Aprendizado: Ingerir casos precedentes, descuidos de análises passadas e padrões de validade de dados.
Portão de Verificação: Rastreamento de 100% das fontes citadas; matrizes de risco testadas contra cenários de estresse.
Comprimir: Salvar templates de síntese, classificações de confiabilidade de fontes e heurísticas de avaliação de risco.

Diretrizes de Envio de Subagentes

Ao enviar subagentes dentro de um loop:

Especificidade de Função: Nunca solicite um agente generalista. Prefixe os prompts com instruções de função de domínio (ex.: Você é o Subagente Reprodução QA...).
Injeção de Memória: Sempre forneça os caminhos ou resumo dos casos relevantes de .loop-memory/ no prompt inicial do subagente.
Transferências Discretas: Subagentes devem se comunicar através de arquivos explícitos (ex.: scripts de reprodução, arquivos de rascunho, rubricas de avaliação) em vez de histórico de conversação.
Portão de Etapa Autônomo: Um subagente NÃO tem permissão para avançar o status de etapas.json para "completo" sem prova verificável (logs, saídas de teste, pontuações de validação).

Erros Comuns e Antipadrões

Antipadrão	Por Que Quebra o Loop	A Prática Correta
Pular a fase Aprender	Agentes reinventam bugs conhecidos ou usam ângulos de copy rejeitados.	Impor a leitura de `.loop-memory/` como etapa 0 em cada prompt.
Omitir a fase Comprimir	Lições são perdidas assim que o contexto da sessão é redefinido.	Nunca concluir uma tarefa sem destilar casos vencedores/falhos em arquivos.
Execução de agente monolítica	Um único agente fica confuso tentando planejar, codificar, verificar e documentar ao mesmo tempo.	Enviar subagentes especializados para cada estágio discreto.
Verificação suave ("parece bom")	Alucinações chegam à produção.	Usar portões determinísticos: suítes de teste, saída de linter, citações factuais.
Loops de repetição ilimitados	Agente entra em loop infinito em um defeito irreparável.	Limitar repetições de loop a 3 iterações antes de acionar um portão de escalação humana.

Agente Arquista de Loop

O que é Agente Arquista de Loop?

Perguntar na sua IA favorita

Documentação