Harness Engineering e Orquestração de Agentes de Código

    A [Recebe a tarefa] --> B [Pensa no próximo passo]
    B --> C {Precisa de uma ferramenta?}
    C -- Sim --> D [Executa: lê arquivo, edita, roda testes]
    D --> E [Observa o resultado]
    E --> B
    C -- Não --> F [Entrega a resposta final]

MindMap
  root((Harness))
    Guias
      AGENTS.md
      Skills
      Documentação do projeto
      Exemplos de código
    Sensores
      Testes automatizados
      Testes de arquitetura
      Linters e formatadores
      Revisão por outro agente
    Ferramentas
      Ler e escrever arquivos
      Build e testes
      MCP e integrações
    Segurança
      Sandbox
      Permissões
      Hooks bloqueantes
      Limite de passos
    Orquestração
      Sub-agentes
      Paralelismo
      Avaliador

contas/
├── AGENTS.md                          # guia inferencial: as regras da casa
├── CLAUDE.md                          # importa o AGENTS.md (para o Claude Code)
├── .claude/
│   ├── settings.json                  # hooks: sensores automáticos
│   └── agents/
│       └── revisor-arquitetura.md     # sub-agente revisor
├── harness/
│   ├── verify.sh                      # sensor computacional único
│   ├── bloquear-arquivos-sensiveis.sh # guarda de segurança
├── pom.xml
└── src/
    ├── main/java/com/exemplo/contas/
    │   ├── dominio/                   # Java puro, sem framework
    │   ├── aplicacao/
    │   │   └── porta/{entrada,saida}/
    │   └── adaptador/
    │       ├── web/
    │       └── persistencia/
    └── test/java/com/exemplo/contas/
        └── ArquiteturaHexagonalTest.java

# Serviço de Contas
Serviço de contas e transferências. Java 25, Spring Boot 4.1, Maven, PostgreSQL.
## Comandos
- Verificação rápida (rode a cada mudança): `./harness/verify.sh quick`
- Verificação completa (rode antes de concluir): `./harness/verify.sh full`
- Nunca finalize uma tarefa com a verificação completa falhando.
## Arquitetura (Hexagonal)
- `dominio`: Java puro. Proibido importar Spring, Jakarta ou Jackson.
- `aplicacao`: casos de uso. Depende só de `dominio` e das portas.
- `adaptador`: web e persistência. Adaptadores não se conhecem entre si.
- Uma dependência nova entre camadas é quase sempre um erro de desenho.
  Revise a direção da seta antes de continuar.
## Convenções
- Injeção de dependência sempre por construtor. Nunca `@Autowired` em campo.
- Objetos de valor e DTOs são `record`.
- Resultados esperados de negócio usam tipos selados (`sealed`), não exceções.
- Dinheiro é `BigDecimal`. Nunca `double`.
- Um teste novo para cada comportamento novo.
## Proibido sem autorização humana
- Editar `application-prod.yml`, arquivos `.env` ou a pasta `harness/`.
- Adicionar dependência ao `pom.xml`.
- Desabilitar ou apagar testes.

@AGENTS.md

<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
    <version>1.4.1</version>
    <scope>test</scope>
</dependency>

package com.exemplo.contas;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import org.springframework.beans.factory.annotation.Autowired;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noFields;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;
@AnalyzeClasses(
        packages = "com.exemplo.contas",
        importOptions = ImportOption.DoNotIncludeTests.class)
