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 22 eventos de ciclo de vida, cada um hookável 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 impõe restrições, delega trabalho, persiste memória entre sessões e orquestra deliberação multi-agente. Este guia cobre cada camada dessa stack: de um único hook a um sistema de consenso com 10 agentes. Zero frameworks necessários. Tudo em bash e JSON.

Andrej Karpathy cunhou um termo para o que cresce ao redor de um agente LLM: garras. Os hooks, scripts e orquestração que permitem ao agente agarrar o mundo fora da sua janela de contexto.¹ A maioria dos desenvolvedores trata agentes de codificação com IA como assistentes interativos. Digitam um prompt, assistem à edição de um arquivo e seguem em frente. Essa abordagem limita a produtividade ao que você consegue supervisionar pessoalmente.

O modelo mental de infraestrutura é diferente: um agente de codificação com IA é 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ê configura, faz deploy e monitora.

A distinção importa porque infraestrutura tem efeito composto. Um hook que bloqueia credenciais em comandos bash protege cada sessão, cada agente, cada execução autônoma. Uma skill que codifica seu critério de avaliação é aplicada consistentemente, seja você quem a invoca ou um agente. Um agente que revisa código por 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 toda vez, independentemente do comportamento do modelo. Exit code 2 bloqueia ações. Exit code 1 apenas alerta.³
• Skills codificam expertise de domínio que se 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 evitam inchaço de contexto. Janelas de contexto isoladas para exploração e análise mantêm a sessão principal enxuta. Até 10 podem rodar em paralelo.⁵
• 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-agente detecta pontos cegos. Agentes individuais não conseguem desafiar suas próprias suposições. Dois agentes independentes com prioridades de avaliação diferentes detectam falhas estruturais que quality gates não conseguem endereçar.⁷
• O padrão 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 rápido de cinco minutos

Antes de mergulhar fundo, aqui está o caminho mais curto do zero até um harness funcional. Um hook, uma skill, um subagent, um resultado.

Passo 1: Crie 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

Configure-o em .claude/settings.json:

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

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

Passo 2: Crie uma 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: injeção SQL, XSS, secrets hardcoded, tratamento de erros ausente, funções com mais de 50 linhas.

Resultado: Claude ativa automaticamente essa expertise sempre que você mencionar review, check ou audit.

Passo 3: Crie um subagent (30 segundos)

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

O que você tem agora

Um harness de três camadas: uma porta de segurança determinística (hook), expertise 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 agentes importa

Simon Willison enquadra o momento atual em torno de uma única observação: escrever código agora é barato.⁸ Correto. Porém, 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 ao redor do modelo que captura o que o modelo deixa passar.

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

Janelas de contexto são finitas e com perdas. Cada leitura de arquivo, saída de ferramenta 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 múltiplos turnos.⁹ A degradação começa em apenas dois turnos e segue uma curva previsível: edições precisas em múltiplos arquivos nos primeiros 30 minutos se degradam em visão de túnel em arquivo único por volta do minuto 90. Janelas de contexto maiores 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 para 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 conformidade, segurança e padrões de equipe, 80% não é aceitável. Hooks garantem a execução: cada Edit ou Write aciona seu formatador, toda vez, sem exceções. Determinístico supera probabilístico.

Perspectivas únicas perdem problemas multidimensionais. Um único agente revisando um endpoint API verificou autenticação, validou sanitização de entrada e conferiu cabeçalhos CORS. Aprovado sem ressalvas. Um segundo agente, instruído separadamente como testador de penetração, encontrou que o endpoint aceitava parâmetros de consulta sem limite que poderiam acionar negação de serviço por amplificação de consultas no banco de dados.⁷ O primeiro agente nunca verificou porque nada em seu framework de avaliação tratava a complexidade de consultas como uma superfície de segurança. Essa lacuna é estrutural. Nenhuma quantidade de engenharia de prompt resolve isso.

