MÓDULO 4.4

🐛 Lendo o estado e debugando

Quando algo dá errado, você vai direto ao .claude/claudex/. Tudo é arquivo de texto. Saber ler é o seu superpoder de debug.

1

📁 Estrutura de .claude/claudex/

.claude/claudex/
├── state.yaml             # estado atual
├── state.yaml.lock        # lockfile (PID dentro)
├── runner.sh              # script da rodada atual
├── findings-round-1.md    # achados R1
├── findings-round-2.md
├── findings-round-3.md
├── log.txt                # log do hook (cada decisão)
├── config.yaml            # sua configuração
├── hooks/
│   └── stop.sh            # o hook
└── personas/
    ├── engineer.md
    ├── security.md
    └── ops.md

Cada arquivo é texto puro. Você pode abrir tudo no editor de texto. Não tem mágica.

2

📄 Lendo state.yaml manualmente

$ cat .claude/claudex/state.yaml

mode: plan
phase: reviewing
round: 2
max_rounds: 3
topic: "adicionar expiração para links curtos"
decision_signal: none
started_at: 2026-04-30T10:32:11Z
last_update: 2026-04-30T10:38:42Z

Em 5 segundos você sabe: ciclo está em plan, fase reviewing, rodada 2/3, está há ~6 minutos rodando.

3

📋 Findings raw — investigando achado específico

Se um achado pareceu errado ou contraditório, abra o findings.md original:

$ cat .claude/claudex/findings-round-2.md

## Rodada 2 - Segurança
[Codex output completo]

## Alto
- Race condition no endpoint X: dois requests
  simultâneos podem [...]

## Médio
- [...]

Você lê o achado em texto puro, decide se faz sentido. Se foi mal interpretado pelo Claude na revisão, você corrige manualmente.

4

🔒 Quando o lockfile fica preso

Sintoma: você invoca /claudex plan e recebe "outro ciclo em andamento". Mas você sabe que não há.

$ cat .claude/claudex/state.yaml.lock

PID: 12345
created_at: 2026-04-29T18:15:32Z

# Verificar se PID 12345 ainda existe:
$ ps -p 12345
  PID TTY  TIME CMD
(processo não encontrado)

# Lock fantasma. Resolver:
$ rm .claude/claudex/state.yaml.lock

Alternativa segura: aguardar 15min — o varredor automático limpa.

5

🔧 Forçando rollback

Se nem /claudex rollback resolver:

# Última cartada: limpar manualmente
$ rm -rf .claude/claudex/*.yaml
$ rm -rf .claude/claudex/*.lock
$ rm -rf .claude/claudex/findings-*.md
$ rm -rf .claude/claudex/runner.sh
$ rm -rf .claude/claudex/log.txt

# NÃO apague hooks/ nem personas/ nem config.yaml
# (esses são instalação, não estado)

$ /claudex:doctor   # confirma que ambiente está OK

Atenção: isso apaga PLAN.md e findings. Use só se outras opções falharam.

6

🩺 /claudex:doctor interpretado

Quando o doctor reporta erro, decifre as mensagens:

✗ Hook: registrado em settings.json
  → Plugin não foi adicionado ao Claude Code.
  FIX: claude plugin reinstall iclaudex

✗ Permissões: hooks executáveis
  → Arquivo .sh sem flag de execução.
  FIX: chmod +x .claude/claudex/hooks/*.sh

✗ Auth: Codex OK
  → codex auth status retornou erro.
  FIX: codex auth login

✗ Lockfile fantasma detectado
  → Lock antigo, processo morto.
  FIX: /claudex:rollback OU rm state.yaml.lock

Cada erro vem com a ação corretiva. --verbose dá ainda mais detalhe.

💡 Filosofia Unix do Claudex

Tudo é texto. Tudo é grep-ável. Tudo é editável manualmente. Quando dá problema, você não fica perdido em logs estruturados ou ferramenta proprietária. Você abre arquivo, lê, conserta. É o que torna debug do Claudex tão rápido.

📌 Resumo

✓
Estrutura .claude/claudex/ — tudo é arquivo de texto.
✓
state.yaml em 5 segundos — diz fase, rodada, tópico.
✓
Findings raw — verifique se Claude interpretou bem.
✓
Lockfile preso — verifique PID, remova manualmente se necessário.
✓
Rollback forçado — limpe arquivos manualmente, preserve config.
✓
Doctor interpretado — cada ✗ vem com FIX.

Próximo Módulo:

4.5 — 📊 Métricas e ROI

← AnteriorPróximo →