Arquitetura de agentes: construindo harnesses de desenvolvimento com IA

Resumo: 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 conectá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 aplica 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 programação com IA como assistentes interativos. Digitam um prompt, observam a 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 programaçã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ê o configura, faz deploy e monitora.

A distinção importa porque infraestrutura acumula ganhos. 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 estando você observando ou não.²

Pontos-chave

• Hooks garantem execução; prompts não. Use hooks para linting, formatação, verificações de segurança e qualquer coisa que precise rodar sempre, independentemente do comportamento do modelo. Exit code 2 bloqueia ações. Exit code 1 apenas alerta.³
• Skills codificam expertise de domínio que auto-ativa. 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 captura pontos cegos. Agentes individuais não conseguem desafiar suas próprias suposições. Dois agentes independentes com prioridades de avaliação diferentes capturam falhas estruturais que quality gates não conseguem resolver.⁷
• 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 apoia na anterior. O Framework de decisão no final fornece uma tabela de consulta para escolher o mecanismo certo para cada tipo de problema.

Por que a arquitetura de agentes é importante

Simon Willison enquadra o momento atual em torno de uma única observação: escrever código agora é barato.⁸ 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 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 39% no desempenho 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 de 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 das fronteiras 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 em 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, sempre, sem exceções. Determinístico supera probabilístico.

Perspectivas únicas perdem problemas multidimensionais. Um único agente revisando um endpoint de 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 limites que poderiam causar negação de serviço por meio de 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 todos os três problemas: hooks aplicam 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 combinável de arquivos, scripts e convenções que envolvem um agente de codificação por 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. Essa é 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 ferramenta correspondente. Arquivos de memory persistem estado entre sessões. Agents 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 inflar e os custos subirem. Usuários avançados configuram as camadas de instrução e extensão, usando a camada Core apenas para orquestração e decisões finais.²

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 nessa 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. O Claude as descobre e aplica automaticamente com base no contexto, sem que você precise chamá-las explicitamente.⁴ O momento em que você se pega re-explicando o mesmo contexto entre sessões é o momento em que deveria criar uma skill.

Quando criar uma skill

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

Criando uma skill

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

Toda skill requer um arquivo SKILL.md com frontmatter em 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

## Verificações de segurança
Ao revisar código, verifique:

### Validação de entrada
- Toda entrada do usuário sanitizada antes de operações no banco de dados
- Consultas parametrizadas (sem interpolação de strings em SQL)
- Codificação de saída para conteúdo HTML renderizado

### Autenticação
- Tokens de sessão validados em cada endpoint protegido
- Verificações de permissão antes de mutações de dados
- Nenhuma credencial hardcoded ou chaves de API no código-fonte

Referência de frontmatter

O campo description é tudo

No início da sessão, Claude Code extrai o name e description de cada skill e os injeta no contexto de Claude. Quando você envia uma mensagem, Claude usa raciocínio de modelo de linguagem para decidir se alguma skill é relevante. Uma análise independente do código-fonte de Claude Code confirma o mecanismo: as descrições das skills são injetadas em uma seção available_skills do 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 digitam naturalmente.

Orçamento de contexto

Todas as descrições de skills compartilham um orçamento de contexto que escala dinamicamente em 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 melhor solução são descrições mais curtas e precisas. Execute /context durante uma sessão para verificar se alguma skill está sendo excluída.

Arquivos de suporte e organização

Skills podem referenciar arquivos adicionais no mesmo diretório:

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

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

Compartilhando skills via Git

