Arquitetando AI Agents de Alta Velocidade: Lições do Release 0.30.0

Tem dias em que tudo flui. O contexto está fresco, as decisões são rápidas, o código sai limpo. E tem dias em que você está tentando fazer um AI agent verificar uma interface no browser, o loop de feedback está quebrado, e você percebe que o problema não é o modelo — é a arquitetura ao redor dele. O release 0.30.0 do meu projeto de developer tools foi um divisor de águas exatamente porque forcei um encontro com esse segundo tipo de dia. Neste artigo, quero compartilhar o que aprendi sobre construir feedback loops confiáveis em agentes de código com Claude Code, especialmente no contexto de verificação browser-based e auditorias de design automatizadas.

O Problema: Agents Sem Chão Firme

A promessa dos AI coding agents é poderosa: você descreve uma tarefa, o agente executa uma sequência de ações, verifica o resultado e itera. Na prática, o ponto mais frágil dessa cadeia é justamente a verificação. Quando o agente escreve código backend, verificar o output é relativamente direto — você roda os testes, lê o stdout, compara o resultado com um schema esperado. Mas quando o domínio é frontend, a coisa complica.

No meu caso, eu queria que o agente conseguisse:

1. Implementar uma mudança de UI (reorganizar componentes, ajustar espaçamentos, padronizar labels)
2. Renderizar a aplicação em um browser real
3. Capturar evidências visuais do resultado
4. Comparar com um critério de aceitação de design
5. Iterar se necessário

O loop parece simples. Mas sem uma estrutura cuidadosa, o agente entra em colapso silencioso: ele acredita que completou a tarefa porque não recebeu nenhum erro — mas ninguém verificou de fato o que foi renderizado.

Isso me ensinou a primeira grande lição: um agente sem feedback explícito e estruturado é um agente que alucina completude.

Construindo o Loop de Feedback: A Arquitetura que Funcionou

Depois de algumas iterações frustradas, cheguei a uma arquitetura em três camadas para o feedback loop do agente. Vou descrever em Python, que é onde faço a orquestração, com TypeScript aparecendo na camada de verificação browser.

Camada 1: O Orquestrador em Python

O orquestrador é responsável por definir a tarefa, invocar o agente, e processar o resultado de cada ciclo. Uso uma estrutura simples de dataclass para representar o estado do ciclo:

from dataclasses import dataclass, field
from typing import Optional
import subprocess
import json

@dataclass
class AgentCycle:
    task_description: str
    acceptance_criteria: list[str]
    max_iterations: int = 5
    current_iteration: int = 0
    verification_results: list[dict] = field(default_factory=list)
    completed: bool = False

def run_agent_cycle(cycle: AgentCycle) -> AgentCycle:
    while not cycle.completed and cycle.current_iteration < cycle.max_iterations:
        cycle.current_iteration += 1
        print(f"[Iteration {cycle.current_iteration}] Running agent...")

        # Invoca o agente (Claude Code via CLI ou SDK)
        agent_result = invoke_agent(
            task=cycle.task_description,
            context=build_context(cycle)
        )

        # Roda verificação após cada ação do agente
        verification = verify_output(cycle.acceptance_criteria)
        cycle.verification_results.append(verification)

        if verification["passed"]:
            cycle.completed = True
            print(f"[Iteration {cycle.current_iteration}] ✓ All criteria met.")
        else:
            failed = [c for c in verification["criteria"] if not c["passed"]]
            print(f"[Iteration {cycle.current_iteration}] ✗ {len(failed)} criteria failed. Continuing...")
            # Atualiza a task com o contexto do que falhou
            cycle.task_description = enrich_task_with_failures(
                cycle.task_description,
                failed
            )

    return cycle

def enrich_task_with_failures(original_task: str, failed_criteria: list[dict]) -> str:
    failure_summary = "\n".join(
        f"- AINDA PENDENTE: {c['description']} (encontrado: {c['actual']}, esperado: {c['expected']})"
        for c in failed_criteria
    )
    return f"{original_task}\n\nCritérios ainda não atendidos:\n{failure_summary}"

