🏗️ Construindo com Claude Code

A abordagem de dividir a construção de um sistema em prompts atômicos, cada um verificado antes do próximo ser executado.

Evita o acúmulo de bugs não detectados que tornam refatoração impossível. Cada camada fica sólida antes de receber peso.

Build incremental, verificação por camada, prompts atômicos, fail-fast por design.

Um documento de especificação que define componentes, responsabilidades, invariantes e contratos antes de qualquer linha de código.

O SPEC força decisões difíceis cedo, quando mudar é barato. Sem ele, cada prompt reimagina a arquitetura do zero.

Componentes e responsabilidades, invariantes de segurança, contratos de interface, decisões de design explícitas.

As seis propriedades que o sistema nunca pode violar: fail-open, escrita atômica, CAS, idempotência, timeouts e limpeza garantida.

Sem invariantes explícitos, cada prompt pode inadvertidamente quebrar uma garantia que outro prompt estabeleceu.

Fail-open, atomic writes, compare-and-swap, idempotência, timeout handling, cleanup guarantees.

O primeiro prompt que cria o esqueleto do plugin: estrutura de arquivos, hook de PreToolUse com fail-open, e integração básica com Claude Code.

O esqueleto define o contrato externo do sistema. Acertar aqui evita reescritas completas nos prompts seguintes.

Plugin scaffold, PreToolUse hook, fail-open por padrão, estrutura de arquivos do plugin.

A propriedade de segurança que garante: se o plugin falhar por qualquer motivo, Claude Code continua funcionando normalmente.

Um hook que bloqueia o trabalho do desenvolvedor quando falha é pior que não existir. Fail-open é a primeira linha de defesa.

Fail-open vs fail-closed, try/catch em hooks, exit codes, degradação graciosa.

O segundo prompt adiciona a máquina de estados que controla as transições entre fases: idle → planning → running → summarizing → done.

Sem estado explícito, o sistema não sabe em qual fase está e pode executar ações fora de ordem ou duplicar trabalho.

State machine, transições de estado, estado persistido em arquivo, fases do loop de revisão.

Técnicas para garantir que o arquivo de estado nunca fica corrompido: escrever em arquivo temporário e renomear atomicamente, verificar versão antes de modificar.

Claude Code pode ser interrompido a qualquer momento. Estado corrompido transforma um erro recuperável em perda permanente de sessão.

Atomic write via rename, compare-and-swap, versioning de estado, recuperação de falha.

O Stop Hook que intercepta o fim de cada turno de Claude e decide: bloquear (continuar o loop) ou aprovar (encerrar a sessão).

Este hook é o coração do loop. Sem ele, o Claudex seria apenas um script que roda uma vez — não um loop de revisão contínua.

Stop Hook, exit code 2 (bloquear), exit code 0 (aprovar), lifecycle do hook, controle de fluxo.

A lógica dentro do Stop Hook que lê o estado atual e decide qual ação tomar: iniciar rodada de revisão, acumular findings, ou ativar sumarização.

O hook precisa de visão completa do estado para tomar decisões corretas. Um switch incorreto pode pular fases ou criar loops infinitos.

Leitura de estado, switch por fase, injeção de instrução no próximo turno, transição de fases.

O script que invoca `claude --print` com o prompt de revisão correto para cada rodada, capturando o output para processamento posterior.

O runner é o ponto de integração entre o hook e o modelo. Problemas aqui se propagam para todas as rodadas de revisão.

claude --print, subprocess invocation, output capture, error handling no runner.

O sistema que extrai findings estruturados (arquivo, linha, severidade, descrição) das respostas do modelo, ao invés de acumular o texto bruto completo.

Acumular respostas completas consome o contexto rapidamente. Findings estruturados permitem múltiplas rodadas sem explodir o token budget.

Structured extraction, findings schema, token efficiency, JSON output parsing.

O mecanismo que instrui o modelo a revisar com perspectiva diferente em cada rodada: engenheiro de software, especialista em segurança, ou SRE de produção.

Um único ponto de vista encontra um subconjunto dos problemas. Personas diferentes ativam diferentes heurísticas e encontram bugs distintos.

Persona rotation, system prompt por rodada, bias de revisão, cobertura multi-perspectiva.

A fase final do loop que agrega todos os findings das rodadas em um relatório estruturado com priorização por severidade.

Raw findings de múltiplas rodadas são barulhentos. A sumarização torna o output acionável para o desenvolvedor.

Findings aggregation, deduplicação, priorização por severidade, formato do relatório final.

