Arquitetura de Agentes: Construindo 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 vinculável a hooks com shell scripts que o modelo não pode 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. Este guia cobre cada camada dessa stack: de um único hook a um sistema de consenso com 10 agents. Zero frameworks necessários. Tudo bash e JSON.

Andrej Karpathy cunhou um termo para o que cresce ao redor de um agent LLM: claws (garras). Os hooks, scripts e orquestração que permitem ao agent agarrar o mundo fora de sua janela de contexto.¹ A maioria dos desenvolvedores trata os AI coding agents como assistentes interativos. Eles digitam um prompt, observam ele 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 AI coding agent é um runtime programável com um kernel LLM. Cada 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 da mesma forma que um servidor web opera dentro das regras do nginx. Você não senta no nginx e digita requisições. Você o configura, faz o deploy e monitora.

A distinção importa porque infraestrutura se acumula. Um hook que bloqueia credenciais em comandos bash protege toda sessão, todo agent, toda execução autônoma. Uma skill que codifica sua rubrica de avaliação se aplica consistentemente, seja você quem a invoca ou um agent. 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 conclusões

• Hooks garantem execução; prompts não. Use hooks para linting, formatação, verificações de segurança e qualquer coisa que precise rodar todas as vezes, independentemente do comportamento do modelo. Exit code 2 bloqueia ações. Exit code 1 apenas avisa.³
• Skills codificam expertise de domínio que ativa automaticamente. O campo description determina tudo. Claude usa raciocínio LLM (não correspondência de palavras-chave) para decidir quando aplicar uma skill.⁴
• Subagents previnem 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 sustentada.⁵
• 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.⁶
• Deliberação multi-agent captura pontos cegos. Agents individuais não conseguem desafiar suas próprias suposições. Dois agents independentes com diferentes prioridades de avaliação capturam falhas estruturais que portões de qualidade não conseguem abordar.⁷
• O padrão do 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 Decision Framework 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 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: Skills fornecem expertise de domínio que se ativa automaticamente com base no contexto. Hooks fornecem gates determinísticos que disparam em cada chamada de tool correspondente. Arquivos de memória persistem o estado entre sessões. Agents personalizados fornecem configurações de subagents especializados.

Camada de Orquestração: Padrões multi-agent coordenam agents 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, então, 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 “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 de harness + execução de tools + container de sandbox + persistência de estado como uma REST API, cobrado em tokens padrão mais $0,08/sessão-hora. A atualização do Agents SDK da OpenAI (16 de abril) formalizou a mesma divisão — harness e computação como camadas separadas, com provedores nativos de sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) e snapshot/rehydrate para sobreviver à perda 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 fresco (arquivos, dirs, arquivos locais, repos Git, env, users, mounts); um SandboxRunConfig para fiação por execução de cliente 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 do filesystem, inspeção de imagem, 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 repo 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 “shell out para claude” e “REST API para Managed Agents” — 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 CallToolResult de tools MCP in-process, deixando o modelo com um blob de erro de validação) e trouxe SandboxNetworkConfig para paridade de schema com o TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

A bifurcação arquitetural agora é real:

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

Como o Harness se Apresenta no Disco

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

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

Cada arquivo nesta estrutura tem um propósito. A árvore ~/.claude/ é 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.⁴ No momento em que você se pegar reexplicando o mesmo contexto entre sessões, é a hora de criar uma skill.

Quando criar uma Skill

Skills são para conhecimento que Claude sempre tem disponível. Slash commands são para ações que você dispara explicitamente. Se estiver decidindo entre as duas, pergunte: “Claude deveria aplicar isso automaticamente, ou eu deveria decidir quando executar?”

Criando uma Skill

Skills ficam em quatro locais possíveis, do escopo mais amplo ao mais restrito:⁴

Toda skill requer 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 os injeta no contexto do Claude. Quando você envia uma mensagem, Claude usa raciocínio de modelo de linguagem para decidir se alguma skill é relevante. Análise independente do código-fonte do Claude Code confirma o mecanismo: as descrições de skills são injetadas em uma seção available_skills do system prompt, e o modelo usa compreensão de linguagem padrão para selecionar as skills relevantes.¹⁰