class ArquiteturaHexagonalTest {
    @ArchTest
    static final ArchRule dominio_nao_depende_de_framework =
            noClasses().that().resideInAPackage("..dominio..")
                    .should().dependOnClassesThat().resideInAnyPackage(
                            "org.springframework..", "jakarta..",
                            "tools.jackson..", "com.fasterxml..")
                    .because("O domínio é Java puro. Se precisar de algo do framework, "
                            + "crie uma porta em aplicacao.porta e implemente no adaptador.");
    @ArchTest
    static final ArchRule aplicacao_nao_conhece_adaptadores =
            noClasses().that().resideInAPackage("..aplicacao..")
                    .should().dependOnClassesThat().resideInAPackage("..adaptador..")
                    .because("A seta de dependência aponta sempre para dentro: "
                            + "adaptador -> aplicacao -> dominio. Use uma porta de saída.");
    @ArchTest
    static final ArchRule adaptadores_nao_se_conhecem =
            slices().matching("..adaptador.(*)..")
                    .should().notDependOnEachOther()
                    .because("Web não fala direto com persistência. "
                            + "A conversa passa pelo caso de uso.");
    @ArchTest
    static final ArchRule sem_injecao_por_campo =
            noFields().should().beAnnotatedWith(Autowired.class)
                    .because("Use injeção por construtor.");
}

#!/usr/bin/env bash
# harness/verify.sh
set -euo pipefail
cd "$(dirname "$0")/.."
modo="${1:-quick}"
case "$modo" in
  quick)
    ./mvnw -q spotless:check
    ./mvnw -q -Dtest=ArquiteturaHexagonalTest \
      -Dsurefire.failIfNoSpecifiedTests=false test
    ;;
  full)
    ./mvnw -q spotless:check verify
    ;;
  *)
    echo "Uso: verify.sh [quick|full]" >&2
    exit 64
    ;;