A regra que toda saída do loop deve produzir output visível para o usuário: seja um relatório completo, uma mensagem de erro, ou confirmação explícita de "nenhum problema encontrado".

Silêncio é ambíguo. O usuário não sabe se o loop terminou com sucesso ou falhou silenciosamente. Saídas explícitas constroem confiança.

Saídas explícitas, never-silent failure, feedback ao usuário, zero findings report.

Quatro slash commands adicionados no sexto prompt: start (iniciar sessão), stop (encerrar), status (estado atual) e doctor (diagnóstico).

Um plugin sem ferramentas de operação é uma caixa preta. Os comandos tornam o sistema inspecionável e controlável pelo usuário.

Slash commands, operabilidade, /claudex:start, /claudex:stop, /claudex:status, /claudex:doctor.

O comando de diagnóstico que verifica a saúde completa do plugin: arquivos presentes, permissões corretas, estado consistente, dependências disponíveis.

Problemas de instalação e configuração são a causa mais comum de "não funciona". O doctor elimina o debug manual linha por linha.

Health check, verificação de dependências, validação de configuração, output estruturado de diagnóstico.

A fase de planning que ocorre antes do primeiro loop: Claude entrevista o usuário sobre o escopo, arquivos relevantes e critérios de qualidade antes de iniciar as rodadas.

Sem planejamento, o loop revisa tudo com a mesma granularidade. A entrevista foca o esforço nos arquivos e preocupações que realmente importam.

Planning phase, scoping interview, context gathering, focused review.

O último prompt que percorre sistematicamente cada caminho de falha do sistema, adicionando guardrails, validações e mensagens de erro claras onde estavam faltando.

Caminhos de erro são onde os sistemas falham em produção. O safety pass força uma revisão estruturada de todos os "e se der errado".

Error path audit, guardrails, defensive programming, error message quality, failure mode coverage.

A estratégia de teste em três camadas: testes de plataforma (o hook registra corretamente?), smoke tests (o plugin inicia?) e e2e sintético (uma sessão completa funciona?).

Cada camada testa diferentes garantias. Pular camadas deixa classes inteiras de bugs sem cobertura.

Platform tests, smoke tests, e2e sintético, test pyramid para plugins Claude Code.

O processo de empacotar, documentar e publicar o plugin — mais o roadmap do que a v2 adiciona: configuração por projeto, integração com CI e novas personas.

Shipar é diferente de "funciona na minha máquina". O processo de publicação revela problemas de documentação e configuração que o desenvolvimento não revela.

Plugin packaging, documentação de instalação, changelog, v2 roadmap.

Comparação direta do código antes e depois do Prompt 07: o que mudou, quais caminhos de erro foram adicionados, quais validações faltavam.

Ver o delta concreto torna o valor do safety pass tangível. Abstrações sobre "qualidade" não convencem — diffs convencem.

Diff analysis, before/after comparison, safety pass delta, code quality metrics.

Bugs reais encontrados durante a construção incremental que não teriam sido encontrados com um único prompt: race conditions, edge cases de estado e falhas de timeout.

Cada bug tem um "quando foi introduzido" e um "quando foi encontrado". O processo incremental comprime essa janela para zero.

Bug detection timing, race conditions, state corruption bugs, early detection value.

Análise dos problemas que surgiriam se todo o Claudex fosse solicitado em um único prompt gigante: inconsistências de arquitetura, falta de verificação entre componentes e bugs não detectados.

Entender os riscos do "one-shot" é o que motiva a disciplina incremental. Sem isso, o processo parece burocracia desnecessária.

One-shot risks, context collapse, unverified assumptions, architectural drift.

Comparação lado a lado de código gerado por um único prompt versus código gerado por sete prompts incrementais — em termos de consistência, edge case coverage e manutenibilidade.

Dados concretos importam mais que argumentos teóricos. Ver o código gerado lado a lado elimina a dúvida sobre se o processo adiciona valor real.

Code quality comparison, incremental vs one-shot, consistency metrics, maintainability score.

O custo de detectar um bug nas camadas superiores (que depende de uma camada incorreta) versus detectá-lo na própria camada: reescrita em cascata, risco de regressão e tempo perdido.

O custo de correção cresce exponencialmente com a distância entre introdução e detecção. Verificar cada camada é uma decisão econômica, não uma preferência estética.

Cascade rewrite cost, detection distance, technical debt accumulation, cost of late detection.

A ponte entre o curso de construção e o curso de uso: quem entendeu como o Claudex foi construído está pronto para operar ele com muito mais consciência.

