Agent Harness seguro para Claude Code e Codex: permissoes, verificacao e rollback

Agentes mais fortes precisam de trilhos mais fortes

No inicio, Claude Code ou Codex parecem depender apenas de bons prompts. Para pequenas alteracoes, isso funciona. Quando o agente passa a tocar deploy, APIs SaaS, arquivos locais, publicacao e envio de emails, o problema principal vira a estrutura em volta dele.

Chamamos essa estrutura de Agent Harness: regras de permissao, plano de execucao, verificacoes, logs e caminho de rollback.

Para entender o conceito primeiro, leia o guia de harness engineering. Para riscos concretos, veja falhas de seguranca com Claude Code.

User request
  |
  v
Agent
  |
  v
[1] Policy layer       O que permite, pergunta ou bloqueia
[2] Plan layer         Quais passos serao executados
[3] Verification layer Como provar que deu certo
[4] Recovery layer     Como recuperar falhas
  |
  v
Files / shell / SaaS APIs / deploy

A documentacao oficial de Claude Code cobre settings, permissions, hooks e MCP. Veja Claude Code settings, Hooks reference e MCP.

Exemplo: publicar um artigo

Publicar um artigo envolve varias etapas.

1. Ler analytics dos ultimos 7 dias
2. Escolher um tema proximo de um cluster forte
3. Verificar artigos existentes
4. Escrever o artigo base
5. Criar todas as versoes de idioma
6. Validar frontmatter, slug e links internos
7. Rodar build
8. Verificar a URL publica
9. Commit e push

Sem um plano, o agente pode terminar o texto e esquecer traducao, build ou verificacao em producao.

SaaS: separar leitura, geracao e envio

Para um agente que pesquisa empresas e prepara emails, a fronteira deve ser clara.

Operacao	Automatico	Motivo
Ler paginas publicas	Sim	Baixo impacto
Salvar CSV local	Sim	Revisavel
Gerar pagina exemplo	Sim	Revisavel antes de publicar
Escrever email	Sim	Ainda nao enviado
Enviar email	Precisa aprovacao	Afeta pessoas reais

Leitura e rascunho podem ser automaticos. Envio, deploy e escrita em producao devem pedir aprovacao.

Policy layer

Uma politica simples ja ajuda muito.

{
  "allowCommands": [
    "npm run build",
    "npm run test",
    "node scripts/content-trend-report.mjs"
  ],
  "askCommands": [
    "git push",
    "wrangler pages deploy",
    "node scripts/outreach-send-mails.mjs --send"
  ],
  "denyCommands": [
    "rm -rf",
    "git reset --hard",
    "curl * | sh",
    "npm publish"
  ],
  "protectedPaths": [
    ".env",
    ".env.local",
    "claudecode-lab-sheets-f54fc47c68f0.json"
  ]
}

Em Claude Code, o projeto pode ter regras equivalentes.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test *)",
      "Bash(node scripts/content-trend-report.mjs *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(wrangler pages deploy *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git reset --hard *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./claudecode-lab-sheets-f54fc47c68f0.json)"
    ]
  }
}

Regras concretas sao melhores do que pedir ao agente para “tomar cuidado”.

Verification layer

O sucesso deve ser verificavel por comando.

const url = process.argv[2];
const response = await fetch(url, { redirect: "follow" });

if (!response.ok) {
  throw new Error(`Page returned ${response.status}: ${url}`);
}

const html = await response.text();
const checks = [
  ["title", /<title>.+<\/title>/i],
  ["description", /<meta name="description"/i],
  ["adsense", /ca-pub-2125588229998303/i],
  ["analytics", /G-3YR0LE68MJ/i]
];

for (const [name, pattern] of checks) {
  if (!pattern.test(html)) throw new Error(`Missing ${name}`);
}

Para artigos com codigo, Playwright pode verificar se blocos pre, code e table nao quebram no mobile.

Recovery layer

Toda execucao deve deixar um log simples.

{
  "runId": "2026-05-19-article-001",
  "topic": "agent harness security",
  "changedFiles": [
    "site/src/content/blog/claude-code-codex-agent-harness-security.mdx"
  ],
  "commands": [
    "node scripts/content-trend-report.mjs --days 7",
    "npm run build"
  ],
  "status": "deployed"
}

No Git, prefira recuperacao especifica.

git status --short
git diff -- site/src/content/blog/target-article.mdx
git revert <bad-commit>

Resumo

A qualidade de um agente nao vem apenas do prompt. Em fluxos reais, ela vem do harness.

• Policy: permitir, perguntar ou bloquear
• Plan: explicar os passos antes de executar
• Verification: provar que funcionou
• Recovery: saber como voltar

Claude Code e Codex sao diferentes, mas ambos precisam da mesma ideia: dar ao agente um caminho seguro de trabalho.