gan-style-harness

Skill Arnes Estilo GAN

Inspirado pelo Design de Arnes da Anthropic para Desenvolvimento de Aplicações de Longa Duração (24 de Março de 2026)

Um arnes multiagente que separa a geração da avaliação, criando um ciclo de feedback adversarial que impulsiona a qualidade muito além do que um único agente pode alcançar.

Insight Central

Quando solicitados a avaliar o próprio trabalho, os agentes são otimistas patológicos — eles elogiam resultados medíocres e se convencem a ignorar problemas legítimos. Mas projetar um avaliador separado para ser implacavelmente rigoroso é muito mais viável do que ensinar um gerador a se autocriticar.

Esta é a mesma dinâmica das GANs (Redes Adversariais Generativas): o Gerador produz, o Avaliador critica, e esse feedback impulsiona a próxima iteração.

Quando Usar

• Construir aplicações completas a partir de um comando de uma linha
• Tarefas de design frontend que exigem alta qualidade visual
• Projetos full-stack que precisam de funcionalidades funcionando, não apenas código
• Qualquer tarefa onde a estética de "AI slop" seja inaceitável
• Projetos onde você deseja investir US$ 50-200 por um resultado de qualidade profissional

Quando NÃO Usar

• Correções rápidas de arquivo único (use o claude -p padrão)
• Tarefas com restrições orçamentárias apertadas (<US$ 10)
• Refatoração simples (use o padrão de des-slopificação)
• Tarefas que já estão bem especificadas com testes (use o fluxo TDD)

Arquitetura

                    ┌─────────────┐
                    │  PLANEJADOR │
                    │  (Sonnet)   │
                    └──────┬──────┘
                           │ Especificação do Produto
                           │ (funcionalidades, sprints, direção de design)
                           ▼
              ┌────────────────────────┐
              │                        │
              │   GERADOR-AVALIADOR    │
              │   CICLO DE FEEDBACK    │
              │                        │
              │  ┌──────────┐          │
              │  │ GERADOR  │--constrói-->│──┐
              │  │ (Sonnet) │          │  │
              │  └────▲─────┘          │  │
              │       │                │  │ aplicação ao vivo
              │    feedback             │  │
              │       │                │  │
              │  ┌────┴─────┐          │  │
              │  │AVALIADOR │<-testa----│──┘
              │  │ (Sonnet) │          │
              │  │+Playwright│         │
              │  └──────────┘          │
              │                        │
              │   5-15 iterações       │
              └────────────────────────┘

Os Três Agentes

1. Agente Planejador

Função: Gerente de produto — expande um resumo simples em uma especificação completa do produto.

Comportamentos principais:

• Recebe um comando de uma linha e produz uma especificação com 16 funcionalidades e múltiplos sprints
• Define histórias de usuário, requisitos técnicos e direção de design visual
• É deliberadamente ambicioso — planejamento conservador leva a resultados decepcionantes
• Produz critérios de avaliação que o Avaliador usará posteriormente

Modelo: Sonnet por padrão; aumente para GAN_PLANNER_MODEL=opus para uma expansão de especificação mais profunda

2. Agente Gerador

Função: Desenvolvedor — implementa funcionalidades de acordo com a especificação.

Comportamentos principais:

• Trabalha em sprints estruturados (ou modo contínuo com modelos mais novos)
• Negocia um "contrato de sprint" com o Avaliador antes de escrever código
• Usa ferramentas full-stack: React, FastAPI/Express, bancos de dados, CSS
• Gerencia git para controle de versão entre iterações
• Lê o feedback do Avaliador e o incorpora na próxima iteração

Modelo: Sonnet por padrão; aumente para GAN_GENERATOR_MODEL=opus para máxima capacidade de codificação

3. Agente Avaliador

Função: Engenheiro de QA — testa a aplicação ao vivo em execução, não apenas o código.

Comportamentos principais:

• Usa o Playwright MCP para interagir com a aplicação ao vivo
• Navega por funcionalidades, preenche formulários, testa endpoints de API
• Pontua com base em quatro critérios (configuráveis):
  1. Qualidade de Design — A aplicação parece um todo coeso?
  2. Originalidade — Decisões personalizadas vs. padrões de template/AI?
  3. Artesanato — Tipografia, espaçamento, animações, microinterações?
  4. Funcionalidade — Todas as funcionalidades realmente funcionam?