esac

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/harness/bloquear-arquivos-sensiveis.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/harness/verify.sh quick 1>&2 || exit 2"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# harness/bloquear-arquivos-sensiveis.sh
set -euo pipefail
entrada="$(cat)"
caminho="$(jq -r '.tool_input.file_path // .tool_input.path // empty' <<< "$entrada")"
case "$caminho" in
  .env|.env.*|*/.env|*/.env.*|application-prod.yml|*/application-prod.yml|harness/*|*/harness/*)
    echo "BLOQUEADO: '$caminho' é protegido. Peça autorização humana." >&2
    exit 2
    ;;
esac
exit 0

---
name: revisor-arquitetura
description: Revisa mudanças de código quanto a arquitetura hexagonal, legibilidade e testes. Use proativamente depois de implementar qualquer funcionalidade.
tools: Read, Grep, Glob
---
Você é um revisor sênior de Java e Spring. Você NÃO edita código nem executa comandos; apenas revisa o diff fornecido na tarefa.
1. Analise as alterações e identifique os arquivos afetados.
2. Verifique: a regra de negócio está no domínio? Há lógica em controllers?
   Os testes cobrem o comportamento novo, inclusive casos de borda?
3. Responda neste formato:
   - APROVADO ou REPROVADO
   - Lista curta de problemas, cada um com arquivo, linha e sugestão objetiva.

Architecture Violation: Rule 'no classes that reside in a package '..aplicacao..'
should depend on classes that reside in a package '..adaptador..', because A seta de
dependência aponta sempre para dentro: adaptador -> aplicacao -> dominio.
Use uma porta de saída.' was violated (1 times):
Class <com.exemplo.contas.aplicacao.TransferenciaService> depends on
<com.exemplo.contas.adaptador.persistencia.ContaJpaRepository>

package com.exemplo.contas.dominio;
import java.math.BigDecimal;
import java.util.Objects;
import java.util.UUID;
public record Conta(UUID id, String titular, BigDecimal saldo) {
    public Conta {
        Objects.requireNonNull(id);
        Objects.requireNonNull(titular);
        Objects.requireNonNull(saldo);
        if (saldo.signum() < 0) {
            throw new IllegalArgumentException("Saldo inicial não pode ser negativo");
        }
    }
    public Conta debitar(BigDecimal valor) {
        validarValor(valor);
        if (saldo.compareTo(valor) < 0) {
            throw new SaldoInsuficienteException(id);
        }
        return new Conta(id, titular, saldo.subtract(valor));
    }
    public Conta creditar(BigDecimal valor) {
        validarValor(valor);
        return new Conta(id, titular, saldo.add(valor));
    }
    private static void validarValor(BigDecimal valor) {
        if (valor == null || valor.signum() <= 0) {
            throw new IllegalArgumentException("Valor deve ser positivo");
        }
    }
}

    subgraph P1 [1. Encadeamento]
      direction LR
      a1[Especificar] --> a2[Implementar] --> a3[Testar] --> a4[Documentar]
    end
    subgraph P2[2. Orquestrador e workers]
      direction TB
      o[Orquestrador] --> w1[Worker: API]
      o --> w2[Worker: Persistência]
      o --> w3[Worker: Testes]
    end
    subgraph P3[3. Gerador e avaliador]
      direction LR
      g[Gerador] --> av[Avaliador]
      av -- reprovado + motivo --> g
      av -- aprovado --> fim[Entrega]
    end

# Execute a partir do checkout principal; cada worker recebe uma pasta e branch.
git worktree add ../contas-api -b agente/api
git worktree add ../contas-persistencia -b agente/persistencia

# Revise e integre uma branch por vez, validando o estado combinado.
# Troque `main` pelo nome da branch principal do seu repositório, se necessário.
git switch main
git merge --no-ff agente/api
./mvnw verify
git merge --no-ff agente/persistencia
./mvnw verify

# Só remova os worktrees depois de integrar e guardar o que precisa ser preservado.
git worktree remove ../contas-api
git worktree remove ../contas-persistencia

src/main/java/com/exemplo/harness/
├── nucleo/
│   ├── Mensagem.java
│   ├── Passo.java
│   ├── Modelo.java
│   ├── DefinicaoFerramenta.java
│   ├── Ferramenta.java
│   ├── Guardrail.java
│   ├── ResultadoAgente.java
│   └── LoopDoAgente.java
├── ferramentas/
│   ├── Workspace.java
│   ├── LerArquivo.java
│   ├── EscreverArquivo.java
│   └── ExecutarVerificacao.java
├── guardrails/
│   └── CaminhosProibidos.java
├── orquestracao/
│   ├── Planejador.java
│   ├── Avaliador.java
│   ├── Veredito.java
│   ├── Relatorio.java
│   ├── FabricaDeWorkers.java
│   └── Orquestrador.java
└── config/
    ├── HarnessProperties.java
    ├── HarnessConfig.java
    └── OrquestracaoController.java

package com.exemplo.harness.nucleo;
public record Mensagem(Papel papel, String conteudo) {
    public enum Papel { USUARIO, ASSISTENTE, FERRAMENTA }
}

package com.exemplo.harness.nucleo;
import java.util.Map;
public sealed interface Passo {
    record ChamarFerramenta(String ferramenta, Map<String, String> argumentos) implements Passo {}
    record Concluir(String resposta) implements Passo {}
}

package com.exemplo.harness.nucleo;
import java.util.List;
/** O "cérebro". Em produção é um adaptador para um provedor de IA. */
public interface Modelo {
    Passo proximoPasso(List<Mensagem> historico,
                       List<DefinicaoFerramenta> ferramentasDisponiveis);
}

package com.exemplo.harness.nucleo;
public record DefinicaoFerramenta(String nome, String descricao) {}

package com.exemplo.harness.nucleo;
import java.util.Map;
/** As "mãos" do agente. */
public interface Ferramenta {
    String nome();
    String descricao();
    String executar(Map<String, String> argumentos) throws Exception;
}

package com.exemplo.harness.nucleo;
import java.util.Optional;
/** Um guarda que pode vetar uma chamada de ferramenta antes de ela acontecer. */
@FunctionalInterface
public interface Guardrail {
    /** Retorna o motivo do bloqueio, ou vazio se a chamada está liberada. */
    Optional<String> verificar(Passo.ChamarFerramenta chamada);
}

