Arquitetura de agentes: criando harnesses de desenvolvimento com IA

TL;DR: Claude Code não é uma caixa de chat com acesso a arquivos. É um runtime programável com 29 eventos de ciclo de vida documentados, cada um conectável a hooks com scripts de shell que o modelo não consegue pular. Empilhe hooks em dispatchers, dispatchers em skills, skills em agents, agents em workflows, e você obtém um harness de desenvolvimento autônomo que aplica restrições, delega trabalho, persiste memória entre sessões e orquestra deliberação multi-agent. Claude Code v2.1.147 adicionou a ferramenta Workflow desativada por padrão (CLAUDE_CODE_WORKFLOWS=1), levando a orquestração multi-agent determinística de scripts puramente em userland para um primitivo de runtime first-party; a v2.1.149 reforça a mesma lição pelo lado da segurança, com correções de bypass de permissões no PowerShell e uma correção de allowlist do sandbox de git-worktree. Hooks e evidence gates ainda são responsáveis pela correção.⁵²⁵³ Este guia cobre todas as camadas desse stack: de um único hook a um sistema de consenso com 10 agents. Sem frameworks. Tudo em bash e JSON.

Andrej Karpathy criou um termo para o que cresce ao redor de um agent LLM: claws. Os hooks, scripts e a orquestração que permitem ao agent agarrar o mundo fora da sua janela de contexto.¹ A maioria dos desenvolvedores trata agents de coding com AI como assistentes interativos. Eles digitam um prompt, observam o agent 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 agent de coding com AI é um runtime programável com um kernel LLM. Toda ação que o modelo executa passa por hooks que você controla. Você define políticas, não prompts. O modelo opera dentro da sua infraestrutura do mesmo modo que um servidor web opera dentro das regras do nginx. Você não fica sentado no nginx digitando requisições. Você configura, implanta e monitora.

A distinção importa porque infraestrutura se acumula. Um hook que bloqueia credenciais em comandos bash protege todas as sessões, todos os agents, todas as execuções autônomas. Uma skill que codifica sua rubrica de avaliação se aplica de forma consistente, seja quando você a invoca ou quando um agent faz isso. Um agent que revisa código em busca de problemas de segurança executa as mesmas verificações, esteja você observando ou não.²

Principais pontos

• Hooks garantem execução; prompts não. Use hooks para linting, formatação, verificações de segurança e qualquer coisa que precise rodar 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 expertise de domínio que é ativada 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 inchaço 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 agents quando os workers precisarem de coordenação contínua.⁵
• A memória vive no sistema de arquivos. Arquivos persistem entre janelas de contexto. CLAUDE.md, MEMORY.md, diretórios de rules e documentos de handoff formam um sistema estruturado de memória externa.⁶
• A deliberação multi-agent encontra pontos cegos. Agents individuais não conseguem desafiar as próprias suposições. Dois agents independentes com prioridades de avaliação diferentes encontram falhas estruturais que quality gates não conseguem resolver.⁷
• O padrão de harness é o sistema. CLAUDE.md, hooks, skills, agents e memória não são recursos independentes. Eles se compõem em uma camada determinística entre você e o modelo, que escala com automação.

Como usar este guia

Cada seção se baseia na anterior. O Framework de decisão no final fornece 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 Harness

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

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

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

Camada de extensão: as skills fornecem expertise de domínio que se ativa automaticamente com base no contexto. Os hooks fornecem portões determinísticos que disparam em cada chamada de ferramenta correspondente. Os arquivos de memória persistem o estado entre sessões. Os agents personalizados fornecem configurações de subagents especializados.

Camada de orquestração: os padrões multi-agent coordenam agentes independentes para pesquisa, revisão e deliberação. Orçamentos de spawn previnem recursão descontrolada. A validação por consenso garante a qualidade.

A percepção principal: a maioria dos usuários trabalha inteiramente na Camada Core, observando o contexto inflar e os custos subirem. Usuários avançados configuram as camadas de Instrução e Extensão e, em seguida, usam a Camada Core 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 “construa 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 + container de sandbox + persistência de estado como uma REST API, cobrada por tokens padrão mais $0,08/sessão-hora. A atualização Agents SDK da OpenAI (16 de abril) formalizou a mesma divisão — harness e computação como camadas separadas, com provedores nativos de sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) e snapshot/rehydrate para sobreviver à perda de container.²³²⁴

A superfície SDK mais profunda do 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 de sandbox e capabilities; um Manifest descrevendo o contrato de workspace recém-criado (arquivos, dirs, arquivos locais, repositórios Git, env, users, mounts); um SandboxRunConfig para configuração por execução do cliente de sandbox, injeção de sessão ao vivo, sobrescritas de manifest, snapshots e limites de concorrência de materialização. As capabilities integradas cobrem acesso ao shell, edição de filesystem, inspeção de imagens, skills, memória de sandbox e compactação. A memória de sandbox persiste lições extraídas entre execuções e as divulga progressivamente; workspaces suportam arquivos locais, entradas de repositório 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 via extras opcionais.²⁴

Para projetos Python que querem incorporar o runtime do Claude Code como uma biblioteca — entre “executar claude via shell” e “REST API para Managed Agents” — o claude-agent-sdk-python é a terceira opção. A série de 28-29 de abril (v0.1.69 → v0.1.71) atualizou o CLI embutido para v2.1.123, elevou o piso da dependência mcp para >=1.19.0 (versões mais antigas descartavam silenciosamente os retornos de CallToolResult das ferramentas in-process do MCP, deixando o modelo com um blob de erro de validação) e trouxe SandboxNetworkConfig para paridade de schema com o SDK TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

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

A bifurcação arquitetural agora é real:

Quando escolher cada um: auto-hospedado continua sendo o caminho certo para equipes que já têm músculo de infraestrutura, querem skills/hooks que controlam, ou estão otimizando profundamente um workflow específico. Gerenciado é o caminho certo para equipes sem engenheiros de plataforma dedicados, quando o tempo até o valor importa mais do que personalização, ou quando as execuções de agents precisam sobreviver ao fechamento do laptop de forma confiável sem você construir essa camada de persistência. Os dois são compatíveis — você pode rodar um harness auto-hospedado que delega tarefas específicas de longa duração para Managed Agents via sua REST API.

Como o harness se parece em 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 nesta estrutura serve a um propósito. A árvore ~/.claude/ é a 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 você chamá-las explicitamente.⁴ O momento em que você percebe que está explicando de novo o mesmo contexto em sessões diferentes é o momento de criar uma skill.

Quando criar uma skill

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

Como criar uma skill

Skills ficam em quatro locais possíveis, 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 description é tudo