O ponto crítico aqui é o enrich_task_with_failures. Em vez de simplesmente re-executar a mesma tarefa, eu realimento o agente com evidências concretas do que ainda está errado. Isso evita que ele fique em loop tentando a mesma abordagem.

Camada 2: Verificação Browser com TypeScript

Para a verificação visual, uso um script TypeScript com Playwright que captura screenshots e extrai métricas de UI:

import { chromium, Browser, Page } from 'playwright';
import * as fs from 'fs';

interface VerificationCriteria {
  selector: string;
  property: string;
  expected: string;
  description: string;
}

interface CriterionResult {
  description: string;
  passed: boolean;
  actual: string;
  expected: string;
}

interface VerificationReport {
  passed: boolean;
  screenshotPath: string;
  criteria: CriterionResult[];
  timestamp: string;
}

async function runBrowserVerification(
  url: string,
  criteria: VerificationCriteria[]
): Promise<VerificationReport> {
  const browser: Browser = await chromium.launch();
  const page: Page = await browser.newPage();

  await page.goto(url, { waitUntil: 'networkidle' });

  const results: CriterionResult[] = [];

  for (const criterion of criteria) {
    const element = page.locator(criterion.selector);
    let actual = '';

    try {
      if (criterion.property === 'text') {
        actual = await element.innerText();
      } else if (criterion.property === 'visible') {
        actual = String(await element.isVisible());
      } else {
        // CSS properties
        actual = await element.evaluate(
          (el, prop) => getComputedStyle(el).getPropertyValue(prop),
          criterion.property
        );
      }

      results.push({
        description: criterion.description,
        passed: actual.trim() === criterion.expected.trim(),
        actual: actual.trim(),
        expected: criterion.expected.trim(),
      });
    } catch (err) {
      results.push({
        description: criterion.description,
        passed: false,
        actual: `ERROR: ${err}`,
        expected: criterion.expected,
      });
    }
  }

  const screenshotPath = `verification-${Date.now()}.png`;
  await page.screenshot({ path: screenshotPath, fullPage: true });
  await browser.close();

  return {
    passed: results.every(r => r.passed),
    screenshotPath,
    criteria: results,
    timestamp: new Date().toISOString(),
  };
}

// Entry point: lê critérios do stdin, escreve report no stdout
async function main() {
  const input = JSON.parse(process.argv[2]);
  const report = await runBrowserVerification(input.url, input.criteria);
  console.log(JSON.stringify(report, null, 2));
}

main().catch(console.error);

Esse script é invocado pelo orquestrador Python via subprocess, e o report JSON retornado alimenta diretamente a função verify_output. O screenshot vai para um diretório de evidências que eu posso consultar quando algo der errado.

Camada 3: Auditoria de Design como Critério Estruturado

Uma das partes mais valiosas desse release foi formalizar o que chamo de "design audit criteria" — critérios de aceitação que vão além de "o componente existe" e chegam em "o componente se comporta conforme o design system".

from typing import TypedDict

class DesignCriterion(TypedDict):
    selector: str
    property: str
    expected: str
    description: str

def build_design_audit_criteria(audit_spec: dict) -> list[DesignCriterion]:
    """
    Converte uma spec de auditoria de design em critérios verificáveis.

    Exemplo de audit_spec:
    {
        "typography": {
            "page-title": {"font-size": "24px", "font-weight": "600"},
        },
        "labels": {
            "pipeline-stage-label": {"text": "Opportunity"}
        },
        "visibility": {
            "billing-status-indicator": {"visible": "true"}
        }
    }
    """
    criteria: list[DesignCriterion] = []

    for category, elements in audit_spec.items():
        for selector, properties in elements.items():
            for prop, expected in properties.items():
                criteria.append(DesignCriterion(
                    selector=f"[data-testid='{selector}']",
                    property=prop,
                    expected=str(expected),
                    description=f"[{category}] {selector}: {prop} deve ser '{expected}'"
                ))

    return criteria

