Dizer “faz tudo aí” pra IA é receita de acidente. Como montar o andaime certo

“Dá uma organizada nesse repositório, deixa bonitinho.”

Na manhã seguinte, a IA tinha “organizado” bonitinho 40 arquivos. Tinha código que funcionava, sim. Só que ela também tinha apagado, limpinho, até os arquivos de configuração que eu jamais deveria ter deixado encostarem.

Você já passou esse frio na espinha?

Por que uma IA que é tão esperta provoca acidente sem o menor pudor? A razão é simples: “ser inteligente” e “trabalhar com segurança” são duas coisas completamente diferentes. É o estagiário que tira nota máxima na prova e, no primeiro dia de trabalho, quebra o caixa da loja. É exatamente isso. Não é problema de capacidade, é problema de andaime.

Esse andaime hoje em dia tem nome: harness. Hoje eu vou explicar isso fugindo ao máximo do palavreado técnico.

Afinal, o que é um harness?

Harness é um programinha pequeno que você coloca do lado de fora da IA.

A imagem mais fácil é o cinto de segurança do operário lá no alto da obra, ou as rodinhas da bicicleta de criança. É o mecanismo que mantém a capacidade da pessoa intacta, mas impede que ela caia. No caso da IA, ele faz mais ou menos isto:

• decide o que a IA vai ler (não mostra tudo);
• decide o que ela vai produzir (deixa a meta clara);
• decide até onde ela age sozinha e em que ponto ela precisa pedir confirmação a um humano;
• checa de forma mecânica se o que saiu dali não veio quebrado.

“Escrever um prompt bom” é só uma fatia disso. O motivo de os acidentes não diminuírem por mais que você lustre o prompt é simples: é como treinar monociclo sem rodinhas. Você pode ser ótimo, mas o problema não estava no equilíbrio.

Por que justamente agora todo mundo fala disso

Até pouco tempo atrás, o que a gente pedia pra IA era basicamente “escreve um texto”, “escreve um código”. O humano lia o que saía e decidia. Tava sob controle.

Acontece que agora a gente começou a entregar o trabalho em si pra IA. Ler arquivos, escolher uma pauta que não repita os artigos que já existem, conferir o que mudou, cadastrar num serviço externo, reportar a causa quando algo falha — quando chega nesse ponto, não tem mais um humano no meio a cada passo. Foi por isso que o risco de “ela faz sozinha e dá ruim” disparou de uma hora pra outra.

O Claude Code tem boa fama não tanto porque o modelo é genial, e sim porque esse andaime é bem-feito. Ferramenta pra ler arquivo, ferramenta pra buscar, mecanismo pra barrar operação perigosa, mecanismo pra fazer ele decorar as regras do projeto. Toda essa “periferia sem graça” é sólida. O que está na moda não é o prompt mágico — é essa periferia sem graça.

Primeiro, faça rodar: o harness mínimo de 30 linhas

Em vez de explicar, é mais rápido rodar. Vamos montar o andaime mínimo: a IA só pode “ler e escrever”, e jamais pode encostar fora da pasta que a gente definiu. Com Node.js e uma chave de API da Anthropic, já roda.

Primeiro, a preparação.

mkdir harness-demo && cd harness-demo
npm init -y
npm install @anthropic-ai/sdk
mkdir sandbox
echo "# Anotações" > sandbox/note.md

Agora escrevemos a “lista de permissões”. Esse é o coração do harness. É a declaração: fora do sandbox, não toca.

{
  "workspace": "./sandbox",
  "maxSteps": 6
}

E o corpo principal (harness.mjs). Decore só um ponto: a safePath é o porteiro que “barra na hora se algo tentar sair da pasta”. Só com ela ali, aquele “acidente dos 40 arquivos” da abertura não acontece.

import Anthropic from "@anthropic-ai/sdk";
import { 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 root = path.resolve(policy.workspace);

// Porteiro: se algo tentar sair da pasta de trabalho, barra ali mesmo
function safePath(p) {
  const resolved = path.resolve(root, p);
  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
    throw new Error(`${p} está fora da pasta de trabalho. Só dá pra tocar dentro de sandbox.`);
  }
  return resolved;
}