A arquitetura de agentes aborda os três problemas: hooks impõem restrições determinísticas, subagents gerenciam isolamento de contexto e orquestração multi-agente fornece perspectivas independentes. Juntos, formam o harness.

O padrão Harness

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

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

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

Camada de Extensão: Skills fornecem expertise de domínio que ativa automaticamente com base no contexto. Hooks fornecem portas determinísticas que disparam em cada chamada de ferramenta correspondente. Arquivos de memória persistem estado entre sessões. Agentes personalizados fornecem configurações especializadas de subagents.

Camada de Orquestração: Padrões multi-agente coordenam agentes independentes para pesquisa, revisão e deliberação. Orçamentos de spawn previnem recursão descontrolada. Validação por consenso garante qualidade.

O insight principal: a maioria dos usuários trabalha inteiramente na Camada Core, observando o contexto inchar e os custos subirem. Usuários avançados configuram as camadas de Instrução e Extensão, depois usam a Camada Core apenas para orquestração e decisões finais.²

Como o Harness se parece 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, formam o harness completo.

Sistema de Skills

Skills são extensões invocadas pelo modelo. Claude as descobre e aplica automaticamente com base no contexto, sem que você precise chamá-las explicitamente.⁴ No momento em que você perceber que está re-explicando o mesmo contexto entre sessões, é 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ê aciona explicitamente. Se estiver decidindo entre os dois, pergunte: “O 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 do 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 das 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 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 faz (revisar código para tipos específicos de problemas), quando usar (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 a 2% da janela de contexto, com um fallback de 16.000 caracteres.⁴ Se você tem muitas skills, mantenha cada descrição concisa. Você pode sobrescrever o orçamento via a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ mas a solução melhor é ter 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

Referencie-os a partir do 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 colegas de equipe fazem pull, recebem a skill automaticamente. Sem instalação, sem configuração. Essa é a forma mais eficaz de padronizar expertise em um time.

Skills como Biblioteca de Prompts

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

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

Cada skill codifica uma faceta diferente da sua expertise. Juntas, formam uma base de conhecimento que Claude utiliza 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 são ativados apenas enquanto a skill está em execução. 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 de SessionStart, injetando restrições de qualidade em cada sessão sem invocação explícita. A skill em si é conhecimento. O hook é aplicação. Juntos, formam uma camada de políticas.

Erros Comuns em Skills

Descrições muito amplas. 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 solução é restringir a descrição ou adicionar disable-model-invocation: true e exigir invocação explícita via /skill-name.⁴

Muitas skills competindo pelo orçamento. Mais skills significa mais descrições competindo pelo orçamento de 2% do contexto. Se você notar que skills não estão ativando, verifique /context para identificar as excluídas. Priorize poucas 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 arquivos de apoio quando necessário. Se informação crítica está em um arquivo de apoio, Claude pode não encontrá-la. Coloque informações essenciais diretamente no SKILL.md.⁴

Arquitetura de Hooks

Hooks são comandos shell acionados por eventos do 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 lista de bloqueio e o rejeita antes que o shell sequer o veja. O hook dispara independentemente da vontade do modelo.

Eventos Disponíveis

O Claude Code expõe mais de 26 eventos de ciclo de vida em sete categorias (a lista de eventos cresce a cada versão — consulte o cheat sheet para a tabela completa atualizada):¹³

Semântica dos 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. Este é o erro de hook mais comum entre equipes.¹⁴

Configuração de Hooks

Hooks ficam em arquivos de configurações. Em nível de projeto (.claude/settings.json) para hooks compartilhados. Em 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 é uma regex que corresponde a nomes de ferramentas: Bash, Write, Edit, Read, Glob, Grep, Agent, ou * para todas as ferramentas. Use "" (string vazia) para eventos sem ferramentas como UserPromptSubmit.

Protocolo de Entrada/Saída de Hooks

Hooks recebem JSON via stdin com o contexto completo:

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

Para controle avançado, hooks PreToolUse podem emitir JSON para modificar a entrada da ferramenta, injetar contexto ou tomar decisões de permissão. Use o wrapper hookSpecificOutput — o formato antigo com decision/reason no nível superior está deprecado 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 após o 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 previnem ações perigosas antes de serem 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 Hook Além de Comandos Shell

O Claude Code suporta quatro tipos de hook:¹³

Hooks de comando (type: "command") executam scripts shell. Rápidos, determinísticos, sem custo de tokens.

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

Hooks de agente (type: "agent") iniciam um subagent com acesso a ferramentas (Read, Grep, Glob) para verificação em múltiplos turnos. Use quando a verificação exige 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
          }
        ]
      }
    ]
  }
}