Descrição ruim:

description: Helps with code

Descrição eficaz:

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

A descrição eficaz inclui: o que ela faz (revisar código em busca de tipos específicos de problemas), quando usá-la (examinar mudanças, PRs, análise de qualidade) e frases-gatilho (review, audit, check) que os usuários naturalmente digitam.

Orçamento de contexto

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

Arquivos de apoio e organização

Skills podem referenciar arquivos adicionais no mesmo diretório:

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

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

Compartilhando Skills via Git

Skills de projeto (.claude/skills/ na raiz do repositório) 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 os colegas de equipe fazem pull, recebem a skill automaticamente. Sem instalação, sem configuração. Esta é a forma mais eficaz de padronizar conhecimento em uma equipe.

Skills como uma biblioteca de prompts

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

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

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

Skills compõem com Hooks

Skills podem definir seus próprios hooks no frontmatter que ativam apenas enquanto a skill é executada. Isso cria comportamento específico de domínio que não polui outras sessões:²

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

Skills de filosofia ativam automaticamente via hooks SessionStart, injetando restrições de qualidade em cada sessão sem invocação explícita. A skill em si é conhecimento. O hook é a aplicação. Juntos, formam uma camada de política.

Erros comuns em 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 é apertar a descrição ou adicionar disable-model-invocation: true e exigir invocação explícita via /skill-name.⁴

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

Informação crítica enterrada em arquivos de apoio. Claude lê o SKILL.md imediatamente, mas só acessa os arquivos de apoio quando necessário. Se informação crítica estiver em um arquivo de apoio, Claude pode não encontrá-la. Coloque informações essenciais diretamente no SKILL.md.⁴

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

Harnesses auto-hospedadas no 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 ao Claude Code informações mais estruturadas sobre quais skills estão disponíveis. O CLI incluído na v0.1.77 é a v2.1.133.

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 na atualização deste guia. A lista de eventos cresce a cada release, então trate a documentação de referência como a fonte da verdade e consulte o cheat sheet para a tabela completa atual antes de configurar hooks em produção:¹³

Semântica dos exit codes

Os exit codes determinam se os 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. Este é o erro de hook mais comum entre as equipes.¹⁴

Configuração de hooks

Hooks ficam em arquivos de configurações. Nível de projeto (.claude/settings.json) para hooks compartilhados. Nível de usuário (~/.claude/settings.json) para hooks pessoais:

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

O campo matcher filtra um valor específico do evento. Para eventos de tool, ele combina com valores de tool_name como Bash, Edit, Write, Read, Glob, Grep, nomes de tools MCP como mcp__server__tool, ou * para todas as tools. Nomes simples e listas separadas por | são correspondências exatas; valores com outros caracteres são expressões regulares JavaScript. Alguns eventos não suportam matchers e sempre disparam quando configurados.¹³

Protocolo de entrada/saída de hooks

Hooks recebem JSON via stdin com 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 retornar JSON para modificar a entrada da tool, injetar contexto ou tomar decisões de permissão. Use o wrapper hookSpecificOutput — o formato anterior decision/reason no nível superior 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 rodam seu formatter após cada mudança de arquivo. A saída do modelo não importa porque o formatter 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 previnem ações perigosas antes que sejam executadas. Hooks PreToolUse em Bash inspecionam comandos e bloqueiam padrões destrutivos com exit code 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 rodam 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 suporta cinco tipos de hooks:¹³

Command hooks (type: "command") rodam scripts shell. Rápidos, determinísticos, sem custo de tokens.

MCP tool hooks (type: "mcp_tool") chamam uma tool em um servidor MCP já conectado. Use-os quando a lógica de validação já vive atrás de uma fronteira MCP e não precisa de um script shell separado.

Prompt hooks (type: "prompt") enviam um prompt single-turn para um modelo Claude rápido. O modelo retorna { "ok": true } para permitir ou { "ok": false, "reason": "..." } para bloquear. Use para avaliação nuançada que regex não consegue expressar.

Agent hooks (type: "agent") instanciam um subagent com acesso a tools (Read, Grep, Glob) para verificação multi-turn. 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
          }
        ]
      }
    ]
  }
}

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 suportado 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

Rodar sete hooks disparando todos no mesmo evento, cada um lendo stdin de forma independente, cria condições de corrida. Dois hooks escrevendo no mesmo arquivo de estado JSON concorrentemente vão truncar o JSON. Cada hook downstream que faz parse desse arquivo quebra.²

A correção: um dispatcher por evento que roda 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

Depuração de hooks

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

1. Teste scripts de forma independente. Faça pipe de JSON de exemplo: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Use stderr para saída de debug. O stderr do exit code 2 é alimentado de volta ao Claude como mensagem de erro. Stderr não-bloqueante (exit 1, 3, etc.) aparece apenas em modo verbose (Ctrl+O).
3. Atenção a falhas do jq. Caminhos JSON errados retornam null silenciosamente. Teste expressões jq contra entradas de tool reais.
4. Verifique os exit codes. Um hook PreToolUse que usa exit 1 fornece zero enforcement enquanto aparenta funcionar.
5. Mantenha os hooks rápidos. Hooks rodam de forma síncrona. Mantenha todos os hooks abaixo de 2 segundos, idealmente abaixo de 500ms.

Streaming de eventos de hook no lado do SDK

Harnesses self-hosted construídos sobre claude-agent-sdk-python (v0.1.74+, 6 de maio de 2026) podem se inscrever em 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) são produzidos pelo mesmo iterador que mensagens do assistant e resultados de tools. Isso espelha a opção includeHookEvents do SDK TypeScript; o CLI empacotado foi atualizado para v2.1.129 no mesmo release.

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

Effort 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 env var $CLAUDE_EFFORT, então comandos Bash podem lê-lo sem fazer parse de JSON. Use isso para escalar o custo do hook conforme o effort tier: pule validação cara em low, rode o gate de segurança completo em xhigh ou max.
• Env var CLAUDE_CODE_SESSION_ID em subprocessos Bash. Subprocessos da tool 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 tools 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.

Memória e contexto

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

Os três mecanismos do colapso multi-turno

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

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

A memória mais confiável que atravessa fronteiras de contexto vive no sistema de arquivos. Claude Code lê CLAUDE.md e arquivos de memória no início de toda sessão e após cada compactação.⁶

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

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

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

Estratégia 2: Compactação proativa

O comando /compact do Claude Code resume a conversa e libera espaço de contexto preservando decisões-chave, conteúdo de arquivos e estado das tarefas.¹⁵

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

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

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

Estratégia 3: Handoffs de sessão

Para tarefas que abrangem múltiplas 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 ler o documento de handoff vai direto para a implementação.¹⁵

Estratégia 4: Iteração com contexto limpo (Ralph Loop)

Para sessões que excedem 60-90 minutos, gere uma instância nova de Claude por iteração. O estado persiste através do sistema de arquivos, não através da 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 contexto limpo por iteração troca 15-20% de overhead da etapa de orientação (ler arquivos de estado, escanear histórico do git) por recursos cognitivos completos a cada 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 limpo produz output de qualidade superior apesar do overhead.

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

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

O Dreaming roda em segundo plano entre sessões, não no caminho crítico. Ele complementa em vez de substituir o padrão de sistema-de-arquivos-como-memória: seu arquivo MEMORY.md continua sendo a superfície principal; o Dreaming escreve entradas de memória curadas no armazenamento de memória dos Managed Agents, que o agente lê no início da sessão. Os dois padrões coexistem para harnesses que misturam estado de sistema de arquivos auto-hospedado com curadoria do lado gerenciado.

O Dreaming está em Research Preview, então o comportamento pode mudar. Os padrões de session-handoffs e CLAUDE.md documentados acima permanecem como o mecanismo de memória autoritativo para harnesses auto-hospedados.

Os anti-padrões

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

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

Começar toda sessão lendo todos os arquivos. Deixe as ferramentas glob e grep do Claude Code encontrarem os 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 tools especificadas e retornam resultados como resumos. Os resultados da exploração não inflam sua conversa principal; apenas as conclusões retornam.⁵

Tipos de Subagent integrados