const tools = [
  { name: "read_file", description: "lê um texto dentro de sandbox",
    input_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] } },
  { name: "write_file", description: "escreve um texto dentro de sandbox",
    input_schema: { type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"] } },
];

async function useTool(name, input) {
  if (name === "read_file") return await readFile(safePath(input.path), "utf8");
  if (name === "write_file") { await writeFile(safePath(input.path), input.content, "utf8"); return "Gravado com sucesso"; }
  throw new Error(`ferramenta desconhecida: ${name}`);
}

const messages = [{ role: "user", content: process.argv.slice(2).join(" ") || "Leia o note.md e escreva um resumo em summary.md." }];

for (let step = 0; step < policy.maxSteps; step++) {
  const res = await client.messages.create({
    model: process.env.ANTHROPIC_MODEL || "claude-sonnet-4-6",
    max_tokens: 1024,
    tools,
    system: "Você é um assistente de arquivos cuidadoso. Use ferramentas só quando necessário e limite o trabalho ao sandbox.",
    messages,
  });
  messages.push({ role: "assistant", content: res.content });

  const calls = res.content.filter((b) => b.type === "tool_use");
  if (calls.length === 0) { console.log(res.content.find((b) => b.type === "text")?.text ?? ""); break; }

  const results = [];
  for (const c of calls) {
    try { results.push({ type: "tool_result", tool_use_id: c.id, content: String(await useTool(c.name, c.input)).slice(0, 4000) }); }
    catch (e) { results.push({ type: "tool_result", tool_use_id: c.id, is_error: true, content: e.message }); }
  }
  messages.push({ role: "user", content: results });
}

Pra rodar, é só isto.

node harness.mjs

São umas poucas dezenas de linhas, mas já estão separados ali o “corpo da IA”, as “ferramentas que ela pode usar”, o “alcance da permissão”, o “teto de tentativas” e o “mecanismo que para quando quebra”. Esse é o esqueleto do harness. Daqui em diante, é só ir somando busca, execução de testes, espera por aprovação e notificação — e ele cresce até virar algo parecido com o Claude Code.

Onde isso faz diferença (3 casos)

1. Conferência de conteúdo em série Se você para no “escreve um post de blog”, a IA produz em série, sem dó, artigos rasos e pautas “quase iguais”. Aí você dá um roteiro ao harness: “lê os títulos existentes → escolhe um ângulo que não repita → escreve o texto → confere caracteres e links no automático”. Resultado: antes de o humano sequer ficar em dúvida sobre a qualidade, o porteiro já barra o artigo raso. Comigo, passou a aparecer todo mês um monte de rascunho que trava antes de publicar. E a sensação é de alívio: ainda bem que travou.

2. Triagem de contatos “Lê os contatos que chegaram e me avisa só os que têm cara de virar negócio.” Ler pode ser automático. Mas o cadastro na lista de clientes fica em espera até um humano apertar o botão. Isso a gente força pelo harness. Leitura automática, escrita em rascunho (dry-run), e só o cadastro final na mão do humano. O acidente de jogar um cliente mal classificado direto no banco de produção desaparece.

3. Um respiro antes do deploy Antes de apertar o botão de publicar, obrigue a conferir: o build passa? as variáveis de ambiente estão todas lá? o diff é o esperado? existe um passo pra reverter? A IA tende a olhar só a “última linha” do log de erro e consertar a coisa errada, então o truque é decidir de antemão “onde olhar”. Não entregue o log inteiro — recorte as poucas dezenas de linhas que importam. Só isso já derruba muito conserto fora do alvo.

3 coisas que dá pra “roubar” do Claude Code

Quando você for montar seu próprio harness, não precisa pensar do zero. O Claude Code é um baú de bons exemplos. Não precisa copiar tudo — adotar logo cedo só estes três já estabiliza demais.

A primeira é separar as regras em camadas. O combinado que nunca muda vai pro arquivo de configuração; a instrução só desta vez vai numa anotação na hora; a preferência de longo prazo vai pra outro lugar. Se você enfia tudo no prompt toda vez, ele fica gigante e a precisão cai.

A segunda é deixar o que é determinístico por conta de comandos. Formatar, checar, testar — sai mais rápido e mais certeiro rodando um npm test do que pedindo pra IA. Pra IA, sobra só o trabalho de “pensar”.

A terceira é mandar a pesquisa pesada pra outro encarregado. Se você despeja log enorme e leitura de um monte de arquivo na conversa principal, o julgamento que importa fica embaçado. Deixe a apuração pra outro processo e receba só a conclusão. Só isso e a nitidez da decisão volta.

3 vacilos que eu mesmo cometi

Vou ser honesto. Meus primeiros harnesses foram um festival de acidentes.

O primeiro foi dar ferramenta demais. Achei que seria útil e preparei umas 30 ferramentas. A IA ficou perdida, “qual eu uso?”, e emendou uma escolha estranha atrás da outra. Hoje eu limito a 5 ou 10 no começo.

O segundo foi mensagem de erro grosseira. Quando eu devolvia só Error: failed, a IA não conseguia consertar nada. Quando passei a devolver a causa e o próximo passo, tipo README.md não encontrado. Em sandbox só existe note.md, ela começou de repente a se virar sozinha.

O terceiro foi confiar a conferência só no olho humano. “Eu confiro no final” quebra, sem falta, justo no dia corrido. Depois que coloquei porteiros que a máquina entende — contagem de caracteres, link quebrado, erro de tipo —, minhas conferências de madrugada despencaram.

Se for começar, comece por aqui

Não saia montando de cara um “agente genial 100% automático”. Escolha uma tarefa pequena que, se der errado, dá pra reverter. Conferir um rascunho, fazer a primeira passada de revisão num PR, triar contatos, checar antes de publicar em staging. Esse tamanho é o ideal.

A ordem é sempre a mesma. ① Definir, estreito, o que pode ser lido → ② deixar clara a meta (o entregável) → ③ deixar a conferência por conta de comandos sempre que der → ④ no começo, deixar toda operação perigosa (apagar, banco de produção, cobrança, force push) no modo “pergunta pro humano”. Só promova pra automático, depois, a operação que você já sabe ser segura. Só de respeitar essa ordem, os acidentes caem de um jeito impressionante.

Como definir permissões está no Guia de configuração de permissões do Claude Code, e a base pra usar em equipe está no CLAUDE.md: boas práticas. Se você quer dividir trabalhos longos, dê uma olhada também nos padrões de uso de subagents. A visão oficial está na fonte primária, a documentação do Claude Agent SDK.

O que aconteceu quando testei na prática

Desde o “acidente dos 40 arquivos” lá da abertura, eu parei de me atormentar com “será que confio na IA”. No lugar disso, o que eu olho é: em qual porteiro ela travou. Só de somar uma safePath ao harness mínimo, os acidentes fora da pasta foram a zero. Quando somei a checagem automática de caracteres e links, o artigo raso passou a travar antes de publicar. Em vez de caçar a IA mais esperta, montar primeiro um andaime onde você cai sem se machucar. Parece volta, mas hoje minha sensação é que esse é o caminho mais rápido.

Resumo

Harness engineering não é a arte de enfeitar prompt. É a arte de desenhar o que mostrar pra IA, o que mandar ela fazer, onde pará-la e como conferir. Comece rodando as 30 linhas aí de cima e somando um “porteiro” ao seu próprio trabalho. A qualidade do que a IA faz se decide menos pela inteligência do modelo e mais pelo andaime que está do lado de fora dele.

Se você quer, de forma mais sistemática, encaixar a IA com segurança no seu próprio trabalho, dê uma espiada na lista de materiais e templates. E se quer organizar permissões, revisão e verificação no time inteiro, veja treinamento e consultoria.