Arquitetura de agentes: como criar harnesses de desenvolvimento com IA

TL;DR: Claude Code não é uma caixa de chat com acesso a arquivos. É um runtime programável com 30 eventos de ciclo de vida documentados, e cada um deles pode ser conectado a hooks com scripts shell que o modelo não pode ignorar. Organize hooks em dispatchers, dispatchers em skills, skills em agentes e agentes em workflows para criar um harness de desenvolvimento autônomo que impõe restrições, delega trabalho, mantém a memória entre sessões e orquestra deliberações multiagente. O Claude Code v2.1.147 adicionou a ferramenta Workflow, desativada por padrão (CLAUDE_CODE_WORKFLOWS=1), levando a orquestração multiagente determinística de scripts puramente criados pelo usuário para um recurso primitivo do runtime oficial; a v2.1.149 reforça a mesma lição pelo lado da segurança, com correções para contornar permissões no PowerShell e para a lista de permissões do sandbox de git worktree. Hooks e evidence gates ainda são responsáveis pela correção.⁵²⁵³ Este guia aborda todas as camadas dessa estrutura: de um único hook a um sistema de consenso com 10 agentes. Nenhum framework é necessário. Tudo em bash e JSON.

Andrej Karpathy cunhou um termo para o que se desenvolve ao redor de um agente LLM: claws. Os hooks, scripts e a orquestração que permitem ao agente interagir com o mundo fora da sua janela de contexto.¹ A maioria dos desenvolvedores trata os agentes de programação com IA como assistentes interativos. Eles digitam um prompt, observam o agente editar um arquivo e seguem em frente. Essa perspectiva limita a produtividade ao que você consegue supervisionar pessoalmente.

O modelo mental de infraestrutura é diferente: um agente de programação com IA é um runtime programável com um kernel LLM. Cada ação executada pelo modelo passa por hooks controlados por você. Você define políticas, não prompts. O modelo opera dentro da sua infraestrutura da mesma forma que um servidor web opera sob as regras do nginx. Você não fica diante do nginx digitando solicitações. Você o configura, faz o deploy e monitora.

Essa diferença importa porque os benefícios da infraestrutura se acumulam. Um hook que bloqueia credenciais em comandos bash protege todas as sessões, todos os agentes e todas as execuções autônomas. Uma skill que codifica seus critérios de avaliação é aplicada de forma consistente, seja quando você a invoca ou quando um agente faz isso. Um agente que revisa a segurança do código executa as mesmas verificações, esteja você acompanhando ou não.²

Principais conclusões

• Hooks garantem a execução; prompts não. Use hooks para linting, formatação, verificações de segurança e tudo o que precisa ser executado sempre, independentemente do comportamento do modelo. O código de saída 2 bloqueia ações. O código de saída 1 apenas exibe um aviso.³
• Skills codificam conhecimentos especializados que são ativados automaticamente. O campo description determina tudo. Claude usa o raciocínio LLM (não a correspondência de palavras-chave) para decidir quando aplicar uma skill.⁴
• Subagents evitam o inchaço do contexto. Janelas de contexto isoladas para exploração e análise mantêm a sessão principal enxuta. Execute subagents independentes em paralelo e use equipes de agentes quando os workers precisarem de coordenação contínua.⁵
• A memória vive no sistema de arquivos. Os arquivos persistem entre janelas de contexto. CLAUDE.md, MEMORY.md, diretórios de regras e documentos de handoff formam um sistema estruturado de memória externa.⁶
• A deliberação multiagente identifica pontos cegos. Agentes individuais não conseguem questionar as próprias suposições. Dois agentes independentes com prioridades de avaliação diferentes identificam falhas estruturais que os quality gates não conseguem resolver.⁷
• O padrão de harness é o sistema. CLAUDE.md, hooks, skills, agentes e memória não são recursos independentes. Eles se combinam em uma camada determinística entre você e o modelo, que acompanha a escala da automação.

Como usar este guia

Cada seção se baseia na anterior. O Framework de decisão, no final, apresenta uma tabela de consulta para escolher o mecanismo certo para cada tipo de problema.

Caminho Direto de Cinco Minutos

Antes do mergulho profundo, aqui está o caminho mais curto do zero a um harness funcional. Um hook, um skill, um subagent, um resultado.

Passo 1: Criar um hook de segurança (2 minutos)

Crie .claude/hooks/block-secrets.sh:

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

Conecte-o em .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

Resultado: Todo comando bash que o Claude executa agora é verificado em busca de credenciais vazadas. O modelo não pode pular essa verificação.

Passo 2: Criar um skill de revisão de código (1 minuto)

Crie .claude/skills/reviewer/SKILL.md com frontmatter (name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob) e um checklist: SQL injection, XSS, segredos hardcoded, tratamento de erros ausente, funções com mais de 50 linhas.

Resultado: Claude ativa automaticamente esse conhecimento sempre que você mencionar revisar, verificar ou auditar.

Passo 3: Invocar um subagent (30 segundos)

Em qualquer sessão do Claude Code, peça ao Claude para revisar os últimos 3 commits em busca de problemas de segurança usando um agent separado. O Claude invoca um Explore agent que lê o diff, aplica o seu skill de revisão e retorna um resumo. Seu contexto principal permanece limpo.

O que você tem agora

Um harness de três camadas: um portão de segurança determinístico (hook), conhecimento de domínio que ativa automaticamente (skill) e análise isolada que protege seu contexto (subagent). Cada seção abaixo expande uma dessas três camadas.

Por que a arquitetura de agents importa

Simon Willison enquadra o momento atual em torno de uma única observação: escrever código ficou barato agora.⁸ Correto. Mas o corolário é que a verificação agora é a parte cara. Código barato sem infraestrutura de verificação produz bugs em escala. O investimento que compensa não é um prompt melhor. É o sistema em torno do modelo que captura o que o modelo deixa passar.

Três forças tornam a arquitetura de agents necessária:

Context windows são finitas e sujeitas a perdas. Cada arquivo lido, saída de tool e turno de conversa consome tokens. A Microsoft Research e a Salesforce testaram 15 LLMs em mais de 200.000 conversas simuladas e encontraram uma queda média de desempenho de 39% da interação de turno único para multi-turno.⁹ A degradação começa em tão poucos quanto dois turnos e segue uma curva previsível: edições precisas em múltiplos arquivos nos primeiros 30 minutos degeneram em visão de túnel em um único arquivo por volta do minuto 90. Context windows mais longas não resolvem isso. A condição “Concat” do mesmo estudo (conversa completa como um único prompt) alcançou 95,1% do desempenho de turno único com conteúdo idêntico. A degradação vem dos limites entre turnos, não dos limites de tokens.

O comportamento do modelo é probabilístico, não determinístico. Dizer ao Claude “sempre execute o Prettier após editar arquivos” funciona aproximadamente 80% das vezes.³ O modelo pode esquecer, priorizar velocidade ou decidir que a mudança é “pequena demais”. Para compliance, segurança e padrões de equipe, 80% não é aceitável. Hooks garantem a execução: todo Edit ou Write aciona seu formatador, toda vez, sem exceções. Determinístico vence probabilístico.

Perspectivas únicas deixam passar problemas multidimensionais. Um único agent revisando um endpoint API verificou autenticação, validou sanitização de entrada e conferiu cabeçalhos CORS. Atestado de saúde impecável. Um segundo agent, instruído separadamente como pentester, descobriu que o endpoint aceitava parâmetros de consulta ilimitados que podiam disparar negação de serviço através de amplificação de consultas ao banco de dados.⁷ O primeiro agent nunca verificou porque nada em seu framework de avaliação tratava a complexidade de consultas como superfície de segurança. Essa lacuna é estrutural. Nenhuma quantidade de prompt engineering corrige isso.

A arquitetura de agents aborda as três questões: hooks impõem restrições determinísticas, subagents gerenciam isolamento de contexto e a orquestração multi-agent fornece perspectivas independentes. Juntos, eles formam o harness.

O padrão de harness

O harness não é um framework. É um padrão: um conjunto combinável de arquivos, scripts e convenções que envolve um agente de programação com IA em uma infraestrutura determinística. Os componentes:

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

Camada de instruções: os arquivos CLAUDE.md e os diretórios de regras definem o que o agente sabe sobre o seu projeto. Eles são carregados automaticamente no início da sessão e após cada compactação. Essa é a memória arquitetural de longo prazo do agente.

Camada de extensão: skills fornecem conhecimento especializado que é ativado automaticamente de acordo com o contexto. Hooks fornecem gates determinísticos que são acionados em cada chamada de ferramenta correspondente. Arquivos de memória mantêm o estado entre sessões. Agentes personalizados fornecem configurações especializadas de subagents.

Camada de orquestração: padrões multiagente coordenam agentes independentes para pesquisa, revisão e deliberação. Limites de spawn evitam recursões descontroladas. A validação por consenso garante a qualidade.

O principal insight: a maioria dos usuários trabalha inteiramente na camada principal, enquanto observa o contexto inflar e os custos aumentarem. Usuários avançados configuram as camadas de instruções e extensão e usam a camada principal apenas para orquestração e decisões finais.²

Harnesses gerenciados vs. auto-hospedados (abril de 2026)

Durante o início de 2026, o caminho de “criar seu próprio harness” era a única opção real. Em abril de 2026, isso mudou. Anthropic lançou Claude Managed Agents em beta público (8 de abril): loop do harness + execução de ferramentas + contêiner sandbox + persistência de estado como uma API REST, cobrada pelos tokens padrão mais US$ 0,08 por hora de sessão. A atualização do Agents SDK da OpenAI (16 de abril) formalizou a mesma divisão — harness e computação como camadas separadas, com provedores nativos de sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) e snapshot/rehydrate para sobreviver à perda do contêiner.²³²⁴

A interface mais completa do SDK no lado da OpenAI chegou no openai-agents Python v0.14.0 (lançado em 15 de abril de 2026 e anunciado em 16 de abril): uma subclasse SandboxAgent de Agent com default_manifest, instruções de sandbox e recursos; um Manifest que descreve o contrato de um workspace novo (arquivos, diretórios, arquivos locais, repositórios Git, ambiente, usuários e montagens); um SandboxRunConfig para configurar, a cada execução, o cliente de sandbox, a injeção de sessões ativas, as substituições do manifesto, os snapshots e os limites de concorrência da materialização. Os recursos integrados abrangem acesso ao shell, edição do sistema de arquivos, inspeção de imagens, skills, memória do sandbox e compactação. A memória do sandbox mantém aprendizados extraídos entre execuções e os revela progressivamente; os workspaces oferecem suporte a arquivos locais, entradas de repositórios Git e montagens remotas (S3, R2, GCS, Azure Blob, S3 Files); os snapshots são portáteis entre provedores. Backends: UnixLocalSandboxClient, DockerSandboxClient e clientes hospedados para Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop e Vercel por meio de extras opcionais.²⁴

Para projetos Python que querem incorporar o runtime Claude Code como uma biblioteca — entre “executar claude por meio do shell” e usar uma “API REST para Managed Agents” — o claude-agent-sdk-python é a terceira opção. A série de 28 e 29 de abril (v0.1.69 → v0.1.71) atualizou o CLI incluído para a v2.1.123, elevou a versão mínima da dependência mcp para >=1.19.0 (versões anteriores descartavam silenciosamente os retornos de CallToolResult das ferramentas MCP em execução no mesmo processo, deixando o modelo com um bloco de erro de validação) e alinhou o esquema de SandboxNetworkConfig ao SDK do TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Em 2026-08-01, o pacote está na v0.2.128 no PyPI (incluindo o CLI do Claude na v2.1.220, com a versão mínima de mcp agora em >=1.23.0), e o SDK do TypeScript está na v0.3.220; a linha 0.2.x evolui de forma incremental a interface 0.1.x descrita aqui — as opções include_hook_events, skills e de configuração do sandbox abaixo continuam atuais —, com os lançamentos recentes concentrados na limpeza de subprocessos e na confiabilidade do streaming NDJSON.⁸⁶

Se o seu harness inclui uma camada de voz ou de tempo real, o openai-agents-python v0.17.0 (8 de maio de 2026) atualizou o RealtimeAgent para usar gpt-realtime-2 por padrão.⁴¹ As sessões de tempo real existentes adotam automaticamente o novo padrão; fixe explicitamente o modelo anterior se você precisar manter o comportamento antigo para avaliação.

Em julho de 2026, a opção gerenciada também ganhou uma solução multiagente no lado da OpenAI: openai-agents-python v0.18.2 (11 de julho) e openai-agents-js v0.13.2 (10 de julho) adicionam suporte multiagente hospedado em beta — orquestração de vários agentes gerenciada pela OpenAI como um serviço hospedado, a contraparte direta do beta público de Managed Multiagent Orchestration da Anthropic, abordado na seção Orquestração multiagente.⁷³ Agora, os dois fornecedores oferecem no nível multiagente a mesma troca que a tabela abaixo descreve para agentes individuais: o fornecedor executa o loop de delegação, e você abre mão da interface de hooks.

A bifurcação arquitetural agora é real:

Quando escolher cada opção: o modelo auto-hospedado continua sendo o mais indicado para equipes que já têm experiência sólida com infraestrutura, querem controlar suas skills e seus hooks ou estão otimizando profundamente um workflow específico. O modelo gerenciado é indicado para equipes sem engenheiros de plataforma dedicados, quando obter resultados rapidamente importa mais do que a personalização ou quando as execuções dos agentes precisam sobreviver de forma confiável ao fechamento do laptop sem que você tenha de criar essa camada de persistência. As duas opções são compatíveis — você pode executar um harness auto-hospedado que delega tarefas específicas de longa duração aos Managed Agents por meio da API REST.

Como o harness aparece no disco

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

Cada arquivo dessa estrutura tem uma finalidade. A árvore ~/.claude/ é uma infraestrutura pessoal que se aplica a todos os projetos. A árvore .claude/ de cada repositório é específica do projeto e compartilhada pelo git. Juntas, elas formam o harness completo.

Sistema de skills

Skills são extensões invocadas pelo modelo. Claude as descobre e aplica automaticamente com base no contexto, sem que você precise chamá-las explicitamente.⁴ O momento em que você percebe que está explicando novamente o mesmo contexto entre sessões é o momento de criar uma skill.

Quando criar uma skill

Skills servem para o conhecimento que Claude sempre tem disponível. Comandos slash servem para as ações que você aciona explicitamente. Se estiver decidindo entre os dois, pergunte: “Claude deve aplicar isso automaticamente ou eu devo decidir quando executar?”

Como criar uma skill

Skills podem ficar em quatro locais, do escopo mais amplo ao mais restrito:⁴

Toda skill exige um arquivo SKILL.md com frontmatter YAML:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Referência do frontmatter

O campo de descrição é tudo

No início da sessão, Claude Code extrai o name e a description de cada skill e os insere no contexto de Claude. Quando você envia uma mensagem, Claude usa o raciocínio do modelo de linguagem para decidir se alguma skill é relevante. Uma análise independente do código-fonte de Claude Code confirma o mecanismo: as descrições das skills são inseridas em uma seção available_skills do prompt do sistema, e o modelo usa a compreensão padrão de linguagem para selecionar as skills relevantes.¹⁰

Descrição ruim:

description: Helps with code

Descrição eficaz:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

A descrição eficaz inclui: o que a skill faz (revisa o código em busca de tipos específicos de problemas), quando usá-la (ao examinar alterações, PRs e a qualidade) e frases-gatilho (revisar, auditar, verificar) que os usuários digitam naturalmente.

Observe que a ativação automática é um controle ajustável, não uma regra: desde a v2.1.215, Claude não invoca mais por conta própria as skills /verify e /code-review incluídas — elas são executadas somente quando invocadas explicitamente, um recuo deliberado na ativação orientada pela descrição para skills pesadas de revisão, cujas execuções não solicitadas custavam mais do que entregavam.⁷⁴

Orçamento de contexto

Todas as descrições de skills compartilham um orçamento de contexto que aumenta dinamicamente para 1% da janela de contexto, com um fallback de 8.000 caracteres.⁴ Se você tiver muitas skills, mantenha cada descrição concisa e apresente primeiro o principal caso de uso. Você pode substituir o orçamento pela variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ mas a melhor solução é criar descrições mais curtas e precisas. Execute /context durante uma sessão para verificar se alguma skill está sendo excluída.