# Exemplo de uso
audit_spec = {
    "labels": {
        "pipeline-stage-label": {"text": "Opportunity"},
        "billing-log-status": {"text": "Paid"},
    },
    "typography": {
        "section-header": {"font-size": "18px"},
    },
    "visibility": {
        "dispute-indicator": {"visible": "true"},
    }
}

criteria = build_design_audit_criteria(audit_spec)
print(f"Auditoria com {len(criteria)} critérios gerada.")

Essa estrutura me deu algo que eu não tinha antes: uma linguagem comum entre o que eu quero que o agente faça e como eu verifico que ele fez. Sem isso, a auditoria é subjetiva e o agente não tem como saber se acertou.

O Que Aprendi Sobre Claude Code nesse Contexto

Trabalhar com Claude Code como o "cérebro" do agente me ensinou algumas coisas específicas sobre como estruturar as instruções.

Seja cirúrgico no contexto. Quando o agente precisa fazer uma mudança de UI — como padronizar um label de vocabulário em vários componentes — quanto mais específico for o contexto fornecido, melhor. Em vez de dizer "padronize os labels de pipeline", funciona melhor dizer: "os componentes PipelineCard, StageFilter e OpportunityBadge usam a string 'lead' em alguns lugares e 'opportunity' em outros. Padronize para 'opportunity' em todos eles."

Feedback de falha é mais valioso que confirmação de sucesso. Quando o verificador browser retorna que um critério falhou, incluir o valor atual junto com o valor esperado no prompt do próximo ciclo corta o número de iterações necessárias pela metade, na minha experiência.

Separe geração de verificação. Uma armadilha clássica é pedir que o agente verifique o próprio trabalho. Isso é como pedir ao programador que faça o próprio code review logo depois de escrever o código — o viés de confirmação entra em ação. A verificação precisa ser uma camada independente, idealmente determinística (testes, screenshots, métricas extraídas do DOM).

Dicas Práticas para Quem Está Construindo Algo Parecido

• Comece com critérios simples e expansão progressiva. No primeiro ciclo, verifique apenas se a aplicação carrega sem erros de console. Adicione critérios de design e comportamento nas iterações seguintes. Agentes que tentam satisfazer 20 critérios de uma vez tendem a falhar em todos eles.

• Use data-testid como contrato. Se o seu frontend usa data-testid de forma consistente, o verificador browser tem um target estável mesmo quando o layout muda. Convenci o agente a adicionar esses atributos como parte da tarefa de implementação, não como afterthought.

• Versione os reports de verificação. Cada execução do loop gera um JSON de verificação e um screenshot. Manter esses artefatos me salvou várias vezes quando precisei entender por que um ciclo específico falhou.

• Defina um budget de iterações e seja honesto sobre falha. Se o agente não satisfez os critérios em N iterações, não é útil continuar em loop. Marque como falha, logue os critérios pendentes, e escale para revisão humana. Agentes que nunca falham explicitamente são agentes que escondem problemas.

• Teste sua pipeline de verificação sem o agente primeiro. Antes de integrar Claude Code, rode o verificador browser manualmente com critérios que você sabe que passam e critérios que você sabe que falham. Se o verificador não é confiável, o agente vai otimizar para uma métrica errada.

Conclusão

O release 0.30.0 foi significativo não pelo número de features que shipper, mas pela mudança de mentalidade que forçou. Eu parei de pensar em AI agents como "ferramentas que fazem coisas" e comecei a pensar neles como processos que precisam de observabilidade. O loop de feedback não é um detalhe de implementação — é a arquitetura central.

Verificação browser-based ainda é difícil. Flakiness, timing issues, estados de UI que dependem de autenticação — há muitos problemas não resolvidos. Mas a estrutura de três camadas (orquestrador Python, verificador TypeScript/Playwright, critérios de design estruturados) me deu uma base sólida para iterar.

Se você está construindo agentes de código e ainda não tem uma camada de verificação independente, esse é o investimento mais valioso que pode fazer. O modelo é bom. O que frequentemente falha é a infraestrutura ao redor dele.