package com.exemplo.harness.nucleo;
public sealed interface ResultadoAgente {
    record Sucesso(String resposta, int passos) implements ResultadoAgente {}
    record Falha(String motivo, int passos) implements ResultadoAgente {}
}

package com.exemplo.harness.nucleo;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;
import static com.exemplo.harness.nucleo.Mensagem.Papel.ASSISTENTE;
import static com.exemplo.harness.nucleo.Mensagem.Papel.FERRAMENTA;
import static com.exemplo.harness.nucleo.Mensagem.Papel.USUARIO;
public final class LoopDoAgente {
    private static final int LIMITE_SAIDA = 4_000;
    private final Modelo modelo;
    private final Map<String, Ferramenta> ferramentas;
    private final List<Guardrail> guardrails;
    private final List<DefinicaoFerramenta> definicoes;
    private final int maxPassos;
    public LoopDoAgente(Modelo modelo, List<Ferramenta> ferramentas,
                        List<Guardrail> guardrails, int maxPassos) {
        if (maxPassos < 1) {
            throw new IllegalArgumentException("maxPassos deve ser maior que zero");
        }
        this.modelo = modelo;
        this.ferramentas = ferramentas.stream()
                .collect(Collectors.toUnmodifiableMap(Ferramenta::nome, Function.identity()));
        this.guardrails = List.copyOf(guardrails);
        this.definicoes = this.ferramentas.values().stream()
                .map(f -> new DefinicaoFerramenta(f.nome(), f.descricao()))
                .toList();
        this.maxPassos = maxPassos;
    }
    public ResultadoAgente executar(String tarefa) {
        var historico = new ArrayList<Mensagem>();
        historico.add(new Mensagem(USUARIO, tarefa));
        for (int passo = 1; passo <= maxPassos; passo++) {
            Passo proximo = modelo.proximoPasso(List.copyOf(historico), definicoes);
            switch (proximo) {
                case Passo.Concluir c -> {
                    historico.add(new Mensagem(ASSISTENTE, c.resposta()));
                    return new ResultadoAgente.Sucesso(c.resposta(), passo);
                }
                case Passo.ChamarFerramenta chamada -> {
                    historico.add(new Mensagem(ASSISTENTE,
                            "Chamada de ferramenta: " + chamada.ferramenta()
                                    + "; argumentos=" + chamada.argumentos()));
                    String resultado = processar(chamada);
                    historico.add(new Mensagem(FERRAMENTA,
                            "Resultado de " + chamada.ferramenta() + ": " + resultado));
                }
            }
        }
        return new ResultadoAgente.Falha(
                "Limite de " + maxPassos + " passos atingido", maxPassos);
    }
    private String processar(Passo.ChamarFerramenta chamada) {
        for (Guardrail guardrail : guardrails) {
            var motivo = guardrail.verificar(chamada);
            if (motivo.isPresent()) {
                return "BLOQUEADO: " + motivo.get();
            }
        }
        var ferramenta = ferramentas.get(chamada.ferramenta());
        if (ferramenta == null) {
            return "ERRO: ferramenta desconhecida. Disponíveis: " + ferramentas.keySet();
        }
        try {
            return truncar(ferramenta.executar(chamada.argumentos()));
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return "ERRO: execução interrompida";
        } catch (Exception e) {
            return "ERRO: " + e.getMessage();
        }
    }
    private static String truncar(String texto) {
        if (texto == null) {
            return "ERRO: a ferramenta retornou null";
        }
        return texto.length() <= LIMITE_SAIDA
                ? texto
                : texto.substring(0, LIMITE_SAIDA) + "\n[... saída truncada ...]";
    }
}

package com.exemplo.harness.ferramentas;
import java.nio.file.Path;
public final class Workspace {
    private final Path raiz;
    public Workspace(Path raiz) {
        this.raiz = raiz.toAbsolutePath().normalize();
    }
    public Path raiz() {
        return raiz;
    }
    public Path resolver(String relativo) {
        if (relativo == null || relativo.isBlank()) {
            throw new IllegalArgumentException("Informe um caminho relativo ao workspace");
        }
        var alvo = raiz.resolve(relativo).normalize();
        if (!alvo.startsWith(raiz)) {
            throw new SecurityException("Caminho fora do workspace: " + relativo);
        }
        return alvo;
    }
}