Arquivos de apoio e organização

Skills podem fazer referência a arquivos adicionais no mesmo diretório:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Faça referência a eles no SKILL.md usando links relativos. Claude lê esses arquivos sob demanda quando a skill é ativada. Mantenha o SKILL.md com menos de 500 linhas e mova o material de referência detalhado para arquivos de apoio.¹²

Como compartilhar skills pelo Git

As skills do projeto (.claude/skills/ na raiz do repositório) são compartilhadas pelo controle de versão:⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Quando os colegas de equipe fazem pull, eles recebem a skill automaticamente. Sem instalação nem configuração. Essa é a maneira mais eficaz de padronizar o conhecimento especializado de uma equipe.

Skills como uma biblioteca de prompts

Além das skills de finalidade única, a estrutura de diretórios funciona como uma biblioteca organizada de prompts:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Cada skill codifica um aspecto diferente do seu conhecimento especializado. Juntas, elas formam uma base de conhecimento que Claude consulta automaticamente com base no contexto. Um desenvolvedor júnior recebe orientação de nível sênior sem precisar pedi-la.

Skills trabalham em conjunto com hooks

Skills podem definir no frontmatter seus próprios hooks, que são ativados somente durante a execução da skill. Isso cria um comportamento específico do domínio que não polui outras sessões:²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

Skills de filosofia são ativadas automaticamente por hooks SessionStart, inserindo restrições de qualidade em todas as sessões sem invocação explícita. A skill é o conhecimento. O hook é a imposição. Juntos, eles formam uma camada de políticas.

Erros comuns com skills

Descrições amplas demais. Uma skill git-rebase-helper que é ativada por qualquer prompt relacionado ao git (rebases, merges, cherry-picks e até git status) polui o contexto em 80% das sessões. A solução é restringir a descrição ou adicionar disable-model-invocation: true e exigir uma invocação explícita por /skill-name.⁴

Skills demais competindo pelo orçamento. Quanto mais skills, mais descrições competem pelo orçamento de 1% do contexto. Se perceber que algumas skills não estão sendo ativadas, verifique em /context quais foram excluídas. Priorize poucas skills bem descritas em vez de muitas skills vagas.

Informações críticas escondidas em arquivos de apoio. Claude lê o SKILL.md imediatamente, mas só acessa os arquivos de apoio quando necessário. Se uma informação crítica estiver em um arquivo de apoio, talvez Claude não a encontre. Coloque as informações essenciais diretamente no SKILL.md.⁴

Superfície de skills do SDK (8 de maio de 2026)

Harnesses auto-hospedados no claude-agent-sdk-python v0.1.77+ devem usar a opção skills de ClaudeAgentOptions para declarar as skills disponíveis, em vez do valor legado "Skill" em allowed_tools.³⁷ O atalho "Skill" foi descontinuado, e a opção dedicada fornece a Claude Code informações mais estruturadas sobre quais skills estão disponíveis. O CLI incluído na v0.1.77 corresponde à v2.1.133.

Convergência de plugins e skills em .claude/skills/ (29 de maio de 2026)

Skills sempre foram carregadas do diretório .claude/skills/ de um projeto. A v2.1.157 de Claude Code estende esse diretório aos plugins: agora, um plugin colocado em .claude/skills/ é carregado automaticamente sem registro em um marketplace, e claude plugin init <name> cria a estrutura inicial de um novo plugin nesse local, com o manifesto e o SKILL.md já conectados.⁵⁸ Isso elimina a diferença entre os dois formatos de ferramentas de projeto que antes ficavam em locais distintos — uma skill independente enviada diretamente ao repositório e um plugin que reúne uma skill, hooks e um servidor MCP, mas que antes precisava de um marketplace para ser instalado. O efeito prático no design do harness: ferramentas restritas ao projeto não precisam mais passar por um registro para serem distribuídas — escreva, faça commit e seus colegas terão a mesma superfície ao executar git pull. Os plugins ainda atendem ao caso de uso de pacotes instaláveis (hooks + skills + servidores MCP + agents em um único ZIP); a mudança é que um projeto não precisa mais criar um marketplace apenas para carregar um plugin da própria árvore.

Como ocultar a superfície incluída para fins de governança (8 de junho de 2026)

Skills representam capacidade, e capacidade representa superfície de ataque. A v2.1.169 de Claude Code adiciona uma configuração disableBundledSkills (e a variável de ambiente correspondente CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) que oculta completamente do modelo as skills, os workflows e os comandos slash integrados incluídos.⁶⁰ Para um harness reforçado ou regulamentado, essa é uma redução deliberada da superfície de ataque: um operador que auditou e aprovou um conjunto específico de skills pessoais e do projeto pode suprimir tudo o que Anthropic fornece por padrão, para que o modelo raciocine apenas sobre a superfície avaliada pelo operador. Trate isso da mesma forma que uma lista de ferramentas permitidas — o padrão oferece ampla capacidade, e desativá-lo é uma decisão de governança, não uma simples configuração de conveniência.

.claude/skills aninhados e resolução pelo mais próximo (16 de junho de 2026)

A v2.1.178 de Claude Code tornou as ferramentas do projeto sensíveis à localização. As skills em diretórios .claude/skills aninhados agora são carregadas quando você trabalha em arquivos dentro desse diretório, e não apenas a partir da raiz do repositório; quando há um conflito de nomes, a skill aninhada aparece como <dir>:<name>, mantendo ambas acessíveis.⁶³ A mesma versão fez com que o restante da superfície do projeto fosse resolvido pela proximidade com o diretório de trabalho: quando o nome de um agent, workflow ou estilo de saída entra em conflito entre diretórios .claude/ aninhados, vence aquele que estiver mais próximo do diretório de trabalho, e o salvamento de um workflow no escopo do projeto usa o .claude/workflows/ existente mais próximo em vez de usar sempre o da raiz.⁶³ Para um monorepo ou um repositório de repositórios, essa é a diferença entre uma única superfície global e plana e ferramentas por pacote que são ativadas conforme o contexto — um services/api/.claude/skills/ pode conter skills específicas de API que aparecem somente enquanto você trabalha nessa árvore, sem entrar em conflito com uma skill de mesmo nome em services/web/.

Arquitetura de hooks

Hooks são comandos de shell acionados por eventos do ciclo de vida do Claude Code.³ Eles são executados fora do LLM como scripts comuns, não como prompts interpretados pelo modelo. O modelo quer executar rm -rf /? Um script bash de 10 linhas verifica o comando em uma lista de bloqueio e o rejeita antes mesmo que o shell o receba. O hook é acionado, quer o modelo queira ou não.

Eventos disponíveis

O Claude Code oferece 30 eventos documentados do ciclo de vida, distribuídos em oito categorias, na data desta atualização do guia. A lista de eventos cresce a cada versão, então considere a documentação de referência como a fonte da verdade e consulte a folha de consulta rápida para ver a tabela completa e atualizada antes de configurar hooks de produção:¹³

DirectoryAdded (v2.1.219) elimina a lacuna do workspace no meio da sessão. A lista de eventos permanecia estável desde a chegada de MessageDisplay na v2.1.152; DirectoryAdded é o primeiro novo evento do ciclo de vida desde então e é acionado depois que /add-dir — ou a solicitação de controle register_repo_root do SDK — registra um novo diretório de trabalho durante uma sessão.⁸⁴ A lacuna que ele elimina é real: até agora, um harness podia validar exaustivamente um workspace em SessionStart e, depois, ver um segundo repositório ser anexado sem que nenhum hook fosse acionado. Tudo o que você verificar sobre o workspace na inicialização — verificações de confiança, varreduras de segredos, regras de escopo de caminhos derivadas da árvore, carregamento de políticas por repositório — precisa ser executado novamente aqui, porque o conjunto de diretórios de uma sessão não permanece mais fixo desde o lançamento. O evento é informativo, não bloqueante, então use-o como gatilho para recalcular o estado e registrar a procedência, não como um gate; se nunca for permitido adicionar determinado diretório, bloqueie-o nas configurações em vez de tentar vetá-lo por meio de um hook. O suporte no SDK chegou na mesma versão (a TypeScript v0.3.219 adiciona DirectoryAdded aos eventos do ciclo de vida do protocolo de controle), portanto harnesses hospedados no SDK recebem esse evento nas mesmas condições que os hospedados no CLI.⁸⁵

Semântica dos códigos de saída

Os códigos de saída determinam se os hooks bloqueiam ações:³

Configuração de hooks

Os hooks ficam nos arquivos de configurações. Use o nível do projeto (.claude/settings.json) para hooks compartilhados e o nível do usuário (~/.claude/settings.json) para hooks pessoais:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