Usar uma ferramenta que você construiu (ou entende em profundidade) é fundamentalmente diferente de usar uma caixa preta. Você sabe o que fazer quando algo dá errado.

Builder's advantage, deep usage, debugging with internals knowledge, curso-claudex.html.

O padrão de escrever um documento de especificação antes de qualquer prompt de código — definindo componentes, responsabilidades e invariantes explicitamente.

Sem SPEC, o modelo improvisa arquitetura em cada prompt. Com SPEC, cada prompt é uma implementação de uma decisão já tomada.

SPEC-first, architecture before code, explicit invariants, design document como primeiro artefato.

O princípio de implementar a propriedade de fail-open no primeiro prompt, antes de qualquer lógica de negócio, garantindo que falhas nunca bloqueiam o trabalho.

Adicionar fail-open retroativamente é muito mais arriscado — você precisa auditar cada caminho de erro novo. Começa com fail-open é uma decisão de arquitetura.

Safety-first architecture, fail-open como invariante, defensive by default, graceful degradation.

A disciplina de testar e verificar cada camada antes de iniciar o prompt seguinte — nunca construir sobre fundação não verificada.

Bugs se multiplicam quando camadas incorretas recebem camadas adicionais. A verificação por camada mantém o custo de correção constante.

Layer verification, test before next prompt, solid foundation principle, incremental validation.

O padrão de persistir todo estado relevante em arquivo, nunca em variáveis de processo ou memória — tornando o estado inspecionável e recuperável.

Estado implícito é invisível para debug e desaparece em crashes. Estado explícito em arquivo sobrevive a reinicializações e pode ser inspecionado com qualquer editor.

Explicit state, file-based persistence, observable state, crash recovery.

A prática de verificar cada função primitiva (escrita atômica, leitura de estado, CAS) de forma isolada antes de compor o sistema completo.

Falhas em composições são difíceis de atribuir. Primitivos verificados individualmente tornam falhas de composição isoláveis imediatamente.

Unit isolation, primitive testing, bottom-up verification, composition safety.

A sequência universal: SPEC → Scaffold → Estado → Lógica principal → Utilitários → Safety pass — aplicável a qualquer projeto, não apenas ao Claudex.

Esta sequência não é específica do Claudex — é um framework reutilizável para qualquer sistema que precisa ser confiável em produção.

Universal build sequence, SPEC→Scaffold→State→Logic→Utils→Safety, reusable framework.

Template completo de SPEC com todas as seções obrigatórias, aplicado ao hook de linting como exemplo concreto.

Um SPEC ruim leva a prompts que reimaginam a arquitetura. Um bom SPEC torna cada prompt uma implementação mecânica de uma decisão já tomada.

SPEC template, seções obrigatórias, exemplo de linting hook, decisões de design explícitas.

A heurística para decidir a granularidade de cada prompt: um prompt por camada verificável, sem misturar concerns que precisam de verificação independente.

Prompts grandes demais perdem a vantagem incremental. Prompts pequenos demais criam fricção sem benefício. A granularidade certa é uma skill que se aprende na prática.

Prompt granularity, one concern per prompt, verification boundary, decomposition heuristics.

A sequência obrigatória de construção: (1) scaffold com fail-open, (2) máquina de estados, (3) lógica principal, (4) safety pass — nesta ordem, sempre.

Inverter a ordem cria problemas: estado adicionado depois quebra a lógica existente, safety pass no início não tem o que auditar. A ordem não é arbitrária.

Build order dependency, scaffold-first, state before logic, safety as final pass.

Critérios explícitos de "pronto para o próximo prompt" — o que testar, o que verificar manualmente e quais propriedades confirmar antes de avançar.

Sem critérios explícitos, "funciona" é subjetivo. Critérios explícitos tornam a verificação sistemática e reproduzível.

Definition of done, layer acceptance criteria, verification checklist, gate conditions.

Como adaptar o conceito de personas de revisão (engenheiro, segurança, SRE) para outros domínios: frontend, data pipeline, CLI tool ou API.

As personas do Claudex são específicas para um plugin de revisão de código. Outros sistemas precisam de perspectivas diferentes — mas o mecanismo é o mesmo.

Domain-specific personas, perspective mapping, review coverage, multi-angle analysis.

Checklist universal de segurança para qualquer plugin Claude Code: fail-open verificado, estado atômico, todos os exit codes testados, mensagens de erro claras, documentação de instalação completa.

Um checklist transforma o safety pass de exercício subjetivo em processo auditável. Cada item tem um teste concreto associado.

Pre-ship checklist, safety audit, exit code coverage, documentation completeness.