package com.exemplo.harness.ferramentas;
import com.exemplo.harness.nucleo.Ferramenta;
import java.nio.file.Files;
import java.util.Map;
public final class LerArquivo implements Ferramenta {
    private final Workspace workspace;
    public LerArquivo(Workspace workspace) {
        this.workspace = workspace;
    }
    @Override public String nome() { return "ler"; }
    @Override public String descricao() { return "Lê um arquivo. Argumento: caminho (relativo ao projeto)."; }
    @Override
    public String executar(Map<String, String> args) throws Exception {
        return Files.readString(workspace.resolver(args.get("caminho")));
    }
}

package com.exemplo.harness.ferramentas;
import com.exemplo.harness.nucleo.Ferramenta;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Map;
public final class EscreverArquivo implements Ferramenta {
    private final Workspace workspace;
    public EscreverArquivo(Workspace workspace) {
        this.workspace = workspace;
    }
    @Override public String nome() { return "escrever"; }
    @Override public String descricao() {
        return "Cria ou sobrescreve um arquivo. Argumentos: caminho, conteudo.";
    }
    @Override
    public String executar(Map<String, String> args) throws Exception {
        Path destino = workspace.resolver(args.get("caminho"));
        Files.createDirectories(destino.getParent());
        Files.writeString(destino, args.get("conteudo"));
        return "OK: " + workspace.raiz().relativize(destino) + " escrito";
    }
}

package com.exemplo.harness.ferramentas;
import com.exemplo.harness.nucleo.Ferramenta;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.time.Duration;
import java.util.Map;
import java.util.concurrent.TimeUnit;
public final class ExecutarVerificacao implements Ferramenta {
    private static final int LIMITE_LOG_BYTES = 1_000_000;
    private final Workspace workspace;
    private final Duration timeout;
    public ExecutarVerificacao(Workspace workspace, Duration timeout) {
        this.workspace = workspace;
        this.timeout = timeout;
    }
    @Override public String nome() { return "verificar"; }
    @Override public String descricao() {
        return "Roda a verificação completa (build, testes, arquitetura). Sem argumentos.";
    }
    @Override
    public String executar(Map<String, String> args) throws Exception {
        // A saída vai para um arquivo temporário para o timeout funcionar
        // mesmo se o processo produzir muita saída.
        var log = Files.createTempFile("verify-", ".log");
        try {
            var processo = new ProcessBuilder("./harness/verify.sh", "full")
                    .directory(workspace.raiz().toFile())
                    .redirectErrorStream(true)
                    .redirectOutput(log.toFile())
                    .start();
            if (!processo.waitFor(timeout.toSeconds(), TimeUnit.SECONDS)) {
                processo.destroyForcibly();
                return "exit=TIMEOUT (" + timeout.toSeconds() + "s)";
            }
            byte[] bytes;
            try (var entrada = Files.newInputStream(log)) {
                bytes = entrada.readNBytes(LIMITE_LOG_BYTES);
            }
            var saida = new String(bytes, StandardCharsets.UTF_8);
            if (Files.size(log) > LIMITE_LOG_BYTES) {
                saida += "\n[saída do processo truncada]";
            }
            return "exit=" + processo.exitValue() + "\n" + saida;
        } finally {
            Files.deleteIfExists(log);
        }
    }
}

package com.exemplo.harness.guardrails;
import com.exemplo.harness.nucleo.Guardrail;
import com.exemplo.harness.nucleo.Passo;
import java.util.List;
import java.util.Optional;
/** Filtro didático complementar; não é uma fronteira de segurança. */
public record CaminhosProibidos(List<String> trechos) implements Guardrail {
    @Override
    public Optional<String> verificar(Passo.ChamarFerramenta chamada) {
        var caminho = chamada.argumentos().getOrDefault("caminho", "");
        return trechos.stream()
                .filter(caminho::contains)
                .findFirst()
                .map(trecho -> "'" + trecho + "' é protegido. Peça autorização humana.");
    }
}

package com.exemplo.harness.orquestracao;
import java.util.List;
/** Quebra um objetivo em subtarefas independentes. Em produção, costuma ser uma chamada ao modelo. */
public interface Planejador {
    List<String> dividir(String objetivo);
}

package com.exemplo.harness.orquestracao;
import com.exemplo.harness.nucleo.ResultadoAgente;
import java.util.List;
public interface Avaliador {
    Veredito avaliar(String objetivo, List<ResultadoAgente> resultados);
}

package com.exemplo.harness.orquestracao;
public sealed interface Veredito {
    record Aprovado() implements Veredito {}
    record Reprovado(String motivo) implements Veredito {}
}

package com.exemplo.harness.orquestracao;
import com.exemplo.harness.nucleo.ResultadoAgente;
import java.util.List;
public record Relatorio(boolean aprovado, int rodadas,
                        List<ResultadoAgente> resultados, String observacao) {}

package com.exemplo.harness.orquestracao;

import com.exemplo.harness.nucleo.LoopDoAgente;

@FunctionalInterface
public interface FabricaDeWorkers {
    // Deve devolver um worker ligado ao worktree exclusivo deste identificador.
    LoopDoAgente criar(String workerId);
}

package com.exemplo.harness.orquestracao;

import com.exemplo.harness.nucleo.LoopDoAgente;
import com.exemplo.harness.nucleo.ResultadoAgente;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public final class Orquestrador {

    private static final int MAX_SUBTAREFAS = 8;

    private final Planejador planejador;
    private final FabricaDeWorkers fabricaDeWorkers;
    private final Avaliador avaliador;
    private final int maxRodadas;

    public Orquestrador(Planejador planejador, FabricaDeWorkers fabricaDeWorkers,
                        Avaliador avaliador, int maxRodadas) {
        if (maxRodadas < 1) {
            throw new IllegalArgumentException("maxRodadas deve ser maior que zero");
        }
        this.planejador = planejador;
        this.fabricaDeWorkers = fabricaDeWorkers;
        this.avaliador = avaliador;
        this.maxRodadas = maxRodadas;
    }

    public Relatorio executar(String objetivo) throws InterruptedException {
        var subtarefas = planejador.dividir(objetivo);
        if (subtarefas.isEmpty() || subtarefas.size() > MAX_SUBTAREFAS) {
            throw new IllegalArgumentException(
                    "O plano deve conter de 1 a " + MAX_SUBTAREFAS + " subtarefas");
        }
        var feedback = "";
        List<ResultadoAgente> ultimos = List.of();

        for (int rodada = 1; rodada <= maxRodadas; rodada++) {
            ultimos = executarEmParalelo(subtarefas, feedback);
            switch (avaliador.avaliar(objetivo, ultimos)) {
                case Veredito.Aprovado a ->
                        return new Relatorio(true, rodada, ultimos, "Aprovado pelo avaliador");
                case Veredito.Reprovado r -> feedback = r.motivo();
            }
        }

        return new Relatorio(false, maxRodadas, ultimos,
                "Limite de rodadas atingido sem aprovação. Revisão humana necessária.");
    }

    private List<ResultadoAgente> executarEmParalelo(List<String> subtarefas, String feedback)
            throws InterruptedException {
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            var futuros = new ArrayList<java.util.concurrent.Future<ResultadoAgente>>();
            for (int i = 0; i < subtarefas.size(); i++) {
                final int indice = i;
                final String tarefa = montarPrompt(subtarefas.get(i), feedback);
                futuros.add(executor.submit(() ->
                        fabricaDeWorkers.criar("worker-" + indice).executar(tarefa)));
            }

            var resultados = new ArrayList<ResultadoAgente>();
            for (var futuro : futuros) {
                try {
                    resultados.add(futuro.get(10, TimeUnit.MINUTES));
                } catch (TimeoutException e) {
                    futuro.cancel(true);
                    resultados.add(new ResultadoAgente.Falha(
                            "Worker excedeu o limite de 10 minutos", 0));
                } catch (ExecutionException e) {
                    resultados.add(new ResultadoAgente.Falha(
                            "Worker falhou: " + e.getCause().getMessage(), 0));
                }
            }
            return resultados;
        }
    }

    private static String montarPrompt(String subtarefa, String feedback) {
        if (feedback.isBlank()) {
            return subtarefa;
        }
        return subtarefa + "\n\nO avaliador reprovou a tentativa anterior com este motivo:\n"
                + feedback + "\nCorrija e tente novamente.";
    }
}