Hooks HTTP (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 de notificação externos 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 ser concluída antes da próxima ação.

Dispatchers em Vez de Hooks Independentes

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

A solução: um dispatcher por evento que executa hooks sequencialmente a partir do 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 independentemente. Envie JSON de exemplo via pipe: 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 verbose (Ctrl+O).
3. Fique atento a falhas do jq. Caminhos JSON incorretos retornam null silenciosamente. Teste expressões jq contra entrada real da ferramenta.
4. Verifique os códigos de saída. Um hook PreToolUse que usa exit 1 não oferece nenhuma aplicação enquanto aparenta funcionar.
5. Mantenha hooks rápidos. Hooks rodam sincronamente. Mantenha todos os hooks abaixo de 2 segundos, idealmente abaixo de 500ms.

Memória e contexto

Toda conversa com IA 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 arquiteturais documentadas no turno 3 podem não sobreviver até o turno 15.⁹

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

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

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

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

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

O arquivo MEMORY.md 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 isso. Três sessões depois, ao encontrar um caso extremo semelhante com inteiros em Python, a entrada no MEMORY.md traz o padrão à tona.¹⁵

Auto Memory (v2.1.32+): Claude Code registra e recupera automaticamente o contexto do projeto. Conforme 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 ao iniciar a sessão. Mantenha-o conciso e crie links para arquivos de tópicos separados para notas 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 completar uma subtarefa distinta (funcionalidade implementada, bug corrigido) - Antes de começar uma nova área do codebase - Quando Claude começa a repetir ou esquecer contexto anterior - Aproximadamente a cada 25-30 minutos durante sessões intensivas

Instruções de compactação personalizadas 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 capturam 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 o contexto completo com custo mínimo de tokens. Iniciar uma nova sessão com claude -c (continue) ou ler o documento de handoff leva direto à implementação.¹⁵

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

Para sessões que excedem 60-90 minutos, inicie uma instância limpa de Claude por iteração. O estado persiste pelo sistema de arquivos, 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 contexto limpo por iteração troca 15-20% de overhead na etapa de orientação (leitura de arquivos de estado, varredura do histórico git) por recursos cognitivos completos em cada iteração.¹⁶ O cálculo de custo-benefício: para sessões com menos de 60 minutos, uma única conversa é mais eficiente. Acima de 90 minutos, o contexto limpo produz resultados de maior qualidade apesar do overhead.

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 offsets de linha: Read file.py offset=100 limit=20 economiza a grande maioria desse custo.¹⁵

Manter saída verbosa de erros no contexto. Após debugar um bug, seu contexto contém mais de 40 stack traces de iterações com falha. 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 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 específicas e retornam resultados como resumos. Os resultados da exploração não inflam sua conversa principal; apenas as conclusões retornam.⁵

Tipos de subagents integrados

Criando subagents personalizados

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

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

You are a senior security engineer reviewing code for vulnerabilities.

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

Focus on actionable security findings, not style issues.

Campos de configuração de subagents

Isolamento com worktree

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

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

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

O isolamento com worktree é essencial para trabalho experimental que pode quebrar o codebase.

Subagents paralelos

Claude Code suporta até 10 subagents paralelos.⁵ Use execução paralela para tarefas de pesquisa independentes:

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

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

O recursion guard

Sem limites de criação, agents delegam para agents que delegam para agents, cada um perdendo contexto e consumindo tokens. O padrão de 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 fundamental: Use orçamentos de criação, não apenas limites de profundidade. Limites baseados em profundidade rastreiam cadeias pai-filho (bloqueado na profundidade 3), mas ignoram a largura: 23 agents na profundidade 1 ainda é “profundidade 1”. Um orçamento de criação 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 (muitos agents no total) em vez de uma métrica indireta (muitos níveis de aninhamento).⁷

Agent Teams (prévia de pesquisa)

Agent Teams coordenam múltiplas instâncias de Claude Code que trabalham independentemente, se comunicam por meio de uma caixa de mensagens e lista de tarefas compartilhadas, e podem questionar as descobertas uns dos outros:⁵

Habilite com: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Quando usar agent teams vs subagents:

Orquestração multi-agente

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

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. Todo o resto adiciona melhorias incrementais.

O gatilho de confiança

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

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

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

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

A máquina de estados

Sete fases, cada uma condicionada pela anterior:⁷

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

RESEARCH: Agentes independentes investigam o tópico. Cada agente recebe uma persona diferente (Arquiteto Técnico, Analista de Segurança, Engenheiro de Performance, entre outros). O isolamento de contexto garante que os agentes não possam ver as descobertas uns dos outros durante a pesquisa.

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

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

A arquitetura de validação com dois gates

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

Gate 1: Validação de consenso (hook PostToolUse). Executa imediatamente após cada agente de deliberação concluir: 1. A fase deve ter atingido pelo menos RANKING 2. Mínimo de 2 agentes concluídos (configurável) 3. A pontuação de consenso atinge o limite adaptativo da tarefa 4. Se algum agente discordou, as preocupações devem estar documentadas

Gate 2: Pride Check (hook Stop). Executa antes que a sessão possa ser encerrada: 1. Métodos diversos: múltiplas personas únicas representadas 2. Transparência de contradição: discordâncias têm razões documentadas 3. Tratamento de complexidade: pelo menos 2 alternativas geradas 4. Confiança de consenso: classificada como forte (acima de 0,85) ou moderada (0,70-0,84) 5. Evidência de melhoria: confiança final supera 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 discordância ausente).⁷