No início da sessão, Claude Code extrai o name e a description de cada skill e injeta essas informações no contexto de Claude. Quando você envia uma mensagem, Claude usa raciocínio de modelo de linguagem para decidir se alguma skill é relevante. Uma análise independente do código-fonte de Claude Code confirma o mecanismo: as descrições das skills são 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 (revisar código para tipos específicos de problemas), quando usá-la (examinar alterações, PRs, análise de qualidade) e frases-gatilho (review, audit, check) que os usuários digitam naturalmente.

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 fallback de 8.000 caracteres.⁴ Se você tem muitas skills, mantenha cada descrição concisa e coloque o principal caso de uso primeiro. Você pode sobrescrever o orçamento pela variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ mas a melhor correçã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

Referencie-os a partir do SKILL.md com links relativos. Claude lê esses arquivos sob demanda quando a skill é ativada. Mantenha SKILL.md com menos de 500 linhas e mova material de referência detalhado para arquivos de suporte.¹²

Compartilhando skills via Git

Skills de projeto (.claude/skills/ na raiz do repo) são compartilhadas via 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 colegas fazem pull, eles recebem a skill automaticamente. Sem instalação, sem configuração. Essa é a forma mais eficaz de padronizar conhecimento especializado 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 organizada de prompts:

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

Cada skill codifica uma faceta diferente da sua especialização. Juntas, elas formam uma base de conhecimento da qual Claude extrai automaticamente conforme o contexto. Um desenvolvedor júnior recebe orientação de nível sênior sem precisar pedir.

Skills se compõem com hooks

Skills podem definir seus próprios hooks no frontmatter, ativados apenas enquanto a skill é executada. Isso cria comportamento específico de domínio sem poluir 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 via hooks SessionStart, injetando restrições de qualidade em toda sessão sem invocação explícita. A skill em si é conhecimento. O hook é fiscalização. Juntos, eles formam uma camada de políticas.

Erros comuns com skills

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

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

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

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

Harnesses self-hosted em claude-agent-sdk-python v0.1.77+ devem usar a opção skills em ClaudeAgentOptions para declarar as skills disponíveis, não o valor legado "Skill" em allowed_tools.³⁷ O atalho "Skill" está obsoleto, e a opção dedicada fornece a Claude Code informações mais estruturadas sobre quais skills estão disponíveis. O CLI incluído na v0.1.77 é v2.1.133.

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

Skills sempre foram carregadas a partir do diretório .claude/skills/ de um projeto. Claude Code v2.1.157 estende esse diretório para plugins: um plugin colocado em .claude/skills/ agora é carregado automaticamente sem registro em marketplace, e claude plugin init <name> cria o scaffold de um novo plugin ali, com o manifesto e o SKILL.md já conectados.⁵⁸ Isso fecha a lacuna entre os dois formatos de tooling de projeto que antes ficavam em lugares diferentes: uma skill simples commitada direto no repo, versus um plugin que empacota uma skill mais hooks mais um servidor MCP, mas que antes precisava de um marketplace para instalação. O efeito prático para design de harness: tooling com escopo de projeto não precisa mais passar por um registro para ser entregue; escreva, faça commit, e os colegas recebem a mesma superfície com git pull. Plugins ainda são responsáveis pelo caso de uso de instalação empacotada (hooks + skills + servidores MCP + agents em um ZIP); a mudança é que um projeto não precisa mais manter um marketplace só para carregar um plugin da própria árvore.

Ocultar a superfície incluída como governança (8 de junho de 2026)

Skills são capacidade, e capacidade é superfície de ataque. Claude Code v2.1.169 adiciona uma configuração disableBundledSkills (e a variável de ambiente correspondente CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) que oculta totalmente do modelo as skills incluídas, os workflows e os slash commands integrados.⁶⁰ Para um harness hardened 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 que Anthropic entrega por padrão, para que o modelo raciocine apenas sobre a superfície validada pelo operador. Trate isso da mesma forma que você trata uma allowlist de ferramentas: o padrão é capacidade ampla, e desativar o padrão é uma decisão de governança, não um toggle de conveniência.

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

Claude Code v2.1.178 tornou o tooling de projeto ciente de localização. Skills em diretórios .claude/skills aninhados agora carregam quando você trabalha em arquivos dentro desse diretório, não apenas a partir da raiz do repo; quando há 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 de projeto resolver pelo diretório mais próximo do diretório de trabalho: quando um nome de agent, workflow ou output-style colide entre diretórios .claude/ aninhados, vence aquele mais próximo do diretório de trabalho, e um salvamento de workflow com escopo de projeto mira o .claude/workflows/ existente mais próximo, em vez de sempre usar a raiz.⁶³ Para um monorepo ou um repo de repos, essa é a diferença entre uma superfície global plana e tooling por pacote que ativa em contexto: um services/api/.claude/skills/ pode carregar skills específicas de API que aparecem apenas enquanto você trabalha naquela árvore, sem colidir com uma skill de mesmo nome em services/web/.

Arquitetura de hooks

Hooks são comandos shell acionados por eventos de ciclo de vida do Claude Code.³ Eles rodam 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 contra uma blocklist e o rejeita antes que o shell sequer o veja. O hook dispara quer o modelo queira ou não.

Eventos disponíveis

O Claude Code expõe 29 eventos de ciclo de vida documentados em oito categorias até esta atualização do guia. A lista de eventos cresce com os lançamentos, então trate a documentação de referência como a fonte da verdade e confira a folha de referência para ver a tabela completa atual antes de conectar hooks de produção:¹³

Semântica de códigos de saída

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

Crítico: Todo hook de segurança deve usar exit 2, não exit 1. Exit 1 é um aviso não bloqueante. O comando perigoso ainda é executado. Esse é o erro mais comum com hooks entre equipes.¹⁴

Configuração de hooks

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 ferramenta, ele corresponde a valores de tool_name como Bash, Edit, Write, Read, Glob, Grep, nomes de ferramentas MCP como mcp__server__tool, ou * para todas as ferramentas. 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 têm suporte a matchers e sempre disparam quando configurados.¹³

Protocolo de entrada/saída de hooks

Hooks recebem JSON em stdin com o contexto completo:

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

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

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

Três tipos de garantias

Antes de escrever qualquer hook, pergunte: 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 que elas sejam executadas. Hooks PreToolUse em Bash inspecionam comandos e bloqueiam padrões destrutivos com 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 suíte de testes e bloqueiam o commit se as verificações de qualidade falharem:

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

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

Tipos de hooks além de comandos shell

O Claude Code oferece suporte a cinco tipos de hooks:¹³