Criando subagents customizados

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 por worktree

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

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

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

O isolamento por worktree é essencial para trabalhos experimentais que podem quebrar o 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 executa em sua própria janela de contexto, encontra o código relevante e retorna um resumo. O contexto principal permanece limpo.

O recursion guard

Sem limites de spawn, agents delegam para agents que delegam para agents, cada um perdendo contexto e queimando 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 (bloqueados na profundidade 3), mas ignoram a largura: 23 agents na profundidade 1 ainda são “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 o modo de falha real (agents totais demais) em vez de uma métrica proxy (níveis de aninhamento demais).⁷

Agent Teams (Research Preview)

Agent Teams coordenam múltiplas instâncias de Claude Code que trabalham de forma independente, se comunicam por uma mailbox e uma task list compartilhadas e podem questionar as descobertas umas das outras:⁵

Habilite com: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Quando usar agent teams vs subagents:

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 agente de IA, não um README para humanos.²¹ O agente não precisa entender por que você usa conventional commits. Ele precisa saber o comando exato a ser executado e como é o “concluído”.

A hierarquia de precedência

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

O que é ignorado

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

Parágrafos em prosa sem comandos. “Valorizamos código limpo e bem testado” é documentação, não operações. O agente lê isso e segue escrevendo código sem testes, porque não há 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. Aborte se o caminho de downgrade estiver ausente.” é.

Prioridades contraditórias. “Seja ágil e entregue rápido” mais “Garanta cobertura de testes abrangente” mais “Mantenha o tempo de execução abaixo de 5 minutos” mais “Execute testes de integração completos antes de cada commit.” O agente não pode satisfazer todos os quatro simultaneamente e por padrão pula a verificação.²¹

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

O que funciona

Instruções com comandos em primeiro lugar:

## 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 fechamento:

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

1. Comandos de build e teste (o agente precisa deles antes de poder fazer qualquer coisa útil)
2. Definição de concluído (previne falsas conclusões)
3. Regras de escalonamento (previne soluções destrutivas)
4. Seções organizadas por tarefa (reduz a análise de instruções irrelevantes)
5. Escopo de diretório (monorepos: mantém as instruções de serviço isoladas)

Pule preferências de estilo até que as quatro primeiras 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 toda grande ferramenta de codificação com IA.²¹ Se sua equipe usa múltiplas ferramentas, escreva AGENTS.md como a fonte canônica e espelhe as seções relevantes em arquivos específicos de cada ferramenta:

Os padrões no AGENTS.md (comandos primeiro, fechamento definido, organizado por tarefa) funcionam em qualquer arquivo de instruções, independentemente da ferramenta. Não mantenha conjuntos paralelos de instruções que se distanciam. Escreva uma fonte autoritativa única e espelhe.

Notas de paridade do Codex

O Codex agora tem equivalentes de primeira classe para as principais camadas do harness, mas a migração é uma tradução de padrões, não uma cópia de arquivos. O Codex lê o AGENTS.md antes do início do trabalho, sobrepondo a orientação global de ~/.codex com instruções de projeto e de repositório aninhado.³¹ As skills do Codex usam o mesmo modelo mental de SKILL.md com divulgação progressiva: o Codex começa com o nome da skill, descrição e caminho do arquivo, e só carrega a skill completa quando decide usá-la.³² O Codex também tem hooks nativos, hooks empacotados em plugins, hooks gerenciados, suporte a MCP e fluxos de trabalho explícitos de subagents.³³³⁴

O mapeamento prático:

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

Testando suas instruções

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

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

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

O teste decisivo: peça ao agente para explicar seus comandos de build. Se ele não conseguir reproduzi-los literalmente, as instruções estão verbosas demais (conteúdo empurrado para fora do contexto), vagas demais (o agente não consegue extrair instruções acionáveis) ou não estão sendo descobertas. A análise do GitHub de 2.500 repositórios constatou que a vagueza 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) chegou com recursos específicos que mudam o que um harness precisa defender:²⁹

