← Voltar ao curso
Nível 3 — Automação e escala · Módulo 3.2 — Hooks: da recomendação à garantia

3.2.5 · Preservando estado através do compact

4 min de vídeo TEC BASIS

Objetivo: ao final, o consultor constrói o hook preservador de estado, que devolve ao contexto o fio do trabalho depois de uma compactação — e sabe por que ele funciona.

O que você precisa levar desta aula

  1. O padrão tem duas metades: PreCompact grava o estado num arquivo em disco, e SessionStart com matcher compact lê o arquivo e reimprime no contexto depois da compactação.
  2. Ele funciona porque SessionStart é um dos três eventos cujo stdout puro vira contexto (aula 3.2.4). Em PostCompact, o mesmo script imprimiria no vazio.
  3. Reinjete ponteiro, não conteúdo: RICEFW em trabalho, decisões, próximo passo — nunca conteúdo de arquivo ou log de comando, que encheriam de novo o contexto que a compactação acabou de esvaziar.

A configuração completa

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          { "type": "command", "command": "./.claude/scripts/salvar-estado.sh" }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "./.claude/scripts/restaurar-estado.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

Sem o matcher: "compact", o hook de restauração rodaria em toda abertura de sessão, reinjetando um estado que talvez não tenha nada a ver com o trabalho do dia.

O script de restauração é trivial

#!/usr/bin/env bash
# Roda em SessionStart (matcher: compact). O stdout aqui VAI para o contexto.
if [ -f .claude/estado-sessao.md ]; then
  echo "## Retomando depois da compactação"
  cat .claude/estado-sessao.md
fi
exit 0

Não tem mistério: ele imprime. O mecanismo inteiro depende do comportamento de stdout de SessionStart, e é por isso que a aula 3.2.4 vem antes desta.

O que reinjetar, e o que não

Reinjete Não reinjete
RICEFW em trabalho, com status Conteúdo dos arquivos abertos
Decisões tomadas na sessão ("a alçada de 50 mil foi confirmada com o cliente") Histórico da conversa
Caminho dos arquivos relevantes Log completo dos comandos rodados
Próximo passo pretendido Resultado integral de teste
Restrição que não pode ser esquecida Qualquer coisa que o Claude possa reler do disco quando precisar

O princípio: reinjete o que só existia na sua cabeça e na conversa. O que está em arquivo, o Claude relê quando precisar — e aí o custo de contexto é pago só se for necessário. Reinjetar conteúdo é encher de novo o que acabou de ser esvaziado.

Também vale para resume e fork

SessionStart dispara em quatro situações: início normal, compact, resume (retomar) e fork (ramificar). Como o hook reexecuta de verdade em cada uma, informação que envelhece é recalculada — carimbo de data, SHA do commit, branch atual. Um estado salvo em arquivo estático ficaria velho; um script que recalcula, não.

Para cobrir retomada e ramificação além da compactação, use múltiplos matchers ou omita o matcher e trate a origem dentro do script.

Regra Wayon Sessão de projeto de cliente que passe de duas horas usa o par PreCompact + SessionStart. O motivo não é conveniência: é rastreabilidade. Quando a compactação descarta a lista de pendências construída durante a sessão, o consultor reconstrói de memória — e é aí que pendência de cliente se perde silenciosamente, sem ninguém notar que se perdeu.

📖 Hooks e compactação · Contexto é o recurso escasso — módulo 2.2

Quiz — 3 questões

1.Por que o hook preservador de estado usa SessionStart com matcher compact em vez de PostCompact, se os dois disparam depois da compactação?
  • a)Porque PostCompact só existe em versão mais recente e nem todo mundo tem

    PostCompact existe e está documentado; a razão da escolha é de capacidade, não de disponibilidade.

  • b)Porque SessionStart é um dos três eventos cujo stdout puro vira contexto, e PostCompact não consegue injetar contexto

    Correto. É esse comportamento de stdout que faz o padrão inteiro funcionar.

  • c)Porque PostCompact dispara antes de o contexto estar pronto para receber texto

    Não é questão de momento: PostCompact simplesmente não tem o caminho de injeção de contexto, em nenhum instante.

Ver resposta e por quê
❌a) PostCompact existe e está documentado; a razão da escolha é de capacidade, não de disponibilidade.
✅b) Correto. É esse comportamento de stdout que faz o padrão inteiro funcionar.
❌c) Não é questão de momento: PostCompact simplesmente não tem o caminho de injeção de contexto, em nenhum instante.
2.Você vai reinjetar o estado da sessão depois da compactação. Qual conteúdo faz sentido?
  • a)O conteúdo dos três arquivos de spec que estavam abertos, para o Claude não precisar reler

    Enche de novo o contexto que a compactação acabou de esvaziar; arquivo o Claude relê do disco quando precisar.

  • b)Quais RICEFW estão em trabalho, com status, as decisões tomadas e o próximo passo

    Correto. Reinjete ponteiro e o que só existia na conversa, não conteúdo recuperável.

  • c)O histórico completo da conversa até o momento da compactação

    É exatamente o que a compactação resumiu de propósito — reinjetar desfaz o ganho e provavelmente estoura o contexto de novo.

Ver resposta e por quê
❌a) Enche de novo o contexto que a compactação acabou de esvaziar; arquivo o Claude relê do disco quando precisar.
✅b) Correto. Reinjete ponteiro e o que só existia na conversa, não conteúdo recuperável.
❌c) É exatamente o que a compactação resumiu de propósito — reinjetar desfaz o ganho e provavelmente estoura o contexto de novo.
3.Você configurou o hook de restauração em SessionStart sem o matcher compact. Qual é a consequência?
  • a)Ele roda em toda abertura de sessão, reinjetando um estado que pode não ter relação com o trabalho do dia

    Correto. O matcher é o que restringe o disparo ao caso de compactação.

  • b)Ele não roda nunca, porque o matcher é obrigatório em SessionStart

    O matcher é opcional: sem ele, o hook roda em todas as origens do evento, não em nenhuma.

  • c)Ele roda apenas na primeira sessão após a configuração

    Não há esse comportamento de execução única; sem matcher, dispara em toda origem do evento.

Ver resposta e por quê
✅a) Correto. O matcher é o que restringe o disparo ao caso de compactação.
❌b) O matcher é opcional: sem ele, o hook roda em todas as origens do evento, não em nenhuma.
❌c) Não há esse comportamento de execução única; sem matcher, dispara em toda origem do evento.