Os padrões extraídos da construção do Claudex — princípios que se aplicam a qualquer plugin, ferramenta ou sistema construído incrementalmente com Claude Code.
O papel do SPEC na construção incremental
A primeira tentação ao construir um plugin com Claude Code é ir direto ao código. "Me cria um hook que faz X." O resultado quase sempre é uma implementação que parece funcionar mas acumula dívida técnica invisível — nomes errados, responsabilidades misturadas, acoplamentos que você só vai notar quando tentar adicionar a segunda feature. O Claudex foi construído de forma diferente: o SPEC veio primeiro, antes de qualquer prompt de código.
O SPEC não é documentação — é uma decisão de design. Ele força você a nomear os componentes antes de criá-los, definir as invariantes antes de implementá-las e estabelecer os limites de responsabilidade antes que o código os atravesse. Quando você manda o primeiro prompt de código, o Claude vai nomear coisas, escolher estruturas de dados e dividir responsabilidades. Sem um SPEC, essas escolhas são feitas ad hoc, baseadas em padrões do treinamento. Com um SPEC, o Claude trabalha dentro das suas decisões — não das dele.
Segurança antes de funcionalidade
O Claudex vive na path crítica do Claude Code: se ele travar, o usuário fica bloqueado. Por isso o primeiro hook que foi construído não fazia nada além de existir e retornar exit 0. Fail-open não é um detalhe de implementação — é uma decisão de arquitetura que determina se o sistema é seguro de operar enquanto ainda está sendo construído.
Fail-open significa que quando algo dá errado — crash, arquivo corrompido, estado inválido — o sistema deixa a operação passar em vez de bloquear. Para um hook do Claude Code, isso se traduz em: qualquer caminho de erro termina em exit 0 com uma mensagem de aviso, nunca em exit 1 ou crash silencioso.
A decisão arquitetural é: este sistema vai priorizar disponibilidade sobre corretude ou o contrário? Para ferramentas de desenvolvimento que ficam na path do usuário, disponibilidade quase sempre vence. Para sistemas de segurança ou pipelines de produção, corretude pode vencer. Você precisa decidir isso antes de escrever qualquer código — porque reescrever todos os caminhos de erro retroativamente é muito mais caro.
Se você construir toda a lógica primeiro e tentar adicionar fail-open depois, vai encontrar um problema: não é uma mudança localizada. Cada função que pode falhar precisa ter seu caminho de erro revisado. Cada chamada de sistema, cada leitura de arquivo, cada parse de JSON. Em código que já existe e funciona, fazer isso sem quebrar nada é difícil. O Claudex adicionou fail-open no prompt 7 exatamente porque os prompts 1–6 precisaram ser revisados sistematicamente — e ainda assim alguns edge cases só apareceram em produção.
O princípio da solidez na construção incremental
Cada um dos 7 prompts do Claudex termina com uma instrução implícita: verifique antes de continuar. Não "rode o código e veja se parece funcionar" — verifique especificamente se os critérios da camada atual estão satisfeitos. Só então o próximo prompt pode ser enviado com segurança.
Cada camada de um sistema construído incrementalmente assume que a camada abaixo está correta. A máquina de estados do Claudex assume que o scaffold está funcionando. O lifecycle do hook assume que a máquina de estados está funcionando. Se você pular a verificação e descobrir um bug três camadas depois, você tem um problema de debug muito mais difícil: o bug pode estar em qualquer uma das camadas não verificadas, e as camadas superiores estão interagindo com o bug de maneiras que obscurecem a causa raiz.
A regra de thumb da engenharia de software é que o custo de corrigir um bug cresce exponencialmente com o tempo entre a introdução e a detecção. O mesmo princípio se aplica a prompts incrementais:
Visibilidade do sistema como princípio de design
O Claudex persiste todo o seu estado em arquivos JSON legíveis por humanos. Não em variáveis de ambiente, não em memória de processo, não em SQLite. Qualquer terminal consegue inspecionar o estado atual com um simples cat. Isso não é escolha de implementação — é um princípio de design que torna o sistema debugável, testável e confiável.
Estado em memória é rápido e conveniente, mas tem três problemas para sistemas incrementalmente construídos: (1) não sobrevive a crashes ou reinicios — o sistema perde o que estava fazendo; (2) não é inspecionável sem um debugger ou logging explícito; (3) não é testável sem executar o sistema inteiro. Estado em arquivo resolve os três: persiste, é visível com qualquer leitor de texto, e pode ser preparado manualmente para testes.
O custo é a complexidade das escritas atômicas — você precisa garantir que uma falha no meio da escrita não corrompeu o estado. O Claudex usa write-to-tmp + mv para isso: escreve em um arquivo temporário e só substitui o arquivo de estado quando a escrita está completa.
Os arquivos de estado ficam em ~/.claudex/loops/ — um diretório por loop ativo, com um state.json dentro de cada um. Para ver o que está acontecendo em tempo real:
Composição confiável começa com primitivos verificados
Antes de o Claudex ter um loop funcionando de ponta a ponta, cada parte foi testada isoladamente: a escrita atômica de estado, a leitura de estado, a transição de fase, o runner de script. Só quando cada primitivo estava provado é que o lifecycle do hook foi construído em cima deles. Esse princípio transforma debugging de "onde está o bug?" para "qual primitivo falhou?"
Quando você sabe que a escrita atômica funciona corretamente, e sabe que a leitura funciona corretamente, e a transição de fase quebra — você sabe exatamente onde está o bug. Sem esse conhecimento prévio, um bug na transição de fase pode parecer um bug de leitura, que pode parecer um bug de escrita. Primitivos verificados são axiomas: você não questiona mais, você confia neles e usa essa confiança para isolar o problema.
Antes de integrar a escrita atômica em qualquer fluxo maior, valide estes três comportamentos individualmente:
A receita universal extraída do Claudex
Os 7 prompts do Claudex não são uma sequência acidental — eles seguem um padrão que se aplica a qualquer sistema que precise ser construído com confiança incremental. O padrão é: SPEC → Scaffold → Estado → Lógica → Utils → Safety. Cada etapa assume a anterior está verificada e adiciona exatamente uma responsabilidade nova.
Qualquer sistema com estado persistente, lógica de decisão e caminhos de erro pode ser construído nessa sequência. A chave é que cada etapa produz um artefato verificável independente — você não precisa de todo o sistema para testar o estado, não precisa do state para verificar o scaffold. Essa decomposição é o que torna a construção incremental com Claude Code confiável em vez de caótica.
Nem todo projeto precisa de 7 prompts. A regra é: comprima etapas que podem ser verificadas juntas, mas nunca pule a verificação entre elas.
Os seis princípios da metodologia — cada um extraído de uma decisão real feita durante a construção do Claudex: