Guia completo de harness engineering: agentes de IA no estilo Claude Code

A ideia de “escreva um prompt bom e deixe a IA cuidar do resto” já não basta para criar agentes úteis. O que está ganhando força é harness engineering: o desenho do andaime ao redor do modelo. Se você conhece test harness em testes de software, pense na versão para agentes: ferramentas, contexto, permissões, verificação e um loop de controle em volta do LLM.

Claude Code é uma referência forte porque não é apenas uma interface de chat. Ele combina ferramentas de arquivo, comandos shell, CLAUDE.md, hooks, modos de permissão, subagents e memória. Neste guia veremos por que harness engineering está em alta, como criar um mini harness em Node.js com policy JSON, e como aplicar o padrão a content automation, code review, SaaS integration, cloud operations e security boundaries.

Por Que Harness Engineering Virou Tendência

Um LLM escolhe bem o próximo passo, mas o trabalho real exige observar o ambiente, escolher contexto, executar ferramentas, lidar com erros, limitar ações perigosas e provar que o resultado funciona. Essa camada externa é o harness.

A documentação do Claude Agent SDK mostra que ele pode carregar recursos no estilo Claude Code, como project instructions, skills, hooks e permissions. A documentação de permissions explica allow rules, deny rules, permission modes e callbacks em runtime. A documentação de prompt caching mostra como reaproveitar contexto estático longo. Tudo isso é engenharia ao redor do modelo, não apenas prompt.

O OODA loop deixa claro:

Fase	O que acontece	Responsável
Observe	ler arquivos, logs, URLs, tickets e estado de APIs	Harness
Orient	organizar e comprimir o contexto	Harness
Decide	escolher a próxima ação	LLM
Act	rodar tool, escrever arquivo, chamar API ou parar	Harness

Três das quatro fases dependem principalmente do harness. Por isso um modelo forte com um harness fraco ainda produz um agente frágil.

O Que Um Harness Deve Conter

Antes de começar, um harness prático responde quatro perguntas: o que o agente pode ler, qual artefato deve produzir, quais checks provam sucesso e quais ações são automáticas, ask-first ou proibidas.

Em um workflow de blog, não basta pedir “escreva um artigo”. O harness lê slugs existentes, escolhe um tema não duplicado, escreve MDX, valida frontmatter, confere code fences, adiciona links oficiais e internos, inclui CTAs para /products/ e /training/, roda build e verifica a URL pública.

Camada	Exemplo	pitfall
Contexto	regras do projeto, estilo, falhas antigas	premissas velhas continuam vivas
Ferramentas	read, grep, write, test, API call	ferramentas demais confundem o modelo
Política	allow, ask, deny, sandbox	ação destrutiva roda sem supervisão
Verificação	test, diff, screenshot, public URL	saída parece boa mas está quebrada
Memória	preferências reutilizáveis	nota temporária vira regra permanente

Diagrama Conceitual

O harness é a camada de controle antes e depois do modelo. O prompt importa, mas policy, context, tools, permission gate e verification loop definem se o workflow é confiável.

flowchart LR
  A["Goal"] --> B["Harness policy"]
  B --> C["Context"]
  B --> D["Tools"]
  B --> E["Permissions"]
  C --> F["LLM decision"]
  D --> F
  E --> G["Safe action"]
  F --> G
  G --> H["Verification"]
  H --> I["Artifact"]
  H --> B

Mini Harness Em Node.js

O exemplo abaixo é pequeno, mas completo: modelo, duas ferramentas, policy, loop, limite de path e erro legível. Defina ANTHROPIC_API_KEY antes.

mkdir harness-demo
cd harness-demo
npm init -y
npm install @anthropic-ai/sdk
node -e "const fs=require('node:fs');fs.mkdirSync('sandbox',{recursive:true});fs.writeFileSync('sandbox/README.md','# Demo\nShip a safer agent workflow.\nKeep writes inside sandbox.\n');"

Salve como policy.json.

{
  "workspace": "./sandbox",
  "maxSteps": 6,
  "tools": {
    "read_file": {
      "allow": true,
      "risk": "Read UTF-8 text only inside workspace"
    },
    "write_file": {
      "allow": true,
      "risk": "Write UTF-8 text only inside workspace"
    }
  }
}

Salve como mini-harness.mjs.

import Anthropic from "@anthropic-ai/sdk";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";

const client = new Anthropic();
const policy = JSON.parse(await readFile(new URL("./policy.json", import.meta.url), "utf8"));
const model = process.env.ANTHROPIC_MODEL || "claude-sonnet-4-6";
const workspace = path.resolve(policy.workspace);

function safePath(requestedPath) {
  const resolved = path.resolve(workspace, requestedPath);
  const inside = resolved === workspace || resolved.startsWith(workspace + path.sep);
  if (!inside) {
    throw new Error(`Path escapes workspace: ${requestedPath}. Use a path under ${policy.workspace}.`);
  }
  return resolved;
}

function ensureAllowed(toolName) {
  const rule = policy.tools?.[toolName];
  if (!rule?.allow) {
    throw new Error(`Tool '${toolName}' is not allowed by policy.json.`);
  }
}

const tools = [
  {
    name: "read_file",
    description: "Read a UTF-8 text file from the allowed workspace.",
    input_schema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
      additionalProperties: false
    }
  },
  {
    name: "write_file",
    description: "Write a UTF-8 text file inside the allowed workspace.",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string" },
        content: { type: "string" }
      },
      required: ["path", "content"],
      additionalProperties: false
    }
  }
];