• Resiliência a falhas de ferramentas: O Opus 4.7 continua mesmo com falhas de ferramentas que interrompiam sessões do Opus 4.6. Você pode reduzir — mas não eliminar — wrappers defensivos de retry no código de subagentes. Mantenha as proteções no nível de hooks; corte o scaffolding in-prompt do tipo “se a ferramenta falhar, tente novamente três vezes”.
• Tier de esforço xhigh (apenas Opus-4.7): Fica entre high e max. Padrão recomendado para workloads de coding e agênticos. Em subagentes de longa duração, xhigh supera significativamente high com custo de tokens sub-proporcional. 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 (header beta task-budgets-2026-03-13). O modelo vê uma contagem regressiva em andamento e ajusta o escopo do trabalho ao orçamento de forma elegante, em vez de esgotar inesperadamente. Use para loops agênticos onde você quer gasto previsível de tokens sem sacrificar qualidade em prompts curtos.
• Consciência de necessidades implícitas: Primeiro modelo Claude a passar em testes de “necessidade implícita” — reconhecendo quando a solicitação literal do usuário subespecifica o que ele realmente precisa. Isso torna a seção “regras de clarificação” 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 aqueles que agora são cobertos nativamente.

Worktree base, caminhos de sandbox e configurações de admin (7 de maio de 2026)

Claude Code v2.1.133 adiciona quatro configurações de tier admin que valem a pena conhecer para harnesses de produção:³⁹

A reversão de worktree.baseRef é a que vale sinalizar para os usuários: agentes que dependiam do comportamento da v2.1.128-v2.1.132 (worktrees fazendo branch a partir do HEAD local) perdem acesso a trabalho não enviado em worktrees novos, a menos que optem por voltar.

O Quality Loop

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

1. Implementar - Escrever o código
2. Revisar - Reler cada linha. Pegar erros de digitação, erros de lógica, seções pouco claras
3. Avaliar - Executar o evidence gate. Verificar padrões, casos extremos, cobertura de testes
4. Refinar - Corrigir cada problema. Nunca adiar para “mais tarde”
5. Zoom Out - Verificar pontos de integração, imports, código adjacente em busca de regressões
6. Repetir - Se algum critério do evidence gate falhar, voltar ao passo 4
7. Reportar - Listar o que mudou, como foi verificado, citar evidências específicas

O Evidence Gate

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

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

Padrões de tratamento de erros

Escritas atômicas em arquivo. Múltiplos agentes escrevendo simultaneamente no mesmo arquivo de estado corrompem JSON. Escreva em arquivos .tmp e depois faça mv atomicamente. O sistema operacional garante que mv é atômico no mesmo sistema de arquivos.¹⁷

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

Recuperação de corrupção de estado. Se o estado for corrompido, o padrão de recuperação recria a partir de defaults seguros em vez de quebrar:¹⁶

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

A armadilha do ((VAR++)) em bash. ((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)) no lugar.¹⁶

Classificação de blast radius

Classifique toda ação de agente por blast radius e aplique gates conforme:²