Por que o consenso é perigoso

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 genuinamente debater e descobriram que, sem incentivos estruturais para discordância, os agentes convergem para a resposta inicial que soa mais confiante, independentemente da correção.¹⁹ Liang et al. identificaram a causa raiz como “Degeneração de Pensamento”: uma vez que um LLM estabelece confiança em uma posição, a autorreflexão não consegue gerar contra-argumentos novos, tornando a avaliação multi-agente estruturalmente necessária.²⁰

Independência é a restrição de design crítica. Dois agentes avaliando a mesma estratégia de deploy 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 falso consenso

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

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

Discordância genérica: Agentes copiando a linguagem de preocupação uns dos outros em vez de gerar objeções independentes.

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

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

O que não funcionou na deliberação

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

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

Com o preço atual do Opus, uma deliberação com 3 agentes custa aproximadamente $0,68-0,90. Uma deliberação com 10 agentes custa $2,25-3,00. O sistema aciona deliberação em aproximadamente 10% das decisões, então o custo amortizado em todas as decisões é de $0,23-0,30 por sessão. Se isso vale a pena depende do custo de 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 executar e como é o resultado esperado.

A hierarquia de precedência

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

O que é ignorado

Esses padrões consistentemente não produzem 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ção. O agente lê e prossegue 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. “Mova rápido e entregue logo” mais “Garanta cobertura abrangente de testes” mais “Mantenha o runtime abaixo de 5 minutos” mais “Execute testes de integração completos antes de cada commit.” O agente não consegue satisfazer todas as quatro simultaneamente e 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 agente nenhum mecanismo para verificar conformidade.

O que funciona

