Arquitetura de agentes: como criar ambientes de desenvolvimento com IA

TL;DR: Claude Code não é uma caixa de chat com acesso a arquivos. É um runtime programável com 31 eventos de ciclo de vida documentados, cada um podendo receber hooks com scripts shell que o modelo não consegue ignorar. Organize hooks em dispatchers, dispatchers em skills, skills em agentes, agentes em workflows, e você terá um harness de desenvolvimento autônomo que impõe restrições, delega trabalho, mantém memória entre sessões e orquestra deliberação multiagente. Os workflows dinâmicos do Claude Code (v2.1.154+) tornaram a orquestração multiagente determinística um recurso nativo — de dezenas a centenas de agentes em segundo plano via /workflows — e a plataforma agora executa subagents em segundo plano por padrão (20 simultâneos, aninhamento de profundidade 3), permite que suas sessões enviem mensagens entre si como pares (v2.1.224) e executa sessões na nuvem em runners auto-hospedados. Hooks e evidence gates continuam responsáveis pela correção.⁵²⁵³⁸⁷ Este guia aborda todas as camadas dessa stack: 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 cresce em torno de um agente LLM: claws. Os hooks, scripts e a orquestração que permitem ao agente alcançar o mundo fora de sua janela de contexto.¹ A maioria dos desenvolvedores trata agentes de programação com IA como assistentes interativos. Eles digitam um prompt, observam o agente editar um arquivo e seguem em frente. Esse enquadramento 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. Toda ação que o modelo realiza passa por hooks que você controla. Você define políticas, não prompts. O modelo opera dentro da sua infraestrutura da mesma forma que um servidor web opera dentro das regras do nginx. Você não fica no nginx digitando requisições. Você o configura, faz o deploy e o monitora.

A distinção importa porque a infraestrutura se multiplica. 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 a invoca. Um agente que revisa código em busca de segurança executa as mesmas verificações, independentemente de você estar 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 precisar 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 avisa.³
• Skills codificam conhecimento especializado que é ativado automaticamente. O campo description determina tudo. Claude usa raciocínio LLM (não correspondência por palavras-chave) para decidir quando aplicar uma skill.⁴
• Subagents evitam o excesso de 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 fica 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 desafiar as próprias suposições. Dois agentes independentes com prioridades de avaliação diferentes identificam falhas estruturais que os quality gates não conseguem abordar.⁷
• 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 escala com a automação.

Como usar este guia

Cada seção se baseia na anterior. O Framework de decisão, no final, oferece 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 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 seu projeto. Eles são carregados automaticamente no início da sessão e após cada compactação. Esta é a memória arquitetural de longo prazo do agente.

Camada de extensão: skills fornecem conhecimento especializado de domínio e são ativadas automaticamente com base no contexto. Hooks fornecem gates determinísticos que são acionados em cada chamada de ferramenta correspondente. Arquivos de memória preservam 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. Orçamentos de spawn impedem recursão descontrolada. A validação por consenso garante a qualidade.

A principal percepção: a maioria dos usuários trabalha inteiramente na Core Layer, vendo o contexto inchar e os custos aumentarem. Usuários avançados configuram as camadas de instruções e extensões e, então, usam a Core Layer 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 os Claude Managed Agents em beta público (8 de abril): loop do harness + execução de ferramentas + contêiner de sandbox + persistência de estado como uma REST API, cobrados com tokens padrão mais US$ 0,08/hora de sessão. A atualização Agents SDK da OpenAI (16 de abril) formalizou a mesma divisão — harness e computação como camadas separadas, com provedores de sandbox nativos (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) e snapshot/rehydrate para sobreviver à perda de contêiner.²³²⁴

A superfície mais profunda de SDK para o lado da OpenAI chegou no openai-agents Python v0.14.0 (lançado em 15 de abril de 2026; anunciado em 16 de abril): uma subclasse SandboxAgent de Agent com default_manifest, instruções e capacidades de sandbox; um Manifest que descreve o contrato de workspace novo (arquivos, diretórios, arquivos locais, repositórios Git, env, usuários, mounts); um SandboxRunConfig para a configuração por execução do cliente de sandbox, injeção de sessão ativa, substituições de manifesto, snapshots e limites de concorrência de materialização. As capacidades integradas incluem acesso ao shell, edição do sistema de arquivos, inspeção de imagens, skills, memória de sandbox e compactação. A memória de sandbox preserva lições extraídas entre execuções e as revela progressivamente; os workspaces oferecem suporte a arquivos locais, entradas de repositórios Git e mounts remotos (S3, R2, GCS, Azure Blob, S3 Files); snapshots são portáveis 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 pelo shell” e “REST API para Managed Agents” — claude-agent-sdk-python é a terceira opção. A série de 28 a 29 de abril (v0.1.69 → v0.1.71) atualizou o CLI incluído para v2.1.123, elevou o requisito mínimo da dependência mcp para >=1.19.0 (versões mais antigas descartavam silenciosamente retornos CallToolResult de ferramentas MCP em processo, deixando o modelo com um blob de erro de validação) e trouxe SandboxNetworkConfig para a paridade de schema com o TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Em 2026-08-12, o pacote está em v0.2.137 no PyPI e o TypeScript SDK em v0.3.229 (ambos verificados nos registros ativos); a linha 0.2.x é incremental em relação à superfície 0.1.x descrita aqui — as opções include_hook_events, skills e de configuração de sandbox abaixo continuam atuais — com lançamentos recentes focados na limpeza de subprocessos e na confiabilidade do stream NDJSON.⁹⁰⁸⁶

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

Em julho de 2026, a coluna gerenciada também ganhou uma abordagem multiagente do lado da OpenAI: openai-agents-python v0.18.2 (11 de julho) e openai-agents-js v0.13.2 (10 de julho) adicionam suporte hospedado a múltiplos agentes em beta — orquestração de múltiplos 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.⁷³ Ambos os fornecedores agora oferecem, na camada 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 superfície de hooks.

A bifurcação arquitetural agora é real:

Quando escolher cada opção: o auto-hospedado continua sendo adequado para equipes que já têm capacidade de infraestrutura, querem skills/hooks sob seu controle ou estão otimizando profundamente um fluxo de trabalho específico. O gerenciado é adequado para equipes sem engenheiros de plataforma dedicados, quando o tempo para gerar valor importa mais do que a personalização, ou quando execuções de agentes precisam sobreviver de forma confiável ao fechamento de laptops sem que você construa essa camada de persistência. Os dois são compatíveis — você pode executar um harness auto-hospedado que delega tarefas específicas de longa duração para Managed Agents via sua REST API.

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 nessa estrutura tem uma finalidade. A árvore ~/.claude/ é uma infraestrutura pessoal que se aplica a todos os projetos. A árvore .claude/ em cada repositório é específica do projeto e compartilhada via 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.⁴ No momento em que você perceber que está reexplicando o mesmo contexto entre sessões, é hora de criar uma skill.

Quando criar uma skill

Skills são para conhecimento que o Claude sempre tem disponível. Slash commands são para ações que você aciona explicitamente. Se estiver decidindo entre os dois, pergunte: “O Claude deve aplicar isso automaticamente ou eu devo decidir quando executá-lo?”

Criando uma skill

As 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 de 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 injeta no contexto do Claude. Quando você envia uma mensagem, o Claude usa raciocínio de modelo de linguagem para decidir se alguma skill é relevante. Uma análise independente do código-fonte do Claude Code confirma o mecanismo: as descrições de skills são injetadas em uma seção available_skills do prompt de sistema, e o modelo usa compreensão de linguagem padrão para selecionar 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 ela faz (revisa código quanto a tipos específicos de problemas), quando usá-la (ao examinar alterações, PRs, análises de qualidade) e frases de gatilho (revisar, auditar, verificar) que os usuários digitam naturalmente.

Observe que a ativação automática é um controle, não uma regra: desde a v2.1.215, o Claude não autoinvoca mais as skills agrupadas /verify e /code-review — elas são executadas somente por invocação explícita, um recuo deliberado da ativação orientada por descrição para skills pesadas de revisão, cujas execuções não solicitadas custavam mais do que rendiam.⁷⁴

Orçamento de contexto

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

Arquivos de suporte e organização

Skills podem referenciar 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 a partir do SKILL.md com links relativos. O 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 suporte.¹²

Compartilhando skills pelo Git

As skills de projeto (.claude/skills/ na raiz do repositório) são compartilhadas por meio do 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, recebem a skill automaticamente. Sem instalação, sem configuração. Essa é a maneira mais eficaz de padronizar especialização em uma equipe.

Skills como uma biblioteca de prompts

Além de skills de propósito único, a estrutura de diretórios funciona como uma biblioteca de prompts organizada:

~/.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 uma faceta diferente da sua especialização. Juntas, formam uma base de conhecimento da qual o Claude recorre automaticamente conforme o contexto. Um desenvolvedor júnior recebe orientação de nível sênior sem precisar pedi-la.

Skills se combinam com hooks

Skills podem definir seus próprios hooks no frontmatter, que são ativados somente enquanto a skill é executada. Isso cria um comportamento específico de 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, injetando restrições de qualidade em todas as sessões sem invocação explícita. A skill em si é conhecimento. O hook é aplicação. Juntos, eles formam uma camada de política.

Erros comuns com skills