• Retorna feedback estruturado com pontuações e problemas específicos
• É projetado para ser implacavelmente rigoroso — nunca elogia trabalho medíocre

Modelo: Sonnet por padrão; aumente para GAN_EVALUATOR_MODEL=opus para julgamento mais forte + uso de ferramentas

Critérios de Avaliação

Os quatro critérios padrão, cada um pontuado de 1 a 10:

## Rubrica de Avaliação

### Qualidade de Design (peso: 0.3)
- 1-3: Genérico, parecido com template, estética de "AI slop"
- 4-6: Competente, mas sem destaque, segue convenções
- 7-8: Identidade visual distinta e coesa
- 9-10: Poderia passar pelo trabalho de um designer profissional

### Originalidade (peso: 0.2)
- 1-3: Cores padrão, layouts comuns, sem personalidade
- 4-6: Algumas escolhas personalizadas, principalmente padrões comuns
- 7-8: Visão criativa clara, abordagem única
- 9-10: Surpreendente, encantador, genuinamente inovador

### Artesanato (peso: 0.3)
- 1-3: Layouts quebrados, estados ausentes, sem animações
- 4-6: Funciona, mas parece bruto, espaçamento inconsistente
- 7-8: Polido, transições suaves, responsivo
- 9-10: Perfeição de pixel, microinterações encantadoras

### Funcionalidade (peso: 0.2)
- 1-3: Funcionalidades principais quebradas ou ausentes
- 4-6: Caminho feliz funciona, casos de borda falham
- 7-8: Todas as funcionalidades funcionam, bom tratamento de erros
- 9-10: À prova de balas, lida com todos os casos de borda

Pontuação

• Pontuação ponderada = soma de (pontuação_do_critério * peso)
• Limiar de aprovação = 7.0 (configurável)
• Máximo de iterações = 15 (configurável, normalmente 5-15 são suficientes)

Uso

Via Comando

# Arnes completo de três agentes
/project:gan-build "Construa um aplicativo de gerenciamento de projetos com quadros Kanban, colaboração em equipe e modo escuro"

# Com configuração personalizada
/project:gan-build "Construa uma plataforma de compartilhamento de receitas" --max-iterations 10 --pass-threshold 7.5

# Modo de design frontend (apenas gerador + avaliador, sem planejador)
/project:gan-design "Crie uma landing page para um rastreador de portfólio de criptomoedas"

Via Script Shell

# Uso básico
./scripts/gan-harness.sh "Construa um dashboard de streaming de música"

# Com opções
GAN_MAX_ITERATIONS=10 \
GAN_PASS_THRESHOLD=7.5 \
GAN_EVAL_CRITERIA="functionality,performance,security" \
./scripts/gan-harness.sh "Construa uma API REST para gerenciamento de tarefas"

Via Claude Code (Manual)

# Passo 1: Planejar
claude -p --model sonnet "Você é um Planejador de Produto. Leia PLANNER_PROMPT.md. Expanda este resumo em uma especificação completa do produto: 'Construa um aplicativo de quadro Kanban'. Escreva a especificação em spec.md"

# Passo 2: Gerar (iteração 1)
claude -p --model sonnet "Você é um Gerador. Leia spec.md. Implemente o Sprint 1. Inicie o servidor de desenvolvimento na porta 3000."

# Passo 3: Avaliar (iteração 1)
claude -p --model sonnet --allowedTools "Read,Bash,mcp__playwright__*" "Você é um Avaliador. Leia EVALUATOR_PROMPT.md. Teste a aplicação ao vivo em http://localhost:3000. Pontue de acordo com a rubrica. Escreva o feedback em feedback-001.md"

# Passo 4: Gerar (iteração 2 — lê o feedback)
claude -p --model sonnet "Você é um Gerador. Leia spec.md e feedback-001.md. Resolva todos os problemas. Melhore as pontuações."

# Repita os passos 3-4 até que o limiar de aprovação seja atingido

Evolução ao Longo das Capacidades dos Modelos

O arnes deve simplificar à medida que os modelos melhoram. Seguindo a evolução da Anthropic:

Estágio 1 — Modelos Mais Fracos (Classe Sonnet)

• Decomposição completa em sprints necessária
• Reinicialização de contexto entre sprints (evitar ansiedade de contexto)
• Mínimo de 2 agentes: Inicializador + Agente de Codificação
• Andaime pesado compensa as limitações do modelo