Instruções orientadas a comandos:

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

## Definição de pronto
Uma tarefa está completa quando TODOS os itens a seguir passam:
1. `ruff check .` retorna 0
2. `pytest -v` retorna 0 sem falhas
3. `mypy app/ --strict` retorna 0
4. Os arquivos alterados foram preparados e commitados
5. A mensagem de commit segue o formato convencional: `type(scope): description`

Seções organizadas por tarefa:

## Ao escrever código
- Execute `ruff check .` após cada alteração de arquivo
- Adicione type hints a todas as novas funções

## Ao revisar código
- Verifique problemas de segurança: `bandit -r app/`
- Confirme a cobertura de testes: `pytest --cov=app --cov-fail-under=80`

## Ao fazer release
- Atualize a versão em `pyproject.toml`
- Execute a suíte completa: `pytest -v && ruff check . && mypy app/`

Regras de escalonamento:

## Quando estiver bloqueado
- Se os testes falharem após 3 tentativas: pare e reporte o teste que falhou com a saída completa
- Se uma dependência estiver faltando: verifique `requirements.txt` primeiro, depois pergunte
- Nunca: delete arquivos para resolver erros, force push ou pule testes

Ordem de escrita

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

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

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

Importação 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 importação: relativa (@docs/file.md), absoluta (@/absolute/path.md) ou diretório home (@~/.claude/file.md). Profundidade máxima: 5 níveis de importação.⁶

Compatibilidade de instruções entre ferramentas

AGENTS.md é um padrão aberto reconhecido por todas as principais ferramentas de codificação com IA.²¹ Se sua equipe usa múltiplas ferramentas, escreva o AGENTS.md como fonte canônica e espelhe as seções relevantes nos arquivos específicos de cada ferramenta:

Os padrões do AGENTS.md (comando primeiro, closure definida, organizado por tarefa) funcionam em qualquer arquivo de instrução, independentemente da ferramenta. Não mantenha conjuntos paralelos de instruções que acabem divergindo. Escreva uma única fonte autoritativa e espelhe.

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 definitivo: Peça ao agente para explicar seus comandos de build. Se ele não conseguir reproduzi-los literalmente, as instruções estão ou muito verbosas (conteúdo empurrado para fora do contexto), muito vagas (o agente não consegue extrair instruções acionáveis), ou não estão sendo descobertas. A análise de 2.500 repositórios feita pela GitHub constatou que a imprecisão causa a maioria das falhas.²¹

Padrões de produção

O quality loop

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

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

O evidence gate

“Eu acredito” e “deveria funcionar” não são evidências. 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 ao Refinar.²²

Padrões de tratamento de erros

Escritas atômicas em arquivos. Múltiplos agentes escrevendo no mesmo arquivo de estado simultaneamente corrompe JSON. Escreva em arquivos .tmp e depois use 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 estado corrompido. Se o estado for corrompido, o padrão de recuperação recria a partir de valores padrão 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++)) no bash. ((VAR++)) retorna código de saída 1 quando VAR é 0 porque 0++ avalia como 0, que o bash trata como falso. Com set -e habilitado, isso mata o script. Use VAR=$((VAR + 1)) em vez disso.¹⁶

Classificação de raio de impacto

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

Remote Control (conectar ao Claude Code local a partir de qualquer navegador ou aplicativo móvel) transforma o controle “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 devem 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 arquivos. 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 a observar

Um rastreamento concreto de sessão

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

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

2. O agente lê o PRD, planeja a primeira story. UserPromptSubmit dispara. O dispatcher injeta: contexto do projeto ativo, baseline de desvio de 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. 90ms. Testes executam. PostToolUse:Bash dispara: heartbeat de atividade registrado, verificação de desvio.

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. Verificações do quality gate: o agente citou evidências? Linguagem evasiva? Comentários TODO no diff? Se qualquer verificação 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 criados em paralelo. Cada um revisa o diff independentemente. Se qualquer revisor sinalizar CRITICAL, a story volta para a fila.