Descrições amplas demais. Uma skill git-rebase-helper que é ativada em qualquer prompt relacionado ao git (rebases, merges, cherry-picks, até mesmo 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 invocação explícita por /skill-name.⁴

Skills demais competindo pelo orçamento. Mais skills significam mais descrições competindo pelo orçamento de contexto de 1%. Se você perceber que skills não estão sendo ativadas, verifique /context para ver quais foram excluídas. Priorize menos skills, bem descritas, em vez de muitas vagas.

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

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

Harnesses auto-hospedados em claude-agent-sdk-python v0.1.77+ devem usar a opção skills em ClaudeAgentOptions para declarar as skills disponíveis, e não o valor legado "Skill" em allowed_tools.³⁷ A forma abreviada "Skill" está depreciada, e a opção dedicada fornece ao Claude Code informações mais estruturadas sobre quais skills estão disponíveis. O CLI agrupado na v0.1.77 é a v2.1.133.

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

As skills sempre foram carregadas do diretório .claude/skills/ de um projeto. O Claude Code v2.1.157 estende esse diretório aos plugins: um plugin colocado em .claude/skills/ agora é carregado automaticamente, sem registro em marketplace, e claude plugin init <name> cria um novo plugin ali com o manifesto e o SKILL.md já conectados.⁵⁸ Isso fecha a lacuna entre as duas formas de ferramentas de projeto que antes ficavam em locais diferentes — uma skill simples enviada diretamente ao repositório, em comparação com um plugin que reúne uma skill mais hooks mais um servidor MCP, mas que antes precisava de um marketplace para ser instalado. O efeito prático para o design de harnesses: ferramentas com escopo de projeto não precisam mais passar por um registro para serem distribuídas — escreva-as, faça commit e os colegas de equipe recebem a mesma superfície ao executar git pull. Os plugins ainda são responsáveis pelo caso de uso de instalação agrupada (hooks + skills + servidores MCP + agents em um ZIP); a mudança é que um projeto não precisa mais configurar um marketplace apenas para carregar um plugin de sua própria árvore. Essa convergência agora tem uma base entre fornecedores: Agent Plugins 1.0.0 (publicado em 6 de agosto de 2026) padroniza o mesmo formato de pacote — um manifesto plugin.json, diretórios skills/ com pastas SKILL.md, mcp.json opcional — como “o formato de pacote portátil para agentes de IA”, adotado no lançamento por VS Code, Cursor, GitHub Copilot, ChatGPT & Codex e Kiro. Trata-se explicitamente de uma camada de empacotamento sobre Agent Skills e MCP, não de uma substituição; observe que Anthropic, autor da especificação Agent Skills, ainda não faz parte da coalizão — portanto, trate a portabilidade do Claude para fora do Claude Code como compatibilidade no nível de formato, não como um contrato bidirecional oficial.⁸⁹

Ocultando a superfície agrupada como governança (8 de junho de 2026)

Skills são capacidade, e capacidade é superfície de ataque. O Claude Code v2.1.169 adiciona uma configuração disableBundledSkills (e a variável de ambiente correspondente CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) que oculta completamente do modelo as skills, workflows e slash commands integrados.⁶⁰ Para um harness reforçado ou regulado, isso é uma redução deliberada da superfície de ataque: um operador que auditou e aprovou um conjunto específico de skills de projeto e pessoais pode suprimir tudo o que o Anthropic inclui por padrão, para que o modelo raciocine apenas sobre a superfície que o operador avaliou. Trate isso da mesma forma que uma lista de permissão de ferramentas — o padrão é uma capacidade ampla, e desativá-lo é uma decisão de governança, não uma alternância de conveniência.

.claude/skills aninhadas e resolução da mais próxima (16 de junho de 2026)

O Claude Code v2.1.178 tornou as ferramentas de projeto sensíveis à localização. Skills em diretórios .claude/skills aninhados agora são carregadas quando você está trabalhando em arquivos sob esse diretório, e não apenas a partir da raiz do repositório; em caso de conflito de nome, a skill aninhada aparece como <dir>:<name> para que ambas continuem acessíveis.⁶³ A mesma versão fez o restante da superfície do projeto ser resolvida em relação ao diretório de trabalho mais próximo: quando o nome de um agent, workflow ou estilo de saída entra em conflito entre diretórios .claude/ aninhados, vence aquele mais próximo do diretório de trabalho, e um salvamento de workflow no escopo do projeto tem como destino o .claude/workflows/ existente mais próximo, em vez de sempre a raiz.⁶³ Para um monorepo ou um repositório de repositórios, essa é a diferença entre uma superfície global plana e ferramentas por pacote que se ativam no 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 shell acionados por eventos do ciclo de vida de Claude Code.³ Eles são executados fora do LLM como scripts simples, não como prompts interpretados pelo modelo. O modelo quer executar rm -rf /? Um script bash de 10 linhas verifica o comando em uma blocklist e o rejeita antes mesmo de o shell vê-lo. O hook é acionado independentemente de o modelo querer ou não.

Eventos disponíveis

Claude Code expõe 31 eventos documentados do ciclo de vida, distribuídos em oito categorias, até a atualização deste guia. A lista de eventos cresce a cada release, portanto trate a documentação de referência como fonte da verdade e consulte a cola para ver a tabela completa atual antes de configurar hooks de produção:¹³

DirectoryAdded (v2.1.219) fecha a lacuna de workspace durante a sessão. A lista de eventos permanece estável desde a chegada de MessageDisplay na v2.1.152; DirectoryAdded é o primeiro novo evento de ciclo de vida desde então e é acionado após /add-dir — ou após a solicitação de controle register_repo_root do SDK — registrar um novo diretório de trabalho no meio de uma sessão.⁸⁴ A lacuna que ele fecha é real: até agora, um harness podia validar exaustivamente um workspace em SessionStart e então ver um segundo repositório ser adicionado sem que hook algum fosse acionado. Tudo o que você declara sobre o workspace na inicialização — verificações de confiança, varreduras de segredos, regras de escopo de caminho 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 já não é fixo no lançamento. O evento é informativo, e não bloqueante; portanto, trate-o como um gatilho para recalcular o estado e registrar a procedência, não como uma barreira. Se um diretório jamais puder ser adicionado, negue-o nas configurações em vez de tentar vetá-lo por um hook. O lado do SDK chegou na mesma release (TypeScript v0.3.219 adiciona DirectoryAdded aos eventos do ciclo de vida do protocolo de controle), então harnesses hospedados pelo SDK o veem no mesmo nível que os do 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 em arquivos de configurações. No nível do projeto (.claude/settings.json) para hooks compartilhados. No 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 tool, ele corresponde a valores de tool_name, como Bash, Edit, Write, Read, Glob, Grep, nomes de tools MCP como mcp__server__tool ou * para todas as tools. Nomes simples e listas separadas por | são correspondências exatas; valores com outros caracteres são expressões regulares JavaScript. Alguns eventos não oferecem suporte a matchers e são sempre acionados quando configurados.¹³ A partir do Claude Code v2.1.195, matchers que contêm identificadores com hífen (code-reviewer, mcp__brave-search) fazem correspondência exata em vez de, por acidente, corresponderem a substrings — um hook destinado a um único agent ou servidor deixa de ser acionado em todo nome que apenas contenha a string; para abranger todas as tools de um servidor MCP com hífen, escreva o padrão explícito mcp__brave-search__.*.⁶⁶ A v2.1.214 aplicou a mesma disciplina a padrões de caminho: uma condição if: de hook que usa um padrão de segmento único dir/** agora corresponde somente a <cwd>/dir, e não a todos os diretórios chamados dir em qualquer lugar da árvore — escreva **/dir/** quando você realmente quiser 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 quaisquer condições de hook que dependiam silenciosamente do comportamento anterior de qualquer profundidade.

Protocolo de entrada/saída de hooks

Hooks recebem JSON na entrada padrão, com todo o contexto:

{
  "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 tool, injetar contexto ou tomar decisões de permissão. Use o wrapper hookSpecificOutput — o formato anterior de decision/reason no nível superior foi descontinuado 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 depois do fato. Hooks PostToolUse em Write/Edit executam seu formatador após 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 de serem executadas. Hooks PreToolUse em Bash inspecionam 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 em pontos de decisão. Hooks PreToolUse em comandos git commit executam seu linter ou conjunto 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 hook além de comandos shell

Claude Code oferece suporte a cinco tipos de hook:¹³ Hooks de comando (type: "command") executam scripts de shell. Rápidos, determinísticos, sem custo de tokens.

Hooks de ferramenta MCP (type: "mcp_tool") chamam uma ferramenta em um servidor MCP já conectado. Use-os quando a lógica de validação já estiver por trás de uma fronteira 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 sutis que regex não consegue expressar.

Hooks de agente (type: "agent") iniciam um subagent com acesso a ferramentas (Read, Grep, Glob) para verificações de vários turnos. Eles são experimentais; prefira hooks de comando para gates de produção e reserve hooks de agente para verificações que realmente exigem inspecionar arquivos reais ou a 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 agente inclui subagent_type, o que permite que um hook compartilhado diferencie uma execução de security-reviewer de um explorer ou worker genérico sem precisar deduzir 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 de volta. Use-os para webhooks, serviços de notificação externos ou validação baseada em API (v2.1.63+). Não há suporte para 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 async para notificações, telemetria e backups. Nunca use async para formatação, validação ou qualquer coisa 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 gravando simultaneamente no mesmo arquivo de estado JSON vão truncar o JSON. Todos os hooks subsequentes que fazem parse desse arquivo falham.²

A solução: um dispatcher por evento que executa hooks sequencialmente a partir de 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. Passe uma entrada JSON de exemplo: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Use stderr para saída de depuração. stderr com código de saída 2 é enviado de volta ao Claude como mensagem de erro. stderr não bloqueante (saída 1, 3 etc.) aparece apenas no modo verbose (Ctrl+O).
3. Fique atento a falhas do jq. Caminhos JSON incorretos retornam null silenciosamente. Teste expressões jq com entradas reais de ferramentas.
4. Verifique os códigos de saída. Um hook PreToolUse que usa exit 1 não aplica nenhuma restrição, embora pareça estar funcionando.
5. Mantenha os hooks rápidos. Hooks são executados de forma síncrona. Mantenha todos os hooks abaixo de 2 segundos, idealmente abaixo de 500 ms.

Streaming de eventos de hook no lado do SDK

harnesses auto-hospedados construídos com claude-agent-sdk-python (v0.1.74+, 6 de maio de 2026) podem assinar eventos de hook diretamente do fluxo de mensagens, em vez de passar por callbacks de scripts de shell.³⁶ Defina include_hook_events=True em ClaudeAgentOptions, e objetos HookEventMessage (PreToolUse, PostToolUse, Stop e outros) serão retornados pelo mesmo iterador das mensagens do assistente e dos resultados das ferramentas. Isso espelha a opção includeHookEvents do SDK TypeScript; o CLI incluído foi atualizado para v2.1.129 na mesma versão.

O padrão de fluxo de eventos é adequado quando seu harness já está em Python e você quer sinais de hook no mesmo fluxo de controle da saída do modelo. O contrato de hooks de scripts de shell (códigos de saída, stdin JSON, dispatchers) continua sendo a resposta certa para harnesses que compõem várias ferramentas, compartilham hooks entre Claude Code e Codex ou precisam de semântica de código de saída para bloqueio.

A série de julho de 2026 do SDK TypeScript (v0.3.205–v0.3.208) tornou o próprio protocolo de streaming mais contratual.⁷⁰ Interrupções agora retornam recibos tipados: uma interrupção confirma quais mensagens enfileiradas ainda estão pendentes por meio de UUIDs still_queued, e as sessões anunciam a capacidade interrupt_receipt_v1 em system/init, para que um coordenador consiga diferenciar “a interrupção chegou” de “a interrupção passou por uma mensagem que já estava em andamento”. Quadros command_lifecycle relatam queued/started/completed/cancelled/discarded por mensagem — a primeira resposta própria para “o que aconteceu com a mensagem que enviei” sem inferência a partir da transcrição. Superfícies menores também foram incluídas: um tipo AgentToolCompletedOutput para payloads de conclusão de subagent, e callbacks canUseTool agora podem retornar {behavior: 'allow'} sem um campo updatedInput.

Uma linha nessa série é um limite mínimo de segurança, não um recurso: a v0.3.208 corrigiu um abort do chamador que chegava durante um hook pendente e era convertido em sucesso do hook — o que significava que uma ferramenta bloqueada por um hook PreToolUse podia executar depois que o chamador tivesse abortado.⁷⁰ Se o seu harness usa hooks no lado do SDK como gate de permissão e depende de abort para cancelar trabalho em andamento, trate a v0.3.208 como a versão mínima; abaixo dela, “abortado” não significava de forma confiável “bloqueado”. Python v0.2.127 (24 de julho de 2026) é o segundo bypass desse tipo em um mês — query() fechava stdin no primeiro quadro result enquanto subagents em segundo plano ainda estavam executando, portanto as chamadas de ferramenta SDK-MCP falhavam com "Stream closed" e ignoravam completamente os hooks PreToolUse.⁸⁵ Dê um nome ao padrão e monitore-o: a aplicação de hooks no lado do SDK falha aberta nas bordas do ciclo de vida — abort, encerramento, fechamento do stream — onde o transporte morre antes que o veredito do hook seja coletado, e falha silenciosamente, porque um hook ignorado parece exatamente um hook que aprovou. Fixe ambas as versões mínimas do SDK e mantenha a camada de shell-hook como a aplicação que você pode comprovar.

Esforço e proveniência da sessão (7–8 de maio de 2026)

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

• effort.level na entrada de hooks. 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, para que comandos Bash possam lê-lo sem fazer parse de JSON. Use isso para dimensionar o custo do hook conforme o nível de esforço: pule validações caras em low, execute o gate de segurança completo em xhigh ou max.
• Variável de ambiente CLAUDE_CODE_SESSION_ID em subprocessos Bash. Subprocessos de ferramentas Bash agora veem o mesmo valor de session_id que os hooks veem, exposto como CLAUDE_CODE_SESSION_ID. Isso fecha a lacuna de proveniência para ferramentas que registram estado por sessão e antes não conseguiam correlacionar eventos de subprocessos com eventos de hooks.

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

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

Claude Code v2.1.136 adicionou um novo nível de hard-deny ao modo automático e corrigiu um conjunto de problemas de plugin e MCP que afetavam harnesses de longa execuçã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 matchers atuais de permitir/negar como uma alavanca de governança inegociável. Use para regras que nunca podem ser substituídas (force-push para a main, arquivos que contêm secrets, acesso ao banco de dados de produção), mesmo quando um operador tiver aprovado a categoria mais ampla nas configurações pessoais. - autoMode.classifyAllShell (v2.1.193). Por padrão, o classificador do modo automático revisa apenas comandos de shell que correspondem a padrões de execução arbitrária de código. Essa configuração encaminha todos os comandos Bash/PowerShell para o classificador — a postura de cobertura máxima para um harness governado —, e a mesma versão exibe os motivos de negação na transcrição, na notificação e em /permissions, transformando bloqueios silenciosos em decisões auditáveis. O Codex reforçou a superfície equivalente 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 passarem silenciosamente.⁶⁶ - O ask do hook limita o classificador (v2.1.211). A questão de precedência entre hook e modo automático agora está resolvida: um hook PreToolUse que retorna uma decisão de permissão ask fixa o resultado final em um prompt — o modo automático não pode escalá-lo de volta para permitir comandos Bash sem sandbox.⁶⁹ Para um harness governado, esta é a camada de garantia que faltava: o ask de um hook é uma parada determinística com participação humana que persiste mesmo em posturas de permissão totalmente automáticas. Use ask (não apenas bloqueios com exit-2) para as operações em que você quer uma decisão humana em vez de uma recusa. - O modelo do classificador é fixado por sessão (v2.1.210). O classificador do modo automático usa Sonnet 5 por padrão e é fixado durante a sessão, portanto mudanças de modelo no meio da sessão não alteram mais qual modelo realiza as classificações de permissão.⁶⁹ A consistência da classificação é uma propriedade de governança; isso elimina uma fonte discreta de divergência. - Os servidores MCP não desaparecem mais após /clear. Servidores configurados em .mcp.json, plugins e conectores do claude.ai estavam saindo silenciosamente do conjunto ativo após um /clear na extensão do VS Code, no plugin JetBrains e no Agent SDK. A correção chega na v2.1.136. Se você viu “MCP server X went missing mid-session”, essa era a causa. - Perda de refresh token de MCP OAuth durante atualização concorrente. Usuários com vários servidores MCP remotos não devem mais precisar fazer nova autenticação diariamente. Gravações de atualização concorrentes estavam sobrescrevendo umas às outras. - O modo Plan agora bloqueia gravações de arquivo corretamente. Uma regra de permissão Edit(...) correspondente estava contornando a proteção contra gravações do modo Plan. O modo Plan agora é aplicado independentemente das regras de permissão. - Hooks Stop e UserPromptSubmit de plugins não falham mais no meio da sessão. A limpeza de cache estava excluindo arquivos de versão de plugins que ainda eram usados pela sessão em execução, interrompendo especificamente esses dois eventos de hook. A correção mantém as versões em uso fixadas. - Entrada skills em plugin.json. Definir skills ocultava o diretório 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 por CLAUDE_ENV_FILE ficando desatualizadas. Variáveis exportadas por hooks SessionStart via CLAUDE_ENV_FILE ficavam desatualizadas após /resume ou /clear. Corrigido na v2.1.136. As sessões agora recarregam o arquivo de ambiente nesses eventos.

Para harnesses de governança, os itens operacionalmente mais interessantes são autoMode.hard_deny (nova alavanca) e a correção para o desaparecimento de MCP (falha silenciosa que interrompia sessões longas). Todo o restante é uma limpeza de qualidade de vida.

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

O Claude Code v2.1.139 adicionou dois detalhes de hook 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 caminho. Ele inicia o comando diretamente, sem um shell, o que elimina toda uma classe de erros de citação e injeção.

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

A mesma versão passa CLAUDE_PROJECT_DIR para servidores stdio MCP e permite que configurações de plugins façam referência a ${CLAUDE_PROJECT_DIR} em comandos.⁴² Ferramentas MCP devem resolver caminhos relativos ao projeto a partir desse valor, em vez de usar o diretório de trabalho de qualquer processo que tenha iniciado 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: roots/list de MCP agora inclui os diretórios de trabalho adicionais da sessão, com notificações roots/list_changed quando eles mudam — portanto, um servidor que respeita as roots de MCP acompanha a estrutura real do workspace com vários diretórios em vez de assumir um único diretório de projeto.⁶⁸

O Claude Code v2.1.140 é, em sua maior parte, uma versão de confiabilidade para operadores de harness: corrige hooks ConfigChange que não eram acionados em mudanças de configurações, fecha casos extremos em que disableAllHooks e allowManagedHooksOnly não se combinavam corretamente entre níveis de configuração e impede que diálogos de permissão exponham variáveis de ambiente não intencionais retornadas por resultados de hook.⁴⁹ Isso torna mais confiáveis os padrões de governança existentes nesta seção; não exige uma nova arquitetura de hook.

O Claude Code v2.1.141 adiciona um campo terminalSequence na saída de hook para notificações desktop, títulos de janela e alertas sonoros sem um terminal de controle.⁵⁰ Trate isso como sinalização para o operador, não como imposição. Gates de segurança e qualidade ainda devem comunicar falhas por meio do 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 o Agent View a um diretório, 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: visões operacionais mais restritas, menos pressupostos sobre instalação de plugins e escopo explícito de token empresarial.

O Claude Code v2.1.142 é mais importante para a orquestração de sessões em segundo plano do que para a semântica de hooks.⁵¹ claude agents agora pode despachar 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 wrappers. Nessa versão, o modo Fast usava Opus 4.7 por padrão, com CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 como fixação para um harness com dependência medida do comportamento do Opus 4.6 — a partir da v2.1.219, o Opus 4.7 está totalmente fora do modo fast e /fast se aplica ao Opus 5 e ao Opus 4.8.⁸⁴ A descoberta de SKILL.md de plugins no nível raiz e a visibilidade de LSP fornecida por plugins reduzem a ambiguidade de empacotamento. Correções em MCP_TOOL_TIMEOUT, worktrees pré-existentes de sessões em segundo plano, suspensão/reativação de daemon e limpeza pós-atualização, além da limpeza de cache de plugins, fecham lacunas de confiabilidade que, de outra forma, parecem bugs de orquestração.

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

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

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 enviar feedback ao Claude e manter o turno em andamento, sem que a resposta seja rotulada como erro de hook. Antes disso, a única alavanca real de um hook Stop era o bloqueio com exit-2, que é interpretado como erro e conta para o limite de bloqueios consecutivos. Para um harness de gate de qualidade, este é o primitivo mais limpo: um hook Stop que detecta “você disse que terminou, mas os testes estão falhando” agora pode injetar “aqui está o que ainda está falhando, continue” em vez de bloquear rigidamente. Use o bloqueio para condições genuínas de parada e additionalContext para “ainda não terminou, eis o motivo”.

Mensagens entre sessões não carregam mais autoridade emprestada. A v2.1.166 reforçou o caso de múltiplas sessões: mensagens retransmitidas via SendMessage de outra sessão Claude não carregam mais a autoridade do usuário de origem, portanto uma sessão receptora recusa solicitações de permissão retransmitidas e o modo automático as bloqueia. Se sua orquestração faz agentes enviarem mensagens entre si, trate uma mensagem recebida como dado não confiável, não como uma instrução autenticada. Este é o mesmo princípio que a seção de segurança aplica à saída de ferramentas, estendido às mensagens entre agentes. A partir da v2.1.199, o Claude Code também detecta e avisa quando um SendMessage é direcionado incorretamente porque dois agentes compartilham o mesmo nome — um complemento de confiabilidade a esse limite de autoridade, já que uma mensagem chegar ao agente errado com o mesmo nome é uma classe própria de bug de orquestração. As sessões agora são pares de primeira classe (v2.1.224+). As mensagens entre sessões passaram do reforço do relay para uma superfície completa: SendMessage/ListAgents permitem que suas sessões descubram e enviem mensagens umas às outras entre suas máquinas (macOS/Linux), com controles crossSessionInbound de aceitar/manter/recusar no lado que recebe — e os runners auto-hospedados permitem que sessões web e mobile do Claude Code sejam executadas em um hardware que você controla. Para a arquitetura de harness, isso transforma “uma sessão” em um nó endereçável: descoberta, política de entrada e o limite de autoridade acima agora são primitivas da plataforma, não scripts de mailbox (o guia do Claude Code documenta o contrato completo).⁸⁷ Uma mudança de postura vem junto: o modo auto se torna o modo de permissão padrão nos planos Pro, Max e Team em 14 de agosto de 2026 — um harness que depende de prompts do modo Manual como seu mecanismo de human-in-the-loop deve fixar defaultMode explicitamente, em vez de presumir isso.⁸⁷

A resiliência de modelo se tornou uma configuração de primeira classe. A configuração fallbackModel agora encadeia até três modelos de backup, tentados em ordem quando o primário está sobrecarregado ou indisponível, e um turno tenta novamente uma vez no fallback diante de erros API inesperados e não repetíveis. Para um harness autônomo de longa execução, isso transforma uma indisponibilidade transitória do modelo primário em uma degradação elegante, em vez de uma execução descartada. 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 um prompt de permissão — um ganho de observabilidade para qualquer coordenador que monitore uma frota de agentes.

Modo seguro para governança clean-room 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 — uma clean-room deliberada. Use-o para responder à pergunta que todo operador acaba fazendo: “esse comportamento vem do modelo ou de algo que configurei?” Quando um hook dispara incorretamente, uma skill é ativada quando não deveria ou um servidor MCP contamina o contexto, --safe-mode oferece uma linha de base conhecida e vazia para comparar. Ele também é uma primitiva de governança: uma forma de executar o modelo puro sem nenhuma da autoridade persistente que seu harness normalmente concede, o que importa quando você precisa reproduzir um resultado sem que qualquer estrutura definida pelo operador o influencie.

Uma observação sobre os níveis de modelo. A partir do Claude Code v2.1.197 (30 de junho de 2026), o Claude Sonnet 5 é o modelo padrão disponibilizado 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 a opção padrão. Este guia considera o Opus 5 (claude-opus-5) como 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 horizonte e alto risco são exatamente onde a profundidade de raciocínio do Opus justifica 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 a US$ 10/US$ 50 por cerca de 2,5× a velocidade padrão — e o 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 o Anthropic caracteriza como “muito mais forte em verificar seu trabalho e iterar cuidadosamente” é a rara atualização que não exige argumento de custo para trabalho com harness; a migração do 4.8 é uma mudança de id. Mude para o Sonnet 5 em trabalhos sensíveis a custo ou de alto volume, nos quais sua relação velocidade-inteligência vence. 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 do Anthropic, um sistema de “classe Mythos” tornado seguro para uso geral, selecionável no Claude Code v2.1.170 via /model claude-fable-5.⁶⁰ Recorra ao nível superior deliberadamente, nas decisões em que a profundidade bruta de raciocínio justifica o custo, e não como uma configuração geral para uma frota. Duas consequências de manutenção 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 Fable-5 do classificador do modo auto — “o melhor modelo Opus disponível” desde a v2.1.176 — agora aponta para o Opus 5.⁸⁴

O Codex lançou o multi-agent v2. O CLI do Codex v0.137.0 mantém a escolha de runtime em cada thread, disponibiliza padrões mais limpos de acompanhamento e metadados para agentes gerados (hide_spawn_agent_metadata agora tem como padrão true) e propaga eventos brutos do pai aos listeners filhos. Seu modelo de subagent continua explícito: tipos de agente integrados default/worker/explorer, agentes personalizados definidos em TOML e controles de concorrência (agents.max_threads padrão 6, agents.max_depth padrão 1). A mesma versão adiciona uma extensão v1 de skills com resolução do catálogo de skills por turno e novos eventos de contribuição ao ciclo de vida de início de thread/erro de turno, reduzindo a diferença em relação à superfície de hooks/skills do Claude Code e mantendo a postura de kernel-sandbox como limite padrão. O Codex v0.138.0–v0.139.0 então reforçou o multi-agent v2 para produção: os payloads de mensagens entre agentes agora são criptografados, um catálogo de configuração de agentes v2 mais um LRU de residência de agentes gerenciam quais agentes permanecem residentes, e a concorrência é contabilizada pela execução ativa, e não pelas threads geradas, portanto agentes ociosos não consomem mais uma vaga.⁶¹ O ciclo de vida API também amadureceu — close_agent foi renomeado para interrupt_agent (v0.139.0) para refletir que ele interrompe um agente em execução, em vez de simplesmente fechar um handle — e avisos de inicialização de MCP gerados por um subagent agora permanecem restritos à thread proprietária, em vez de serem duplicados no transcript do pai.⁶¹ Para quem cria orquestração no lado do Codex, essas são as diferenças 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 pelo limite da thread. O Codex v0.140.0 então abriu uma interface entre ferramentas: /import traz seletivamente configuração inicial, configuração de projeto e chats recentes do Claude Code para o Codex, e sessões se tornaram permanentemente excluíveis (codex delete / /delete, com proteções de confirmação).⁶⁴ /import é o primeiro reconhecimento oficial de que operadores transitam entre harnesses — a configuração que você cria para um não fica mais presa nele.

Memória e contexto

Toda conversa de IA opera dentro de uma janela de contexto finita. Conforme a conversa cresce, o sistema compacta os turnos anteriores para abrir espaço para novo conteúdo. A compactação é com perdas. Decisões de arquitetura documentadas no turno 3 podem não sobreviver até o turno 15.⁹

Os três mecanismos do colapso em múltiplos turnos

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

Estratégia 1: filesystem como memória

A memória mais confiável entre limites de contexto fica no filesystem. Claude Code lê CLAUDE.md e arquivos de memória no início de cada sessão e após 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 sessões. Quando você descobre que ((VAR++)) falha com set -e no bash quando VAR é 0, você registra isso. Três sessões depois, quando encontra um caso de borda semelhante com inteiros em Python, a entrada no MEMORY.md traz o padrão à tona.¹⁵

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. A memória automática carrega as primeiras 200 linhas no seu system prompt no início da sessão. Mantenha-a concisa e crie links para arquivos separados por tópico com notas detalhadas.⁶ A partir da v2.1.210, uma gravação em MEMORY.md que ultrapassa o limite de tamanho gera erro em vez de truncar silenciosamente⁶⁹ — a falha aparece no momento da gravação, em vez de resultar em entradas de memória que simplesmente desapareceram. Se seu harness automatiza gravações de memória, trate esse erro; a plataforma está dizendo que o arquivo precisa de curadoria, não de uma nova tentativa.

Curadoria de memória em vez de volume de memória (maio de 2026): Um preprint recente no arXiv sobre cooperação entre agentes LLM apresenta a ampliação da recuperação como um possível modo de falha: nos experimentos dos autores, um histórico visível mais longo degradou a cooperação em 18 das 28 configurações de jogo de modelos.⁴⁸ Trate isso como um alerta de design, não como uma regra concluída. A regra de produção já está clara o suficiente: mantenha MEMORY.md curto, crie links para detalhes e coloque resumos prontos para decisão nas transferências. Dumps brutos de transcrições, logs de ferramentas e feeds longos de recuperação devem ficar em armazenamento pesquisável, não 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 decisões importantes, conteúdos de arquivos e o estado da tarefa.¹⁵

Quando compactar: - Depois de concluir uma subtarefa distinta (recurso implementado, bug corrigido) - Antes de iniciar uma nova área do codebase - Quando Claude começa a repetir ou esquecer o contexto anterior - Aproximadamente a cada 25-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 prompt cache. Ele move uma sessão para um novo diretório de trabalho durante o fluxo sem quebrar o cache acumulado ao longo do turno.⁶⁰ Antes disso, mudar de diretório significava uma sessão nova e um cache frio. Em uma sessão de longa duração que migra de um repositório para outro no mesmo nível — algo comum em trabalhos com monorepo e múltiplos serviços — /cd mantém intacto o prefixo caro armazenado em cache enquanto redireciona o contexto do filesystem.

Estratégia 3: transferências de sessão

Para tarefas que abrangem várias sessões, crie documentos de transferência 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 o contexto completo com um custo mínimo de tokens. Iniciar uma nova sessão com claude -c (continuar) ou ler o documento de transferência leva você diretamente à implementação.¹⁵

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

Para sessões que ultrapassam 60-90 minutos, inicie uma nova instância de Claude por iteração. O estado persiste pelo filesystem, não pela memória conversacional. Cada iteração recebe o orçamento completo de contexto:¹⁶

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

Compare com uma única sessão longa:

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

A abordagem de contexto novo por iteração troca uma sobrecarga de 15-20% pela etapa de orientação (ler arquivos de estado, examinar o histórico do git) por recursos cognitivos completos em cada iteração.¹⁶ O cálculo de custo-benefício: para sessões com menos de 60 minutos, uma única conversa é mais eficiente. Após 90 minutos, o contexto novo produz resultados de maior qualidade apesar da sobrecarga.

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

Os Managed Agents de Anthropic e Claude adicionaram o Dreaming como Research Preview em 6 de maio de 2026.³⁵ Segundo Anthropic: “Dreaming é um processo agendado que revisa suas sessões de agente e seus armazenamentos de memória, 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 sessões, não no caminho crítico. Ele complementa, em vez de substituir, o padrão de filesystem como memória: seu arquivo MEMORY.md continua sendo a superfície estrutural; 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 estado auto-hospedado no filesystem com curadoria no lado gerenciado.

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

Os antipadrões

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

Manter uma saída de erro detalhada no contexto. Depois de depurar um bug, seu contexto contém mais de 40 stack traces de iterações que falharam. Um único /compact após corrigir o bug remove esse peso morto.

Iniciar toda sessão lendo todos os arquivos. Deixe que as ferramentas de glob e grep do Claude Code encontrem arquivos relevantes sob demanda, economizando mais de 100.000 tokens de pré-carregamento desnecessário.¹⁵

Padrões de subagents

Subagents são instâncias especializadas de Claude que executam tarefas complexas de forma independente. A maioria começa com um contexto limpo (sem interferência da conversa principal) — a exceção é o tipo fork abaixo, que herda tudo deliberadamente —, opera com ferramentas especificadas e retorna os resultados como resumos. Os resultados da exploração não sobrecarregam sua conversa principal; apenas as conclusões retornam.⁵

Tipos de subagents integrados

Criação de 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 por worktree

Subagents podem operar em git worktrees temporários, que oferecem uma cópia completa e isolada 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 por worktree é essencial para trabalhos experimentais que possam danificar a base de código.

Isolamento só é isolamento quando a barreira se mantém. O Claude Code v2.1.210 corrigiu um bug que permitia que subagents isolados por worktree alterassem o checkout principal — exatamente a falha que esse mecanismo existe para impedir.⁶⁹ Se você depende de isolation: worktree como limite de segurança, e não apenas como conveniência, considere a v2.1.210 como a versão mínima. A alteração complementar de permissões segue na direção oposta: desde a 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 correta para agentes que trabalham em worktrees paralelos, mas significa que uma permissão concedida durante um experimento descartável continua válida depois do experimento — conceda-a pensando no repositório inteiro, não apenas no worktree à sua frente.

A v2.1.216 concluiu o trabalho, elevando o isolamento por worktree de correção de bugs a mecanismo com nível de proteção efetiva.⁷⁴ A correção da v2.1.210 impediu que subagents em worktrees alterassem o checkout principal por meio de invocações comuns 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 apontar qualquer um deles para o checkout compartilhado. Todas essas rotas de escape agora estão fechadas. A mesma versão corrigiu casos em que sessões de worktree acabavam no worktree remanescente de um projeto diferente, impediu que gravações de workflows e tarefas agendadas seguissem um link simbólico colocado em .claude até um destino fora do projeto e fez /rewind se recusar a atravessar links simbólicos e hard links. O padrão nas quatro correções é o mesmo: um limite de isolamento precisa resistir a redirecionamentos deliberados — substituições por variáveis de ambiente do git, implantação de links simbólicos —, não apenas ao comportamento padrão. Se isolation: worktree for um limite de segurança no seu harness, e não 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 precisam de coordenação 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.

O recursion guard

Sem limites de criação, agentes delegam para agentes que delegam para outros agentes, cada um perdendo contexto e consumindo tokens. O padrão de recursion guard impõe 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 crucial: use orçamentos de criação, não apenas limites de profundidade. Limites baseados em profundidade acompanham cadeias entre pais e filhos (bloqueadas na profundidade 3), mas ignoram a largura: 23 agentes na profundidade 1 ainda são “profundidade 1”. Um orçamento de criação acompanha o total de filhos ativos de cada pai, limitado a um máximo configurável. O modelo de orçamento corresponde ao verdadeiro modo de falha (agentes demais no total), e não a uma métrica indireta (níveis de aninhamento demais).⁷

O padrão de profundidade de aninhamento mudou três vezes; não construa sua solução sobre ele. O Claude Code v2.1.172 (10 de junho de 2026) permitiu que subagents criassem seus próprios subagents, com aninhamento de até 5 níveis — antes, a delegação era efetivamente limitada a um nível.⁶² Isso permaneceu assim da v2.1.172 até a v2.1.216. A v2.1.217 (21 de julho de 2026) reduziu o limite para 1, desativando a criação aninhada por padrão. Depois, a v2.1.219 (24 de julho de 2026) chegou a um meio-termo: “Subagents agora podem criar 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 — as duas últimas mudanças em um intervalo de três dias.

A interpretação útil não é que um desses números esteja correto. É que a plataforma ainda está buscando o padrão adequado, e por isso “o que vier na versão” é a escolha errada para um harness herdar. Trate a profundidade de aninhamento como uma linha explícita do orçamento: defina CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH com a profundidade de que sua arquitetura realmente precisa — para a maioria das orquestrações, 1 ou 2 —, para que uma atualização não altere silenciosamente até que ponto sua frota delega. O argumento fundamental permanece inalterado apesar de toda essa instabilidade: cadeias de agentes delegando para agentes consomem contexto e tokens mais rapidamente do que produzem resultados, e a profundidade é um risco a incluir no orçamento, não um recurso a perseguir. O recursion guard acima é o que impede que uma árvore profunda se expanda para centenas de agentes ativos, independentemente de como o padrão mude no futuro, e um limite definido por você é o único número de profundidade que continuará significando o que você espera após a próxima versão.

O modo automático agora avalia as criações antes de iniciá-las. O Claude Code v2.1.178 eliminou a lacuna correspondente de governança: no modo automático, a criação de subagents é avaliada pelo classificador de permissões antes que o subagent seja iniciado, não apenas quando ele começa a executar ações.⁶³ Antes, um subagent podia ser criado para solicitar uma ação que a sessão pai não teria permissão para executar — a própria criação era a brecha. A avaliação no momento da criação faz com que o recursion guard e o modelo de permissões finalmente se encontrem: um filho não pode ser usado como intermediário para uma ação proibida pela política.

A plataforma agora inclui um orçamento de criação nativo. O Claude Code v2.1.212 (julho de 2026) adicionou proteções nativas contra loops descontrolados: as sessões são limitadas a 200 criações de subagents por padrão (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 criação que esta seção documenta como script do usuário desde a v1.0 agora é fornecido pela plataforma — uma validação do modelo de orçamento em vez do modelo de profundidade. Porém, observe a calibração: 200 criações são uma ordem de grandeza acima do orçamento de 12 agentes na configuração acima. Os limites nativos são fusíveis contra um loop realmente descontrolado, não orçamentos ajustados à sua arquitetura. Mantenha o guard do usuário para orçamentos por pai, acompanhamento de profundidade e limites que correspondam ao que sua orquestração deve realmente fazer; deixe que o limite da plataforma capture o que passar por ele.

O conjunto de proteções nativas agora abrange quatro eixos. Três deles dão suporte exatamente ao que o guard do usuário nesta seção acompanha: total de criaçõ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, atualmente 3 por padrão 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 sem limites em agentes de segundo plano).⁷⁸⁸⁴ A v2.1.219 adiciona um quarto eixo que os guards do usuário geralmente não tinham: largura da orquestração, o número de agentes que um único workflow planejado pode conter, lançado 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 criação agora conta com proteção nativa em todos os eixos para os quais foi projetado, além de um para o qual não foi.

A observação sobre calibração ainda se aplica, mas de maneira desigual. As 200 criaçõ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 definir uma arquitetura. A diretriz de largura é o primeiro número nativo na mesma escala de um orçamento real: 15 agentes por workflow fica ao lado dos 12 deste guia, perto 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ê consiga defender; defina a diretriz de largura conforme o formato da orquestração que você pretendia construir.

Agent Teams (versão prévia para 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 contestar 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 objetivos (maio de 2026)

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

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 trate como prova de qualidade. Ele oferece observabilidade; testes, review gates 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 por vários 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 para 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 respaldados por comandos ou scripts quando uma falha precisar bloquear o processo.

Ferramenta Workflow (v2.1.147+)

Os workflows dinâmicos do Claude Code são um recurso lançado e disponível por padrão: desde a v2.1.154, eles orquestram de dezenas a centenas de agentes em segundo plano, monitorados por /workflows, com um controle “Dynamic workflow size” em /config (v2.1.202) e uma chave de configurações workflowSizeGuideline cuja diretriz padrão é média — tente usar menos de 15 agentes, salvo instrução em contrário (v2.1.219). O recurso estreou uma versão antes como a ferramenta Workflow desativada por padrão na v2.1.147, atrás de CLAUDE_CODE_WORKFLOWS=1; a época dessa flag ficou para trás, mas o princípio arquitetural que ela introduziu permanece.⁵² Ela oferece ao Claude Code um recurso nativo de orquestração para fluxos que antes exigiam scripts personalizados de dispatch, estado da caixa de mensagens e convenções de coordenação entre subagents.

Não remova o harness que a envolve. 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 criação ou de etapas do workflow para impedir 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 o formato da orquestração; use hooks, testes e review gates para determinar a verdade.

Os workflows dinâmicos agora incluem uma opinião sobre largura (v2.1.219). Por padrão, workflows dinâmicos usam 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, e a diretriz atual aparece na linha de status do workflow em execução.⁸⁴ O número é uma recomendação, não uma imposição; ele orienta o planejador em vez de bloquear um plano amplo. O que torna sua configuração valiosa é o mecanismo de distribuição: a nova chave de configurações workflowSizeGuideline pode ser definida em qualquer arquivo de configurações — incluindo configurações gerenciadas e do projeto, e está nos tipos de configurações do TypeScript SDK desde a v0.3.219 —, portanto a largura da orquestração passa a ser 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 se decompõe. Duas observações para operadores: a linha do /config fica oculta quando um arquivo de configurações determina o valor, o que é o comportamento correto, mas parece uma configuração ausente se você não souber o motivo; e, como a diretriz orienta o planejador em vez de impedir a execução, ela pertence à coluna de formato, não à de segurança. A largura descontrolada continua sendo responsabilidade do limite de criação.

Vale manter a perspectiva de que este é o quarto eixo de proteção nativa — largura da orquestração, ao lado de quantidade de criações, profundidade de aninhamento e execução simultânea — e o primeiro que o 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ão na mesma ordem de grandeza do orçamento de deliberação de 12 agentes usado por este guia desde a v1.0. Quando o padrão da plataforma e seu próprio orçamento convergem a partir de direções opostas, isso é o mais próximo de uma confirmação independente que esses números podem oferecer.

Fork de sessões e MCP movido automaticamente para segundo plano (julho de 2026)

O Claude Code v2.1.212 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 foi renomeado como /subtask. A distinção é importante para o design da orquestração: /subtask é um desvio 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 todo o contexto, mais próxima de uma criação de loop Ralph do que de um subagent. Se os scripts do seu harness presumiam que /fork permanecia na sessão, agora eles distribuem trabalho em segundo plano.

A mesma versão move automaticamente chamadas lentas de MCP para segundo plano: uma chamada de ferramenta MCP que leva mais de dois minutos é transferida automaticamente para execução em segundo plano (ajuste o limite com CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS).⁶⁹ Um servidor MCP lento não paralisa mais o loop agêntico — mas isso também significa que “a ferramenta retornou” e “o turno continuou” deixaram de ser o mesmo evento, portanto hooks ou scripts que pressupunham a conclusão síncrona do 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 de assistente dos subagents para a saída stream-json.⁶⁹ Um processo coordenador que consome o stream do pai agora pode observar diretamente o progresso dos subagents, 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 esse recurso além do primeiro nível: subagents criados na profundidade 2 ou superior agora também aparecem no stream encaminhado, identificados pelo id tool_use do Agent que os criou.⁸⁴ Essa identificação é 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 qual filho, permitindo reconstruir a árvore de delegação a partir do stream, em vez de deduzi-la. Se seu consumidor de stream foi criado considerando apenas um nível de subagents, agora ele verá texto de agentes cuja existência desconhecia; agrupe pelo id tool_use que iniciou cada um, em vez de presumir que toda linha encaminhada pertence a um filho direto.

Orquestração multiagente

Sistemas de IA de agente único têm um ponto cego estrutural: eles não conseguem desafiar as próprias premissas.⁷ A deliberação multiagente força uma avaliação independente a partir de múltiplas perspectivas antes que qualquer decisão seja consolidada.

Orquestração entre ferramentas (abril de 2026): o Google lançou como open source o Scion em 7 de abril — um hipervisor multiagente que executa Claude Code, Gemini CLI e outros “agentes profundos” como processos simultâneos, cada um com container, git worktree e credenciais isolados. Executa localmente, em hub ou no Kubernetes. A filosofia explícita é: “isolamento acima de restrições” — os agentes operam com alta autonomia dentro de limites impostos na camada de infraestrutura, não no prompt.²⁵ Isso estende diretamente o argumento de isolamento de subagents entre fornecedores de ferramentas diferentes. Se o seu fluxo de trabalho abrange Claude e modelos da OpenAI, o Scion é a primeira implementação de referência real para subagents entre ferramentas com isolamento de worktree + credenciais por agente.

Debate não é uma solução milagrosa: o grupo de pesquisa M3MAD-Bench (início de 2026) constatou que o debate multiagente atinge um platô e pode ser prejudicado por consensos enganosos — argumentos válidos perdem quando outros agentes afirmam com confiança a resposta errada.²⁶ O Tool-MAD melhora isso ao conceder a cada agente acesso a ferramentas heterogêneas e usar pontuações de Fidelidade/Relevância na etapa de avaliação. Se você estiver criando uma orquestração no estilo de debate, invista em (a) heterogeneidade de ferramentas por agente e (b) pontuação quantitativa de avaliação, em vez de presumir que mais agentes = respostas melhores.

Orquestração multiagente gerenciada e Outcomes (beta público)

Se você não quiser criar a infraestrutura de deliberação descrita abaixo, a Orquestração multiagente entrou em beta público no Claude Managed Agents em 6 de maio de 2026.³⁵ Segundo Anthropic: “Quando há trabalho demais para um único agente executar 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 rastreamento já vem incluído. Segundo Anthropic: “você também pode rastrear cada etapa no Claude Console: qual agente fez o quê, em que ordem e por quê, dando a você visibilidade total sobre como sua tarefa foi delegada e executada.”³⁵

O recurso complementar em beta público é Outcomes. Segundo Anthropic: “você escreve uma rubrica descrevendo como é o sucesso, e o agente trabalha para alcançá-lo. Um avaliador separado analisa a saída em relação aos seus critérios na própria janela de contexto, para não ser influenciado pelo raciocínio do agente.”³⁵ Esta é a versão de serviço gerenciado do padrão de validação de dois gates documentado mais adiante nesta seção: a rubrica substitui o gate escrito manualmente, e 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 à sua própria superfície de hooks (bloqueio PreToolUse, semântica de código de saída, dispatchers personalizados) ou quando o harness precisa ser executado sem dependências externas. O Multiagent gerenciado é a resposta certa quando delegação padrão com avaliação por rubrica é o contrato de que você realmente precisa.

Deliberação mínima viável

Comece com 2 agentes e 1 regra: os agentes precisam avaliar de forma independente antes de ver o trabalho uns dos outros.⁷

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 abrange 80% do valor. Todo o resto adiciona melhorias incrementais.

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 - Ela exige conhecimento especializado?
3. Risco - A decisão é reversível?
4. Dependência de contexto - Ela exige compreender o sistema mais amplo?

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

O limite se adapta conforme o tipo de tarefa. Decisões de segurança exigem consenso de 0,85. Alterações na documentação precisam de apenas 0,50. Isso evita o excesso de engenharia em tarefas simples e garante que decisões arriscadas recebam escrutínio.⁷

A máquina de estados

Sete fases, cada uma condicionada à anterior:⁷

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

RESEARCH: Agentes independentes investigam o tópico. Cada agente recebe uma persona diferente (Arquiteto Técnico, Analista de Segurança, Engenheiro de Performance e outros). 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 de Debate identifica conflitos. O agente de Síntese combina descobertas não contraditórias.

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

A arquitetura de validação de dois gates

Dois gates de validação detectam problemas em estágios diferentes:⁷

Gate 1: Validação de consenso (hook PostToolUse). Executado imediatamente após a conclusão de cada agente de deliberação: 1. A fase deve ter alcançado pelo menos RANKING 2. Pelo menos 2 agentes concluíram (configurável) 3. A pontuação de consenso atende ao limite adaptado à tarefa 4. Se algum agente discordou, as preocupações devem ser documentadas

Gate 2: Pride Check (hook Stop). Executado antes que a sessão possa ser encerrada: 1. Métodos diversos: múltiplas personas únicas representadas 2. Transparência de contradições: discordâncias têm motivos documentados 3. Tratamento da 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 supera a confiança inicial

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

Por que a concordância é perigosa

Charlan Nemeth estudou a discordâ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 rapidamente a um acordo. O dissidente não precisa estar certo. O ato de discordar força a maioria a examinar premissas que, de outra forma, deixaria passar.¹⁸

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

A independência é a restrição de design crítica. Dois agentes avaliando a mesma estratégia de implantação, 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 comportamento de manada.⁷

Detectando concordância falsa

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

Agrupamento de pontuações: Todos os agentes com pontuações em um intervalo de 0,3 ponto em uma escala de 10 pontos sinalizam contaminação por contexto compartilhado, e não uma 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, uma nova execução com isolamento de contexto novo distribuiu as pontuações entre 5,8 e 8,9.

Discordância padronizada: 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 Analista de Segurança e um Engenheiro de Performance raramente concordam em tudo).

O detector de conformidade identifica os casos óbvios (cerca de 10-15% das deliberações em que os agentes convergem rápido demais). Nos 85-90% restantes, os gates de consenso e Pride Check fornecem validação suficiente.

O que não funcionou na deliberação

Rodadas de debate de formato livre. Três rodadas de texto de ida e volta em uma discussão sobre indexação de banco de dados produziram 7.500 tokens de debate. Rodada 1: discordância genuína. Rodada 2: posições reafirmadas. Rodada 3: argumentos idênticos com palavras diferentes. A pontuação estruturada por dimensão substituiu o debate de formato livre, reduzindo o custo em 60% e melhorando a qualidade do ranking.⁷

Um único gate de validação. A primeira implementação executava um hook de validação no fim da sessão. Um agente concluiu a deliberação com uma pontuação de consenso de 0,52 (abaixo do limite), depois continuou em tarefas não relacionadas por 20 minutos antes que o hook de fim de sessão sinalizasse a falha. Dividir em dois gates (um na conclusão da tarefa e outro no fim da sessão) detectou os mesmos problemas em pontos diferentes 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 representa 15.000-24.000 tokens adicionais por decisão. Com 10 agentes, aproximadamente 50.000-80.000 tokens.⁷

Nos preços atuais do Opus 5 ($5/$25 por MTok), uma deliberação com 3 agentes custa aproximadamente US$ 0,23-0,30. Uma deliberação com 10 agentes custa US$ 0,75-1,00. O sistema aciona a deliberação em aproximadamente 10% das decisões, então o custo amortizado em todas as decisões é de US$ 0,08-0,10 por sessão. (Edições anteriores citavam valores 3 vezes maiores, calculados com os preços legados de US$ 15/US$ 75 do Opus 4.x.) Se isso vale a pena depende do custo de 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)

Claude Opus 4.7 (16 de abril de 2026) foi lançado com recursos específicos que mudam o que um harness precisa prevenir:²⁹

• Resiliência a falhas de ferramentas: O Opus 4.7 continua após falhas de ferramentas que interrompiam sessões do Opus 4.6. Você pode reduzir — mas não eliminar — wrappers defensivos de retry no código de subagents. Mantenha as proteções no nível de hooks; reduza a estrutura de prompt do tipo “se a ferramenta falhar, tente novamente três vezes”.
• Nível de esforço xhigh: Introduzido junto com o Opus 4.7 e agora compatível com os modelos Opus atuais (o Opus 4.8 foi lançado com ele como /effort xhigh na v2.1.154; o Opus 5 o herda). Fica entre high e max. É o padrão recomendado para workloads de programação e agentic. Em subagents de longa duração, xhigh supera high de forma significativa, com custo de tokens subproporcional. max continua sendo a escolha certa para raciocínio difícil em uma única execução; xhigh é melhor para tarefas contínuas.
• Teto de orçamento de tokens: Configurável por execução de agente via output_config.task_budget (header beta task-budgets-2026-03-13). O modelo vê uma contagem regressiva em execução e ajusta o escopo do trabalho ao orçamento de forma elegante, em vez de ficar sem tokens inesperadamente. Use em loops agentic quando quiser gastos previsíveis de tokens sem sacrificar a qualidade em prompts curtos.
• Consciência de necessidades implícitas: Primeiro modelo Claude a passar em testes de “necessidade implícita” — reconhecendo quando a solicitação literal do usuário não especifica 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 tem 200 linhas de proteções do tipo “considere também X quando o usuário pedir Y”, elimine as que agora são cobertas nativamente.

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

Claude Code v2.1.133 adiciona quatro configurações de nível administrativo que vale conhecer para harnesses de produção:³⁹

A reversão de worktree.baseRef é a que você deve destacar para os usuários: agentes que dependiam do comportamento da v2.1.128-v2.1.132 (worktrees criando branches a partir do HEAD local) perdem acesso ao trabalho não enviado em worktrees novos, a menos que optem novamente por esse comportamento.

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

Claude Code v2.1.136 adicionou CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL para reativar a pesquisa de qualidade na sessão para empresas que capturam as respostas pelo OpenTelemetry.⁴⁰ Se sua organização envia eventos OTel para uma stack central de observabilidade, essa variável de ambiente coloca a pesquisa de volta no caminho dos dados, para que o sinal de qualidade flua pelo mesmo pipeline que as métricas de latência e erro. Trate-o como opt-in: o padrão mantém a pesquisa desativada, o que é correto 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 de produção.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER permite que ambientes gerenciados iniciem o processo Claude Code por meio de um binário wrapper corporativo — o ponto de integração para agentes de endpoint, verificações de política no momento da inicialização e ambientes em que todo processo deve ser executado sob um supervisor obrigatório. Se sua empresa antes simulava isso com aliases de shell ou scripts de launcher bifurcados, esta é a interface compatível.

A mesma versão reduziu o overhead de runtime onde os harnesses mais o sentem: até 7× mais rápido em rodadas de uso de ferramentas em sessões com altas contagens de ferramentas MCP, e transcrições de sessão 79× menores.⁶⁸ Isso suaviza — sem reverter — a orientação de Custo como arquitetura: CLI-first ainda vence para operações pontuais sem estado, mas um harness que carrega dezenas de ferramentas MCP não paga mais a penalidade por rodada que pagava na primavera, e o armazenamento de transcrições deixa de ser um custo oculto de longas execuções autônomas.

O quality loop

Um processo obrigatório de revisão para todas as mudanças não triviais:

1. Implementar - Escreva o código
2. Revisar - Releia cada linha. Encontre erros de digitação, erros de lógica e trechos pouco claros
3. Avaliar - Execute o evidence gate. Verifique padrões, casos extremos e cobertura de testes
4. Refinar - Corrija todos os problemas. Nunca adie para “depois”
5. Ampliar a visão - Verifique pontos de integração, imports e código adjacente em busca de regressões
6. Repetir - Se qualquer critério do evidence gate falhar, volte à etapa 4
7. Relatar - Liste o que mudou, como foi verificado e cite evidências específicas

O evidence gate

“Acredito” e “deve funcionar” não são evidências. Cite caminhos de arquivos, saída de testes ou código específico.

Se você não puder apresentar evidências para qualquer linha, volte a Refinar.²²

Autoridade humana para merge

Um estudo do arXiv de maio de 2026 sobre 29.585 ciclos de vida de pull requests de agentes de IA separa autonomia operacional de governança de merge.⁴⁷ A lição arquitetural útil é simples: agentes podem iniciar o trabalho, levar branches adiante, abrir PRs, revisar o trabalho e resumir riscos, enquanto a autoridade para merge permanece um limite de governança separado.

Torne esse limite explícito no harness. Deixe os agentes prepararem PRs e reunirem 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 a automação executa um merge, preserve logs que distingam o executor da pessoa ou política que o autorizou.

Padrões de tratamento de erros

Gravações atômicas de arquivos. Vários agentes escrevendo simultaneamente no mesmo arquivo de estado corrompem JSON. Escreva em arquivos .tmp e depois use mv de forma atômica. O sistema operacional garante que mv é 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 corrupção de estado. Se o estado for corrompido, o padrão de recuperação recria a partir de padrões seguros em vez de falhar:¹⁶

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 do bash ((VAR++)). ((VAR++)) retorna o código de saída 1 quando VAR é 0 porque 0++ é avaliado como 0, algo que o bash trata como falso. Com set -e ativado, isso encerra o script. Use VAR=$((VAR + 1)) em vez disso.¹⁶

Classificação de raio de impacto

Classifique cada ação do agente pelo raio de impacto e aplique o gate correspondente:²

O Remote Control (conectar-se ao Claude Code local de 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 próxima tarefa 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 de testes, saída do linter, códigos de status HTTP e verificações de existência de arquivos. Uma tarefa inicial que pedia ao agente para “escrever testes que passam” gerou assert True e assert 1 == 1. Tecnicamente correto. Na prática, inútil.¹⁶

Modos de falha para observar

Um rastreamento concreto de sessão

Um rastreamento de sessão de uma execução autônoma que processa um PRD com 5 stories:²

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

2. O agente lê o PRD, planeja a primeira story. UserPromptSubmit é acionado. O dispatcher injeta: contexto do projeto ativo, linha de base de desvio da sessão.

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

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

5. O agente termina a story. 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, saída 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 story volta para a fila.

8. A story passa. A próxima story é carregada. O ciclo se repete para todas as 5 stories.

Total de hooks acionados em 5 stories: ~340. Tempo total em hooks: ~12 segundos. Esse overhead evitou três vazamentos de credenciais, um comando destrutivo e duas implementações incompletas em uma única execução noturna.

Estudo de caso: processamento noturno de PRD

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

Os dois vazamentos de credenciais exigiram a rotação de chaves API e a auditoria de serviços downstream: aproximadamente 4 horas de resposta ao incidente. O overhead do harness que evitou o equivalente foi de 2,4 segundos de bash por story. A taxa de conclusão falsa caiu de 35% para 4% porque o hook Stop executou testes de forma independente antes de permitir que o agente informasse a conclusão.

Considerações de segurança

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

Anthropic publicou uma estrutura formal para a confiabilidade de agentes em 9 de abril de 2026.²⁷ Os cinco princípios são paralelos — e ampliam — o raciocínio do Evidence Gate deste guia:

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

Turno sem estado e identidade autodeclarada do MCP. A especificação do MCP concluiu sua transição para um núcleo sem estado (SEP-2575) com a revisão de 28 de julho de 2026, agora a especificação Current, que elimina o handshake stateful de initialize que antes carregava a identidade do servidor. Uma alteração no rascunho da especificação incorporada em 16 de julho (PR #3002) restaura a identidade como uma superfície opcional: os servidores podem incluir um objeto io.modelcontextprotocol/serverInfo na resposta _meta, 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 — 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 auditoria baseada em logs no nome declarado de um servidor MCP, esse nome é uma alegação, não uma credencial; fixe a confiança no transporte e na configuração (qual servidor você configurou em qual endpoint), nunca no que o servidor diz ser. A revisão sem estado foi lançada conforme o cronograma em 28 de julho de 2026 (server/discover obrigatório, negociação da versão do protocolo via _meta, cabeçalho Streamable HTTP) — a orientação de confiança acima descreve o comportamento lançado.

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 vereditos respaldados por evidências da detecção Sigma/YARA/Nova/Snort. É o primeiro produto na categoria de sandbox para skills.²⁸

O sandbox

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

Piso de segurança de maio de 2026. Claude Code v2.1.149 corrigiu um bypass de permissão de diretório de trabalho no PowerShell, várias lacunas na análise de permissões relacionadas a regras de permissão do PowerShell e variáveis obsoletas, além de um bug na allowlist de escrita do sandbox para git-worktree que cobria toda a raiz do repositório principal em vez de apenas os internos compartilhados do git.⁵³ Se o seu harness permite PowerShell ou agentes isolados por worktree, trate a v2.1.149+ como o piso e mantenha as regras de shell restritas. PowerShell(*) abrangente e exceções de escrita para todo o repositório são atalhos de orquestração, não limites de segurança.

Bloqueio do sandbox do OpenAI Agents SDK (v0.17.0, 8 de maio de 2026). Do lado da OpenAI, a v0.17.0 de openai-agents-python reforçou um limite paralelo: LocalFile.src e LocalDir.src agora são 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 concedida por Manifest.extra_path_grants com SandboxPathGrant.⁴¹ Origens locais relativas são resolvidas a partir de base_dir; caminhos absolutos já precisam estar dentro dele ou ter uma concessão. Isso fecha um problema de limite de artefatos locais: versões anteriores permitiam que manifestos trouxessem caminhos arbitrários do host para um workspace de sandbox. Migração: declare raízes confiáveis do host no nível do manifesto com SandboxPathGrant(path=..., read_only=True) para montagens somente leitura. Trate extra_path_grants como configuração confiável da aplicação; nunca preencha concessões a partir da saída do modelo ou de entrada de manifesto não confiável.

Piso complementar do OpenAI Agents SDK (v0.17.3). A linha 0.17.1-0.17.3 adicionou mais reforços de sandbox e sessão: limites de extração de arquivos, validação de subcaminhos do GitRepo, erros mais claros do provedor de sandbox, credenciais de mountpoint mantidas fora de comandos de sandbox, rejeição de raízes relativas de workspace de sandbox e tratamento de estado terminal do sandbox da Vercel.⁵⁴ Se você usa sandboxes hospedados pela OpenAI ou apoiados por provedores, em vez de apenas hooks do Claude Code, trate a 0.17.3 como o piso atual para os padrões desta seção.

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

A publicação de engenharia da Anthropic “How we contain Claude across products” (25 de maio de 2026) é a própria articulação do fornecedor dos princípios que esta seção ensina de forma fragmentada — o sandbox no nível de configurações acima, o piso de isolamento por worktree, a postura de tratar tudo como não confiável.⁸¹ Seu movimento central é mapear a força da contenção à superfície do produto, e o próprio mapeamento é a lição: não há um único design correto de isolamento, apenas isolamento adequado a quem está supervisionando e ao que pode dar errado.

• Contêineres gVisor efêmeros (claude.ai). A execução no lado do servidor é executada em contêineres gVisor em infraestrutura isolada, com um sistema de arquivos efêmero por sessão. O modelo de ameaça é o isolamento da infraestrutura e dos tenants — a máquina do usuário nunca pode ser alcançada, então nada local precisa ser protegido.
• Sandboxing do sistema operacional com humano no circuito (Claude Code). O padrão descrito no parágrafo sobre sandbox acima, declarado como política: Seatbelt no macOS e bubblewrap no Linux, com leituras permitidas, escritas limitadas ao workspace e rede negada por padrão — o humano aprova aquilo que o limite não cobre. A Anthropic tornou o runtime open source (sandbox-runtime), para que o limite seja auditável. A publicação é franca sobre o elo fraco: aproximadamente 93% dos prompts de permissão são aprovados, e o classificador do auto mode — que detecta cerca de 83% dos comportamentos excessivamente proativos antes da execução, enquanto reduz os prompts de aprovação em 84% — existe justamente porque a fadiga de aprovação é uma propriedade 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 em hypervisors de plataforma — framework Apple Virtualization no macOS, 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 keychain do host, e cada sessão recebe um token com escopo e revogável de forma independente. Um proxy MITM defensivo dentro da VM impõe isso, encaminhando apenas solicitações que carregam o próprio token de sessão provisionado da VM — uma chave inserida por um invasor é rejeitada no limite, porque somente a VM conhece a procedência.

Os princípios de design por trás da taxonomia são a parte transferível. Contenha primeiro na camada de ambiente, oriente depois na camada de modelo: toda defesa probabilística tem uma taxa de falha diferente de zero, portanto limites determinísticos precisam capturar aquilo que a orientação no nível do prompt não detecta — o argumento deste guia de que hooks garantem a execução, reformulado pelo fornecedor. Adeque a força do isolamento à capacidade de supervisão do usuário: um desenvolvedor pode avaliar um comando bash antes de aprová-lo; um trabalhador do conhecimento não pode — é por isso que Code recebe um diálogo de permissão e Cowork recebe uma VM selada. Prefira primitivas testadas em batalha em vez de código de isolamento personalizado: hypervisors, seccomp e runtimes de contêineres sobreviveram ao escrutínio adversarial melhor do que os próprios proxies de allowlist e parsers de configuração personalizados da Anthropic. Trate a configuração local do projeto e as saídas de ferramentas como não confiáveis: a instrução da publicação é tratar abertura de projeto e carregamento de configuração como qualquer solicitação de entrada 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 MCP autodeclarada. Mantenha as credenciais fora do sandbox: tokens com escopo, revogáveis e por sessão, em vez de chaves ambientais que o agente poderia vazar.

A superfície de configurações está alcançando o primeiro princípio (v2.1.219). “Contenha primeiro na camada de ambiente” é fácil de defender e tem sido difícil de configurar de fato, porque o sandbox do Claude Code resolvia o que suas regras não cobriam perguntando — e um prompt de permissão é uma defesa probabilística usando uma fantasia determinística, como admite o número de 93% de aprovações acima. sandbox.network.strictAllowlist elimina a pergunta para egress: com essa opção definida, a solicitação de um comando em sandbox para um host fora da allowlist é negada diretamente em vez de gerar um prompt.⁸⁴ Combine-a com sandbox.filesystem.disabled da v2.1.216 e as duas configurações formam uma postura, em vez de uma pilha de toggles — a contenção do sistema de arquivos e da rede pode ser selecionada de forma independente, e a contenção de rede agora pode ser determinística. Para um harness sem supervisão, esta é a mais importante das duas, porque egress é onde uma instrução injetada se torna exfiltração, e o caso extremo da fadiga de aprovação é não haver ninguém no teclado para se fatigar. O custo é o custo normal de um limite determinístico: a allowlist precisa estar correta, e um host que você esqueceu falha como uma negação opaca, não como uma pergunta. Liste os hosts dos quais seus agentes realmente precisam e então remova o prompt.

Nada disso substitui a camada de hooks; isso fica abaixo dela. Os padrões de contenção são o piso determinístico, e o histórico de imposição de worktree neste guia é a mesma lição em miniatura: um limite só conta se resistir a redirecionamento deliberado, e as primitivas com maior chance de resistir são aquelas que não foram escritas para a ocasião.

Limites de permissão

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

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

Claude Code v2.1.178 ampliou as regras de permissão do nível da ferramenta para o nível de parâmetro: Tool(param:value) corresponde aos parâmetros de entrada de uma ferramenta, com * como curinga. O exemplo canônico é Agent(model:opus) — uma regra que impede que subagents sejam iniciados em uma camada específica de modelo.⁶³ Arquiteturalmente, isso fecha uma lacuna que a tabela de quatro níveis acima não conseguia expressar: antes, você permitia ou negava uma ferramenta por inteiro, mas não podia restringir como ela era chamada. Agora, uma política de governança pode dizer “subagents podem iniciar, mas não na camada Fable 5” ou “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 combinam — a allowlist define quais camadas existem para a sessão, e as regras no nível de parâmetros restringem como os subagents as utilizam. A partir da v2.1.196, administradores também podem definir um modelo padrão para toda a organização no console da organização, exibido como “Org default” em /model, para que uma frota herde um padrão governado sem que cada operador precise fixar um — um piso que complementa o teto da allowlist.

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

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 de segmento único dir/** — Edit(src/**), por exemplo — aprovava automaticamente edições em qualquer diretório chamado src em qualquer profundidade, incluindo vendor/some-package/src/ e todos os outros src/ aninhados que o autor da regra nunca quis autorizar. Essas regras agora se ancoram apenas em <cwd>/dir; se você realmente quiser correspondência em qualquer profundidade, declare-a com **/dir/**.⁷⁴ Regras de negação e pergunta deliberadamente mantêm a antiga correspondência em qualquer profundidade. Essa assimetria é o design correto de falha segura: uma regra de permissão que corresponde de forma restrita demais falha com segurança (você recebe um prompt), enquanto uma regra de negação que corresponde de forma restrita demais falha aberta (um caminho bloqueado passa) — por isso, as permissões ficaram mais restritas 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 fazê-lo na v2.1.214; essa é a correção funcionando como esperado, mas vale revisar suas allowlists para declarar novamente a abrangência que você realmente quer.

Proteções contra comandos destrutivos no Auto Mode (junho de 2026)

Claude Code v2.1.183 reduziu o raio de explosão do auto mode para as operações que silenciosamente perdem trabalho ou desmontam ambientes. Agora, o auto mode bloqueia permanentemente, a menos que você tenha pedido explicitamente por elas 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 feito pelo agente nesta sessão; e desativação de infraestrutura (terraform destroy, pulumi destroy, cdk destroy) a menos que você tenha indicado a stack específica.⁶⁵ Arquiteturalmente, isso complementa a verificação de spawn e as regras no nível de parâmetros acima: em vez de controlar qual ferramenta ou como ela é iniciada, controla um pequeno conjunto de comandos irreversíveis específicos por intenção — o agente ainda pode executá-los, mas apenas mediante instrução explícita, não por iniciativa própria. Para um harness autônomo, codifique o mesmo princípio nos seus próprios hooks PreToolUse: os comandos que destroem estado merecem uma regra de negação por padrão que somente um sinal explícito do operador remove.

Julho de 2026: o auto mode chega ao enterprise, e um prompt não pode ser dispensado. O auto mode alcançou GA no Amazon Bedrock, Google Vertex AI e Microsoft Foundry na v2.1.207, com uma configuração gerenciada disableAutoMode como opt-out para empresas — a postura de 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 lacuna da plataforma.⁶⁸ Em seguida, a v2.1.208 tornou absoluta a proteção contra remoções catastróficas: prompts de confirmação para remoções catastróficas agora atravessam tanto --dangerously-skip-permissions quanto o auto mode.⁶⁸ Este é um precedente notável — a primeira confirmação no Claude Code que nenhuma postura de permissão, inclusive a flag explícita de bypass, pode dispensar. Designs de harnesses autônomos que presumiam que --dangerously-skip-permissions significava literalmente zero prompts devem considerar essa exceção; ela é acionada exatamente onde um loop sem supervisão pode causar os danos mais irrecuperáveis.

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 seu próprio rastro de auditoria.⁶⁸ Primeiro, uma regra do auto mode agora bloqueia a adulteração de arquivos de transcrição — o registro da sessão deixou de ser algo que as próprias chamadas de ferramenta da sessão podem reescrever. Segundo, as notificações de tarefas em segundo plano agora informam explicitamente que nenhuma entrada humana ocorreu enquanto a tarefa foi executada. A segunda medida visa uma falha sutil: antes, um modelo que resumisse uma tarefa em segundo plano poderia apresentar (ou inventar) uma “aprovação” na transcrição que nunca ocorreu, e nada na notificação a contradizia. Agora, a própria notificação é a contraevidência.

A lição arquitetural se generaliza para o Evidence Gate: transcrições, notificações e logs são superfícies de auditoria, e superfícies de auditoria não devem ser graváveis pelo objeto que auditam. A plataforma agora impõe isso para sua própria transcrição; aplique a mesma regra ao seu harness — relatórios de evidência, saídas de testes e registros de deliberação pertencem fora do caminho gravável pelo modelo.

Defesa contra prompt injection

Skills e hooks oferecem defesa em profundidade contra prompt injection:

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

allowed-tools: Read, Grep, Glob

Hooks PreToolUse validam cada chamada de ferramenta independentemente de como o modelo foi instruído:

# 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

Isolamento de subagent limita o raio de explosão. Um subagent com permissionMode: plan não pode fazer alterações mesmo que seu prompt esteja comprometido.

O piso da plataforma subiu em julho de 2026. Claude Code v2.1.210 reforçou a Agent tool contra prompt injection indireto transportado em conteúdo que um subagent leu — um arquivo, página da web ou resultado de ferramenta envenenado obtido por um subagent tem menos capacidade de orientar a própria superfície de delegação.⁶⁹ E a v2.1.211 reforçou o elo humano na cadeia: as prévias de permissão agora neutralizam caracteres Unicode de substituição bidirecional, largura zero e semelhantes, de modo que um comando não pode mais ser criado para parecer inofensivo no diálogo de aprovação enquanto executa outra coisa.⁶⁹ A segunda correção é mais importante para harnesses em que um humano aprova prévias renderizadas sob pressão de tempo — a exibição também era uma superfície de injection. Nenhuma das mudanças substitui as defesas no nível de hooks acima; elas elevam o piso 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 para que conteúdo sensível e políticas executáveis vazem ou escapem. O aviso GHSA-f3jg-756w-gm35 do GitHub aborda um problema de filtro de payload do Gryph Agents no qual conteúdo sensível de payload de ferramentas poderia permanecer em logs locais SQLite sob o comportamento de logging padrão.⁴⁵ O OSV GHSA-wxxx-gvqv-xp7p aborda uma fuga de sandbox de guardrail de código personalizado LiteLLM em um endpoint de proxy protegido por administrador.⁴⁶

A regra de produção: trate transcrições de agentes, payloads de ferramentas, logs SQLite e execução de guardrails como infraestrutura sensível. Remova dados sensíveis antes da persistência, aplique limites de retenção e mantenha o código de guardrail personalizado em sandbox e revisável. Uma regra no nível do prompt de “não registre secrets” não é suficiente; o caminho de logging e guardrails precisa de testes determinísticos.

Segurança de hooks

Hooks HTTP que interpolam variáveis de ambiente em cabeçalhos exigem uma lista explícita de allowedEnvVars para evitar 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 entre responsabilidades humanas e de agentes:¹⁷

O padrão: humanos assumem decisões que exigem contexto organizacional, julgamento ético ou direção estratégica. Agentes assumem decisões que exigem busca computacional em grandes espaços de possibilidades. Hooks impõem o limite.

Aplicação recursiva de hooks

Hooks também são disparados para ações de subagents.¹³ Se Claude iniciar um subagent por meio da Agent tool, seus hooks PreToolUse e PostToolUse serão executados para cada ferramenta que o subagent usar. Sem aplicação recursiva de hooks, um subagent poderia ignorar seus limites de segurança. O evento SubagentStop permite executar limpeza ou validação quando um subagent é concluído.

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

Custo como arquitetura

Custo é uma decisão arquitetural, não uma reflexão operacional tardia.² Três níveis:

Nível de token. Compressão do system prompt. Remova exemplos de código de tutorial (o modelo conhece os APIs), consolide regras duplicadas entre arquivos e substitua explicações por restrições. “Rejeite chamadas de ferramentas que correspondam a caminhos sensíveis” faz o mesmo trabalho que uma explicação de 15 linhas sobre por que as credenciais não devem ser lidas.

Nível de agente. Spawns novos em vez de conversas longas. Cada história em uma execução autônoma recebe um novo agente com contexto limpo. O contexto nunca aumenta demais porque cada agente começa do zero. Briefing em vez de memória: modelos executam um briefing claro melhor do que navegam por 30 etapas de contexto acumulado.

Nível de arquitetura. CLI-first em vez de MCP quando a operação não tem estado. Uma chamada claude --print para uma avaliação pontual custa menos e não adiciona overhead de conexão. MCP faz sentido quando a ferramenta precisa de estado persistente ou streaming.

Estrutura de decisão

Quando usar cada mecanismo:

Skills vs Hooks vs Subagents

Perguntas frequentes

Quantos hooks são hooks demais?

O limite é o desempenho, não a quantidade. Cada hook é executado de forma síncrona, portanto o tempo total de execução dos hooks é somado a cada chamada de ferramenta correspondente. 95 hooks nas configurações de usuário e de projeto são executados sem latência perceptível quando cada hook é concluído em menos de 200 ms. O limite a observar: se um hook PostToolUse acrescenta mais de 500 ms a cada edição de arquivo, a sessão fica lenta. Faça o profiling dos seus hooks com time antes de implantá-los.¹⁴

Os hooks podem impedir que Claude Code execute um comando?

Sim. Hooks PreToolUse bloqueiam qualquer ação de ferramenta ao sair com o código 2. Claude Code cancela a ação pendente e mostra ao modelo a saída stderr do hook. Claude vê o motivo da rejeição e sugere uma alternativa mais segura. A saída 1 é um aviso não bloqueante, no qual 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 no nível do projeto (incluídos no commit do seu repositório e compartilhados com sua equipe) ou em ~/.claude/settings.json para hooks no nível do usuário (pessoais, aplicados a todos os projetos). Hooks no nível do projeto têm precedência quando ambos existem. Use caminhos absolutos para arquivos de script a fim de evitar problemas de diretório de trabalho.¹⁴

Toda decisão precisa de deliberação?

Não. O módulo de confiança pontua decisões em quatro dimensões (ambiguidade, complexidade, impacto e dependência de contexto). Apenas decisões com pontuação geral de confiança abaixo de 0,70 acionam a deliberação, cerca de 10% do total de decisões. Correções de documentação, renomeações de variáveis e edições rotineiras ignoram totalmente a deliberação. Arquitetura de segurança, alterações de esquema do banco de dados e implantações irreversíveis a acionam de forma consistente.⁷

Como testo um sistema projetado para produzir discordância?

Teste tanto os caminhos de sucesso quanto os de falha. Sucesso: os agentes discordam de forma produtiva e chegam a um consenso. Falha: os 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 dos agentes, verificando que ambos os gates de validação capturam todos os modos de falha documentados. Um sistema de deliberação em produção executa 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 da deliberação na latência?

Uma deliberação com 3 agentes adiciona 30–60 segundos de tempo de relógio (este design de deliberação executa seus agentes sequencialmente pela Agent tool; a plataforma em si executa subagents simultaneamente em segundo plano desde a v2.1.198). Uma deliberação com 10 agentes adiciona 2–4 minutos. Os hooks de consenso e pride check são executados em menos de 200 ms 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 inteiro com menos de 150 linhas. Arquivos longos são truncados pelas janelas de contexto, então coloque primeiro as instruções mais críticas: comandos e definições de encerramento antes das preferências de estilo.²¹

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

Os princípios arquiteturais (hooks como gates determinísticos, skills como especialização de domínio, subagents como contextos isolados, sistema de arquivos como memória) se aplicam conceitualmente a qualquer sistema agentic. A implementação específica usa os eventos de ciclo de vida, padrões de matcher e a Agent tool de Claude Code. AGENTS.md leva os mesmos padrões ao Codex, Cursor, Copilot, Amp e Windsurf.²¹ O padrão de harness é independente de ferramenta, mesmo que os detalhes de implementação sejam específicos de cada 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

Localizações de arquivos

Changelog

Referências