Skills de projeto (.claude/skills/ na raiz do 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. Esta é a forma mais eficaz de padronizar expertise em uma equipe.

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 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 se compõem com hooks

Skills podem definir seus próprios hooks no frontmatter que se ativam 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 se 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 é aplicação. Juntos, formam uma camada de políticas.

Erros comuns com skills

Descrições muito amplas. Uma skill git-rebase-helper que se 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 contexto de 2%. Se você perceber que skills não estão ativando, verifique /context para ver as excluídas. Priorize menos skills bem descritas em vez de muitas vagas.

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

Arquitetura de Hooks

Hooks são comandos shell disparados 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 22 eventos de ciclo de vida em seis categorias:¹³

Semântica dos Códigos de Saída

Os códigos de saída 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 equipes.¹⁴

Configuração de Hooks

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

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

O campo matcher é 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 dos 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 emitir JSON para modificar a entrada da ferramenta, injetar contexto ou tomar decisões de permissão:

{
  "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 impedem ações perigosas antes que sejam executadas. Hooks PreToolUse em Bash inspecionam comandos e bloqueiam padrões destrutivos com código de saída 2:

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

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

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

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

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

Tipos de Hook Além de Comandos Shell

O Claude Code suporta três 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 rápido do Claude. 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") criam um subagent com acesso a ferramentas (Read, Grep, Glob) para verificação em múltiplos turnos. Use quando a verificação requer 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 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 subsequente que fizer parsing 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

Depurando Hooks

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

1. Teste scripts de forma independente. Passe JSON de exemplo via pipe: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Use stderr para saída de depuração. Tudo escrito em stderr aparece no contexto do Claude.
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 garantia enquanto aparenta funcionar.
5. Mantenha hooks rápidos. Hooks rodam de forma síncrona. 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 do Colapso Multi-Turno

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 limites de contexto reside 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. O auto memory carrega as primeiras 200 linhas no prompt do sistema no início da sessão. Mantenha-o conciso e vincule a 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údos de arquivos e estado das tarefas.¹⁵

Quando compactar: - Após completar uma subtarefa distinta (funcionalidade implementada, bug corrigido) - Antes de iniciar 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 personalizadas 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 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 contexto completo com custo mínimo de tokens. Iniciar uma nova sessão com claude -c (continuar) 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 por iteração.¹⁶ O cálculo de custo-benefício: para sessões com menos de 60 minutos, uma única conversa é mais eficiente. Além de 90 minutos, o contexto limpo produz saída de maior qualidade apesar do overhead.

Os Antipadrõ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 grande maioria desse custo.¹⁵

Manter saída verbosa de erros no contexto. Após depurar um bug, seu contexto contém mais de 40 stack traces de iterações fracassadas. 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 especificadas 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 a 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 agente roda em sua própria janela de contexto, encontra código relevante e retorna um resumo. O contexto principal permanece limpo.

O guard de recursão

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

Agent Teams (prévia de pesquisa)

Agent Teams coordenam múltiplas instâncias de Claude Code que trabalham de forma independente, se comunicam via uma caixa de mensagens e lista de tarefas compartilhadas, e podem contestar as conclusões umas das outras:⁵

Ative 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 a avaliação independente de múltiplas perspectivas antes que qualquer decisão seja consolidada.

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 três níveis:

O limite se adapta por tipo de tarefa. Decisões de segurança exigem consenso de 0.85. Alterações de 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 alcançado pelo menos RANKING 2. Mínimo de 2 agentes concluídos (configurável) 3. A pontuação de consenso atende ao 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ções: 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 pontos diferentes do ciclo de vida correspondem a como as falhas realmente ocorrem: algumas são instantâneas (pontuação ruim) e algumas 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 alcançam consenso rápido. O dissidente não precisa estar certo. O ato de discordância 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 de estar correta.¹⁹ Liang et al. identificaram a causa raiz como “Degeneration-of-Thought”: 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 crítica de design. 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 Concordância Falsa

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, não 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, a reexecução com isolamento de contexto novo espalhou 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.

Ausência de perspectivas minoritárias: 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 troca de texto 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% enquanto melhorava 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 concluiu a deliberação com uma pontuação de consenso de 0.52 (abaixo do limite), depois continuou em tarefas não relacionadas por 20 minutos antes que o hook de fim de sessão sinalizasse a falha. Dividir em dois gates (um na conclusão da tarefa, outro no fim da sessão) capturou os mesmos problemas em pontos diferentes do ciclo de vida.⁷

Custo da Deliberação

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

No 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 é $0,23-0,30 por sessão. Se isso vale a pena depende do quanto uma decisão ruim custa.

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 carregam automaticamente e fornecem contexto estruturado sem poluir 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. “Nós 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 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 consegue satisfazer as quatro simultaneamente e por padrão pula a verificação.²¹

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

O Que Funciona

Instruções com comando primeiro:

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

## Definição de conclusão
Uma tarefa está completa quando TODOS os itens a seguir passam:
1. `ruff check .` retorna código 0
2. `pytest -v` retorna código 0 sem falhas
3. `mypy app/ --strict` retorna código 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/`
- Verifique a cobertura de testes: `pytest --cov=app --cov-fail-under=80`

## Ao fazer releases
- 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 com falha 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 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 conclusão (previne conclusões falsas)
3. Regras de escalonamento (previne soluções destrutivas)
4. Seções organizadas por tarefa (reduz o processamento de instruções irrelevantes)
5. Escopo por diretório (monorepos: mantém instruções de serviços 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ções.⁶

Compatibilidade de instruções entre ferramentas

AGENTS.md é um padrão aberto adotado por mais de 60.000 projetos e 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, definido por closure, organizado por tarefa) funcionam em qualquer arquivo de instrução independentemente da ferramenta. Não mantenha conjuntos paralelos de instruções que divergem entre si. Escreva uma 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 decisivo: 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 da GitHub de 2.500 repositórios constatou que a falta de clareza 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 lógicos, 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. Visão ampla - Verifique pontos de integração, imports, código adjacente em busca de regressões
6. Repetir - Se qualquer critério do evidence gate falhar, volte ao passo 4
7. Reportar - 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 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 estado corrompido. Se o estado for corrompido, o padrão de recuperação recria a partir de valores padrão seguros em vez de travar:¹⁶

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

A armadilha 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-se ao Claude Code local a partir de qualquer navegador ou app mobile) 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: resultado de testes passa/falha, saída de linter, códigos de status HTTP, verificações de existência de arquivos. Uma tarefa inicial que pedia 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 do 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 carrega. O ciclo se repete para todas as 5 stories.

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

Considerações de segurança

O Sandbox

Claude Code roda em um sandbox que restringe acesso à rede e operações no sistema de arquivos. O sandbox impede que o modelo faça requisições de rede arbitrárias ou acesse arquivos fora do diretório do projeto.¹³

Limites de permissão

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

Defesa contra prompt injection

Skills e hooks oferecem defesa em profundidade contra prompt injection:

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

allowed-tools: Read, Grep, Glob

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

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

Isolamento de subagents limita o raio de impacto. Um subagent com permissionMode: plan não consegue fazer alterações mesmo se seu prompt for comprometido.

Segurança de hooks

Hooks HTTP que interpolam variáveis de ambiente em headers requerem uma lista explícita de 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 responsabilidades entre humano e agente

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

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

Aplicação recursiva de hooks

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

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

Custo como arquitetura

Custo é uma decisão arquitetural, não algo que se resolve depois.² Três níveis:

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

Nível de agente. Spawns novos 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 30 passos de contexto acumulado.

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

Framework de decisão

Quando usar cada mecanismo:

Skills vs Hooks vs Subagents

FAQ

Quantos hooks é demais?

Performance, não quantidade, é a restrição. Cada hook roda sincronamente, 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 completa 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. Faça profile dos seus hooks com time antes de implantá-los.¹⁴

Hooks podem bloquear Claude Code de executar um comando?

Sim. Hooks PreToolUse bloqueiam qualquer ação de ferramenta saindo com código 2. Claude Code cancela a ação pendente e mostra a saída stderr do hook para o modelo. Claude vê o motivo da rejeição e sugere uma alternativa mais segura. Exit 1 é um aviso não-bloqueante onde a ação continua normalmente.³

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

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 todo 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, impacto, dependência de contexto). Apenas decisões com pontuação abaixo de 0.70 de confiança geral disparam deliberação — aproximadamente 10% do total de decisões. Correções de documentação, renomeação de variáveis e edições rotineiras pulam deliberação completamente. Arquitetura de segurança, mudanças de schema de banco de dados e deploys irreversíveis disparam 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 consenso. Falha: agentes convergem rápido demais, nunca convergem ou excedem budgets de spawn. Testes ponta a ponta simulam cada cenário com respostas determinísticas de agentes, verificando que ambos os portões de validação capturam todos os modos de falha documentados. Um sistema de 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 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 via Agent tool). Uma deliberação com 10 agentes adiciona 2-4 minutos. Os hooks de consenso e pride check rodam cada um em menos de 200ms. O gargalo principal é o tempo de inferência do LLM por agente, nã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, então coloque as instruções mais críticas primeiro: comandos e definições de closure antes de preferências de estilo.²¹

Isso funciona com ferramentas além 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. 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 Subagents

---
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 dos Arquivos

Registro de Alterações

Referências