Módulo 2.2 — Arquivo de Estado YAML

A pasta de estado: tudo que o ciclo precisa lembrar

🧠 Memória entre turnos

Cada turno do Claude é independente — quando termina, a memória da conversa some do ponto de vista do hook. O Claudex precisa de um lugar pra guardar contexto entre turnos. Esse lugar é um arquivo YAML.

📍 Onde fica

.claude/claudex/state.yaml

Por convenção do plugin. O hook lê esse arquivo no início, decide a ação, e às vezes atualiza antes de devolver controle.

🔑 Campos: mode, phase, round

mode: plan          # plan | review | none
phase: reviewing    # drafting | reviewing | summarizing | done
round: 2             # rodada atual (1-N)

mode: qual operação está rodando — plan (criando), review (auditando) ou none (sem ciclo).
phase: em que fase do ciclo estamos. Hook usa essa informação pra decidir o próximo passo.
round: qual rodada — define qual persona o Codex vai assumir e qual findings.md ler.

⚙️ Campos: max_rounds e topic

max_rounds: 3
topic: "adicionar expiração para links curtos"

max_rounds é o limite de revisões. Quando round > max_rounds, o hook entra na fase de sumarização e termina o ciclo. Você define ao invocar o comando: /claudex plan -5 seta max_rounds: 5.

topic é a descrição que você passou. O Claudex usa nas mensagens da sumarização e no log, pra você se lembrar do que esse ciclo era. Sem ele, ao olhar logs antigos, você não saberia o assunto.

🚦 Campo: decision_signal

Esse é o campo mais "esperto". Guarda sinais de decisão emitidos pelo Claude ou Codex que o hook precisa observar pra mudar comportamento.

decision_signal: none          # operação normal
decision_signal: user_canceled # /claudex cancel disparado
decision_signal: force_done    # Claude declarou que plano já está bom

Permite saída antecipada do ciclo. Se Codex acha que o plano já está blindado e não há mais o que melhorar, ele pode setar esse sinal pra evitar rodadas desnecessárias.

📁 Onde fica salvo

.claude/
└── claudex/
    ├── state.yaml          # estado atual
    ├── state.yaml.lock     # lockfile (impede concorrência)
    ├── runner.sh           # script gerado para rodada atual
    ├── findings-round-1.md # achados da rodada 1
    ├── findings-round-2.md
    ├── findings-round-3.md
    └── log.txt             # log do hook

Tudo é local ao projeto. Se você abre dois projetos diferentes, cada um tem seu próprio .claude/claudex/ independente. Sem mistura.

📝 Por que YAML

YAML foi escolhido em vez de JSON porque é legível por humanos. Você pode abrir o arquivo, entender o estado em 5 segundos, e até editar manualmente em casos de debug.

✓ YAML escolhido

• Sem aspas obrigatórias
• Comentários inline
• Edição manual viável
• Diff legível em git

✗ JSON descartado

• Aspas em toda chave
• Sem comentários
• Difícil de editar à mão
• Diff ruim

💡 Para debug

Quando algo der errado, você abre state.yaml e vê exatamente o que aconteceu. Sem precisar de ferramenta, sem precisar de log estruturado. É a mesma filosofia do "tudo é arquivo de texto" do Unix.

📌 Resumo

✓

Memória entre turnos — sem o YAML, cada turno começaria do zero.

✓

6 campos governam tudo — mode, phase, round, max_rounds, topic, decision_signal.

✓

Local ao projeto — fica em .claude/claudex/, não compartilha entre projetos.

✓

YAML, não JSON — legibilidade humana é prioridade.

✓

decision_signal permite saída antecipada — cancel, force_done.

✓

Debug por leitura direta — abre o arquivo e entende.

Próximo Módulo:

2.3 — 🏃 O Runner Script

← Anterior Próximo →