Estágio 2 — Modelos Capazes (Classe Opus 4.5)

• Arnes completo de 3 agentes: Planejador + Gerador + Avaliador
• Contratos de sprint antes de cada fase de implementação
• Decomposição em 10 sprints para aplicações complexas
• Reinicialização de contexto ainda útil, mas menos crítica

Estágio 3 — Modelos de Fronteira (Classe Opus 4.6)

• Arnes simplificado: única passagem de planejamento, geração contínua
• Avaliação reduzida a uma única passagem final (o modelo é mais inteligente)
• Nenhuma estrutura de sprint necessária
• Compactação automática lida com o crescimento do contexto

Princípio-chave: Cada componente do arnes codifica uma suposição sobre o que o modelo não pode fazer sozinho. Quando os modelos melhoram, re-teste essas suposições. Elimine o que não for mais necessário.

Configuração

Variáveis de Ambiente

Variável	Padrão	Descrição
GAN_MAX_ITERATIONS	15	Ciclos máximos gerador-avaliador
GAN_PASS_THRESHOLD	7.0	Pontuação ponderada para aprovação (1-10)
GAN_PLANNER_MODEL	sonnet	Modelo para o agente planejador
GAN_GENERATOR_MODEL	sonnet	Modelo para o agente gerador
GAN_EVALUATOR_MODEL	sonnet	Modelo para o agente avaliador
GAN_EVAL_CRITERIA	design,originality,craft,functionality	Critérios separados por vírgula
GAN_DEV_SERVER_PORT	3000	Porta para a aplicação ao vivo
GAN_DEV_SERVER_CMD	npm run dev	Comando para iniciar o servidor de desenvolvimento
GAN_PROJECT_DIR	.	Diretório de trabalho do projeto
GAN_SKIP_PLANNER	false	Pular o planejador, usar especificação diretamente
GAN_EVAL_MODE	playwright	playwright, screenshot ou code-only

Modos de Avaliação

Modo	Ferramentas	Melhor Para
playwright	MCP do Navegador + interação ao vivo	Aplicações full-stack com UI
screenshot	Captura de tela + análise visual	Sites estáticos, apenas design
code-only	Testes + linting + build	APIs, bibliotecas, ferramentas CLI

Anti-Padrões

1. Avaliador muito leniente — Se o avaliador aprovar tudo na iteração 1, sua rubrica é muito generosa. Aperte os critérios de pontuação e adicione penalidades explícitas para padrões comuns de IA.

2. Gerador ignorando feedback — Garanta que o feedback seja passado como um arquivo, não inline. O gerador deve ler feedback-NNN.md no início de cada iteração.

3. Loops infinitos — Sempre defina GAN_MAX_ITERATIONS. Se o gerador não conseguir melhorar após um platô de pontuação por 3 iterações, pare e sinalize para revisão humana.

4. Avaliador testando superficialmente — O avaliador deve usar o Playwright para interagir com a aplicação ao vivo, não apenas capturar tela. Clique em botões, preencha formulários, teste estados de erro.

5. Avaliador elogiando suas próprias correções — Nunca deixe o avaliador sugerir correções e depois avaliar essas correções. O avaliador apenas critica; o gerador corrige.

6. Exaustão de contexto — Para sessões longas, use a compactação automática do Claude Agent SDK ou reinicie o contexto entre fases principais.

Resultados: O Que Esperar

Com base nos resultados publicados pela Anthropic:

Métrica	Agente Único	Arnes GAN	Melhoria
Tempo	20 min	4-6 horas	12-18x mais longo
Custo	US$ 9	US$ 125-200	14-22x mais caro
Qualidade	Mal funcional	Pronto para produção	Mudança de fase
Funcionalidades principais	Quebradas	Todas funcionando	N/A
Design	AI slop genérico	Distinto, polido	N/A

A troca é clara: cerca de 20x mais tempo e custo para um salto qualitativo na qualidade da saída. Isso é para projetos onde a qualidade importa.

Referências

• Anthropic: Harness Design for Long-Running Apps — Artigo original de Prithvi Rajasekaran
• Epsilla: The GAN-Style Agent Loop — Deconstrução da arquitetura
• Martin Fowler: Harness Engineering — Contexto mais amplo do setor
• OpenAI: Harness Engineering — Trabalho paralelo da OpenAI