O campo matcher filtra um valor específico do evento. Para eventos de ferramentas, ele corresponde a valores de tool_name, como Bash, Edit, Write, Read, Glob, Grep, nomes de ferramentas do MCP, como mcp__server__tool, ou * para todas as ferramentas. Nomes simples e listas separadas por | têm correspondência exata; valores com outros caracteres são expressões regulares do JavaScript. Alguns eventos não aceitam matchers e são sempre acionados quando configurados.¹³ Desde o Claude Code v2.1.195, matchers contendo identificadores com hífen (code-reviewer, mcp__brave-search) usam correspondência exata, em vez de corresponder acidentalmente a substrings — um hook direcionado a um agente ou servidor não é mais acionado para todos os nomes que apenas contêm a string; para abranger todas as ferramentas de um servidor MCP com hífen, escreva o padrão explícito mcp__brave-search__.*.⁶⁶ A v2.1.214 aplicou o mesmo rigor aos padrões de caminho: uma condição if: de hook que usa um padrão dir/** de segmento único agora corresponde apenas a <cwd>/dir, não a todos os diretórios chamados dir em qualquer ponto da árvore — use **/dir/** quando você realmente quiser abranger qualquer profundidade.⁷⁴ Assim como na mudança da v2.1.195, a correção troca uma abrangência acidental por uma intenção declarada; audite todas as condições de hooks que dependiam silenciosamente do antigo comportamento em qualquer profundidade.

Protocolo de entrada/saída dos hooks

Os hooks recebem JSON via stdin com o contexto completo:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

Para controle avançado, hooks PreToolUse podem gerar JSON para modificar a entrada da ferramenta, injetar contexto ou tomar decisões de permissão. Use o wrapper hookSpecificOutput — o antigo formato de nível superior decision/reason está obsoleto para PreToolUse:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Três tipos de garantias

Antes de escrever qualquer hook, pergunte: de que tipo de garantia eu preciso?¹⁴

Garantias de formatação asseguram consistência após a ação. Hooks PostToolUse em Write/Edit executam o formatador depois de cada alteração de arquivo. A saída do modelo não importa porque o formatador normaliza tudo.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Garantias de segurança impedem ações perigosas antes que sejam executadas. Hooks PreToolUse em Bash inspecionam os comandos e bloqueiam padrões destrutivos com o código de saída 2:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

Garantias de qualidade validam o estado nos pontos de decisão. Hooks PreToolUse em comandos git commit executam o linter ou a suíte de testes e bloqueiam o commit se as verificações de qualidade falharem:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

Tipos de hooks além de comandos de shell

O Claude Code aceita cinco tipos de hooks:¹³

Hooks de comando (type: "command") executam scripts de shell. São rápidos, determinísticos e não têm custo de tokens. Hooks de tool do MCP (type: "mcp_tool") chamam uma tool em um servidor MCP já conectado. Use-os quando a lógica de validação já estiver por trás de um limite do MCP e não precisar de um script de shell separado.

Hooks de prompt (type: "prompt") enviam um prompt de turno único para um modelo Claude rápido. O modelo retorna { "ok": true } para permitir ou { "ok": false, "reason": "..." } para bloquear. Use-os para avaliações complexas que uma regex não consegue expressar.

Hooks de Agent (type: "agent") iniciam um subagent com acesso a tools (Read, Grep, Glob) para verificação em vários turnos. Eles são experimentais; prefira hooks de comando para gates de produção e reserve os hooks de Agent para verificações que realmente exijam a inspeção de arquivos reais ou da saída de testes:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

A partir do Claude Code v2.1.140, a entrada de hooks de Agent inclui subagent_type, o que permite que um hook compartilhado diferencie a execução de um security-reviewer da execução de um explorer ou worker genérico sem precisar inferir isso pelo texto do prompt.⁴⁹

Hooks HTTP (type: "http") enviam a entrada JSON do evento como uma solicitação POST para uma URL e recebem JSON como resposta. Use-os para webhooks, serviços externos de notificação ou validação baseada em API (v2.1.63+). Não são compatíveis com eventos SessionStart:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Hooks assíncronos

Os hooks podem ser executados em segundo plano sem bloquear a execução. Adicione async: true para operações não críticas, como notificações e logging:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

Use hooks assíncronos para notificações, telemetria e backups. Nunca use hooks assíncronos para formatação, validação ou qualquer tarefa que precise ser concluída antes da próxima ação.

Dispatchers em vez de hooks independentes

Executar sete hooks disparados pelo mesmo evento, cada um lendo stdin de forma independente, cria condições de corrida. Dois hooks que gravam simultaneamente no mesmo arquivo de estado JSON truncarão o JSON. Todos os hooks posteriores que analisarem esse arquivo falharão.²

A solução: um dispatcher por evento que execute os hooks sequencialmente usando o stdin armazenado em cache:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Depuração de hooks

Cinco técnicas para depurar hooks que falham silenciosamente:¹⁴

1. Teste os scripts de forma independente. Encaminhe um JSON de exemplo: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Use stderr para a saída de depuração. O stderr do código de saída 2 é retornado ao Claude como uma mensagem de erro. O stderr não bloqueante (saída 1, 3 etc.) aparece somente no modo detalhado (Ctrl+O).
3. Fique atento a falhas do jq. Caminhos JSON incorretos retornam null silenciosamente. Teste as expressões jq com uma entrada real da tool.
4. Verifique os códigos de saída. Um hook PreToolUse que usa exit 1 não impõe restrição alguma, embora pareça funcionar.
5. Mantenha os hooks rápidos. Os hooks são executados de forma síncrona. Mantenha todos abaixo de 2 segundos, de preferência abaixo de 500ms.

Streaming de eventos de hooks no SDK

Harnesses auto-hospedados criados com claude-agent-sdk-python (v0.1.74+, 6 de maio de 2026) podem assinar eventos de hooks diretamente no stream de mensagens, em vez de usar callbacks de scripts de shell.³⁶ Defina include_hook_events=True em ClaudeAgentOptions, e os objetos HookEventMessage (PreToolUse, PostToolUse, Stop e outros) serão produzidos pelo mesmo iterador que as mensagens do assistente e os resultados das tools. Isso corresponde à opção includeHookEvents do SDK do TypeScript; o CLI incluído também foi atualizado para a v2.1.129 na mesma versão.

O padrão de stream de eventos é a opção certa quando o harness já está no Python e você quer os sinais dos hooks no mesmo fluxo de controle da saída do modelo. O contrato de hooks de scripts de shell (códigos de saída, JSON via stdin, dispatchers) continua sendo a solução certa para harnesses que combinam várias tools, compartilham hooks entre Claude Code e Codex ou precisam da semântica dos códigos de saída para bloquear ações.

A série de julho de 2026 do SDK do TypeScript (v0.3.205–v0.3.208) tornou o próprio protocolo de streaming mais contratual.⁷⁰ Agora, as interrupções retornam recibos tipados: uma interrupção confirma quais mensagens enfileiradas ainda estão pendentes por meio de UUIDs em still_queued, e as sessões anunciam o recurso interrupt_receipt_v1 em system/init, permitindo que um coordenador diferencie entre “a interrupção foi aplicada” e “a interrupção chegou tarde demais para uma mensagem já em andamento”. Os frames command_lifecycle informam os estados de cada mensagem — enfileirada/iniciada/concluída/cancelada/descartada —, a primeira resposta oficial para “o que aconteceu com a mensagem que enviei” sem precisar inferir pelo histórico. Também foram adicionados recursos menores: um tipo AgentToolCompletedOutput para payloads de conclusão de subagents, e callbacks canUseTool agora podem retornar {behavior: 'allow'} sem um campo updatedInput.

Uma linha dessa série representa um requisito mínimo de segurança, não um recurso: a v0.3.208 corrigiu um problema no qual o cancelamento do chamador durante um hook pendente era convertido em sucesso do hook — o que significava que uma tool protegida por um hook PreToolUse poderia ser executada depois que o chamador tivesse cancelado.⁷⁰ Se o seu harness usa hooks no SDK como um gate de permissão e depende do cancelamento para interromper trabalhos em andamento, considere a v0.3.208 como a versão mínima; abaixo dela, “cancelado” não significava “bloqueado” de forma confiável. O Python v0.2.127 (24 de julho de 2026) é o segundo bypass desse tipo em um mês — query() fechava o stdin no primeiro frame result enquanto subagents em segundo plano ainda estavam em execução, fazendo com que as chamadas de tools SDK-MCP falhassem com "Stream closed" e ignorassem completamente os hooks PreToolUse.⁸⁵ Dê um nome ao padrão e fique atento a ele: a aplicação de hooks no SDK falha de forma permissiva nas transições do ciclo de vida — cancelamento, encerramento, fechamento do stream — em que o transporte é interrompido antes que o veredito do hook seja coletado. E a falha é silenciosa, porque um hook ignorado parece exatamente igual a um hook que aprovou. Fixe as versões mínimas dos dois SDK e mantenha a camada de hooks de shell como o mecanismo de controle que você consegue comprovar.

Proveniência de esforço e sessão (7 e 8 de maio de 2026)

Duas adições no Claude Code v2.1.132 e v2.1.133 fornecem aos hooks e subprocessos sinais melhores sobre o contexto de execução:³⁸³⁹

• effort.level na entrada do hook. Agora, os hooks recebem um campo JSON effort.level na mesma entrada que contém tool_input e session_id. O mesmo valor é exportado como a variável de ambiente $CLAUDE_EFFORT, permitindo que comandos Bash o leiam sem analisar o JSON. Use isso para dimensionar o custo do hook de acordo com o nível de esforço: ignore validações caras em low e execute o gate de segurança completo em xhigh ou max.
• Variável de ambiente CLAUDE_CODE_SESSION_ID em subprocessos Bash. Agora, os subprocessos da tool Bash recebem o mesmo valor de session_id visto pelos hooks, exposto como CLAUDE_CODE_SESSION_ID. Isso elimina a lacuna de proveniência das tools que registram o estado por sessão e que antes não conseguiam correlacionar eventos de subprocessos com eventos de hooks.

Os dois sinais estão disponíveis sem alterações no código; hooks existentes que ignoram os novos campos continuam funcionando.

autoMode.hard_deny e correções de hooks/plugins na v2.1.136 (8 de maio de 2026)

O Claude Code v2.1.136 adicionou um novo nível de negação obrigatória ao modo automático e corrigiu um conjunto de problemas de plugins e do MCP que afetavam harnesses de longa duração:⁴⁰ - settings.autoMode.hard_deny. Regras do classificador do modo automático que bloqueiam incondicionalmente, independentemente da intenção do usuário ou de exceções de permissão. Isso fica acima dos comparadores existentes de permissão/bloqueio como um mecanismo de governança inegociável. Use-o para regras que nunca devem ser ignoradas (force-push para a branch main, arquivos que contêm segredos, acesso ao banco de dados de produção), mesmo quando um operador tiver aprovado a categoria mais ampla em suas configurações pessoais. - autoMode.classifyAllShell (v2.1.193). Por padrão, o classificador do modo automático analisa apenas comandos shell que correspondem a padrões de execução arbitrária de código. Essa configuração encaminha todos os comandos Bash/PowerShell pelo classificador — a postura de cobertura máxima para um harness governado — e a mesma versão exibe os motivos do bloqueio na transcrição, na notificação e em /permissions, transformando bloqueios silenciosos em decisões auditáveis. O Codex tornou a funcionalidade equivalente mais rigorosa na v0.142.2: comandos PowerShell que contêm regiões AST executáveis que seu classificador de segurança não consegue inspecionar agora exigem aprovação, em vez de serem permitidos silenciosamente.⁶⁶ - O ask do hook estabelece o limite mínimo do classificador (v2.1.211). A questão da precedência entre hooks e o modo automático agora está resolvida: um hook PreToolUse que retorna uma decisão de permissão ask estabelece como resultado final mínimo a solicitação de confirmação — o modo automático não pode promovê-la novamente para permissão em comandos Bash executados fora do sandbox.⁶⁹ Para um harness governado, esse é o nível de garantia que faltava: o ask de um hook é uma parada determinística com intervenção humana que permanece até mesmo em posturas de permissão totalmente automáticas. Use ask (não apenas bloqueios com código de saída 2) nas operações em que você quer uma decisão humana, e não uma recusa. - O modelo do classificador fica fixado por sessão (v2.1.210). O classificador do modo automático usa o Sonnet 5 por padrão e permanece fixado durante a sessão, portanto mudanças de modelo no meio da sessão não alteram mais qual modelo faz as classificações de permissão.⁶⁹ A consistência da classificação é uma propriedade de governança; isso elimina uma fonte discreta de variação. - Os servidores MCP não desaparecem mais depois de /clear. Servidores configurados em .mcp.json, plugins e conectores do claude.ai estavam sendo removidos silenciosamente do conjunto ativo após um /clear na extensão do VS Code, no plugin do JetBrains e no Agent SDK. A correção chegou na v2.1.136. Se você percebeu que “o servidor MCP X desapareceu no meio da sessão”, essa era a causa. - Perda do refresh token do OAuth do MCP durante atualizações simultâneas. Usuários com vários servidores MCP remotos não devem mais precisar refazer a autenticação diariamente. Gravações simultâneas de atualização estavam sobrescrevendo umas às outras. - O modo de planejamento agora bloqueia corretamente a gravação de arquivos. Uma regra de permissão Edit(...) correspondente estava contornando a proteção contra gravação do modo de planejamento. Agora, o modo de planejamento é aplicado independentemente das regras de permissão. - Os hooks Stop e UserPromptSubmit de plugins não falham mais no meio da sessão. A limpeza do cache estava excluindo arquivos de versões de plugins ainda usados pela sessão em execução, interrompendo especificamente esses dois eventos de hook. A correção mantém fixadas as versões em uso. - Entrada skills em plugin.json. Definir skills estava ocultando a pasta padrão skills/ do plugin. Agora, a entrada é combinada corretamente, e apontá-la para um caminho de arquivo gera um erro explícito em vez de falhar silenciosamente. - Variáveis de ambiente do hook SessionStart em CLAUDE_ENV_FILE ficavam desatualizadas. As variáveis exportadas por hooks SessionStart por meio de CLAUDE_ENV_FILE ficavam desatualizadas após /resume ou /clear. Corrigido na v2.1.136. Agora, as sessões recarregam o arquivo de ambiente nesses eventos.

Para harnesses de governança, os itens operacionalmente relevantes são autoMode.hard_deny (um novo mecanismo) e a correção do desaparecimento do MCP (uma falha silenciosa que interrompia sessões longas). Todo o restante são melhorias de conveniência.

Argumentos estruturados de hooks e continuação após bloqueio (11 de maio de 2026)

O Claude Code v2.1.139 adicionou dois detalhes de hooks importantes para harnesses de produção: uma forma de execução args: string[] para hooks de comando e continueOnBlock para hooks PostToolUse.⁴²⁴⁴ Prefira args quando um hook precisar de valores dinâmicos ou placeholders de caminhos. Ele inicia o comando diretamente, sem um shell, eliminando toda uma categoria de erros de aspas e injeção.

Use continueOnBlock quando um hook PostToolUse precisar devolver o motivo da rejeição ao Claude e continuar o turno em vez de encerrar o fluxo. Trate-o como um recurso para melhorar a experiência do operador, não como uma forma de contornar a segurança. Um gate de bloqueio ainda deve impedir o resultado inseguro.

A mesma versão passa CLAUDE_PROJECT_DIR para servidores stdio MCP e permite que as configurações de plugins façam referência a ${CLAUDE_PROJECT_DIR} nos comandos.⁴² As ferramentas MCP devem resolver caminhos relativos ao projeto com base nesse valor, e não no diretório de trabalho do processo que iniciou o servidor. As versões do início de julho de 2026 (v2.1.203–v2.1.206) estenderam o mesmo princípio ao nível do protocolo: o roots/list do MCP agora inclui os diretórios de trabalho adicionais da sessão, com notificações roots/list_changed quando eles mudam — assim, um servidor que respeita as raízes do MCP acompanha a estrutura real do workspace com vários diretórios em vez de presumir um único diretório de projeto.⁶⁸

O Claude Code v2.1.140 é principalmente uma versão de confiabilidade para operadores de harnesses: corrige hooks ConfigChange que não eram acionados quando as configurações mudavam, resolve casos extremos em que disableAllHooks e allowManagedHooksOnly não se combinavam corretamente entre diferentes níveis de configuração e impede que as caixas de diálogo de permissão exponham variáveis de ambiente não pretendidas retornadas pelos resultados dos hooks.⁴⁹ Isso torna mais confiáveis os padrões de governança existentes nesta seção; não exige uma nova arquitetura de hooks.

O Claude Code v2.1.141 adiciona o campo terminalSequence à saída dos hooks para notificações na área de trabalho, títulos de janelas e sinais sonoros sem um terminal controlador.⁵⁰ Trate isso como sinalização para o operador, não como mecanismo de aplicação. Os gates de segurança e qualidade ainda devem comunicar falhas pelo contrato normal de bloqueio: saída estruturada do hook junto com o comportamento de saída que impede a ação insegura. A mesma versão adiciona claude agents --cwd <path> para limitar a Agent View a uma pasta, CLAUDE_CODE_PLUGIN_PREFER_HTTPS para instalações de plugins em ambientes sem chaves GitHub SSH e ANTHROPIC_WORKSPACE_ID para regras de federação de identidade de carga de trabalho que abrangem mais de um workspace.⁵⁰ Esses são detalhes de arquitetura para harnesses de equipe: visualizações operacionais mais específicas, menos pressupostos na instalação de plugins e escopo explícito de tokens empresariais.

O Claude Code v2.1.142 é mais importante para a orquestração de sessões em segundo plano do que para a semântica dos hooks.⁵¹ Agora, claude agents pode iniciar sessões em segundo plano com flags explícitas de diretório, configurações, MCP, plugin, permissão, modelo e esforço, em vez de depender do estado de um wrapper. Nessa versão, o modo rápido passou a usar o Opus 4.7 por padrão, com CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 para fixar o modelo em um harness cuja dependência do comportamento do Opus 4.6 tenha sido medida — a partir da v2.1.219, o Opus 4.7 não faz mais parte do modo rápido, e /fast se aplica ao Opus 5 e ao Opus 4.8.⁸⁴ A descoberta do SKILL.md na raiz do plugin e a visibilidade de LSPs fornecidos por plugins reduzem a ambiguidade do empacotamento. Correções em MCP_TOOL_TIMEOUT, worktrees preexistentes de sessões em segundo plano, suspensão/reativação do daemon, limpeza após atualizações e limpeza do cache de plugins eliminam falhas de confiabilidade que, de outra forma, pareceriam bugs de orquestração.

Direcionamento por Stop hooks, autoridade entre sessões e multi-agent v2 (junho de 2026)

Quatro mudanças do início de junho são importantes para o design de harnesses e sistemas multi-agent.⁵⁹

Os hooks Stop/SubagentStop ganharam um canal de direcionamento. A partir do Claude Code v2.1.163, um hook Stop ou SubagentStop pode retornar hookSpecificOutput.additionalContext para fornecer feedback ao Claude e manter o turno em andamento, sem que a resposta seja rotulada como erro de hook. Antes disso, o único mecanismo efetivo de um Stop hook era o bloqueio com código de saída 2, que aparece como erro e conta para o limite de bloqueios consecutivos. Para um harness com quality gates, esse é um recurso mais adequado: um Stop hook que detecta “você disse que terminou, mas os testes estão falhando” agora pode injetar “isto ainda está falhando, continue” em vez de bloquear o fluxo. Use o bloqueio para condições reais de parada e additionalContext para “ainda não terminou; veja o motivo”.

Mensagens entre sessões não carregam mais autoridade emprestada. A v2.1.166 reforçou a segurança no cenário com várias sessões: mensagens encaminhadas por SendMessage de outra sessão do Claude não carregam mais a autoridade do usuário de origem, portanto uma sessão receptora recusa solicitações de permissão encaminhadas e o modo automático as bloqueia. Se sua orquestração permite que agentes troquem mensagens, trate uma mensagem recebida como dados não confiáveis, não como uma instrução autenticada. Esse é o mesmo princípio que a seção de segurança aplica à saída de ferramentas, estendido à comunicação entre agentes. A partir da v2.1.199, o Claude Code também detecta e alerta quando uma SendMessage é encaminhada incorretamente porque dois agentes têm o mesmo nome — um complemento de confiabilidade para esse limite de autoridade, pois uma mensagem que chega ao agente errado com o mesmo nome constitui uma categoria própria de bug de orquestração. A resiliência do modelo se tornou uma configuração de primeira classe. A configuração fallbackModel agora encadeia até três modelos de backup, testados em ordem quando o principal está sobrecarregado ou indisponível, e um turno tenta novamente uma vez no fallback em caso de erros inesperados e não repetíveis de API. Para um harness autônomo de longa duração, isso transforma uma interrupção temporária do modelo principal em uma degradação gradual, em vez de descartar a execução. claude agents --json também adicionou um campo waitingFor (v2.1.162), que mostra o que uma sessão em segundo plano bloqueada está aguardando, como uma solicitação de permissão — um ganho de observabilidade para qualquer coordenador que monitore regularmente uma frota de agentes.

Modo seguro para governança em ambiente isolado e solução de problemas. O Claude Code v2.1.169 adiciona uma flag --safe-mode (e a variável de ambiente correspondente CLAUDE_CODE_SAFE_MODE) que inicia uma sessão com todas as personalizações desativadas de uma só vez: CLAUDE.md, plugins, skills, hooks e servidores MCP.⁶⁰ É o inverso do harness — um ambiente isolado criado de propósito. Use-o para responder à pergunta que todo operador acaba fazendo: “esse comportamento vem do modelo ou de algo que configurei?” Quando um hook é acionado incorretamente, uma skill é ativada quando não deveria ou um servidor MCP contamina o contexto, --safe-mode oferece uma referência conhecida e vazia para comparação. Ele também é um recurso básico de governança: uma forma de executar o modelo puro, sem nenhuma das autoridades persistentes que seu harness normalmente concede, algo importante quando você precisa reproduzir um resultado sem a influência de qualquer estrutura de suporte definida pelo operador.

Uma observação sobre os níveis de modelos. Desde o Claude Code v2.1.197 (30 de junho de 2026), Claude Sonnet 5 é o modelo padrão fornecido para novas sessões — contexto nativo de 1M, preço promocional de US$ 2/US$ 10 por MTok até 31 de agosto — substituindo o Opus 4.8 como opção pronta para uso. Este guia considera o Opus 5 (claude-opus-5) o padrão recomendado para agentes: o modelo para executar harnesses autônomos, a menos que você escolha deliberadamente outro, porque loops de agentes de longo prazo e alto risco são exatamente onde a profundidade de raciocínio do Opus compensa seu custo. O Opus 5 foi lançado em 24 de julho de 2026 como o novo Opus padrão no Claude Code v2.1.219 — contexto de 1M, US$ 5/US$ 25 por MTok (o mesmo preço do Opus 4.8 que ele substitui), modo rápido por US$ 10/US$ 50 com aproximadamente 2,5× a velocidade padrão — e a Anthropic relata que ele mais que dobrou o desempenho do Opus 4.8 no Frontier-Bench v0.1, ficando a menos de 0,5% da pontuação do Fable 5 no CursorBench 3.2 pela metade do custo.⁸⁴⁸⁷ Mesmo preço, mais capacidade e um modelo que a Anthropic descreve como “muito mais competente para verificar o próprio trabalho e iterar com cuidado” formam aquele raro upgrade que dispensa argumentos de custo para trabalhos com harness; para migrar da versão 4.8, basta alterar o id. Use o Sonnet 5 em trabalhos sensíveis a custo ou de alto volume, nos quais sua relação entre velocidade e inteligência se destaca. Acima do Opus está o Claude Fable 5 (claude-fable-5), lançado em 9 de junho de 2026 — um novo nível descrito como o modelo mais poderoso da Anthropic, um sistema “Mythos-class” seguro para uso geral, selecionável no Claude Code v2.1.170 por meio de /model claude-fable-5.⁶⁰ Recorra deliberadamente ao nível superior nas decisões em que a profundidade bruta de raciocínio justifique o custo, não como configuração geral para toda uma frota. Duas consequências práticas da transição para o Opus 5: o Opus 4.7 saiu do modo rápido (/fast agora se aplica ao Opus 5 e ao Opus 4.8), e o fallback do Fable 5 no classificador do modo automático — “o melhor modelo Opus disponível” desde a v2.1.176 — agora seleciona o Opus 5.⁸⁴

O Codex lançou o multi-agent v2. O Codex CLI v0.137.0 mantém a escolha do runtime em cada thread, oferece padrões mais claros de acompanhamento e metadados para agentes gerados (hide_spawn_agent_metadata agora tem true como padrão) e propaga eventos brutos do agente pai para os listeners dos agentes filhos. Seu modelo de subagents permanece explícito: tipos de agente integrados default/worker/explorer, agentes personalizados definidos em TOML e controles de concorrência (agents.max_threads com padrão 6, agents.max_depth com padrão 1). A mesma versão adiciona uma extensão v1 de skills, com resolução do catálogo de skills a cada turno e novos eventos de contribuição ao ciclo de vida para início de thread e erro de turno, reduzindo a diferença em relação à interface de hooks/skills do Claude Code, enquanto mantém a abordagem de sandbox no kernel como limite padrão. Em seguida, as versões Codex v0.138.0–v0.139.0 reforçaram o multi-agent v2 para produção: os payloads das mensagens entre agentes agora são criptografados, um catálogo v2 de configurações de agentes junto com um LRU de residência de agentes gerencia quais deles permanecem residentes, e a concorrência é contabilizada por execução ativa, não por threads geradas, então agentes ociosos não ocupam mais uma vaga.⁶¹ O ciclo de vida de API também amadureceu — close_agent foi renomeado como interrupt_agent (v0.139.0) para deixar claro que ele interrompe um agente em execução, em vez de apenas fechar um identificador — e os avisos de inicialização de MCP gerados por um subagent agora permanecem restritos à thread proprietária, em vez de serem duplicados na transcrição do agente pai.⁶¹ Para quem desenvolve orquestração no Codex, esses recursos representam a diferença entre uma demonstração e uma frota: transporte de mensagens criptografado, residência limitada, concorrência contabilizada por execução e avisos que não vazam para além dos limites da thread. Depois, o Codex v0.140.0 abriu um ponto de integração entre ferramentas: /import transfere seletivamente a configuração inicial, a configuração do projeto e conversas recentes do Claude Code para o Codex, e as sessões passaram a poder ser excluídas permanentemente (codex delete / /delete, com proteções de confirmação).⁶⁴ /import é o primeiro reconhecimento oficial de que os operadores transitam entre harnesses — a configuração que você cria para um deles não fica mais presa ali.

Memória e contexto

Toda conversa com IA opera dentro de uma janela de contexto finita. Conforme a conversa cresce, o sistema compacta as interações anteriores para abrir espaço para novos conteúdos. Essa compactação gera perdas. Decisões arquitetônicas documentadas na interação 3 podem não chegar à interação 15.⁹

Os três mecanismos do colapso em múltiplas interações

O estudo da MSR/Salesforce identificou três mecanismos independentes, cada um exigindo uma intervenção diferente:⁹

Estratégia 1: sistema de arquivos como memória

A memória mais confiável entre diferentes contextos fica no sistema de arquivos. Claude Code lê CLAUDE.md e os arquivos de memória no início de cada sessão e depois de cada compactação.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

O arquivo MEMORY.md registra erros, decisões e padrões entre as sessões. Quando você descobre que ((VAR++)) falha com set -e no bash quando VAR é 0, registra essa informação. Três sessões depois, ao encontrar um caso semelhante envolvendo números inteiros em Python, a entrada do MEMORY.md recupera esse padrão.¹⁵

Auto Memory (v2.1.32+): Claude Code registra e recupera automaticamente o contexto do projeto. Enquanto você trabalha, Claude grava observações em ~/.claude/projects/{project-path}/memory/MEMORY.md. O Auto Memory carrega as primeiras 200 linhas no prompt do sistema no início da sessão. Mantenha o arquivo conciso e inclua links para arquivos separados por assunto quando precisar de anotações detalhadas.⁶ Desde a v2.1.210, uma gravação em MEMORY.md que excede o limite de tamanho gera um erro em vez de ser silenciosamente truncada⁶⁹ — a falha aparece no momento da gravação, em vez de produzir entradas de memória que desaparecem sem aviso. Se o seu harness automatiza gravações na memória, trate esse erro; ele é a forma da plataforma informar que o arquivo precisa de curadoria, não de uma nova tentativa.

Curadoria da memória em vez de volume de memória (maio de 2026): Um preprint recente do arXiv sobre cooperação entre agentes LLM apresenta a ampliação da capacidade de recordação como um possível modo de falha: nos experimentos dos autores, um histórico visível mais longo prejudicou a cooperação em 18 de 28 configurações de jogos com modelos.⁴⁸ Encare isso como um alerta de design, não como uma lei definitiva. A regra para produção já está clara: mantenha o MEMORY.md curto, inclua links para os detalhes e coloque resumos prontos para orientar decisões nos handoffs. Dumps brutos de transcrições, logs de ferramentas e feeds extensos de recordações devem ficar em um armazenamento pesquisável, não ser inseridos automaticamente no prompt ativo.

Estratégia 2: compactação proativa

O comando /compact do Claude Code resume a conversa e libera espaço de contexto, preservando as principais decisões, o conteúdo dos arquivos e o estado da tarefa.¹⁵

Quando compactar: - Depois de concluir uma subtarefa independente (recurso implementado, bug corrigido) - Antes de começar a trabalhar em uma nova área da base de código - Quando Claude começar a repetir informações ou esquecer o contexto anterior - Aproximadamente a cada 25 a 30 minutos durante sessões intensivas

Instruções personalizadas de compactação no CLAUDE.md:

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

A compactação protege a conversa; o comando /cd (Claude Code v2.1.169) protege o cache do prompt. Ele transfere uma sessão para um novo diretório de trabalho durante a execução sem invalidar o cache acumulado ao longo da interação.⁶⁰ Antes disso, mudar de diretório exigia uma nova sessão e um cache frio. Em uma sessão longa que passa de um repositório para outro relacionado — algo comum em trabalhos com monorepos e vários serviços —, /cd mantém intacto o custoso prefixo em cache enquanto redireciona o contexto do sistema de arquivos.

Estratégia 3: handoffs entre sessões

Para tarefas que abrangem várias sessões, crie documentos de handoff que registrem todo o estado:

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

A estrutura Status/Files/Decision/Blocked/Next fornece à sessão sucessora todo o contexto com um custo mínimo de tokens. Iniciar uma nova sessão com claude -c (continuar) ou ler o documento de handoff permite ir direto para a implementação.¹⁵

Estratégia 4: iteração com contexto novo (o Ralph loop)

Para sessões que ultrapassam 60 a 90 minutos, inicie uma nova instância de Claude a cada iteração. O estado persiste por meio do sistema de arquivos, não da memória da conversa. Cada iteração recebe todo o orçamento de contexto:¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

Compare isso com uma única sessão longa:

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

A abordagem de usar um contexto novo a cada iteração troca um overhead de 15% a 20% na etapa de orientação (leitura dos arquivos de estado e análise do histórico do git) por todos os recursos cognitivos disponíveis em cada iteração.¹⁶ O cálculo de custo-benefício é o seguinte: para sessões com menos de 60 minutos, uma única conversa é mais eficiente. Depois de 90 minutos, um contexto novo produz resultados de maior qualidade apesar do overhead.

Estratégia 5: curadoria gerenciada da memória (Dreaming)

Os Managed Agents de Claude do Anthropic adicionaram o Dreaming como Research Preview em 6 de maio de 2026.³⁵ Segundo o Anthropic: “Dreaming é um processo agendado que analisa as sessões e os armazenamentos de memória do seu agente, extrai padrões e faz a curadoria das memórias para que seus agentes melhorem ao longo do tempo.”³⁵

O Dreaming é executado em segundo plano entre as sessões, não no caminho crítico. Ele complementa, em vez de substituir, o padrão de sistema de arquivos como memória: seu arquivo MEMORY.md continua sendo a base de sustentação; o Dreaming grava entradas de memória selecionadas no armazenamento de memória dos Managed Agents, que o agente lê no início da sessão. Os dois padrões coexistem em harnesses que combinam o estado do sistema de arquivos auto-hospedado com a curadoria do lado gerenciado.

O Dreaming está em Research Preview, portanto seu comportamento pode mudar. Os padrões de handoffs entre sessões e de CLAUDE.md documentados acima continuam sendo o mecanismo de memória definitivo para harnesses auto-hospedados.

Os antipadrões

Ler arquivos inteiros quando você precisa de 10 linhas. A leitura de um único arquivo com 2.000 linhas consome de 15.000 a 20.000 tokens. Use offsets de linha: Read file.py offset=100 limit=20 economiza a maior parte desse custo.¹⁵

Manter mensagens de erro detalhadas no contexto. Depois de depurar um bug, seu contexto contém mais de 40 stack traces de tentativas malsucedidas. Executar /compact uma única vez após corrigir o bug elimina esse peso morto.

Começar cada sessão lendo todos os arquivos. Deixe que as ferramentas glob e grep do Claude Code encontrem os arquivos relevantes conforme necessário, economizando mais de 100.000 tokens de pré-carregamento desnecessário.¹⁵

Padrões de subagents

Subagents são instâncias especializadas de Claude que realizam tarefas complexas de forma independente. Eles começam com um contexto limpo (sem interferência da conversa principal), operam com as ferramentas especificadas e retornam os resultados como resumos. Os resultados da exploração não sobrecarregam sua conversa principal; apenas as conclusões retornam.⁵

Tipos de subagents integrados

Criando subagents personalizados

Defina subagents em .claude/agents/ (projeto) ou ~/.claude/agents/ (pessoal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Campos de configuração de subagents

Isolamento com worktree

Subagents podem operar em git worktrees temporários, o que oferece uma cópia isolada completa do repositório:⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

O isolamento com worktree é essencial para trabalhos experimentais que possam quebrar a base de código.

Isolamento só é isolamento quando a fronteira se mantém. A v2.1.210 do Claude Code corrigiu um bug que permitia que subagents isolados por worktree alterassem o checkout principal — exatamente a falha que esse mecanismo existe para evitar.⁶⁹ Se você depende de isolation: worktree como uma fronteira de segurança, e não apenas como conveniência, considere a v2.1.210 como a versão mínima. A mudança de permissões relacionada segue na direção oposta: a partir da v2.1.211, regras de “sempre permitir” persistem na raiz do repositório entre worktrees, portanto uma regra aceita em um worktree se aplica aos worktrees irmãos do mesmo repositório.⁶⁹ Essa é a ergonomia certa para agentes executados em worktrees paralelos, mas significa que uma permissão concedida durante um experimento descartável continua válida depois do fim do experimento — conceda-a pensando no repositório inteiro, não apenas no worktree à sua frente.

A v2.1.216 concluiu o trabalho, levando o isolamento com worktree do nível de correção de bugs para o nível de aplicação rigorosa.⁷⁴ A correção da v2.1.210 impediu que subagents em worktrees alterassem o checkout principal por meio do uso comum do git, mas o próprio git oferece redirecionamento explícito — git -C <path>, --git-dir e as variáveis de ambiente GIT_DIR/GIT_WORK_TREE —, e um subagent isolado por worktree ainda podia direcionar qualquer uma dessas opções ao checkout compartilhado. Todas essas rotas de escape agora estão fechadas. A mesma versão corrigiu sessões de worktree que ocasionalmente terminavam em um worktree remanescente de um projeto diferente, impediu que gravações de workflows e tarefas agendadas seguissem um link simbólico colocado em .claude para um destino fora do projeto e fez /rewind se recusar a percorrer links simbólicos e hard links. O padrão nas quatro correções é o mesmo: uma fronteira de isolamento precisa resistir ao redirecionamento deliberado — substituições por variáveis de ambiente do git, inserção de links simbólicos —, não apenas ao comportamento padrão. Se isolation: worktree for uma fronteira de segurança no seu harness, e não apenas uma conveniência, a v2.1.216 é a nova versão mínima.

Subagents paralelos

Use subagents paralelos para tarefas de pesquisa independentes que não precisem se coordenar entre si:⁵

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Cada agente é executado em sua própria janela de contexto, encontra o código relevante e retorna um resumo. O contexto principal permanece limpo.

A proteção contra recursão

Sem limites de inicialização, agentes delegam a agentes que delegam a outros agentes, cada um perdendo contexto e consumindo tokens. O padrão de proteção contra recursão aplica limites de orçamento:¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Lição fundamental: use orçamentos de inicialização, não apenas limites de profundidade. Limites baseados em profundidade acompanham cadeias entre pais e filhos (bloqueadas na profundidade 3), mas não consideram a largura: 23 agentes na profundidade 1 ainda correspondem à “profundidade 1”. Um orçamento de inicialização acompanha o total de filhos ativos por pai, limitado a um máximo configurável. O modelo de orçamento corresponde ao modo de falha real (agentes demais no total), em vez de usar uma métrica indireta (níveis demais de aninhamento).⁷

O padrão de profundidade de aninhamento mudou três vezes; não construa sua arquitetura sobre ele. A v2.1.172 do Claude Code (10 de junho de 2026) permitiu que sub-agents iniciassem seus próprios sub-agents, com aninhamento de até 5 níveis — antes, a delegação era efetivamente limitada a um nível.⁶² Isso permaneceu da v2.1.172 até a v2.1.216. A v2.1.217 (21 de julho de 2026) reduziu o limite para 1, desativando por padrão a inicialização aninhada. Depois, a v2.1.219 (24 de julho de 2026) chegou a um meio-termo: “Subagents agora podem iniciar subagents aninhados até a profundidade 3 por padrão (antes era 1); defina CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 para desativar o aninhamento.”⁸⁴ Cinco, depois um, depois três — com as duas últimas mudanças ocorrendo em três dias.

A conclusão útil não é que qualquer um desses números esteja correto. É que a plataforma ainda procura o padrão ideal, o que torna “o que vier na versão” uma escolha inadequada para um harness herdar. Trate a profundidade de aninhamento como uma linha explícita do orçamento: defina CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH de acordo com a profundidade realmente necessária para sua arquitetura — na maioria das orquestrações, 1 ou 2 — para que uma atualização não altere silenciosamente a profundidade de delegação da sua frota. O argumento central não muda com toda essa instabilidade: cadeias de agentes delegando a outros agentes consomem contexto e tokens mais rápido do que produzem resultados, e a profundidade é um risco que deve entrar no orçamento, não uma capacidade a ser perseguida. A proteção contra recursão acima impede que uma árvore profunda se expanda para centenas de agentes ativos, independentemente de como o padrão volte a mudar, e um limite definido por você é o único número de profundidade que continuará significando o que você espera depois da próxima versão.

O modo automático agora avalia as inicializações antes que elas ocorram. A v2.1.178 do Claude Code corrigiu a lacuna correspondente de governança: no modo automático, as inicializações de subagents são avaliadas pelo classificador de permissões antes que o subagent seja iniciado, não apenas depois que ele começa a realizar ações.⁶³ Antes, um subagent podia ser iniciado para solicitar uma ação que a sessão pai não teria permissão para realizar — a própria inicialização era o desvio. A avaliação no momento da inicialização finalmente conecta a proteção contra recursão ao modelo de permissões: um filho não pode ser usado como intermediário para disfarçar uma ação proibida pela política.

A plataforma agora inclui um orçamento de inicialização nativo. A v2.1.212 do Claude Code (julho de 2026) adicionou proteções nativas contra loops descontrolados: por padrão, as sessões são limitadas a 200 inicializações de subagents (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION para ajustar, /clear redefine o contador), e WebSearch é limitado a 200 chamadas por sessão (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ O padrão de orçamento de inicialização que esta seção documenta como script criado pelo usuário desde a v1.0 agora é fornecido pela plataforma — uma validação do modelo de orçamento em relação ao modelo de profundidade. Mas observe a calibração: 200 inicializações é uma ordem de grandeza acima do orçamento de 12 agentes da configuração acima. Os limites nativos são fusíveis contra um loop realmente descontrolado, não orçamentos ajustados à sua arquitetura. Mantenha a proteção criada pelo usuário para orçamentos por pai, acompanhamento de profundidade e limites adequados ao que sua orquestração realmente deve fazer; deixe que o limite da plataforma capture o que conseguir escapar.

O conjunto nativo de proteções agora abrange quatro eixos. Três deles reforçam exatamente o que a proteção criada pelo usuário desta seção acompanha: total de inicializações por sessão (v2.1.212, limite de 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), profundidade de aninhamento (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, padrão atual de 3 e comprovadamente instável) e execução simultânea (v2.1.217, padrão de 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS — uma única mensagem não pode mais se expandir para um número ilimitado de agentes em segundo plano).⁷⁸⁸⁴ A v2.1.219 adiciona um quarto eixo que as proteções criadas pelo usuário geralmente não tinham: largura da orquestração, o número de agentes que um único workflow planejado pode conter, fornecido como diretriz padrão de “tente usar menos de 15 agentes” e configurável em qualquer arquivo de configurações por meio de workflowSizeGuideline (abordado na seção sobre a ferramenta Workflow abaixo). O padrão de orçamento de inicialização agora conta com suporte em todos os eixos para os quais foi projetado, além de um eixo adicional.

A observação sobre calibração ainda se aplica, mas de forma desigual. As 200 inicializações e os 20 agentes simultâneos são fusíveis — uma ordem de grandeza acima do orçamento de deliberação de 12 agentes na configuração acima, dimensionados para capturar um loop descontrolado, não para moldar uma arquitetura. A diretriz de largura é o primeiro número nativo na mesma faixa de um orçamento real: 15 agentes por workflow fica muito próximo dos 12 deste guia, o bastante para que adotar o padrão da plataforma não custe nada e discordar dele exija um motivo concreto. Defina os três fusíveis com valores que você possa justificar; defina a diretriz de largura de acordo com o formato da orquestração que você pretendia construir.

Agent Teams (prévia de pesquisa)

Agent Teams coordenam várias instâncias de Claude Code que trabalham de forma independente, comunicam-se por uma caixa de mensagens e uma lista de tarefas compartilhadas e podem questionar as descobertas umas das outras:⁵

Ative com: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Quando usar Agent Teams em vez de subagents:

Agent View e loops de objetivo (maio de 2026)

A v2.1.139 do Claude Code adicionou o Agent View, uma interface em prévia de pesquisa iniciada com claude agents que mostra em uma única tela as sessões de Claude Code em execução, bloqueadas e concluídas.⁴²⁴³ A documentação oficial apresenta o recurso como uma maneira de distribuir e gerenciar várias sessões, acompanhar o que cada uma está fazendo e identificar quais precisam da intervenção do operador.⁴³ Isso oferece ao trabalho multiagente uma visão operacional que os resumos finais não conseguem proporcionar.

Use o Agent View ao promover um padrão de subagent ou equipe: verifique quais sessões estão bloqueadas, quais ainda estão em execução e se a distribuição do trabalho corresponde à arquitetura pretendida. Não o considere uma prova de qualidade. Ele oferece observabilidade; testes, gates de revisão e relatórios de evidências ainda determinam se o trabalho é sólido.

A mesma versão adicionou /goal, que define uma condição de conclusão e permite que Claude continue entre os turnos até que a condição seja atendida, inclusive no uso interativo, com -p e com Remote Control.⁴² Trate /goal como um loop de conclusão limitado à sessão, não como substituto de gates determinísticos. Ele é útil para manter um agente concentrado em um objetivo, mas testes, verificações de citações, verificações de deploy e hooks de segurança devem continuar apoiados por comandos ou scripts quando uma falha precisar bloquear o processo.

Ferramenta Workflow (v2.1.147+)

A v2.1.147 do Claude Code adiciona uma ferramenta Workflow, desativada por padrão, para orquestração multiagente determinística. Ative-a com CLAUDE_CODE_WORKFLOWS=1.⁵² Do ponto de vista da arquitetura, isso é importante porque oferece ao Claude Code um recurso nativo de orquestração para fluxos que antes exigiam scripts personalizados de distribuição, estado da caixa de mensagens e convenções de coordenação entre subagents.

Não remova o harness ao redor dela. Um Workflow pode estruturar a execução, mas não substitui seu modelo de segurança. Mantenha os hooks PreToolUse e PostToolUse como camada de bloqueio, mantenha orçamentos de inicialização ou de etapas do workflow para evitar largura descontrolada, mantenha o estado do sistema de arquivos auditável e mantenha os relatórios finais de evidências fora da autoavaliação do modelo. Na prática: use Workflow para definir a estrutura da orquestração; use hooks, testes e gates de revisão para determinar a verdade.

Workflows dinâmicos agora incluem uma opinião sobre largura (v2.1.219). Workflows dinâmicos usam por padrão uma diretriz de tamanho médio — “tente usar menos de 15 agentes” —, com outros tamanhos e uma opção irrestrita disponíveis em Dynamic workflow size no /config, enquanto a diretriz atual aparece na linha de status do workflow em execução.⁸⁴ O número é consultivo, não obrigatório; ele orienta o planejador em vez de bloquear um plano amplo. O que justifica configurá-lo é o mecanismo de distribuição: a nova chave de configurações workflowSizeGuideline pode ser definida em qualquer arquivo de configurações — inclusive em configurações gerenciadas e configurações de projeto, além de estar nos tipos de configurações de SDK do TypeScript desde a v0.3.219 —, portanto a largura da orquestração se torna algo que uma equipe ou organização pode padronizar, em vez de algo que cada operador precisa redescobrir.⁸⁵ Defina-a no nível do projeto para representar como o trabalho da sua base de código realmente pode ser decomposto. Duas observações para operadores: a linha do /config fica oculta quando o valor é controlado por um arquivo de configurações, o que é o comportamento correto, mas parece uma configuração ausente quando você não sabe o motivo; e, como a diretriz orienta o planejador em vez de controlar a execução, ela pertence à coluna de estrutura, não à coluna de segurança. Controlar a largura descontrolada ainda é responsabilidade do limite de inicializações.

A interpretação que vale preservar é que este é o quarto eixo nativo de proteção — largura da orquestração, ao lado do número de inicializações, da profundidade de aninhamento e da execução simultânea — e o primeiro que Anthropic calibrou com um tamanho plausível de trabalho, em vez de tratá-lo como um fusível contra descontrole. Quinze agentes por workflow está na mesma ordem de grandeza do orçamento de deliberação de 12 agentes que este guia utiliza desde a v1.0. Quando o padrão da plataforma e seu próprio orçamento convergem partindo de direções opostas, isso é o mais próximo que esses números chegam de uma confirmação independente.

Bifurcação de sessões e MCP automático em segundo plano (julho de 2026)

A v2.1.212 do Claude Code reformulou dois recursos de orquestração.⁶⁹ Agora, /fork cria uma nova sessão em segundo plano a partir do estado atual da conversa — a linha bifurcada é executada de forma independente enquanto a original continua trabalhando —, e o comportamento anterior dentro da sessão passou a se chamar /subtask. A distinção é importante para o design da orquestração: /subtask é um desvio com escopo limitado dentro do ciclo de vida de uma sessão; /fork é uma forma barata de criar uma sessão paralela em segundo plano que herda o contexto completo, mais próxima da inicialização de um loop Ralph do que de um subagent. Se os scripts do seu harness presumiam que /fork permanecia na mesma sessão, agora eles distribuem trabalho em segundo plano.

A mesma versão coloca automaticamente chamadas lentas de MCP em segundo plano: uma chamada de ferramenta de MCP que dure mais de dois minutos é movida automaticamente para execução em segundo plano (ajuste o limite com CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS).⁶⁹ Um servidor de MCP lento não paralisa mais o loop agêntico — mas isso também significa que “a ferramenta retornou” e “o turno continuou” não são mais o mesmo evento, portanto hooks ou scripts que presumiam a conclusão síncrona de MCP devem se basear no resultado da ferramenta, não no limite do turno.

Para orquestração headless, a v2.1.211 adicionou --forward-subagent-text (variável de ambiente: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT), que encaminha o texto do assistente do subagent para a saída de stream-json.⁶⁹ Um processo coordenador que consome o stream do agente pai agora pode observar diretamente o progresso do subagent, em vez de consultar transcrições repetidamente ou aguardar o resumo final — o complemento de observabilidade para subagents executados em segundo plano por padrão. A v2.1.219 estendeu isso além do primeiro nível: subagents iniciados na profundidade 2 ou superior agora também aparecem no stream encaminhado, identificados pelo id de tool_use da ferramenta Agent que os iniciou.⁸⁴ Essa chave é a parte sobre a qual você deve construir. Com o aninhamento novamente ativado por padrão, um stream simples de texto de subagents é ambíguo — o id informa ao coordenador qual pai produziu cada filho, permitindo reconstruir a árvore de delegação a partir do stream, em vez de inferi-la. Se o consumidor do seu stream foi desenvolvido considerando apenas um nível de subagents, agora ele verá textos de agentes cuja existência desconhecia; agrupe-os pelo id de tool_use da inicialização, em vez de presumir que cada linha encaminhada pertence a um filho direto.

Orquestração Multiagente

Sistemas de IA com agente único têm um ponto cego estrutural: não conseguem desafiar suas próprias suposições.⁷ A deliberação multiagente força avaliação independente a partir de múltiplas perspectivas antes que qualquer decisão seja travada.

Orquestração entre ferramentas (abril de 2026): O Google liberou o código do Scion em 7 de abril — um hipervisor multiagente que executa Claude Code, Gemini CLI e outros “deep agents” como processos concorrentes, cada um com container isolado, git worktree e credenciais. Roda local, em hub ou em Kubernetes. Filosofia explícita: “isolamento sobre restrições” — agentes operam com alta autonomia dentro de fronteiras impostas na camada de infraestrutura, não no prompt.²⁵ Isso estende diretamente o argumento de isolamento de subagents para fornecedores de ferramentas distintos. Se seu workflow abrange Claude e modelos OpenAI, o Scion é a primeira implementação de referência real para subagents entre ferramentas com worktree + isolamento de credenciais por agente.

Debate não é uma bala de prata: O cluster de pesquisa M3MAD-Bench (início de 2026) descobriu que o debate multiagente atinge um platô e pode ser subvertido por consenso enganoso — argumentos válidos perdem quando outros agentes afirmam a resposta errada com confiança.²⁶ O Tool-MAD melhora isso dando a cada agente acesso heterogêneo a ferramentas e usando pontuações de Faithfulness/Relevance no estágio de julgamento. Se você está construindo orquestração no estilo debate, invista em (a) heterogeneidade de ferramentas por agente e (b) pontuação quantitativa do juiz, em vez de assumir que mais agentes = melhores respostas.

Orquestração e Outcomes Multiagente Gerenciados (Public Beta)

Se você não quer construir a infraestrutura de deliberação descrita abaixo, a Multiagent Orchestration entrou em Public Beta em Claude Managed Agents em 6 de maio de 2026.³⁵ Segundo a Anthropic: “Quando há trabalho demais para um único agente fazer bem, a orquestração multiagente permite que um agente líder divida o trabalho em partes e delegue cada uma a um especialista com seu próprio modelo, prompt e ferramentas.”³⁵ Os especialistas “trabalham em paralelo em um sistema de arquivos compartilhado e contribuem para o contexto geral do agente líder.”³⁵

O tracing já vem na caixa. Segundo a Anthropic: “você também pode rastrear cada passo no Claude Console: qual agente fez o quê, em que ordem e por quê, dando a você visibilidade total de como sua tarefa foi delegada e executada.”³⁵

O recurso companheiro em Public Beta é Outcomes. Segundo a Anthropic: “você escreve uma rubrica descrevendo como é o sucesso e o agente trabalha em direção a ela. Um avaliador separado julga a saída contra seus critérios em sua própria janela de contexto, então não é influenciado pelo raciocínio do agente.”³⁵ Esta é a versão gerenciada do padrão de validação de duas portas documentado mais adiante nesta seção: a rubrica substitui a porta escrita à mão, o avaliador separado substitui o validador de consenso.

A deliberação auto-hospedada continua sendo a resposta certa quando a validação precisa se integrar com sua própria superfície de hooks (bloqueio PreToolUse, semântica de exit code, dispatchers customizados) ou quando o harness deve rodar sem dependências externas. A Multiagent Gerenciada é a resposta certa quando a delegação padrão mais avaliação por rubrica é o contrato que você realmente precisa.

Deliberação Mínima Viável

Comece com 2 agentes e 1 regra: os agentes devem avaliar de forma independente antes de ver o trabalho um do outro.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

Esse padrão cobre 80% do valor. Tudo o mais adiciona melhoria incremental.

O Gatilho de Confiança

Nem toda tarefa precisa de deliberação. Um módulo de pontuação de confiança avalia quatro dimensões:¹⁷

1. Ambiguidade - A consulta tem múltiplas interpretações válidas?
2. Complexidade do domínio - Requer conhecimento especializado?
3. Impacto - A decisão é reversível?
4. Dependência de contexto - Requer entendimento do sistema mais amplo?

A pontuação mapeia para três níveis:

O limiar se adapta por tipo de tarefa. Decisões de segurança exigem consenso de 0,85. Mudanças de documentação precisam apenas de 0,50. Isso evita superengenharia em tarefas simples enquanto garante que decisões arriscadas recebam escrutínio.⁷

A Máquina de Estados

Sete fases, cada uma controlada pela anterior:⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH: Agentes independentes investigam o tópico. Cada agente recebe uma persona diferente (Technical Architect, Security Analyst, Performance Engineer e outras). O isolamento de contexto garante que os agentes não consigam ver as descobertas uns dos outros durante a pesquisa.

DELIBERATION: Os agentes veem todas as descobertas da pesquisa e geram alternativas. O agente Debate identifica conflitos. O agente Synthesis combina descobertas não contraditórias.

RANKING: Cada agente pontua cada abordagem proposta em 5 dimensões ponderadas:

A Arquitetura de Validação de Duas Portas

Duas portas de validação capturam problemas em estágios diferentes:⁷

Porta 1: Validação de Consenso (hook PostToolUse). Roda imediatamente após cada agente de deliberação concluir: 1. A fase deve ter chegado pelo menos a RANKING 2. Mínimo de 2 agentes concluídos (configurável) 3. A pontuação de consenso atinge o limiar adaptativo à tarefa 4. Se algum agente discordou, as preocupações devem ser documentadas

Porta 2: Pride Check (hook Stop). Roda antes que a sessão possa fechar: 1. Métodos diversos: múltiplas personas únicas representadas 2. Transparência de contradições: dissidências têm razões documentadas 3. Tratamento de complexidade: pelo menos 2 alternativas geradas 4. Confiança do consenso: classificada como forte (acima de 0,85) ou moderada (0,70-0,84) 5. Evidência de melhoria: a confiança final excede a confiança inicial

Dois hooks em diferentes pontos do ciclo de vida correspondem a como as falhas realmente ocorrem: algumas são instantâneas (pontuação ruim) e outras são graduais (baixa diversidade, documentação de dissidência ausente).⁷

Por Que a Concordância É Perigosa

Charlan Nemeth estudou a dissidência minoritária de 1986 até seu livro de 2018 In Defense of Troublemakers. Grupos com dissidentes tomam decisões melhores do que grupos que chegam a um acordo rápido. O dissidente não precisa estar certo. O ato de discordar força a maioria a examinar suposições que de outra forma seriam ignoradas.¹⁸

Wu et al. testaram se agentes LLM conseguem debater genuinamente e descobriram que, sem incentivos estruturais para discordância, os agentes convergem para a resposta inicial mais confiante, independentemente da correção.¹⁹ Liang et al. identificaram a causa raiz como “Degeneration-of-Thought”: uma vez que um LLM estabelece confiança em uma posição, a auto-reflexão não consegue gerar contra-argumentos novos, tornando a avaliação multiagente estruturalmente necessária.²⁰

Independência é a restrição crítica de design. Dois agentes avaliando a mesma estratégia de deployment com visibilidade das descobertas um do outro produziram pontuações de 0,45 e 0,48. Os mesmos agentes sem visibilidade: 0,45 e 0,72. A diferença entre 0,48 e 0,72 é o custo do efeito manada.⁷

Detectando Concordância Falsa

Um módulo de detecção de conformidade rastreia padrões que sugerem que agentes estão concordando sem avaliação genuína:⁷

Agrupamento de pontuações: Cada agente pontuando dentro de 0,3 pontos em uma escala de 10 sinaliza contaminação de contexto compartilhado em vez de avaliação independente. Quando cinco agentes avaliando uma refatoração de autenticação pontuaram o risco de segurança entre 7,1 e 7,4, executar novamente com isolamento de contexto fresco espalhou as pontuações para 5,8-8,9.

Dissidência boilerplate: Agentes copiando a linguagem de preocupação uns dos outros em vez de gerar objeções independentes.

Perspectivas minoritárias ausentes: Aprovação unânime de personas com prioridades conflitantes (um Security Analyst e um Performance Engineer raramente concordam em tudo).

O detector de conformidade captura os casos óbvios (aproximadamente 10-15% das deliberações em que os agentes convergem rápido demais). Para os 85-90% restantes, as portas de consenso e pride check fornecem validação suficiente.

O Que Não Funcionou na Deliberação

Rodadas de debate em formato livre. Três rodadas de texto de vai e vem para uma discussão de indexação de banco de dados produziram 7.500 tokens de debate. Rodada 1: discordância genuína. Rodada 2: posições reformuladas. Rodada 3: argumentos idênticos com palavras diferentes. Pontuação dimensional estruturada substituiu o debate em formato livre, reduzindo o custo em 60% enquanto melhorava a qualidade do ranking.⁷

Porta de validação única. A primeira implementação rodava um único hook de validação no final da sessão. Um agente concluía a deliberação com pontuação de consenso de 0,52 (abaixo do limiar), depois continuava em tarefas não relacionadas por 20 minutos antes que o hook de fim de sessão sinalizasse a falha. Dividir em duas portas (uma na conclusão da tarefa, outra no fim da sessão) capturou os mesmos problemas em diferentes pontos do ciclo de vida.⁷

Custo da Deliberação

Cada agente de pesquisa processa aproximadamente 5.000 tokens de contexto e gera 2.000-3.000 tokens de descobertas. Com 3 agentes, isso são 15.000-24.000 tokens adicionais por decisão. Com 10 agentes, aproximadamente 50.000-80.000 tokens.⁷

Nos preços atuais do Opus, uma deliberação de 3 agentes custa aproximadamente US$ 0,68-0,90. Uma deliberação de 10 agentes custa US$ 2,25-3,00. O sistema dispara deliberação em aproximadamente 10% das decisões, então o custo amortizado em todas as decisões é de US$ 0,23-0,30 por sessão. Se isso vale a pena depende de quanto custa uma decisão ruim.

Quando Deliberar

Design do CLAUDE.md

O CLAUDE.md é uma política operacional para um agente de IA, não um README para humanos.²¹ O agente não precisa entender por que você usa commits convencionais. Ele precisa saber o comando exato que deve executar e o que significa uma tarefa estar “concluída”.

A hierarquia de precedência

Os arquivos de regras são carregados automaticamente e fornecem contexto estruturado sem sobrecarregar o CLAUDE.md.⁶

O que é ignorado

Estes padrões comprovadamente não produzem nenhuma mudança observável no comportamento do agente:²¹

Parágrafos em prosa sem comandos. “Valorizamos código limpo e bem testado” é documentação, não uma instrução operacional. O agente lê isso e começa a escrever código sem testes porque não há nenhuma instrução acionável.

Diretrizes ambíguas. “Tenha cuidado com migrações de banco de dados” não é uma restrição. “Execute alembic check antes de aplicar migrações. Interrompa se o caminho de downgrade estiver ausente.” é.

Prioridades contraditórias. “Avance rápido e entregue logo” junto com “Garanta uma cobertura de testes abrangente”, “Mantenha o tempo de execução abaixo de 5 minutos” e “Execute todos os testes de integração antes de cada commit”. O agente não consegue atender às quatro instruções simultaneamente e, por padrão, acaba ignorando a verificação.²¹

Guias de estilo sem aplicação. “Siga o Guia de Estilo Python do Google” sem ruff check --select D não oferece ao agente nenhum mecanismo para verificar a conformidade.

O que funciona

Instruções que começam pelo comando:

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Definições de conclusão:

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Seções organizadas por tarefa:

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

Regras de escalonamento:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

Ordem de escrita

Se você estiver começando do zero, adicione as seções nesta ordem de prioridade:²¹

1. Comandos de build e teste (o agente precisa deles antes de conseguir fazer algo útil)
2. Definição de conclusão (evita falsas conclusões)
3. Regras de escalonamento (evitam soluções alternativas destrutivas)
4. Seções organizadas por tarefa (reduzem o processamento de instruções irrelevantes)
5. Escopo por diretório (monorepos: mantém isoladas as instruções de cada serviço)

Deixe as preferências de estilo de lado até que as quatro primeiras estejam funcionando.

Agora, a plataforma audita seu CLAUDE.md para você. Desde as versões do início de julho de 2026 (v2.1.203–v2.1.206), o /doctor analisa o CLAUDE.md e propõe remover conteúdo que o modelo consegue deduzir por conta própria a partir da base de código — estruturas de diretórios repetidas, convenções de frameworks já presentes no código e listas de comandos que duplicam scripts de pacotes.⁶⁸ Essa é uma confirmação oficial da tese desta seção: as instruções justificam os tokens que consomem quando registram aquilo que o agente não consegue deduzir (políticas, limites e definições de conclusão), não o que ele pode ler no disco. Execute /doctor depois que o CLAUDE.md crescer significativamente e trate as propostas de redução como ponto de partida — mas preserve as regras operacionais que ele possa classificar como “dedutíveis” se elas forem restrições essenciais, não meras descrições.

Importações de arquivos

Faça referência a outros arquivos no CLAUDE.md:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Sintaxe de importação: relativa (@docs/file.md), absoluta (@/absolute/path.md) ou do diretório pessoal (@~/.claude/file.md). Profundidade máxima: 5 níveis de importação.⁶

Compatibilidade de instruções entre ferramentas

O AGENTS.md é um padrão aberto reconhecido por todas as principais ferramentas de programação com IA.²¹ Se sua equipe usa várias ferramentas, adote o AGENTS.md como fonte canônica e replique as seções relevantes nos arquivos específicos de cada ferramenta:

Os padrões do AGENTS.md (comandos em primeiro lugar, conclusão definida e organização por tarefa) funcionam em qualquer arquivo de instruções, independentemente da ferramenta. Não mantenha conjuntos paralelos de instruções que possam divergir. Escreva uma única fonte oficial e replique-a.

Observações sobre a paridade com o Codex

Agora, o Codex tem equivalentes de primeira classe para as principais camadas do harness, mas a migração exige traduzir padrões, não apenas copiar arquivos. O Codex lê o AGENTS.md antes de começar a trabalhar, combinando as orientações globais de ~/.codex com as instruções do projeto e dos repositórios aninhados.³¹ As skills do Codex usam o mesmo modelo mental de SKILL.md com divulgação progressiva: o Codex começa com o nome, a descrição e o caminho do arquivo da skill e só carrega a skill completa quando decide usá-la.³² O Codex também oferece hooks nativos, hooks incluídos em plugins, hooks gerenciados, suporte a MCP e fluxos de trabalho explícitos com subagents.³³³⁴

O Codex v0.138.0–v0.139.0 tornou a descoberta do AGENTS.md mais robusta em espaços de trabalho não triviais: agora, o carregamento passa pela abstração do sistema de arquivos do ambiente e preserva os caminhos lógicos durante a busca, garantindo que o arquivo correto seja selecionado mesmo quando o espaço de trabalho está em um sistema de arquivos remoto ou em uma árvore com links simbólicos.⁶¹ Isso é importante sempre que seu AGENTS.md canônico é a fonte oficial e o agente trabalha em um checkout montado, materializado em um contêiner ou com links simbólicos — situações em que uma busca ingênua por caminhos selecionaria silenciosamente o arquivo de instruções errado ou não encontraria nenhum. Se você replica um único AGENTS.md oficial entre serviços, considere essa versão o requisito mínimo para confiar que o arquivo carregado pelo agente é realmente aquele que você escreveu.

Em seguida, o Codex v0.141.0 tornou o próprio caminho de execução remota mais robusto: agora, executores remotos se conectam por canais Noise-relay autenticados e criptografados de ponta a ponta (o plano de controle e o executor não precisam mais confiar no relay entre eles), a execução remota entre plataformas preserva o diretório de trabalho e o shell nativos do executor, e o TLS aceita assinaturas de certificados P-521 para proxies empresariais.⁶⁵ Se sua orquestração aciona executores do Codex através de uma fronteira de rede, essa é a diferença entre presumir que o relay é confiável e usar criptografia de ponta a ponta — considere-a o requisito mínimo para qualquer topologia de executores remotos.

A linha de versões de julho de 2026 mostra os dois runtimes convergindo para os mesmos recursos fundamentais, embora partindo de direções opostas.⁷² O Codex v0.143.0 faz com que as ferramentas MCP sejam carregadas por tool search por padrão — os schemas das ferramentas são adiados e buscados sob demanda, em vez de serem carregados antecipadamente no contexto —, o mesmo padrão de carregamento adiado de ferramentas que o Claude Code disponibiliza por meio de sua interface ToolSearch e a solução correta, nos dois runtimes, para o inchaço de contexto quando há muitas ferramentas MCP. O Codex v0.144.0 adiciona um modo de aprovação de apps writes: ações somente leitura são executadas sem solicitar confirmação, enquanto escritas exigem aprovação — um recurso realmente novo de controle de permissões, situado entre os modos somente leitura e aprovação automática, que a lista de modos do Claude Code não representa diretamente (o equivalente mais próximo é o modo plan, que bloqueia completamente as escritas em vez de solicitar aprovação para cada uma). A mesma versão leva a autenticação interativa do MCP à disponibilidade geral. E a v0.144.5 amplia a detecção de comandos perigosos, refletindo as proteções contra comandos destrutivos lançadas pelo Claude Code nas versões v2.1.183 e v2.1.208. Para o design de harnesses entre runtimes, a convergência é o ponto central: carregamento adiado de ferramentas, aprovação gradual de escritas e bloqueio de comandos perigosos no nível da intenção estão se tornando requisitos básicos, não diferenciais entre fornecedores.

O Codex v0.145.0 leva essa convergência ainda mais longe em duas frentes.⁷⁶ A interface opcional multi-agent V2 foi estabilizada: agora, os modelos dos sub-agents, os níveis de raciocínio e a concorrência são configuráveis, e as funções de agentes que haviam sido removidas foram restauradas — a resposta do Codex à configuração de modelo e nível de esforço por subagent no frontmatter de .claude/agents/. Além disso, o /import evoluiu para uma migração completa entre harnesses: além da importação das configurações do Claude Code lançada na v0.140.0, agora ele migra configurações do Claude Code e do Cursor — incluindo servidores MCP, plugins, sessões, comandos e memórias com escopo de projeto. Para equipes que executam os dois runtimes, o custo de migração entre eles continua caindo em uma direção; as camadas de harness que você cria sobre o Claude Code — servidores, skills como comandos e memória — são cada vez mais um estado portátil, não uma dependência exclusiva de um fornecedor.

O mapeamento prático:

A diferença importante: os subagents do Claude podem ser selecionados automaticamente a partir das descrições, enquanto a documentação atual do Codex apresenta fluxos de trabalho com subagents como explícitos. Isso torna skills e hooks a escolha padrão adequada para comportamentos sempre ativos do harness no Codex; subagents são indicados para trabalho paralelo deliberado, revisão e exploração.

Como testar suas instruções

Verifique se o agente realmente lê e segue suas instruções:

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

O teste decisivo: peça ao agente que explique seus comandos de build. Se ele não conseguir reproduzi-los literalmente, as instruções são extensas demais (o conteúdo foi empurrado para fora do contexto), vagas demais (o agente não consegue extrair instruções acionáveis) ou não estão sendo descobertas. A análise de 2.500 repositórios feita pelo GitHub constatou que a falta de clareza causa a maioria das falhas.²¹

Padrões de produção

Padrões de longo horizonte do Opus 4.7 (abril de 2026)

O Claude Opus 4.7 (16 de abril de 2026) foi lançado com recursos específicos que mudam aquilo contra o qual um harness precisa se proteger:²⁹

• Resiliência a falhas de ferramentas: o Opus 4.7 continua operando após falhas de ferramentas que interrompiam sessões do Opus 4.6. Você pode reduzir — mas não eliminar — os wrappers defensivos de repetição no código dos subagents. Mantenha as proteções no nível dos hooks; reduza a estrutura “se a ferramenta falhar, tente novamente três vezes” nos prompts.
• Nível de esforço xhigh (somente Opus-4.7): fica entre high e max. É o padrão recomendado para programação e cargas de trabalho com agentes. Em subagents de longa duração, xhigh supera significativamente high com um custo de tokens proporcionalmente menor. max continua sendo a escolha certa para raciocínios difíceis executados de uma só vez; xhigh é melhor para tarefas contínuas.
• Limite do orçamento de tokens: configurável por execução do agente por meio de output_config.task_budget (cabeçalho beta task-budgets-2026-03-13). O modelo acompanha uma contagem regressiva contínua e ajusta o escopo do trabalho ao orçamento de forma controlada, em vez de ficar sem tokens inesperadamente. Use em loops de agentes nos quais você queira gastos previsíveis de tokens sem sacrificar a qualidade em prompts curtos.
• Percepção de necessidades implícitas: primeiro modelo Claude a passar nos testes de “necessidade implícita” — reconhecendo quando a solicitação literal do usuário não especifica tudo o que ele realmente precisa. Isso torna a seção de “regras de esclarecimento” do CLAUDE.md menos necessária. Se o seu CLAUDE.md tiver 200 linhas de proteções do tipo “também considere X quando o usuário pedir Y”, remova aquelas que agora são atendidas nativamente.

Base de worktree, caminhos do sandbox e configurações administrativas (7 de maio de 2026)

O Claude Code v2.1.133 adiciona quatro configurações administrativas importantes para harnesses de produção:³⁹

A reversão de worktree.baseRef é o ponto que deve ser destacado aos usuários: os agentes que dependiam do comportamento das versões v2.1.128 a v2.1.132 (worktrees criando branches a partir do HEAD local) perdem o acesso a trabalhos ainda não enviados em worktrees novos, a menos que reativem esse comportamento.

Pesquisa de feedback do OTel para observabilidade empresarial (8 de maio de 2026)

O Claude Code v2.1.136 adicionou CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL para reativar a pesquisa de qualidade durante a sessão em empresas que capturam as respostas por meio do OpenTelemetry.⁴⁰ Se a sua organização envia eventos do OTel para uma stack central de observabilidade, essa variável de ambiente recoloca a pesquisa no fluxo de dados para que os sinais de qualidade passem pelo mesmo pipeline das métricas de latência e erro. Trate esse recurso como opt-in: por padrão, a pesquisa permanece desativada, o que é adequado para implantações sem OTel.

Launchers corporativos e desempenho em escala de MCP (julho de 2026)

Duas mudanças da v2.1.207 são importantes para implantações em produção.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER permite que ambientes gerenciados iniciem o processo do Claude Code por meio de um binário wrapper corporativo — o ponto de integração para agentes de endpoint, verificações de políticas durante a inicialização e ambientes nos quais todos os processos precisam ser executados sob um supervisor obrigatório. Se a sua empresa antes simulava isso com aliases de shell ou scripts de launcher derivados, agora este é o ponto de integração oficialmente compatível.

A mesma versão reduziu o overhead de runtime no ponto em que os harnesses mais o sentem: rodadas de uso de ferramentas até 7× mais rápidas em sessões com grandes quantidades de ferramentas MCP e transcrições de sessão 79× menores.⁶⁸ Isso ameniza — sem invalidar — a orientação em Custo como arquitetura: priorizar CLI ainda é a melhor opção para operações stateless pontuais, mas um harness que carrega dezenas de ferramentas MCP deixou de pagar a penalidade por rodada que existia no primeiro semestre, e o armazenamento de transcrições deixou de ser um custo oculto de longas execuções autônomas.

O quality loop

Um processo obrigatório de revisão para todas as alterações que não sejam triviais:

1. Implemente - Escreva o código
2. Revise - Releia cada linha. Identifique erros de digitação, erros de lógica e trechos pouco claros
3. Avalie - Execute o evidence gate. Verifique padrões, casos extremos e cobertura de testes
4. Refine - Corrija todos os problemas. Nunca deixe para “depois”
5. Amplie a perspectiva - Verifique pontos de integração, imports e o código adjacente em busca de regressões
6. Repita - Se algum critério do evidence gate falhar, volte à etapa 4
7. Relate - Liste o que mudou, como foi verificado e cite evidências específicas

O evidence gate

“Eu acredito” e “deve funcionar” não são evidências. Cite caminhos de arquivos, resultados de testes ou trechos específicos do código.

Se você não conseguir apresentar evidências para alguma linha, volte à etapa de refinamento.²²

Autoridade humana para merges

Um estudo do arXiv de maio de 2026 sobre o ciclo de vida de 29.585 pull requests de agentes de IA separa a autonomia operacional da governança de merges.⁴⁷ A lição útil de arquitetura é simples: os agentes podem iniciar o trabalho, dar continuidade às branches, abrir PRs, revisar o trabalho e resumir os riscos, enquanto a autoridade para fazer merges permanece como uma fronteira de governança separada.

Torne essa fronteira explícita no harness. Permita que os agentes preparem PRs e coletem evidências; exija aprovação humana para merges, releases e operações destrutivas no repositório, a menos que a organização tenha uma política de automação auditada separadamente. Quando uma automação executar um merge, preserve logs que diferenciem quem o executou da pessoa ou política que o autorizou.

Padrões de tratamento de erros

Gravações atômicas de arquivos. Vários agentes gravando simultaneamente no mesmo arquivo de estado corrompem JSON. Grave em arquivos .tmp e depois use mv de forma atômica. O sistema operacional garante que mv seja atômico no mesmo sistema de arquivos.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Recuperação de estado corrompido. Se o estado for corrompido, o padrão de recuperação o recria a partir de valores padrão seguros, em vez de encerrar com erro:¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

A armadilha ((VAR++)) do bash. ((VAR++)) retorna o código de saída 1 quando VAR é 0, pois 0++ é avaliado como 0, que o bash interpreta como falso. Com set -e ativado, isso encerra o script. Use VAR=$((VAR + 1)) no lugar.¹⁶

Classificação do raio de impacto

Classifique cada ação do agente pelo raio de impacto e aplique os gates correspondentes:²

O Remote Control (conexão ao Claude Code local por qualquer navegador ou aplicativo móvel) transforma o gate “Externo” de uma espera bloqueante em uma notificação assíncrona. O agente continua trabalhando na tarefa seguinte enquanto você revisa a anterior pelo celular.²

Especificação de tarefas para execuções autônomas

Tarefas autônomas eficazes incluem três elementos: objetivo, critérios de conclusão e referências de contexto:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Os critérios precisam ser verificáveis por máquina: aprovação/reprovação em testes, resultado do linter, códigos de status HTTP e verificações de existência de arquivos. Uma tarefa inicial que pediu ao agente para “escrever testes que passem” produziu assert True e assert 1 == 1. Tecnicamente correto. Na prática, inútil.¹⁶

Modos de falha que exigem atenção

Um trace concreto de sessão

Um trace de sessão de uma execução autônoma que processou um PRD com 5 histórias:²

1. SessionStart é acionado. O dispatcher injeta: data atual, detecção do projeto, restrições filosóficas e inicialização do acompanhamento de custos. Cinco hooks, 180 ms no total.

2. O agente lê o PRD e planeja a primeira história. UserPromptSubmit é acionado. O dispatcher injeta: contexto do projeto ativo e baseline de desvio da sessão.

3. O agente chama Bash para executar os testes. PreToolUse:Bash é acionado. Verificação de credenciais, validação do sandbox e detecção do projeto. 90 ms. Os testes são executados. PostToolUse:Bash é acionado: heartbeat de atividade registrado e verificação de desvio.

4. O agente chama Write para criar um arquivo. PreToolUse:Write é acionado: verificação do escopo do arquivo. PostToolUse:Write é acionado: verificação do lint e acompanhamento de commits.

5. O agente conclui a história. Stop é acionado. O quality gate verifica: o agente citou evidências? Usou linguagem evasiva? Há comentários TODO no diff? Se alguma verificação falhar, retorna o código 2 e o agente continua.

6. Verificação independente: um agente novo executa a suíte de testes sem confiar no autorrelato do agente anterior.

7. Três agentes de revisão de código são iniciados em paralelo. Cada um revisa o diff de forma independente. Se algum revisor sinalizar CRITICAL, a história volta para a fila.

8. A história é aprovada. A próxima é carregada. O ciclo se repete para todas as 5 histórias.

Total de hooks acionados nas 5 histórias: ~340. Tempo total nos hooks: ~12 segundos. Esse overhead evitou três vazamentos de credenciais, um comando destrutivo e duas implementações incompletas em uma única execução durante a noite.

Estudo de caso: processamento noturno de PRD

Um harness de produção processou 12 PRDs (47 histórias) em 8 sessões noturnas. As métricas comparam os primeiros 4 PRDs (harness mínimo: somente CLAUDE.md) com os últimos 8 (harness completo: hooks, skills, quality gates e revisão multiagente).

Os dois vazamentos de credenciais exigiram a rotação das chaves de API e a auditoria dos serviços downstream: aproximadamente 4 horas de resposta a incidentes. O overhead do harness que evitou ocorrências equivalentes foi de 2,4 segundos de bash por história. A taxa de conclusões falsas caiu de 35% para 4% porque o hook Stop executou os testes de forma independente antes de permitir que o agente declarasse a conclusão.

Considerações de segurança

Os cinco princípios dos agentes confiáveis (Anthropic, abril de 2026)

A Anthropic publicou um framework formal para a confiabilidade de agentes em 9 de abril de 2026.²⁷ Os cinco princípios são paralelos — e ampliam — o conceito de evidence gate deste guia:

A Anthropic também doou o MCP para a Agentic AI Foundation da Linux Foundation, juntando-se ao AGENTS.md (agora mantido em conjunto com OpenAI, Google, Cursor, Factory e Sourcegraph). Os padrões de interoperabilidade entre agentes agora são independentes de fornecedor.²⁷

Turno sem estado e identidade autodeclarada do MCP (julho de 2026). A especificação do MCP está em transição para um núcleo sem estado (SEP-2575), que elimina o handshake de inicialização com estado que antes carregava a identidade do servidor. Uma alteração no rascunho da especificação, incorporada em 16 de julho (PR #3002), restabelece a identidade como uma superfície opcional: os servidores podem incluir um objeto io.modelcontextprotocol/serverInfo no _meta da resposta, e clientInfo passa a ser opcional nas solicitações.⁷¹ A parte relevante para a segurança é o que a especificação diz sobre confiança: essa identidade é autodeclarada e não verificada — serve apenas para exibição e registro — e NÃO DEVE orientar decisões de segurança. Se o seu harness baseia allowlists, regras de permissão ou auditorias por logs no nome declarado por um servidor MCP, esse nome é uma alegação, não uma credencial; vincule a confiança ao transporte e à configuração (qual servidor você configurou e em qual endpoint), nunca ao que o servidor afirma ser. A revisão final da especificação sem estado está prevista para 28 de julho de 2026 — espere que os detalhes do protocolo nesta seção se consolidem na próxima atualização.

Ferramentas de sandbox para skills: Para equipes que tratam skills como uma superfície de ataque, o SandyClaw da Permiso (lançado em 2 de abril de 2026) executa skills em um sandbox dedicado e fornece veredictos baseados em evidências por meio de detecções Sigma/YARA/Nova/Snort. É o primeiro produto da categoria de sandbox para skills.²⁸

O sandbox

O Claude Code oferece um modo sandbox opcional (ativado pelo settings.json ou pelo comando /sandbox) que restringe o acesso à rede e as operações no sistema de arquivos usando isolamento no nível do sistema operacional (seatbelt no macOS e bubblewrap no Linux). Quando ativado, o sandbox impede que o modelo faça solicitações arbitrárias de rede ou acesse arquivos fora da pasta do projeto. Sem o sandbox, o Claude Code usa um modelo baseado em permissões, no qual você aprova ou nega cada chamada de ferramenta.¹³

Patamar mínimo de segurança de maio de 2026. O Claude Code v2.1.149 corrigiu um desvio de permissão do diretório de trabalho no PowerShell, várias falhas na análise de permissões relacionadas a regras de permissão e variáveis obsoletas do PowerShell, além de um bug na allowlist de gravação do sandbox para git worktrees que abrangia toda a raiz do repositório principal, em vez de apenas os componentes internos compartilhados do git.⁵³ Se o seu harness permite PowerShell ou agentes isolados por worktree, trate a v2.1.149+ como o patamar mínimo e mantenha as regras de shell restritas. Exceções amplas como PowerShell(*) e permissões de gravação para todo o repositório são atalhos de orquestração, não limites de segurança.

Reforço do sandbox do OpenAI Agents SDK (v0.17.0, 8 de maio de 2026). Do lado da OpenAI, a v0.17.0 do openai-agents-python reforçou um limite semelhante: LocalFile.src e LocalDir.src agora ficam restritos ao base_dir de materialização (o diretório de trabalho atual do processo SDK quando o manifesto é aplicado), a menos que a origem seja explicitamente autorizada por Manifest.extra_path_grants com SandboxPathGrant.⁴¹ Origens locais relativas são resolvidas a partir do base_dir; caminhos absolutos já precisam estar dentro dele ou ter uma autorização. Isso resolve um problema no limite de artefatos locais: versões anteriores permitiam que manifestos levassem caminhos arbitrários do host para um workspace em sandbox. Migração: declare raízes confiáveis do host no nível do manifesto usando SandboxPathGrant(path=..., read_only=True) para montagens somente leitura. Trate extra_path_grants como uma configuração confiável da aplicação; nunca preencha autorizações com a saída do modelo ou com entradas não confiáveis do manifesto.

Patamar mínimo complementar do OpenAI Agents SDK (v0.17.3). A série 0.17.1–0.17.3 adicionou mais reforços ao sandbox e às sessões: limites para extração de arquivos compactados, validação de subcaminhos do GitRepo, erros mais claros dos provedores de sandbox, credenciais de pontos de montagem mantidas fora dos comandos do sandbox, rejeição de raízes relativas de workspace no sandbox e tratamento do estado terminal do sandbox da Vercel.⁵⁴ Se você usa sandboxes hospedados pela OpenAI ou mantidos por provedores, em vez de apenas hooks do Claude Code, trate a versão 0.17.3 como o patamar mínimo atual para os padrões desta seção.

Três padrões de contenção entre produtos (Anthropic, maio de 2026)

O artigo de engenharia da Anthropic, “Como contemos o Claude entre produtos” (25 de maio de 2026), apresenta a própria formulação do fornecedor para os princípios que esta seção ensina gradualmente — o sandbox no nível das configurações descrito acima, o patamar mínimo de isolamento por worktree e a postura de tratar tudo como não confiável.⁸¹ Sua ideia central é associar a intensidade da contenção à superfície do produto, e esse mapeamento é a própria lição: não existe um único projeto correto de isolamento, apenas um isolamento adequado a quem está supervisionando e ao que pode dar errado.

• Contêineres gVisor efêmeros (claude.ai). A execução no servidor ocorre em contêineres gVisor, sobre uma infraestrutura isolada e com um sistema de arquivos efêmero por sessão. O modelo de ameaças envolve o isolamento da infraestrutura e dos tenants — a máquina do usuário nunca pode ser acessada, portanto não há nada local a proteger.
• Sandbox do sistema operacional com supervisão humana (Claude Code). O padrão descrito no parágrafo sobre sandbox acima, formulado como política: Seatbelt no macOS e bubblewrap no Linux, com leituras permitidas, gravações restritas ao workspace e rede negada por padrão — o humano aprova o que o limite não cobre. A Anthropic tornou o runtime open source (sandbox-runtime) para que o limite possa ser auditado. O artigo é franco sobre o elo mais fraco: cerca de 93% das solicitações de permissão são aprovadas, e o classificador do auto mode — que detecta cerca de 83% dos comportamentos precipitados antes da execução, enquanto reduz as solicitações de aprovação em 84% — existe justamente porque a fadiga de aprovação é uma questão de segurança, não uma reclamação de UX. Essa é a postura de camada de verificação que este guia acompanha desde a v2.1.193.
• VMs seladas (Claude Cowork). Máquinas virtuais completas executadas nos hipervisores da plataforma — framework Apple Virtualization no macOS e HCS no Windows — com apenas o workspace selecionado e a pasta .claude montados; nada mais no host fica visível. As credenciais nunca entram na VM: elas permanecem no chaveiro do host, e cada sessão recebe um token com escopo limitado e revogável de forma independente. Um proxy MITM defensivo dentro da VM aplica essa regra, permitindo apenas solicitações que carregam o token de sessão provisionado para a própria VM — uma chave inserida por um invasor é rejeitada no limite, porque somente a VM conhece sua procedência.

Os princípios de projeto por trás da taxonomia são a parte que pode ser aplicada em outros contextos. Primeiro, contenha na camada do ambiente; depois, oriente na camada do modelo: toda defesa probabilística tem uma taxa de falha diferente de zero, portanto limites determinísticos precisam capturar o que a orientação no nível do prompt não detecta — o argumento deste guia de que os hooks garantem a execução, reafirmado pelo fornecedor. Ajuste a intensidade do isolamento à capacidade de supervisão do usuário: um desenvolvedor consegue avaliar um comando bash antes de aprová-lo; um profissional do conhecimento, não — por isso Code recebe uma caixa de diálogo de permissão e Cowork recebe uma VM selada. Prefira componentes consolidados a código de isolamento personalizado: hipervisores, seccomp e runtimes de contêiner resistiram melhor à análise adversarial do que os proxies de allowlist e os analisadores de configuração personalizados da própria Anthropic. Trate configurações locais do projeto e saídas de ferramentas como não confiáveis: o artigo instrui tratar a abertura de projetos e o carregamento de configurações como qualquer solicitação recebida da internet, e a saída de ferramentas como uma superfície de ataque mesmo quando a ferramenta é confiável — a mesma postura que este guia aplica a mensagens entre agentes, conteúdo lido por subagents e identidade autodeclarada do MCP. Mantenha as credenciais fora do sandbox: use tokens com escopo limitado, revogáveis e específicos por sessão, em vez de chaves disponíveis no ambiente que o agente poderia vazar.

A superfície de configurações está alcançando o primeiro princípio (v2.1.219). É fácil concordar com “primeiro, contenha na camada do ambiente”, mas colocá-lo em prática tem sido complicado, porque o sandbox do Claude Code resolvia o que suas regras não cobriam fazendo perguntas — e uma solicitação de permissão é uma defesa probabilística disfarçada de determinística, como admite o índice de aprovação de 93% acima. sandbox.network.strictAllowlist elimina a pergunta para o tráfego de saída: quando essa opção está definida, a solicitação de um comando em sandbox para um host fora da allowlist é negada imediatamente, em vez de gerar uma solicitação de aprovação.⁸⁴ Combine-a com o sandbox.filesystem.disabled da v2.1.216, e as duas configurações formarão uma postura, em vez de um amontoado de opções — a contenção do sistema de arquivos e da rede pode ser selecionada de forma independente, e a contenção da rede agora pode ser determinística. Para um harness sem supervisão, essa é a mais importante das duas, porque é pelo tráfego de saída que uma instrução injetada se transforma em exfiltração, e o caso extremo da fadiga de aprovação é não haver ninguém diante do teclado para se cansar. O custo é o custo habitual de um limite determinístico: a allowlist precisa estar correta, e um host esquecido resulta em uma negação opaca, em vez de uma pergunta. Enumere os hosts de que seus agentes realmente precisam e então remova a solicitação de aprovação.

Nada disso substitui a camada de hooks; ela fica acima desses mecanismos. Os padrões de contenção formam o patamar determinístico, e o histórico de aplicação de worktrees neste guia ensina a mesma lição em escala menor: um limite só vale se resistir a redirecionamentos deliberados, e os componentes com maior probabilidade de resistir são aqueles que não foram criados especificamente para a ocasião.

Limites de permissão

O sistema de permissões controla as operações em vários níveis:

Regras de permissão no nível dos parâmetros (junho de 2026)

O Claude Code v2.1.178 estendeu as regras de permissão do nível da ferramenta para o nível dos parâmetros: Tool(param:value) faz a correspondência com os parâmetros de entrada de uma ferramenta, usando * como curinga. O exemplo canônico é Agent(model:opus) — uma regra que impede a criação de subagents em uma camada específica de modelo.⁶³ Em termos de arquitetura, isso elimina uma lacuna que a tabela de quatro níveis acima não conseguia expressar: antes, você permitia ou negava uma ferramenta por completo, mas não conseguia restringir como ela era chamada. Agora, uma política de governança pode determinar que “subagents podem ser criados, mas não na camada Fable 5” ou que “Bash é permitido, mas não com esta flag” como uma regra determinística, em vez de uma solicitação no nível do prompt.

Uma configuração gerenciada complementar, enforceAvailableModels (v2.1.175), restringe a seleção de modelos de cima para baixo: ela fixa o modelo Default e impede que configurações no escopo do usuário ou do projeto ampliem a allowlist gerenciada availableModels.⁶³ As duas se complementam — a allowlist define quais camadas estão disponíveis para a sessão, enquanto as regras no nível dos parâmetros restringem como os subagents as utilizam. Desde a v2.1.196, os administradores também podem definir um modelo padrão para toda a organização pelo console da organização, exibido como “Org default” em /model, para que toda a frota herde um padrão administrado sem exigir que cada operador fixe um modelo — um patamar mínimo que complementa o limite máximo da allowlist.

Regras de permissão com escopo de caminho são ancoradas ao diretório de trabalho (julho de 2026)

O Claude Code v2.1.214 corrigiu uma correspondência excessiva discreta nas regras de permissão com escopo de caminho: uma regra de permissão com um padrão dir/** de segmento único — como Edit(src/**) — aprovava automaticamente edições em qualquer diretório chamado src, em qualquer profundidade, incluindo vendor/some-package/src/ e todos os outros diretórios src/ aninhados que o autor da regra nunca pretendeu autorizar. Agora, essas regras são ancoradas apenas a <cwd>/dir; se você realmente quiser uma correspondência em qualquer profundidade, declare-a com **/dir/**.⁷⁴ As regras de negação e solicitação mantêm deliberadamente a antiga correspondência em qualquer profundidade. Essa assimetria é o projeto fail-safe correto: uma regra de permissão com correspondência restrita demais falha de forma segura (você recebe uma solicitação), enquanto uma regra de negação com correspondência restrita demais falha de forma permissiva (um caminho bloqueado escapa) — por isso, as permissões ficaram mais rigorosas e as negações permaneceram amplas. Se suas configurações dependem de padrões de permissão de segmento único para cobrir caminhos aninhados, elas deixaram silenciosamente de fazer isso na v2.1.214; isso significa que a correção está funcionando como esperado, mas vale revisar suas allowlists para declarar novamente a abrangência que você realmente deseja.

Proteções do auto mode contra comandos destrutivos (junho de 2026)

O Claude Code v2.1.183 reduziu o raio de impacto do auto mode para operações que silenciosamente eliminam trabalho ou desmantelam ambientes. Agora, o auto mode bloqueia de forma rígida, a menos que você os tenha solicitado explicitamente na sessão: operações destrutivas do git (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend quando o commit não foi criado pelo agente nesta sessão; e desmantelamento de infraestrutura (terraform destroy, pulumi destroy, cdk destroy), a menos que você tenha indicado a stack específica.⁶⁵ Em termos de arquitetura, isso complementa a verificação de criação de agentes e as regras no nível dos parâmetros acima: em vez de controlar qual ferramenta é usada ou como ela é criada, controla por intenção um pequeno conjunto de comandos irreversíveis específicos — o agente ainda pode executá-los, mas somente mediante instrução explícita, não por iniciativa própria. Para um harness autônomo, codifique o mesmo princípio em seus próprios hooks PreToolUse: comandos que destroem estado merecem uma regra de negação por padrão, suspensa apenas por um sinal explícito do operador.

Julho de 2026: o auto mode chega às empresas, e uma solicitação se torna obrigatória. O auto mode alcançou disponibilidade geral no Amazon Bedrock, Google Vertex AI e Microsoft Foundry na v2.1.207, com uma configuração gerenciada disableAutoMode para empresas que não quiserem usá-lo — a postura do classificador como camada de verificação agora está disponível em todas as plataformas empresariais primárias, e desativá-la é uma decisão explícita de governança, não uma limitação da plataforma.⁶⁸ Em seguida, a v2.1.208 tornou absoluta a proteção contra remoções catastróficas: as solicitações de confirmação para remoções catastróficas agora se sobrepõem tanto a --dangerously-skip-permissions quanto ao auto mode.⁶⁸ Esse é um precedente relevante — a primeira confirmação do Claude Code que nenhuma postura de permissão, incluindo a flag explícita de desvio, pode dispensar. Projetos de harness autônomo que presumiam que --dangerously-skip-permissions significava literalmente nenhuma solicitação devem considerar essa exceção; ela é acionada exatamente no ponto em que um loop sem supervisão pode causar o dano mais irreversível.

Proteções contra fabricação (julho de 2026)

As versões v2.1.203–v2.1.206 fecharam dois caminhos pelos quais um agente poderia fabricar o próprio registro de auditoria.⁶⁸ Primeiro, uma regra do auto mode agora impede adulterações nos arquivos de transcrição — o registro da sessão não pode mais ser reescrito pelas chamadas de ferramentas da própria sessão. Segundo, as notificações de tarefas em segundo plano agora informam explicitamente que não houve entrada humana durante a execução da tarefa. A segunda mudança corrige uma falha sutil: ao resumir uma tarefa em segundo plano, um modelo podia antes apresentar (ou inventar) uma “aprovação” na transcrição que nunca ocorreu, sem que nada na notificação a contradissesse. Agora, a própria notificação serve como contraevidência.

A lição de arquitetura se aplica de forma geral ao evidence gate: transcrições, notificações e logs são superfícies de auditoria, e essas superfícies não podem ser gravadas pelo que elas auditam. Agora, a plataforma impõe isso à própria transcrição; aplique a mesma regra ao seu harness — relatórios de evidências, resultados de testes e registros de deliberação devem ficar fora do caminho gravável pelo modelo.

Defesa contra injeção de prompt

Skills e hooks fornecem defesa em profundidade contra injeção de prompt:

Skills com restrições de ferramentas impedem que um prompt comprometido obtenha acesso de gravação:

allowed-tools: Read, Grep, Glob

hooks PreToolUse validam cada chamada de ferramenta, independentemente de como o prompt do modelo foi elaborado:

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

O isolamento de subagents limita o raio de impacto. Um subagent com permissionMode: plan não pode fazer alterações, mesmo que seu prompt esteja comprometido.

O patamar da plataforma subiu em julho de 2026. O Claude Code v2.1.210 reforçou o Agent tool contra injeção indireta de prompt transportada em conteúdo lido por um subagent — um arquivo contaminado, uma página da web ou um resultado de ferramenta obtido por um subagent passa a ter menos capacidade de manipular a própria superfície de delegação.⁶⁹ E a v2.1.211 reforçou o elo humano da cadeia: as prévias de permissão agora neutralizam caracteres Unicode de substituição bidirecional, largura zero e aparência semelhante, impedindo que um comando seja criado para parecer inofensivo na caixa de diálogo de aprovação enquanto executa outra coisa.⁶⁹ A segunda correção é mais importante para harnesses nos quais um humano aprova prévias renderizadas sob pressão de tempo — a exibição também era uma superfície de injeção. Nenhuma das mudanças substitui as defesas no nível dos hooks descritas acima; elas elevam o patamar abaixo delas.

Logs e proteções de agentes são superfícies de segurança

Dois avisos de maio de 2026 reforçam um padrão: a infraestrutura de agentes cria novos lugares onde conteúdo confidencial e políticas executáveis podem vazar ou escapar. O aviso GHSA-f3jg-756w-gm35 do GitHub aborda um problema no filtro de payloads do Gryph Agents, no qual conteúdo confidencial do payload de ferramentas podia permanecer em logs SQLite locais com o comportamento padrão de registro.⁴⁵ O OSV GHSA-wxxx-gvqv-xp7p aborda um escape do sandbox de proteções com código personalizado do LiteLLM em um endpoint de proxy protegido por administrador.⁴⁶

A regra para produção: trate transcrições de agentes, payloads de ferramentas, logs SQLite e execução de proteções como infraestrutura confidencial. Oculte dados sensíveis antes de persistir, aplique limites de retenção e mantenha o código personalizado das proteções em sandbox e sujeito a revisão. Uma regra no nível do prompt como “não registre segredos” não é suficiente; o caminho de registro e das proteções precisa de testes determinísticos.

Segurança dos hooks

hooks HTTP que interpolam variáveis de ambiente nos cabeçalhos exigem uma lista explícita allowedEnvVars para impedir a exfiltração arbitrária de variáveis de ambiente:¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

A divisão de responsabilidades entre humanos e agentes

A segurança em arquiteturas de agentes exige uma divisão clara de responsabilidades entre humanos e agentes:¹⁷

O padrão: humanos são responsáveis por decisões que exigem contexto organizacional, julgamento ético ou direcionamento estratégico. Agentes são responsáveis por decisões que exigem busca computacional em grandes espaços de possibilidades. hooks impõem esse limite.

Aplicação recursiva de hooks

hooks também são acionados para ações de subagents.¹³ Se o Claude criar um subagent por meio do Agent tool, seus hooks PreToolUse e PostToolUse serão executados para cada ferramenta usada pelo subagent. Sem a aplicação recursiva de hooks, um subagent poderia contornar seus controles de segurança. O evento SubagentStop permite executar limpeza ou validação quando um subagent é concluído.

Isso não é opcional. Um agente que cria um subagent sem seus hooks de segurança é um agente que pode fazer force-push para a main, ler arquivos de credenciais ou executar comandos destrutivos enquanto seus controles observam a conversa principal sem fazer nada.

Custo como arquitetura

O custo é uma decisão de arquitetura, não uma consideração operacional posterior.² Há três níveis:

Nível de tokens. Compactação do prompt do sistema. Remova exemplos didáticos de código (o modelo conhece os APIs), elimine regras duplicadas entre arquivos e substitua explicações por restrições. “Rejeite chamadas de ferramentas que correspondam a caminhos confidenciais” realiza o mesmo trabalho que uma explicação de 15 linhas sobre por que credenciais não devem ser lidas.

Nível de agentes. Prefira novas instâncias a conversas longas. Cada história em uma execução autônoma recebe um novo agente com contexto limpo. O contexto nunca cresce demais porque cada agente começa do zero. Prefira um briefing à memória: os modelos executam melhor um briefing claro do que navegam por 30 etapas de contexto acumulado.

Nível de arquitetura. Prefira CLI ao MCP quando a operação não tiver estado. Uma chamada claude --print para uma avaliação pontual custa menos e não adiciona sobrecarga de conexão. O MCP faz sentido quando a ferramenta precisa de estado persistente ou streaming.

Framework de decisão

Quando usar cada mecanismo:

Skills vs Hooks vs Subagents

FAQ

Quantos hooks são demais?

Desempenho, não quantidade, é a restrição. Cada hook roda de forma síncrona, então o tempo total de execução dos hooks é somado a cada chamada de ferramenta correspondente. 95 hooks em configurações de nível de usuário e de projeto rodam sem latência perceptível quando cada hook termina em menos de 200ms. O limite para observar: se um PostToolUse hook adiciona mais de 500ms a cada edição de arquivo, a sessão começa a parecer lenta. Faça profile dos seus hooks com time antes de implantá-los.¹⁴

Hooks podem impedir Claude Code de executar um comando?

Sim. PreToolUse hooks bloqueiam qualquer ação de ferramenta ao sair com código 2. Claude Code cancela a ação pendente e mostra a saída stderr do hook para o modelo. Claude vê o motivo da rejeição e sugere uma alternativa mais segura. Saída 1 é um aviso não bloqueante em que a ação ainda prossegue.³

Onde devo colocar os arquivos de configuração de hooks?

As configurações de hooks ficam em .claude/settings.json para hooks de nível de projeto (comitados no seu repositório, compartilhados com a sua equipe) ou em ~/.claude/settings.json para hooks de nível de usuário (pessoais, aplicados a todos os projetos). Hooks de nível de projeto têm precedência quando ambos existem. Use caminhos absolutos para arquivos de script para evitar problemas com diretório de trabalho.¹⁴

Toda decisão precisa de deliberation?

Não. O módulo de confiança pontua decisões em quatro dimensões (ambiguidade, complexidade, impacto, dependência de contexto). Apenas decisões com pontuação abaixo de 0,70 de confiança geral disparam deliberation, cerca de 10% do total de decisões. Correções de documentação, renomeações de variáveis e edições rotineiras pulam deliberation completamente. Arquitetura de segurança, mudanças de schema de banco de dados e deploys irreversíveis disparam esse processo de forma consistente.⁷

Como testo um sistema projetado para produzir discordância?

Teste tanto os caminhos de sucesso quanto os de falha. Sucesso: agentes discordam de forma produtiva e chegam a um consenso. Falha: agentes convergem rápido demais, nunca convergem ou excedem os orçamentos de spawn. Testes end-to-end simulam cada cenário com respostas determinísticas de agentes, verificando que ambos os portões de validação capturam todos os modos de falha documentados. Um sistema de deliberation em produção roda 141 testes em três camadas: 48 testes de integração bash, 81 testes unitários de Python e 12 simulações de pipeline end-to-end.⁷

Qual é o impacto de latência da deliberation?

Uma deliberation com 3 agentes adiciona 30-60 segundos de tempo real (os agentes rodam sequencialmente pelo Agent tool). Uma deliberation com 10 agentes adiciona 2-4 minutos. Os hooks de consenso e pride check rodam em menos de 200ms cada. O principal gargalo é o tempo de inferência de LLM por agente, não a sobrecarga de orquestração.⁷

Qual deve ser o tamanho de um arquivo CLAUDE.md?

Mantenha cada seção com menos de 50 linhas e o arquivo total com menos de 150 linhas. Arquivos longos são truncados pelas janelas de contexto, então coloque as instruções mais críticas no início: comandos e definições de encerramento antes de preferências de estilo.²¹

Isso pode funcionar com ferramentas além de Claude Code?

Os princípios arquiteturais (hooks como portões determinísticos, skills como expertise de domínio, subagents como contextos isolados, sistema de arquivos como memória) se aplicam conceitualmente a qualquer sistema agêntico. A implementação específica usa eventos de ciclo de vida, padrões de matcher e Agent tool do Claude Code. AGENTS.md leva os mesmos padrões para Codex, Cursor, Copilot, Amp e Windsurf.²¹ O padrão de harness é agnóstico à ferramenta, mesmo que os detalhes de implementação sejam específicos da ferramenta.

Cartão de referência rápida

Configuração de hooks

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Frontmatter de Skill

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Definição de subagent

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

Códigos de saída

Comandos principais

Locais dos arquivos

Registro de alterações

Referências