package com.exemplo.harness.orquestracao;
import com.exemplo.harness.nucleo.Ferramenta;
import com.exemplo.harness.nucleo.ResultadoAgente;
import java.util.List;
import java.util.Map;
public final class AvaliadorPorVerificacao implements Avaliador {
    private final Ferramenta verificar;
    public AvaliadorPorVerificacao(Ferramenta verificar) {
        this.verificar = verificar;
    }
    @Override
    public Veredito avaliar(String objetivo, List<ResultadoAgente> resultados) {
        for (var resultado : resultados) {
            if (resultado instanceof ResultadoAgente.Falha falha) {
                return new Veredito.Reprovado("Uma subtarefa falhou: " + falha.motivo());
            }
        }
        String saida;
        try {
            saida = verificar.executar(Map.of());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return new Veredito.Reprovado("Verificação interrompida");
        } catch (Exception e) {
            return new Veredito.Reprovado("Verificação não executou: " + e.getMessage());
        }
        return saida.startsWith("exit=0")
                ? new Veredito.Aprovado()
                : new Veredito.Reprovado(saida);
    }
}

package com.exemplo.harness.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import java.nio.file.Path;
import java.time.Duration;
@ConfigurationProperties(prefix = "harness")
public record HarnessProperties(
        Path workspace,
        @DefaultValue("25") int maxPassos,
        @DefaultValue("3") int maxRodadas,
        @DefaultValue("10m") Duration timeoutVerificacao) {}

# application.yml
harness:
  workspace: /srv/projetos/contas
  max-passos: 25
  max-rodadas: 3
  timeout-verificacao: 10m

package com.exemplo.harness.config;
import com.exemplo.harness.ferramentas.ExecutarVerificacao;
import com.exemplo.harness.ferramentas.Workspace;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableConfigurationProperties(HarnessProperties.class)
class HarnessConfig {
    @Bean
    Workspace workspace(HarnessProperties props) {
        // Adequado para um worker sequencial ou para um workspace isolado.
        return new Workspace(props.workspace());
    }
    @Bean
    ExecutarVerificacao executarVerificacao(Workspace workspace, HarnessProperties props) {
        return new ExecutarVerificacao(workspace, props.timeoutVerificacao());
    }
}

package com.exemplo.harness.config;
import com.exemplo.harness.orquestracao.Orquestrador;
import com.exemplo.harness.orquestracao.Relatorio;
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@ConditionalOnBean(Orquestrador.class)
@RequestMapping("/orquestracoes")
class OrquestracaoController {
    record Pedido(String objetivo) {}
    private final Orquestrador orquestrador;
    OrquestracaoController(Orquestrador orquestrador) {
        this.orquestrador = orquestrador;
    }
    @PostMapping
    Relatorio criar(@RequestBody Pedido pedido) throws InterruptedException {
        return orquestrador.executar(pedido.objetivo());
    }
}

