Os defaults do Claude Code te levam longe. Mas existe um ponto — geralmente por volta do terceiro mês de uso sério — em que você já passou deles. Você quer um efeito colateral determinístico depois de cada chamada de tool. Você quer que o agent leia seu wiki interno. Você quer entregar uma ferramenta custom que conversa com a API sob medida da sua empresa.

É para isso que serve este artigo. Quatro padrões:

1. Hooks — cola determinística entre os passos do agent.
2. Servidores MCP — dados de empresa que o agent pode ler.
3. Ferramentas custom — seus próprios comandos plugados no agent.
4. Cirurgia de system prompt — quando os prompts sozinhos não vão te levar lá.

1. Hooks — cola determinística

Um hook é um script que dispara em um evento conhecido: onFileEdit, onShellRun, onSessionStart, onSessionEnd, etc. Não são "IA"; são shell puro.

Por que importam: te permitem adicionar garantias determinísticas em torno de um agent que de outro modo é probabilístico.

Exemplos que rodo em todo projeto:

{
  "hooks": {
    "onSessionStart": "scripts/claude-onstart.sh",
    "onFileEdit": "scripts/claude-onedit.sh",
    "onSessionEnd": "scripts/claude-onend.sh"
  }
}

scripts/claude-onstart.sh:

#!/usr/bin/env bash
# Snapshot do working tree antes do agent começar.
git stash push -u -m "claude-pre-session-$(date +%s)" --keep-index || true

scripts/claude-onedit.sh:

#!/usr/bin/env bash
# Depois de cada edição, prettier só no arquivo alterado.
file="$1"
if [ -f "$file" ]; then
  pnpm prettier --write "$file" --log-level silent
fi

scripts/claude-onend.sh:

#!/usr/bin/env bash
# No fim da sessão, despachamos o transcript.
cp ~/.claude/sessions/last.jsonl /var/log/claude/$(date +%F-%H%M).jsonl

Três hooks. Cada sessão agora é snapshot-able, formatada e auditada. Nenhum é IA; todos são infraestrutura.

2. Servidores MCP — seus dados dentro do agent

Model Context Protocol (MCP) é o padrão para permitir que um agent leia fontes de dados externas em tempo de sessão. Em vez de colar uma página do Confluence, você conecta o servidor MCP e o agent pode navegar sob demanda.

Os padrões que vi pagar:

• MCP para o bug tracker. O agent lê o ticket, comentários incluídos, antes de começar a implementar.
• MCP para o schema do DB de staging. O agent pode introspeccionar tabelas em vez de adivinhar.
• MCP para os runbooks. O agent lê docs/runbooks/<incident-type>.md automaticamente.

A configuração vive em .claude/mcp.json:

{
  "servers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-linear"],
      "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
    },
    "company-docs": {
      "command": "node",
      "args": ["./mcp/company-docs.js"]
    }
  }
}

Dois avisos:

• Servidores MCP rodam com seus privilégios. Trate como CLIs; revise o código deles antes de plugar.
• MCP pode vazar. Se você conecta um servidor que expõe dados de cliente, toda sessão consegue lê-los. Escope apertado.

3. Ferramentas custom — seus próprios verbos

Sub-agents e slash commands deixam você reusar texto. Ferramentas custom deixam você adicionar verbos chamáveis.

Exemplo: uma ferramenta deploy-preview. O agent não deveria rodar shell pra deployar um preview — formas demais de isso dar errado. Em vez disso, exponha uma ferramenta:

{
  "tools": {
    "deploy-preview": {
      "description": "Deploya um preview environment para a branch atual.",
      "schema": {
        "type": "object",
        "properties": {
          "branch": { "type": "string" }
        },
        "required": ["branch"]
      },
      "command": "scripts/deploy-preview.sh"
    }
  }
}

Agora o agent vê um verbo chamado deploy-preview com uma entrada tipada. O script que você escreve decide o que ele faz. O agent não consegue escapar do contrato.

É o mesmo padrão que eu usaria para:

• run-load-test
• migrate-staging
• tail-prod-logs (somente leitura)
• notify-pager-duty

Cada um é um guard rail que diz "o agent pode fazer isso, exatamente desse jeito, nunca mais fundo."

4. Cirurgia de system prompt

Às vezes o comportamento de um sub-agent está quase certo e um ajuste no system prompt fecha a lacuna. Três padrões:

4a. O bloco "rules"

Sempre coloque os inegociáveis sob um header chamado rules:

# rules
- Nunca adicione @ts-ignore.
- Nunca modifique arquivos em /infra/.
- Sempre rode `pnpm test` antes de declarar sucesso.

O agent trata isso como mais duro do que meras instruções porque parece uma lista de leis.

4b. Schema de saída primeiro

Se você quer saída estruturada (handoffs, JSON, YAML), coloque o schema antes da explicação em prosa. Agents ancoram nos primeiros 200 tokens.

# schema de saída (sempre no topo do system prompt)
status: ok | needs-human | failed
artifacts: [path: string]
notes: string
next: code-reviewer | release-bot | done

# rationale (abaixo do schema, jamais acima)
# Você emite isso pra que o próximo agent do pipeline saiba exatamente onde você está.

4c. Contra-exemplos

Mostre o que NÃO fazer:

# saída ruim
"Pronto. O cache está implementado."

# saída boa
status: ok
artifacts: [{path: "lib/cache.ts"}]
notes: "LRU + TTL implementados. Todos os testes verdes."
next: code-reviewer

Contra-exemplos são, estranhamente, mais eficazes do que exemplos positivos pra obter conformidade. Não tenho uma teoria profunda do porquê; empiricamente, funciona.

Quando você precisa dos quatro juntos

O workflow avançado que acende times de verdade:

hook (onSessionStart)              → snapshot stash
agent lê CLAUDE.md                 → contexto
agent chama servidor MCP           → lê ticket Linear
agent chama tool custom            → run-load-test
hook (onFileEdit)                  → prettier
agent emite handoff estruturado    → code-reviewer
hook (onSessionEnd)                → despacha transcript

Cada camada adiciona determinismo, rastreabilidade ou capacidade. Nenhuma é "o agent". Todas são andaime.

Essa é a lição, quatro artigos dentro dos padrões avançados: o agent é a parte pequena. O andaime é o trabalho de engenharia.

---

Último artigo da série: O futuro do desenvolvimento agêntico — pra onde isso está indo em 2026, no que eu apostaria e a linha além da qual eu seria cético.