gan-style-harness

Habilidade GAN-Style Harness

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

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

Ideia Central

Quando solicitados a avaliar o próprio trabalho, agentes são otimistas patológicos — elogiam resultados medíocres e se convencem de que problemas legítimos não existem. 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 prompt 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 "IA genérica" seja inaceitável
• Projetos onde você deseja investir $50-200 por um resultado de qualidade profissional

Quando NÃO Usar

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

Arquitetura

                    ┌─────────────┐
                    │   PLANNER   │
                    │  (Sonnet)   │
                    └──────┬──────┘
                           │ Especificação do Produto
                           │ (funcionalidades, sprints, direção de design)
                           ▼
              ┌────────────────────────┐
              │                        │
              │   LOOP DE FEEDBACK     │
              │   GERADOR-AVALIADOR    │
              │                        │
              │  ┌──────────┐          │
              │  │ GERADOR  │--constrói-->│──┐
              │  │ (Sonnet) │          │  │
              │  └────▲─────┘          │  │
              │       │                │  │ app 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 prompt resumido em uma especificação completa do produto.

Comportamentos principais:

• Recebe um prompt 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 abaixo do esperado
• Produz critérios de avaliação que o Avaliador usará posteriormente

Modelo: Sonnet por padrão; aumente para GAN_PLANNER_MODEL=opus para expandir a especificação com mais profundidade

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 em execução, não apenas o código.

Comportamentos principais:

• Usa Playwright MCP para interagir com a aplicação ao vivo
• Clica nas funcionalidades, preenche formulários, testa endpoints de API
• Pontua com base em quatro critérios (configuráveis):
  1. Qualidade do Design — Parece um todo coeso?
  2. Originalidade — Decisões personalizadas vs. padrões de template/IA?
  3. Acabamento — 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 e uso de ferramentas mais fortes

Critérios de Avaliação

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

## Rubrica de Avaliação

### Qualidade do Design (peso: 0.3)
- 1-3: Genérico, semelhante a template, estética de "IA genérica"
- 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 prontos, sem personalidade
- 4-6: Algumas escolhas personalizadas, maioria dos padrões comuns
- 7-8: Visão criativa clara, abordagem única
- 9-10: Surpreendente, encantador, genuinamente novo

### Acabamento (peso: 0.3)
- 1-3: Layouts quebrados, estados ausentes, sem animações
- 4-6: Funciona, mas parece áspero, espaçamento inconsistente
- 7-8: Polido, transições suaves, responsivo
- 9-10: Perfeito em pixels, microinterações encantadoras

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

Pontuação

• Pontuação ponderada = soma de (pontuação_do_critério * peso)
• Limite de aprovação = 7.0 (configurável)
• Iterações máximas = 15 (configurável, normalmente 5-15 são suficientes)

Uso

Via Comando

# Harness 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 página de destino para um rastreador de portfólio de criptomoedas"

Via Script Shell

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

# Com opções
GAN_MAX_ITERATIONS=10 \
GAN_PASS_THRESHOLD=7.5 \
GAN_EVAL_CRITERIA="funcionalidade,desempenho,segurança" \
./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 de 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 o aplicativo 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é atingir o limite de aprovação

Evolução com as Capacidades dos Modelos

O harness deve ser simplificado à 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)

• Harness 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)

• Harness simplificado: uma ú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 harness codifica uma suposição sobre o que o modelo não pode fazer sozinho. Quando os modelos melhoram, reteste essas suposições. Remova 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,originalidade,acabamento,funcionalidade	Critérios separados por vírgula
GAN_DEV_SERVER_PORT	3000	Porta para o aplicativo 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 a especificação diretamente
GAN_EVAL_MODE	playwright	playwright, screenshot, ou code-only

Modos de Avaliação

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

Antipadrões

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

2. Gerador ignorando feedback — Certifique-se de 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 3 iterações de platô de pontuação, pare e sinalize para revisão humana.

4. Avaliador testando superficialmente — O avaliador deve usar o Playwright para interagir com o aplicativo ao vivo, não apenas capturar sua 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 redefina o contexto entre as fases principais.

Resultados: O que Esperar

Com base nos resultados publicados pela Anthropic:

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

A troca é clara: ~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 por Prithvi Rajasekaran
• Epsilla: The GAN-Style Agent Loop — Decomposição da arquitetura
• Martin Fowler: Harness Engineering — Contexto mais amplo da indústria
• OpenAI: Harness Engineering — Trabalho paralelo da OpenAI