async function executeTool(name, input) {
  ensureAllowed(name);
  if (name === "read_file") {
    return await readFile(safePath(input.path), "utf8");
  }
  if (name === "write_file") {
    const target = safePath(input.path);
    await mkdir(path.dirname(target), { recursive: true });
    await writeFile(target, input.content, "utf8");
    return `written ${input.path}`;
  }
  throw new Error(`Unknown tool: ${name}`);
}

async function run(goal) {
  const messages = [{ role: "user", content: goal }];

  for (let step = 0; step < policy.maxSteps; step++) {
    const response = await client.messages.create({
      model,
      max_tokens: 1200,
      tools,
      system: "You are a careful file assistant. Use tools when needed. Keep writes under policy workspace.",
      messages
    });

    messages.push({ role: "assistant", content: response.content });
    const toolUses = response.content.filter((block) => block.type === "tool_use");

    if (toolUses.length === 0) {
      const text = response.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(text);
      return;
    }

    const results = [];
    for (const toolUse of toolUses) {
      try {
        const output = await executeTool(toolUse.name, toolUse.input);
        results.push({ type: "tool_result", tool_use_id: toolUse.id, content: String(output).slice(0, 8000) });
      } catch (error) {
        results.push({
          type: "tool_result",
          tool_use_id: toolUse.id,
          is_error: true,
          content: error instanceof Error ? error.message : String(error)
        });
      }
    }
    messages.push({ role: "user", content: results });
  }

  throw new Error(`Max steps reached: ${policy.maxSteps}`);
}

const goal = process.argv.slice(2).join(" ") || "Read README.md and write summary.md with three bullet points.";
await run(goal);

Execute:

node mini-harness.mjs

Mesmo pequeno, ele mostra o padrão essencial: schema de ferramentas, policy, sandbox, limite de passos, erros úteis e artefato verificável. Adicione grep, tests, approval UI, APIs SaaS e hooks para se aproximar de Claude Code.

Cinco Use Cases Concretos

1. content automation Um prompt fraco diz “escreva um post”. Um harness forte lê posts existentes, evita tema duplicado, escreve MDX, valida frontmatter e code fences, adiciona links oficiais e internos, insere CTAs para /products/ e /training/, roda build e checa a URL pública. O pitfall é produzir resumos localizados rasos só para publicar mais rápido.

2. code review Um review harness lê git diff, testes, arquivos alterados e regras locais. A resposta deve ser findings-first: bugs, risk, regressões e testes ausentes antes do resumo. O risco é o modelo apenas descrever a mudança.

3. SaaS integration Com Notion, HubSpot, Stripe ou CRM, separe read-only lookup, dry-run mutation e approved write. Leads podem ser classificados e virar rascunho de atualização, mas o write real deve pedir aprovação. O pitfall é gravar cliente, cobrança ou nota errada em produção.

4. cloud operations Operar cloud não é só deploy. O harness deve verificar variáveis de ambiente, build, diff, target, rollback, health endpoint e public URL. O risk é corrigir a última linha do log sem achar a causa raiz.

5. security boundaries Security boundaries vêm no início. Read pode ser amplo, mas Write precisa ficar no workspace. Shell deve usar allow-list. rm, force push, DB de produção, billing e secrets devem ser deny ou ask-first. Harness evita confiança excessiva.

O Que Copiar Do Claude Code

Primeiro, contexto em camadas: regras estáveis em CLAUDE.md, progresso da sessão no plan e preferências duráveis na memory.

Segundo, hooks para o determinístico. Format, lint, tests, link checks e screenshots devem rodar como comandos. Claude interpreta erros e propõe correções.

Terceiro, isolamento de trabalho ruidoso. Logs longos, busca ampla, tradução multilíngue e refactors grandes combinam com subagents ou etapas separadas.

Pitfalls Frequentes

Ferramentas demais reduzem precisão. Comece com 5 a 10 tools claras.

Erros ilegíveis impedem self-repair. Troque Error: failed por uma mensagem que diga o que faltou e qual é o próximo passo.

Ignorar prompt caching aumenta custo e latência. Separe contexto estático e dinâmico.

Sem verificação, output bonito pode quebrar em produção. Artigos precisam de frontmatter e code fence checks; código precisa de tests; cloud precisa de health checks; SaaS precisa de audit log.

Permissões se alargam com facilidade. Revise allow, ask e deny periodicamente.

Próximo Passo

Para começar pela segurança, leia o guia de permissões do Claude Code. Para contexto de projeto, veja boas práticas de CLAUDE.md. Para dividir trabalho pesado, leia padrões de subagents no Claude Code. Para custo, consulte otimização de tokens no Claude Code.

Como referência rápida, mantenha o Claude Code Quick Reference Cheatsheet. Templates e playbooks estão em /products/. Se sua equipe precisa desenhar permissões, review gates, verificação, publicação e revenue workflow, comece por /training/.

O Que Verifiquei Na Prática

No workflow da ClaudeCodeLab, o maior valor do harness é tornar falhas visíveis. Um prompt cria um artigo; um harness confere profundidade, code fences, frontmatter, links, CTAs e public URL. Assim a operação deixa de depender de confiança cega no output e passa a depender de gates verificáveis.

Resumo

Harness engineering decide o que o modelo pode ver, o que pode fazer, onde deve parar e como o resultado será verificado. Claude Code é um ótimo exemplo porque o valor não está só no modelo, mas no scaffold ao redor. Rode o mini harness acima e adicione uma boundary e um check ao seu próprio use case.

Referências

• Claude Agent SDK: Claude Code features
• Claude Agent SDK permissions
• Claude Agent SDK hooks
• Claude API models overview
• Prompt caching