8. Story aprovada. Próxima story carregada. O ciclo se repete para todas as 5 stories.

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

Estudo de caso: processamento noturno de PRD

Um harness de produção processou 12 PRDs (47 stories) 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 multi-agente).

Os dois vazamentos de credenciais exigiram a rotação de chaves API e auditoria de serviços downstream: aproximadamente 4 horas de resposta a incidentes. A sobrecarga do harness que evitou o equivalente foi de 2,4 segundos de bash por story. A taxa de conclusão falsa caiu de 35% para 4% porque o Stop hook executava testes independentemente antes de permitir que o agente reportasse como concluído.

Considerações de segurança

O Sandbox

Claude Code suporta um modo sandbox opcional (habilitado via settings.json ou o comando /sandbox) que restringe o acesso à rede e operações no sistema de arquivos usando isolamento em nível de sistema operacional (seatbelt no macOS, bubblewrap no Linux). Quando habilitado, o sandbox impede que o modelo faça requisiçõ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 onde você aprova ou nega chamadas individuais de ferramentas.¹³

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 ferramentas impedem que um prompt comprometido obtenha acesso de escrita:

allowed-tools: Read, Grep, Glob

PreToolUse hooks 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 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

HTTP hooks que interpolam variáveis de ambiente em cabeçalhos requerem uma lista explícita allowedEnvVars para prevenir 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 humano-agente

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

O padrão: humanos são responsáveis por decisões que requerem contexto organizacional, julgamento ético ou direção estratégica. Agentes são responsáveis por decisões que requerem busca computacional em grandes espaços de possibilidades. Hooks garantem essa fronteira.

Aplicação recursiva de hooks

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

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

Custo como arquitetura

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

Nível de tokens. Compressão do system prompt. Remova exemplos de código tutoriais (o modelo conhece as APIs), consolide regras duplicadas entre arquivos e substitua explicações por restrições. “Rejeitar chamadas de ferramentas 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. Instâncias novas 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 como prioridade sobre MCP quando a operação é stateless. 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.

Framework de decisão

Quando usar cada mecanismo:

Skills vs Hooks vs Subagents

FAQ

Quantos hooks é demais?

O desempenho, não a quantidade, é o fator limitante. Cada hook roda de forma síncrona, então o tempo total de execução dos hooks se soma 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 conclui em menos de 200ms. O limite a observar: se um hook PostToolUse adiciona mais de 500ms a cada edição de arquivo, a sessão fica lenta. Analise o desempenho dos seus hooks com time antes de implantá-los.¹⁴

Hooks podem impedir o Claude Code de executar um comando?

Sim. Hooks PreToolUse 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 para o modelo. O Claude vê o motivo da rejeição e sugere uma alternativa mais segura. Exit 1 é um aviso não bloqueante onde a ação continua normalmente.³

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

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

Toda decisão precisa de 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 a deliberação, aproximadamente 10% do total de decisões. Correções de documentação, renomeação de variáveis e edições rotineiras ignoram a deliberação completamente. Arquitetura de segurança, mudanças de esquema de banco de dados e deploys irreversíveis acionam consistentemente.⁷

Como testar um sistema projetado para produzir discordância?

Teste tanto caminhos de sucesso quanto de falha. Sucesso: agentes discordam produtivamente e chegam a um consenso. Falha: agentes convergem rápido demais, nunca convergem ou excedem os budgets de spawn. Testes de ponta a ponta simulam cada cenário com respostas determinísticas de agentes, verificando que ambos os validation gates capturam cada modo de falha documentado. 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 de ponta a ponta.⁷

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

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

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

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

Isso funciona com ferramentas além do Claude Code?

Os princípios arquiteturais (hooks como gates 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. 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 de cada ferramenta.

Cartão de referência rápida

Configuração de hooks

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

Frontmatter de skills

---
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ção de arquivos

Changelog

Referências