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>

Checklist de implantação: comece pelo ponto de saída

O primeiro mistake não costuma ser escrever um prompt ruim. O problema aparece quando o agente começa lendo informação e termina executando ações externas sem uma fronteira clara. Por isso, defina o ponto de saída de cada workflow antes de automatizar.

Em conteúdo, o ponto de saída não é “o artigo foi escrito”. É “a URL pública responde 200, os tags de Analytics e AdSense continuam presentes, e os blocos de código não quebram no mobile”. Em prospecção, o ponto de saída não é “o email foi enviado”. É “a lista de empresas, a página de amostra e o rascunho do email estão prontos para revisão”. Em segurança, o ponto de saída não é “o código mudou”. É “diff, testes e rollback estão claros”.

use case	Automatizar primeiro	Manter aprovação
Conteúdo	tema, rascunho, tradução, links internos, build	deploy, git push, mudanças em anúncios
Integração SaaS	leitura, CSV, resumo, rascunho	envio, exclusão, cobrança
Segurança	proposta de patch, testes, impacto	secrets, produção, permissões mais amplas

O pitfall mais perigoso é misturar leitura e execução. Ler issues, logs e páginas web é útil. Mas se o mesmo agente também pode enviar email, apagar dados ou fazer deploy em produção, uma instrução maliciosa em um documento externo pode virar ação real. O OWASP trata Prompt Injection e Excessive Agency no Top 10 for LLM Applications, e esse risk é muito próximo do dia a dia de agentes de código.

Para Claude Code, use os guias oficiais de security e permissions. Para Codex, a página da OpenAI sobre code generation ajuda a posicionar o produto. Dentro do ClaudeCodeLab, leia também falhas de segurança e prompts perigosos.

Templates prontos estão em /products/. Para desenhar permissões, CI, revisão e deploy com a equipe, /training/ é o caminho mais direto.

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.