package com.exemplo.harness;
import com.exemplo.harness.ferramentas.EscreverArquivo;
import com.exemplo.harness.ferramentas.Workspace;
import com.exemplo.harness.guardrails.CaminhosProibidos;
import com.exemplo.harness.nucleo.*;
import com.exemplo.harness.orquestracao.*;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
import static org.assertj.core.api.Assertions.assertThat;
class HarnessTest {
    /** Modelo de mentira: devolve passos pré-definidos e guarda o último histórico recebido. */
    static final class ModeloRoteirizado implements Modelo {
        private final Iterator<Passo> roteiro;
        List<Mensagem> ultimoHistorico = List.of();
        ModeloRoteirizado(Passo... passos) {
            this.roteiro = List.of(passos).iterator();
        }
        @Override
        public Passo proximoPasso(List<Mensagem> historico,
                                  List<DefinicaoFerramenta> ferramentasDisponiveis) {
            this.ultimoHistorico = historico;
            return roteiro.next();
        }
    }
    @Test
    void guardrailImpedeEscritaEmArquivoProtegido(@TempDir Path pasta) {
        var workspace = new Workspace(pasta);
        var modelo = new ModeloRoteirizado(
                new Passo.ChamarFerramenta("escrever",
                        Map.of("caminho", ".env", "conteudo", "SEGREDO=1")),
                new Passo.Concluir("terminei"));
        var loop = new LoopDoAgente(modelo,
                List.of(new EscreverArquivo(workspace)),
                List.of(new CaminhosProibidos(List.of(".env"))),
                5);
        var resultado = loop.executar("grave o segredo");
        assertThat(resultado).isInstanceOf(ResultadoAgente.Sucesso.class);
        assertThat(Files.exists(pasta.resolve(".env"))).isFalse();
        assertThat(modelo.ultimoHistorico.getLast().conteudo()).contains("BLOQUEADO");
    }
    @Test
    void workspaceRejeitaCaminhoComTravessia(@TempDir Path pasta) {
        var workspace = new Workspace(pasta);
        var modelo = new ModeloRoteirizado(
                new Passo.ChamarFerramenta("escrever",
                        Map.of("caminho", "../fora.txt", "conteudo", "x")),
                new Passo.Concluir("ok"));
        new LoopDoAgente(modelo, List.of(new EscreverArquivo(workspace)), List.of(), 5)
                .executar("tente escapar");
        assertThat(modelo.ultimoHistorico.getLast().conteudo())
                .contains("ERRO")
                .contains("fora do workspace");
    }
    @Test
    void loopParaNoLimiteDePassos() {
        // Modelo que nunca conclui: sempre pede uma ferramenta inexistente.
        Modelo teimoso = (historico, ferramentas) -> new Passo.ChamarFerramenta("nada", Map.of());
        var resultado = new LoopDoAgente(teimoso, List.of(), List.of(), 3).executar("tarefa");
        assertThat(resultado).isEqualTo(new ResultadoAgente.Falha("Limite de 3 passos atingido", 3));
    }
    @Test
    void orquestradorTentaDeNovoComFeedbackAteAprovar() throws Exception {
        Planejador planejador = objetivo -> List.of("parte A", "parte B");
        var avaliacoes = new AtomicInteger();
        Avaliador avaliador = (objetivo, resultados) ->
                avaliacoes.incrementAndGet() == 1
                        ? new Veredito.Reprovado("faltou teste")
                        : new Veredito.Aprovado();
        var orquestrador = new Orquestrador(
                planejador,
                workerId -> new LoopDoAgente(
                        new ModeloRoteirizado(new Passo.Concluir("feito")),
                        List.of(), List.of(), 5),
                avaliador,
                3);
        var relatorio = orquestrador.executar("criar módulo de extratos");
        assertThat(relatorio.aprovado()).isTrue();
        assertThat(relatorio.rodadas()).isEqualTo(2);
        assertThat(relatorio.resultados()).hasSize(2);
    }
}