O Remote Control (conectar ao Claude Code local a partir de qualquer browser ou aplicativo 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 seu 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

Critérios precisam ser verificáveis por máquina: aprovação/falha de testes, saída de linter, códigos de status HTTP, checagens de existência de arquivo. Uma tarefa inicial que pediu ao agente para “escrever testes que passem” produziu assert True e assert 1 == 1. Tecnicamente correto. Praticamente inútil.¹⁶

Modos de falha para ficar de olho

Um trace de sessão concreto

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

1. SessionStart dispara. O dispatcher injeta: data atual, detecção de projeto, restrições de filosofia, inicialização de cost tracking. Cinco hooks, 180ms no total.

2. O agente lê a PRD, planeja a primeira história. UserPromptSubmit dispara. O dispatcher injeta: contexto do projeto ativo, baseline de drift da sessão.

3. O agente chama Bash para rodar testes. PreToolUse:Bash dispara. Checagem de credenciais, validação de sandbox, detecção de projeto. 90ms. Os testes rodam. PostToolUse:Bash dispara: heartbeat de atividade registrado, checagem de drift.

4. O agente chama Write para criar um arquivo. PreToolUse:Write dispara: checagem de escopo do arquivo. PostToolUse:Write dispara: checagem de lint, rastreamento de commit.

5. O agente termina a história. Stop dispara. Os quality gates checam: o agente citou evidências? Linguagem hedging? Comentários TODO no diff? Se alguma checagem falhar, exit 2 e o agente continua.

6. Verificação independente: Um agente novo executa a suíte de testes sem confiar no auto-relato do agente anterior.

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

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

Total de hooks disparados ao longo das 5 histórias: ~340. Tempo total em hooks: ~12 segundos. Esse overhead preveniu três vazamentos de credenciais, um comando destrutivo e duas implementações incompletas em uma única execução overnight.

Estudo de caso: Processamento de PRD overnight

Um harness de produção processou 12 PRDs (47 histórias) em 8 sessões overnight. As métricas comparam as primeiras 4 PRDs (harness mínimo: apenas CLAUDE.md) com as últimas 8 (harness completo: hooks, skills, quality gates, revisão multiagente).

Os dois vazamentos de credenciais exigiram rotacionar chaves de API e auditar serviços downstream: cerca de 4 horas de resposta a incidente. O overhead do harness que preveniu o equivalente foi 2,4 segundos de bash por história. 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 pronto.

Considerações de segurança

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

A Anthropic publicou um framework formal para confiabilidade de agentes em 9 de abril de 2026.²⁷ Os cinco princípios são paralelos — e estendem — o pensamento do Evidence Gate apresentado neste guia:

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

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

O Sandbox

O Claude Code suporta um modo sandbox opcional (habilitado via settings.json ou pelo comando /sandbox) que restringe o acesso à rede e operações de filesystem usando isolamento em nível de SO (seatbelt no macOS, bubblewrap no Linux). Quando habilitado, o sandbox impede que o modelo faça requisições arbitrárias de rede ou acesse arquivos fora do diretório do projeto. Sem sandboxing, o Claude Code usa um modelo baseado em permissões onde você aprova ou nega chamadas de tool individuais.¹³

Limites de permissão

O sistema de permissões controla operações em múltiplos níveis:

Defesa contra prompt injection

Skills e hooks fornecem defesa em profundidade contra prompt injection:

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

allowed-tools: Read, Grep, Glob

PreToolUse hooks validam cada chamada de tool independentemente de como o modelo foi instruído via prompt:

# 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 subagents limita o raio de impacto. Um subagent com permissionMode: plan não pode fazer alterações mesmo que seu prompt seja comprometido.

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 detêm decisões que exigem contexto organizacional, julgamento ético ou direção estratégica. Agentes detêm decisões que exigem busca computacional em grandes espaços de possibilidades. Hooks aplicam essa fronteira.

Aplicação recursiva de hooks

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

Isso não é opcional. Um agent que spawna um subagent sem seus hooks de segurança é um agent que pode fazer force-push para a 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 um detalhe operacional posterior.² Três níveis:

Nível de token. Compressão do system prompt. Remova exemplos de código tutorial (o modelo conhece os APIs), colapse regras duplicadas entre arquivos e substitua explicações por restrições. “Reject tool calls matching sensitive paths” faz o mesmo trabalho que uma explicação de 15 linhas sobre por que credenciais não devem ser lidas.

Nível de agent. Spawns frescos em vez de conversas longas. Cada story em uma execução autônoma recebe um novo agent com contexto limpo. O contexto nunca infla porque cada agent começa do zero. Briefing em vez de memória: modelos executam um briefing claro melhor do que navegam 30 passos de contexto acumulado.

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

Framework de decisão

Quando usar cada mecanismo:

Skills vs Hooks vs Subagents

FAQ

Quantos hooks são demais?

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

Os hooks podem impedir que o Claude Code execute um comando?

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

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

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

Toda decisão precisa de deliberação?

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

Como testar um sistema projetado para produzir discordância?

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

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

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

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

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

Isso pode funcionar com tools diferentes do Claude Code?

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

Cartão de referência rápida

Configuração de hooks

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

Frontmatter de skill

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

Definição de subagent

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

Instructions for the subagent.

Códigos de saída

Comandos principais

Localizações de arquivos

Changelog

Referências