Command hooks (type: "command") executam scripts 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 quando a lógica de validação já fica atrás de uma fronteira MCP e não precisa de um script shell separado.

Prompt hooks (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 para avaliações com nuance que regex não consegue expressar.

Agent hooks (type: "agent") geram um subagent com acesso a ferramentas (Read, Grep, Glob) para verificação em múltiplos turnos. Eles são experimentais; prefira command hooks para gates de produção e reserve agent hooks para verificações que realmente exigem inspecionar arquivos reais ou 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 agent hook 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 adivinhar pelo texto do prompt.⁴⁹

HTTP hooks (type: "http") enviam a entrada JSON do evento como uma requisição POST para uma URL e recebem JSON de volta. Use para webhooks, serviços externos de notificação 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

Hooks podem rodar 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 terminar antes da próxima ação.

Dispatchers em vez de hooks independentes

Executar sete hooks que disparam no mesmo evento, cada um lendo stdin independentemente, cria condições de corrida. Dois hooks escrevendo simultaneamente no mesmo arquivo de estado JSON vão truncar o JSON. Todo hook downstream que faz parse desse arquivo quebra.²

A correção: um dispatcher por evento que executa hooks sequencialmente a partir de stdin 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

Debugging de hooks

Cinco técnicas para fazer debugging de hooks que falham silenciosamente:¹⁴

1. Teste scripts de forma independente. Faça pipe de um JSON de exemplo: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Use stderr para saída de debug. Stderr com código de saída 2 é enviado de volta ao Claude como mensagem de erro. Stderr não bloqueante (exit 1, 3, etc.) aparece apenas no modo detalhado (Ctrl+O).
3. Fique atento a falhas do jq. Caminhos JSON incorretos retornam null silenciosamente. Teste expressões jq contra entradas reais de ferramenta.
4. Verifique códigos de saída. Um hook PreToolUse que usa exit 1 oferece zero enforcement mesmo parecendo funcionar.
5. Mantenha hooks rápidos. Hooks rodam de forma síncrona. Mantenha todos os hooks abaixo de 2 segundos, idealmente abaixo de 500 ms.

Streaming de eventos de hook do lado do SDK

Harnesses self-hosted criados com claude-agent-sdk-python (v0.1.74+, 6 de maio de 2026) podem assinar eventos de hook diretamente do stream de mensagens, em vez de passar por callbacks de scripts shell.³⁶ Defina include_hook_events=True em ClaudeAgentOptions e objetos HookEventMessage (PreToolUse, PostToolUse, Stop e outros) saem do mesmo iterator que mensagens do assistente e resultados de ferramentas. Isso espelha a opção includeHookEvents do TypeScript SDK; o CLI incluído foi atualizado para v2.1.129 no mesmo release.

O padrão de event-stream é o encaixe certo quando seu harness já vive em Python e você quer sinais de hooks no mesmo fluxo de controle da saída do modelo. O contrato de hook por script shell (códigos de saída, stdin JSON, dispatchers) continua sendo a resposta certa para harnesses que compõem múltiplas ferramentas, compartilham hooks entre Claude Code e Codex, ou precisam de semântica de código de saída para bloqueio.

Esforço e proveniência de 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 um sinal melhor sobre seu contexto de execução:³⁸³⁹

• effort.level na entrada do hook. Hooks agora recebem um campo JSON effort.level na mesma entrada que carrega tool_input e session_id. O mesmo valor é exportado como a variável de ambiente $CLAUDE_EFFORT, então comandos Bash podem lê-lo sem fazer parse de JSON. Use isso para dimensionar o custo do hook conforme o nível de esforço: pule validação cara 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 da ferramenta Bash agora veem o mesmo valor 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 subprocesso com eventos de hook.

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

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

O Claude Code v2.1.136 adicionou uma nova camada hard-deny ao auto mode e corrigiu um conjunto de problemas de plugin e MCP que afetavam harnesses de longa duração:⁴⁰

• settings.autoMode.hard_deny. Regras do classificador de auto mode que bloqueiam incondicionalmente, independentemente da intenção do usuário ou de exceções allow. Isso fica acima dos matchers allow/deny existentes como uma alavanca de governança inegociável. Use para regras que nunca devem ser sobrescritas (force-push para main, arquivos com segredos, acesso a banco de dados de produção), mesmo quando um operador aprovou a categoria mais ampla em suas configurações pessoais.
• Servidores MCP não desaparecem mais depois de /clear. Servidores configurados em .mcp.json, plugins e connectors do claude.ai estavam saindo silenciosamente do conjunto ativo depois de 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 OAuth do MCP em refresh concorrente. Usuários com vários servidores MCP remotos não devem mais precisar de reautenticação diária. Escritas de refresh concorrentes estavam sobrescrevendo umas às outras.
• Plan mode agora bloqueia gravações de arquivos corretamente. Uma regra allow correspondente a Edit(...) estava contornando a proteção contra escrita do plan mode. Agora o plan mode é aplicado independentemente de regras allow.
• Hooks Stop e UserPromptSubmit de plugin não falham mais no meio da sessão. A limpeza de cache estava apagando arquivos de versão de plugin ainda em uso pela sessão em execução, quebrando especificamente esses dois eventos de hook. A correção mantém versões em uso fixadas.
• Entrada skills em plugin.json. Definir skills estava ocultando a pasta padrão skills/ do plugin. Agora a entrada compõe corretamente, e apontá-la para um caminho de arquivo gera um erro explícito em vez de falhar silenciosamente.
• Variáveis de ambiente de hook SessionStart em CLAUDE_ENV_FILE ficando obsoletas. Vars exportadas por hooks SessionStart via CLAUDE_ENV_FILE ficavam obsoletas depois de /resume ou /clear. Corrigido na v2.1.136. Sessões agora recarregam o arquivo env nesses eventos.

Para harnesses de governança, os itens operacionalmente interessantes são autoMode.hard_deny (nova alavanca) e a correção do desaparecimento de MCP (falha silenciosa que quebrava sessões longas). Todo o resto é melhoria 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 exec args: string[] para command hooks e continueOnBlock para hooks PostToolUse.⁴²⁴⁴ Prefira args quando um hook precisa de valores dinâmicos ou placeholders de caminho. Ele inicia o comando diretamente sem shell, o que remove uma classe inteira de erros de aspas e injeção.

Use continueOnBlock quando um hook PostToolUse deve enviar seu motivo de 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 um bypass de segurança. Um gate bloqueante ainda deve bloquear o resultado inseguro.

O mesmo release passa CLAUDE_PROJECT_DIR para servidores stdio MCP e permite que configs de plugin referenciem ${CLAUDE_PROJECT_DIR} em comandos.⁴² Ferramentas MCP devem resolver caminhos relativos ao projeto a partir desse valor, não a partir do diretório de trabalho do processo que por acaso iniciou o servidor.

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

O Claude Code v2.1.141 adiciona um campo terminalSequence na saída de hook para notificações de desktop, títulos de janela e sons sem um terminal controlador.⁵⁰ Trate isso como sinalização ao operador, não enforcement. Gates de segurança e qualidade ainda devem comunicar falhas pelo contrato normal de bloqueio: saída estruturada de hook mais o comportamento de saída que impede a ação insegura. O mesmo release adiciona claude agents --cwd <path> para limitar o Agent View a um diretório, CLAUDE_CODE_PLUGIN_PREFER_HTTPS para instalações de plugin em ambientes sem chaves GitHub SSH, e ANTHROPIC_WORKSPACE_ID para regras de federação de identidade de workload que cobrem mais de um workspace.⁵⁰ Esses são detalhes de arquitetura para harnesses de equipe: visões operacionais mais estreitas, menos suposições de instalação de plugin e escopo explícito de token empresarial.

O Claude Code v2.1.142 é mais importante para orquestração de sessões em segundo plano do que para 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. Fast mode agora usa Opus 4.7 por padrão; fixe CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 apenas se um harness tiver dependência medida do comportamento do Opus 4.6. A descoberta de SKILL.md de plugin no nível raiz e a visibilidade de LSP fornecida por plugin reduzem ambiguidade de empacotamento. Correções em MCP_TOOL_TIMEOUT, worktrees preexistentes de sessões em segundo plano, sleep/wake de daemon e limpeza pós-upgrade, além de limpeza de cache de plugin, fecham lacunas de confiabilidade que, de outro modo, parecem bugs de orquestração.

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

Quatro mudanças do início de junho importam para o design de harness 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 entregar 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 Stop hook era o bloqueio exit-2, que é lido como erro e conta para o limite de bloqueios consecutivos. Para um harness com quality gate, esse é o primitivo mais limpo: um Stop hook que detecta “você disse que terminou, mas os testes estão vermelhos” agora pode injetar “isto ainda está falhando, continue” em vez de hard-block. Use o bloqueio para condições reais de parada e additionalContext para “ainda não terminou, aqui está o motivo.”

Mensagens entre sessões não carregam mais autoridade emprestada. A v2.1.166 endureceu o caso multi-session: mensagens retransmitidas via SendMessage de outra sessão Claude não carregam mais a autoridade do usuário de origem, então uma sessão receptora recusa solicitações de permissão retransmitidas e o auto mode as bloqueia. Se sua orquestração faz agents enviarem mensagens entre si, trate uma mensagem recebida como dados não confiáveis, não como uma instrução autenticada. Esse é o mesmo princípio que a seção de segurança aplica à saída de ferramentas, estendido para mensagens entre agentes.

Resiliência de modelo virou 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 faz retry automático uma vez no fallback para erros API inesperados e não repetíveis. Para um harness autônomo de longa duração, isso transforma uma indisponibilidade transitória do modelo primário em degradação graciosa, em vez de uma execução perdida. 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 esteja fazendo polling de uma frota de agentes.

Safe mode para governança em clean room e troubleshooting. 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 toda personalização desativada de uma vez: CLAUDE.md, plugins, skills, hooks e servidores MCP.⁶⁰ Isso é o inverso do harness — uma clean room deliberada. Use para responder à pergunta que todo operador acaba fazendo: “esse comportamento vem do modelo ou de algo que eu configurei?” Quando um hook dispara errado, uma skill ativa quando não deveria, ou um servidor MCP contamina o contexto, --safe-mode dá uma linha de base sabidamente vazia para comparar. Também é um primitivo de governança: uma forma de executar o modelo puro sem nenhuma autoridade persistente que seu harness normalmente concede, o que importa quando você precisa reproduzir um resultado sem qualquer scaffolding definido pelo operador influenciando-o.

Uma observação sobre tiers de modelo. Este guia trata o Opus 4.8 como o padrão agentic do Claude Code — o modelo que executa harnesses autônomos, a menos que você selecione outro. Em 9 de junho de 2026, a Anthropic lançou o Claude Fable 5 (claude-fable-5), um novo tier acima do Opus descrito como seu modelo mais poderoso — um sistema “Mythos-class” tornado seguro para uso geral — selecionável no Claude Code v2.1.170 via /model claude-fable-5.⁶⁰ O Opus 4.8 continua sendo o padrão agentic; use o tier superior deliberadamente, nas decisões em que a profundidade bruta de raciocínio justifica o custo, não como uma configuração genérica para uma frota.

Codex lançou multi-agent v2. O Codex CLI v0.137.0 mantém a escolha de runtime em cada thread, expõe padrões mais limpos de follow-up e metadata para agents gerados (hide_spawn_agent_metadata agora é true por padrão) e propaga eventos brutos do parent para listeners child. Seu modelo de subagent continua explícito: tipos de agent built-in default/worker/explorer, agents customizados definidos em TOML e controles de concorrência (agents.max_threads padrão 6, agents.max_depth padrão 1). O mesmo release adiciona uma extensão de skills v1 com resolução de catálogo de skills por turno e novos eventos contribuintes de ciclo de vida thread-start/turn-error, reduzindo a distância em relação à superfície de hooks/skills do Claude Code, enquanto mantém a postura de kernel-sandbox como a fronteira padrão. Em seguida, o Codex v0.138.0–v0.139.0 endureceu o multi-agent v2 para produção: payloads de mensagens entre agents agora são criptografados, um catálogo de configs de agent v2 mais um LRU de residência de agents gerenciam quais agents ficam residentes, e a concorrência é contabilizada por execução ativa, não por threads geradas, então agents ociosos não consomem mais um slot.⁶¹ O ciclo de vida API também amadureceu — close_agent foi renomeado para interrupt_agent (v0.139.0) para refletir que ele interrompe um agent em execução, em vez de apenas fechar um handle — e avisos de inicialização MCP gerados por um subagent agora ficam restritos à thread proprietária, em vez de duplicarem no transcript do parent.⁶¹ Para qualquer pessoa criando orquestração do lado do Codex, essa é a diferença entre uma demo e uma frota: transporte de mensagens criptografado, residência limitada, concorrência contada por execução e avisos que não vazam pela fronteira de thread. O Codex v0.140.0 então abriu uma junção entre ferramentas: /import puxa seletivamente setup, config de projeto e chats recentes do Claude Code para o Codex, e sessões passaram a ser deletáveis permanentemente (codex delete / /delete, com salvaguardas de confirmação).⁶⁴ /import é o primeiro reconhecimento oficial de que operadores se movem entre harnesses — a configuração que você cria para um não fica mais presa nele.

Memória e contexto

Toda conversa com AI opera dentro de uma janela de contexto finita. Conforme a conversa cresce, o sistema comprime turnos anteriores para abrir espaço para novo conteúdo. A compressão tem 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 vive no filesystem. Claude Code lê CLAUDE.md e arquivos de memória no início de cada sessão e depois de cada compactação.⁶

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

O arquivo MEMORY.md captura erros, decisões e padrões entre sessões. Quando você descobre que ((VAR++)) falha com set -e no bash quando VAR é 0, registre isso. Três sessões depois, quando você encontra um caso de borda inteiro parecido em Python, a entrada no MEMORY.md revela o padrão.¹⁵

Auto Memory (v2.1.32+): Claude Code registra e recupera automaticamente o contexto do projeto. Enquanto você trabalha, Claude escreve observações em ~/.claude/projects/{project-path}/memory/MEMORY.md. A auto memory carrega as primeiras 200 linhas no seu system prompt no início da sessão. Mantenha o conteúdo conciso e use links para arquivos de tópicos separados quando precisar de notas detalhadas.⁶

Curadoria de memória em vez de volume de memória (maio de 2026): Um preprint recente do arXiv sobre cooperação entre agents LLM enquadra a expansão da recuperação como um possível modo de falha: nos experimentos dos autores, um histórico visível mais longo prejudicou a cooperação em 18 de 28 configurações de modelo-jogo.⁴⁸ Trate isso como um alerta de design, não como uma lei definitiva. A regra de produção já é clara o bastante: mantenha MEMORY.md curto, faça links para os detalhes e coloque resumos prontos para decisão nos handoffs. Dumps brutos de transcript, logs de ferramentas e feeds longos de recuperação pertencem ao armazenamento pesquisável, não automaticamente ao prompt ativo.

Estratégia 2: compactação proativa

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

Quando compactar: - Depois de concluir uma subtarefa distinta (funcionalidade implementada, bug corrigido) - Antes de começar uma nova área do codebase - Quando Claude começar a repetir ou esquecer 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 no meio do fluxo sem quebrar o cache acumulado ao longo do turno.⁶⁰ Antes disso, trocar de diretório significava uma sessão nova e um cache frio. Para uma sessão longa que muda de um repositório para outro irmão — comum em trabalhos com monorepo e múltiplos serviços — /cd mantém intacto o prefixo caro em cache enquanto redireciona o contexto do filesystem.

Estratégia 3: handoffs de sessão

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

## 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 contexto completo com custo mínimo de tokens. Começar uma nova sessão com claude -c (continue) ou lendo o documento de handoff leva direto à implementação.¹⁵

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

Para sessões que passam de 60-90 minutos, gere 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: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

Compare com uma única sessão longa:

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

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

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

Os Managed Agents de Claude da Anthropic adicionaram Dreaming como Research Preview em 6 de maio de 2026.³⁵ Segundo a Anthropic: “Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.”³⁵

Dreaming roda 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 de sustentação; Dreaming escreve entradas de memória curadas no armazenamento de memória dos Managed Agents, que o agent lê no início da sessão. Os dois padrões coexistem para harnesses que misturam estado em filesystem self-hosted com curadoria no lado gerenciado.

Dreaming está em Research Preview, então o comportamento pode mudar. Os padrões de session-handoffs e CLAUDE.md documentados acima continuam sendo o mecanismo de memória autoritativo para harnesses self-hosted.

Os antipadrões

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

Manter saída de erro verbosa no contexto. Depois de depurar um bug, seu contexto contém mais de 40 stack traces de iterações com falha. Um único /compact depois de corrigir o bug libera esse peso morto.

Começar toda sessão lendo todos os arquivos. Deixe as ferramentas glob e grep do Claude Code encontrarem 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 lidam com tarefas complexas de forma independente. Eles começam com um contexto limpo (sem poluição da conversa principal), operam com ferramentas especificadas e retornam resultados como resumos. Os resultados da exploração não incham sua conversa principal; apenas as conclusões retornam.⁵

Tipos de subagent integrados

Como criar 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 subagent

Isolamento com worktree

Subagents podem operar em git worktrees temporárias, fornecendo 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 com worktree é essencial para trabalho experimental que pode quebrar a codebase.

Subagents paralelos

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

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

Cada agent roda na própria janela de contexto, encontra código relevante e retorna um resumo. O contexto principal permanece limpo.

O recursion guard

Sem limites de spawn, agents delegam para agents que delegam para agents, cada um perdendo contexto e consumindo tokens. O padrão recursion guard impõe orçamentos:¹⁶

#!/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 crítica: Use orçamentos de spawn, não apenas limites de profundidade. Limites baseados em profundidade rastreiam cadeias pai-filho (bloqueadas na profundidade 3), mas deixam passar largura: 23 agents na profundidade 1 ainda é “profundidade 1”. Um orçamento de spawn rastreia o total de filhos ativos por pai, limitado a um máximo configurável. O modelo de orçamento mapeia para o modo de falha real (agents demais no total), em vez de uma métrica indireta (níveis de aninhamento demais).⁷

Delegação recursiva agora é uma profundidade de primeira classe. A partir do Claude Code v2.1.172 (10 de junho de 2026), sub-agents podem iniciar seus próprios sub-agents, aninhando até 5 níveis de profundidade — antes, a delegação era efetivamente limitada a um nível.⁶² Isso torna o recursion guard acima mais importante, não menos: a plataforma agora permite exatamente as cadeias de agents-delegando-para-agents que queimam contexto e tokens, então o orçamento de spawn e o limite de profundidade são o que impede uma árvore de 5 níveis de se expandir para centenas de agents ativos. Trate 5 níveis como um teto permitido pela plataforma, não como um padrão a perseguir.

O modo auto agora avalia spawns antes que eles sejam iniciados. O Claude Code v2.1.178 fechou a lacuna equivalente de governança: no modo auto, spawns de subagent são avaliados pelo classificador de permissão antes de o subagent iniciar, não apenas depois que ele começa a executar ações.⁶³ Antes, um subagent podia ser iniciado para solicitar uma ação que a sessão pai teria sido impedida de executar — o próprio spawn era o bypass. A avaliação no momento do spawn significa que o recursion guard e o modelo de permissões finalmente se encontram: um filho não pode ser usado como etapa de lavagem para uma ação proibida pela policy.

Agent Teams (Research Preview)

Agent Teams coordenam várias instâncias de Claude Code que trabalham de forma independente, comunicam-se por uma caixa de entrada 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 vs subagents:

Agent View e goal loops (maio de 2026)

Claude Code v2.1.139 adicionou Agent View, uma interface em research-preview iniciada com claude agents que mostra sessões de Claude Code em execução, bloqueadas e concluídas em uma única tela.⁴²⁴³ A documentação oficial a apresenta como uma forma de despachar e gerenciar muitas sessões, ver o que cada sessão está fazendo e identificar quais precisam de intervenção do operador.⁴³ Isso dá ao trabalho multi-agent uma visão operacional que resumos finais não conseguem fornecer.

Use Agent View ao promover um padrão de subagent ou equipe: inspecione 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 trate isso como prova de qualidade. É observabilidade; testes, review gates e relatórios de evidência ainda decidem se o trabalho é sólido.

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

Workflow Tool (v2.1.147+)

Claude Code v2.1.147 adiciona uma ferramenta Workflow, desativada por padrão, para orquestração multi-agent determinística. Ative com CLAUDE_CODE_WORKFLOWS=1.⁵² Arquiteturalmente, isso é importante porque dá ao Claude Code um primitivo de orquestração de primeira classe para fluxos que antes exigiam scripts de dispatch personalizados, estado de mailbox e convenções de coordenação de subagents.

Não exclua o harness ao redor dela. Um Workflow pode estruturar a execução, mas não substitui seu modelo de segurança. Mantenha hooks PreToolUse e PostToolUse como camada de bloqueio, mantenha orçamentos de spawn ou orçamentos de etapas de workflow para evitar crescimento descontrolado em largura, mantenha o estado do filesystem auditável e mantenha relatórios finais de evidência fora da autoavaliação do modelo. Na prática: use Workflow para a forma da orquestração; use hooks, testes e review gates para a verdade.

Orquestração Multiagente

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

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

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

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

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

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

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

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

Deliberação Mínima Viável

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

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

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

O Gatilho de Confiança

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

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

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

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

A Máquina de Estados

Sete fases, cada uma controlada pela anterior:⁷

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

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

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

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

A Arquitetura de Validação de Duas Portas

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

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

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

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

Por Que a Concordância É Perigosa

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

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

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

Detectando Concordância Falsa

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

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

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

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

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

O Que Não Funcionou na Deliberação

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

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

Custo da Deliberação

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

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

Quando Deliberar

Design do CLAUDE.md

CLAUDE.md é uma política operacional para um AI agent, não um README para humanos.²¹ O agent não precisa entender por que você usa conventional commits. Ele precisa saber o comando exato para executar e como “done” se parece.

A hierarquia de precedência

Arquivos de regras carregam automaticamente e fornecem contexto estruturado sem poluir o CLAUDE.md.⁶

O que é ignorado

Estes padrões não produzem nenhuma mudança observável no comportamento do agent de forma confiável:²¹

Parágrafos em prosa sem comandos. “Valorizamos código limpo e bem testado” é documentação, não operação. O agent lê isso e segue escrevendo código sem testes porque não há uma instrução acionável.

Diretivas 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 cobertura de testes abrangente”, “Mantenha o runtime abaixo de 5 minutos” e “Execute testes de integração completos antes de cada commit.” O agent não consegue satisfazer as quatro ao mesmo tempo e, por padrão, acaba pulando a verificação.²¹

Guias de estilo sem enforcement. “Siga o Google Python Style Guide” sem ruff check --select D não dá ao agent nenhum mecanismo para verificar conformidade.

O que funciona

Instruções começando 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 estiver começando do zero, adicione seções nesta ordem de prioridade:²¹

1. Comandos de build e teste (o agent precisa disso antes de conseguir fazer qualquer coisa útil)
2. Definição de done (evita conclusões falsas)
3. Regras de escalonamento (evita workarounds destrutivos)
4. Seções organizadas por tarefa (reduz o processamento de instruções irrelevantes)
5. Escopo por diretório (monorepos: mantém instruções de serviço isoladas)

Deixe preferências de estilo de lado até que os quatro primeiros itens estejam funcionando.

Imports de arquivos

Referencie outros arquivos dentro do 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 import: relativa (@docs/file.md), absoluta (@/absolute/path.md) ou diretório home (@~/.claude/file.md). Profundidade máxima: 5 níveis de imports.⁶

Compatibilidade de instruções entre ferramentas

AGENTS.md é um padrão aberto reconhecido por todas as principais ferramentas de AI coding.²¹ Se sua equipe usa várias ferramentas, escreva o AGENTS.md como a fonte canônica e espelhe as seções relevantes em arquivos específicos de cada ferramenta:

Os padrões em AGENTS.md (começar pelo comando, definir conclusão, organizar por tarefa) funcionam em qualquer arquivo de instruções, independentemente da ferramenta. Não mantenha conjuntos de instruções paralelos que se desviam com o tempo. Escreva uma fonte autoritativa e espelhe.

Notas de paridade do Codex

Codex agora tem equivalentes de primeira classe para as principais camadas de harness, mas a migração é uma tradução de padrões, não uma cópia de arquivos. Codex lê AGENTS.md antes do trabalho começar, combinando orientações globais de ~/.codex com instruções do projeto e de repositórios aninhados.³¹ Codex skills usam o mesmo modelo mental de SKILL.md com progressive disclosure: Codex começa com o nome, a descrição e o caminho do arquivo da skill, depois carrega a skill completa somente quando decide usá-la.³² Codex também tem hooks nativos, hooks empacotados em plugins, hooks gerenciados, suporte a MCP e workflows explícitos de subagent.³³³⁴

Codex v0.138.0–v0.139.0 reforçou essa descoberta de AGENTS.md para workspaces não triviais: o carregamento agora passa pela abstração de filesystem do ambiente e preserva caminhos lógicos durante a caminhada de descoberta, então o arquivo certo é selecionado mesmo quando o workspace é um filesystem remoto ou uma árvore com symlinks.⁶¹ Isso importa sempre que seu AGENTS.md canônico é a fonte autoritativa e o agent está operando sobre um checkout montado, materializado em container ou com symlinks — os casos em que uma caminhada ingênua por caminhos escolhe silenciosamente o arquivo de instruções errado ou nenhum arquivo. Se você espelha um AGENTS.md autoritativo entre serviços, trate isso como o mínimo para confiar que o arquivo que o agent realmente carregou é o que você escreveu.

Codex v0.141.0 então reforçou o próprio caminho de execução remota: executores remotos agora se conectam por canais Noise-relay autenticados e criptografados de ponta a ponta (o plano de controle e o executor não confiam mais no relay entre eles), a execução remota cross-platform preserva o diretório de trabalho e o shell nativos do executor, e o TLS aceita assinaturas de certificado P-521 para proxies empresariais.⁶⁵ Se sua orquestração aciona executores Codex através de uma fronteira de rede, essa é a diferença entre uma premissa de relay confiável e uma de criptografia de ponta a ponta — trate isso como a baseline para qualquer topologia de executor remoto.

O mapeamento prático:

A diferença importante: subagents do Claude podem ser selecionados automaticamente a partir de descrições, enquanto o Codex atualmente documenta workflows de subagent como explícitos. Isso torna skills e hooks o padrão certo para comportamento de harness sempre ativo no Codex; subagents são para trabalho paralelo deliberado, revisão e exploração.

Testando suas instruções

Verifique se o agent 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 agent para explicar seus comandos de build. Se ele não conseguir reproduzi-los literalmente, as instruções são verbosas demais (conteúdo empurrado para fora do contexto), vagas demais (o agent não consegue extrair instruções acionáveis) ou não estão sendo descobertas. A análise da GitHub com 2.500 repositórios descobriu que a imprecisão 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 capacidades específicas que mudam aquilo contra o qual um harness precisa se defender:²⁹

• Resiliência a falhas de ferramentas: Opus 4.7 continua avançando mesmo após falhas de ferramentas que interrompiam sessões do Opus 4.6. Você pode reduzir, mas não eliminar, os wrappers defensivos de retry no código de subagent. Mantenha as proteções no nível de hook; reduza o scaffolding no prompt do tipo “se a ferramenta falhar, tente novamente três vezes”.
• Faixa de esforço xhigh (somente Opus-4.7): Fica entre high e max. É o padrão recomendado para workloads de coding e agentes. 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 single-shot; xhigh é melhor para tarefas sustentadas.
• Teto de orçamento de tokens: Configurável por execução de agente via output_config.task_budget (beta header task-budgets-2026-03-13). O modelo vê uma contagem regressiva em andamento e ajusta o escopo do trabalho ao orçamento, em vez de ficar sem tokens inesperadamente. Use em loops agentes quando você quer gasto previsível de tokens sem sacrificar a qualidade em prompts curtos.
• Consciência de necessidade implícita: Primeiro modelo Claude a passar nos testes de “necessidade implícita”, reconhecendo quando o pedido literal do usuário especifica menos do 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 guardrails do tipo “considere também X quando o usuário pedir Y”, remova as que agora já são cobertas nativamente.

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

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

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

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

Claude Code v2.1.136 adicionou CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL para reativar a pesquisa de qualidade dentro da sessão em empresas que capturam as respostas via OpenTelemetry.⁴⁰ Se sua organização envia eventos OTel para uma stack central de observabilidade, essa env var recoloca a pesquisa no caminho dos dados, para que o sinal de qualidade flua pelo mesmo pipeline das métricas de latência e erro. Trate isso como opt-in: o padrão mantém a pesquisa suprimida, o que está correto para implantações sem OTel.

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 typos, erros de lógica e seções pouco claras
3. Avaliar - Execute o evidence gate. Verifique padrões, edge cases e cobertura de testes
4. Refinar - Corrija todos os problemas. Nunca empurre para “depois”
5. Dar zoom out - 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 para a etapa 4
7. Reportar - Liste o que mudou, como foi verificado e cite evidências específicas

O Evidence Gate

“Eu acredito” e “deveria” não são evidência. Cite caminhos de arquivos, saída de testes ou código específico.

Se você não conseguir produzir evidência para qualquer linha, volte para Refinar.²²

Autoridade humana de merge

Um estudo arXiv de maio de 2026 com 29.585 ciclos de vida de pull requests de agentes de IA separa agência operacional de governança de merge.⁴⁷ A lição útil de arquitetura é simples: agentes podem iniciar o trabalho, levar branches adiante, abrir PRs, revisar trabalho e resumir riscos, enquanto a autoridade de merge permanece como uma fronteira de governança separada.

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

Padrões de tratamento de erros

Escritas 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 SO 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 travar:¹⁶

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

Classificação do raio de impacto

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

Remote Control (conectar ao Claude Code local a partir de qualquer navegador ou app mobile) 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 ponteiros 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/falha de testes, saída de linter, códigos de status HTTP, verificações de existência de arquivo. Uma tarefa inicial que pediu ao agente para “escrever testes que passam” produziu assert True e assert 1 == 1. Tecnicamente correto. Na prática, sem valor.¹⁶

Modos de falha para monitorar

Um trace concreto de sessão

Um trace de sessão de uma execução autônoma processando um PRD com 5 stories:²

1. SessionStart dispara. Dispatcher injeta: data atual, detecção de projeto, restrições de filosofia, inicialização de rastreamento de custo. Cinco hooks, 180 ms no total.

2. O agente lê o PRD e planeja a primeira story. UserPromptSubmit dispara. Dispatcher injeta: contexto ativo do projeto, baseline de drift da sessão.

3. O agente chama Bash para executar testes. PreToolUse:Bash dispara. Verificação de credenciais, validação de sandbox, detecção de projeto. 90 ms. Testes executam. PostToolUse:Bash dispara: heartbeat de atividade registrado, verificação de drift.

4. O agente chama Write para criar um arquivo. PreToolUse:Write dispara: verificação de escopo de arquivo. PostToolUse:Write dispara: verificação de lint, rastreamento de commit.

5. O agente finaliza a story. Stop dispara. Quality gate verifica: o agente citou evidências? Linguagem evasiva? Comentários TODO no diff? Se qualquer verificação falhar, sai com 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 code review são iniciados em paralelo. Cada um revisa o diff de forma independente. Se qualquer reviewer sinalizar CRITICAL, a story volta para a fila.

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

Total de hooks disparados 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 durante a noite.

Estudo de caso: processamento noturno de PRD

Um harness de produção processou 12 PRDs (47 stories) ao longo de 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 rotacionar chaves API e auditar serviços downstream: cerca de 4 horas de resposta a incidente. O overhead do harness que evitou o equivalente foi de 2,4 segundos de bash por story. A taxa de falsa conclusão caiu de 35% para 4% porque o Stop hook executou testes de forma independente antes de permitir que o agente reportasse a tarefa como concluída.

Considerações de segurança

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

Anthropic publicou um framework formal para confiabilidade de agentes em 9 de abril de 2026.²⁷ Os cinco princípios acompanham — e ampliam — o pensamento de Evidence Gate neste guia:

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

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 entrega vereditos com evidências a partir de detecção Sigma/YARA/Nova/Snort. Primeiro produto na categoria de sandbox para skills.²⁸

O Sandbox

Claude Code oferece suporte a um modo sandbox opcional (ativado via settings.json ou pelo comando /sandbox) que restringe o acesso à rede e operações no 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 em que 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 de análise de permissão em regras de permissão e variáveis obsoletas no PowerShell, além de um bug de allowlist de escrita no sandbox de git-worktree que cobria toda a raiz do repositório principal em vez de apenas os componentes internos compartilhados do git.⁵³ Se o seu harness permite PowerShell ou agentes isolados por worktree, trate v2.1.149+ como o piso e mantenha as regras de shell restritas. Exceções amplas como PowerShell(*) e permissões de escrita para todo o repositório são atalhos de orquestração, não limites de segurança.

Bloqueio de sandbox do OpenAI Agents SDK (v0.17.0, 8 de maio de 2026). No lado da OpenAI, openai-agents-python v0.17.0 apertou uma fronteira paralela: LocalFile.src e LocalDir.src agora ficam restritos ao base_dir de materialização (o diretório de trabalho atual do processo SDK quando o manifesto é aplicado), a menos que a origem seja concedida explicitamente via 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 fronteira de artefato local: versões anteriores permitiam que manifestos puxassem caminhos arbitrários do host para um workspace em 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 de aplicação confiável; nunca preencha concessões a partir de saída do modelo ou entrada de manifesto não confiável.

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

Limites de permissão

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

Regras de permissão em nível de parâmetro (junho de 2026)

Claude Code v2.1.178 estendeu regras de permissão do nível da ferramenta para o nível do parâmetro: Tool(param:value) compara com os parâmetros de entrada de uma ferramenta, com * como wildcard. O exemplo canônico é Agent(model:opus) — uma regra que bloqueia a criação de subagents 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 conseguia restringir como ela era chamada. Uma política de governança agora pode dizer “subagents podem ser criados, 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 em nível de 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 compõem — a allowlist define quais camadas existem para a sessão, e as regras em nível de parâmetro restringem como subagents as utilizam.

Guardrails de comando destrutivo no Auto Mode (junho de 2026)

Claude Code v2.1.183 reduziu o raio de impacto do auto mode para operações que perdem trabalho silenciosamente ou desmontam ambientes. O auto mode agora bloqueia de forma rígida, a menos que você tenha pedido explicitamente na sessão: operações git destrutivas (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 desmontagem de infraestrutura (terraform destroy, pulumi destroy, cdk destroy), a menos que você tenha nomeado a stack específica.⁶⁵ Arquiteturalmente, isso complementa a validação de spawn e as regras em nível de parâmetro acima: em vez de controlar qual ferramenta ou como ela é criada, controla um conjunto pequeno de comandos irreversíveis específicos por intenção — o agente ainda pode executá-los, mas apenas com 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: comandos que destroem estado merecem uma regra de negação por padrão que só um sinal explícito do operador remove.

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 ganhe 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 impacto. Um subagent com permissionMode: plan não consegue fazer alterações mesmo se seu prompt for comprometido.

Logs de agente e guardrails são superfícies de segurança

Dois avisos de maio de 2026 reforçam um padrão: infraestrutura de agentes cria novos lugares onde conteúdo sensível e políticas executáveis podem vazar ou escapar. O Advisory GHSA-f3jg-756w-gm35 do GitHub cobre um problema de filtro de payload no Gryph Agents em que conteúdo sensível de payload de ferramenta podia permanecer em logs SQLite locais sob o comportamento padrão de logging.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p cobre uma fuga de sandbox em guardrail de código personalizado do LiteLLM em um endpoint de proxy protegido por admin.⁴⁶

A regra de produção: trate transcrições de agente, payloads de ferramentas, logs SQLite e execução de guardrail como infraestrutura sensível. Redija antes de persistir, aplique limites de retenção e mantenha código personalizado de guardrail em sandbox e passível de revisão. Uma regra em nível de prompt como “não registre segredos” não basta; o caminho de logging e guardrail precisa de testes determinísticos.

Segurança de hooks

Hooks HTTP que interpolam variáveis de ambiente em headers exigem uma lista explícita allowedEnvVars para impedir a exfiltração arbitrária de variáveis de ambiente:¹³

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

A divisão de responsabilidade entre humano e agente

Segurança em arquiteturas de agentes exige uma divisão clara entre responsabilidades humanas e do agente:¹⁷

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

Aplicação recursiva de hooks

Hooks disparam também para ações de subagent.¹³ Se Claude cria um subagent via Agent tool, seus hooks PreToolUse e PostToolUse executam para cada ferramenta que o subagent usa. Sem aplicação recursiva de hooks, um subagent poderia contornar seus gates de segurança. O evento SubagentStop permite executar limpeza ou validação quando um subagent termina.

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

Custo como arquitetura

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

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

Nível de agente. Novos spawns em vez de conversas longas. Cada story em uma execução autônoma recebe um novo agente com contexto limpo. O contexto nunca infla 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 primeiro em vez de MCP quando a operação é sem estado. Uma chamada claude --print para uma avaliação única 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

FAQ

Quantos hooks são hooks demais?

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

Hooks podem impedir o Claude Code de executar um comando?

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

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

As configurações de hooks ficam em .claude/settings.json para hooks em nível de projeto (commitadas no seu repositório, compartilhadas com sua equipe) ou em ~/.claude/settings.json para hooks em nível de usuário (pessoais, aplicadas a todos os projetos). Hooks em nível de projeto têm precedência quando ambos existem. Use caminhos absolutos para arquivos de script para evitar problemas com o 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, dependência de contexto). Apenas decisões com pontuação abaixo de 0,70 de confiança geral acionam deliberação, cerca de 10% do total de decisões. Correções de documentação, renomeações de variáveis e edições rotineiras pulam totalmente a deliberação. Arquitetura de segurança, alterações de schema de banco de dados e deploys irreversíveis a acionam de forma consistente.⁷

Como testar um sistema criado para produzir discordância?

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

Qual é o impacto de latência da deliberação?

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

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

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

Isso pode funcionar com ferramentas diferentes do Claude Code?

Os princípios arquiteturais (hooks como portões determinísticos, skills como conhecimento de domínio, subagents como contextos isolados, filesystem 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 Agent tool do Claude Code. AGENTS.md leva os mesmos padrões para Codex, Cursor, Copilot, Amp e Windsurf.²¹ O padrão de harness é agnóstico de ferramenta, mesmo que os detalhes de implementação sejam específicos da ferramenta.

Cartão de referência rápida

Configuração de hooks

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

Frontmatter de skill

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

Definição de subagent

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

Instructions for the subagent.

Exit codes

Comandos principais

Locais dos arquivos

Registro de alterações

Referências