🏗️ Esqueleto primeiro
O scaffold é a estrutura vazia do sistema — arquivos criados, interfaces declaradas, pontos de integração estabelecidos, mas sem lógica real. É o primeiro prompt de qualquer build bem-feito. Define o contrato externo antes que qualquer comportamento seja implementado.
🏗️ O que o scaffold entrega
- •Estrutura de diretórios e arquivos do plugin
- •Hooks registrados com fail-open por padrão
- •Interface de invocação definida (mas não implementada)
- •Configuração mínima para o sistema ser instalado
💡 Por que scaffold antes de lógica
Implementar lógica antes de ter estrutura é construir sobre areia. Quando a arquitetura se mostra inadequada no prompt 4, você reescreve tudo. Com scaffold verificado primeiro, prompts 2-8 são incrementos sobre uma fundação sólida.
⚙️ Estado antes do comportamento
Depois do scaffold, a segunda camada é a máquina de estados — representação explícita de quais fases o sistema pode estar e quais transições são válidas. Nenhum comportamento real é implementado até que o estado esteja verificado.
Estado inicial
Plugin instalado, sem sessão ativa. Aguardando primeiro trigger.
Execução ativa
Sessão em andamento. Transições são controladas pelo hook de ciclo de vida.
Sessão encerrada
Ciclo completo. Sistema retorna para idle após cleanup.
Estado implícito: o bug mais difícil de debugar
Sem máquina de estados explícita, o sistema acumula estado implícito — variáveis globais, flags booleanas, condições aninhadas. Cada um funciona em isolamento, mas a combinação cria comportamentos impossíveis de prever sem executar o código.
🧠 Lógica sobre estado
A terceira camada implementa o comportamento real — a lógica de negócio que faz o sistema útil. Esta camada só é construída depois que scaffold e estado estão verificados, porque a lógica depende de ambos para funcionar corretamente.
O que a camada de lógica implementa
- •Leitura do estado atual para tomar decisões
- •Execução das ações específicas de cada fase
- •Transições de estado baseadas em resultados
- •Integração com serviços externos (APIs, modelos)
💡 Lógica testável por isolamento
Com scaffold e estado verificados, a lógica pode ser testada com estado controlado — injetando fases específicas e confirmando o comportamento correto. Sem as camadas anteriores verificadas, cada teste da lógica também testa implicitamente as camadas anteriores.
🛡️ Segurança por último
O safety pass é a quarta e última camada — hardening do sistema com todas as primitivas de segurança. É aplicado sobre um sistema funcionalmente correto, não sobre um sistema em construção.
✓ Safety pass correto
- ✓Aplicado após lógica verificada
- ✓Adiciona fail-open em todos os caminhos de erro
- ✓Converte writes para write-then-rename
- ✓Adiciona versioning para CAS
✗ Safety pass incorreto
- ✗Aplicado enquanto lógica ainda tem bugs
- ✗Mascara bugs com tratamento de erro genérico
- ✗Segurança que protege comportamento incorreto
- ✗Bugs de lógica visíveis apenas em produção
⚠️ O que acontece quando você pula etapas
Cada padrão de bug em LLM coding tem um diagnóstico. A maioria não vem de código ruim — vem de sequência incorreta. Reconhecer o padrão permite diagnóstico rápido e regressão cirúrgica.
Bug de sequência #1: Lógica sem scaffold
Sintoma: Sistema funciona em testes mas falha ao instalar em outro ambiente
Causa: Estrutura de arquivos e pontos de integração foram assumidos, não especificados
Bug de sequência #2: Lógica sem estado explícito
Sintoma: Comportamento correto na primeira execução, incorreto nas seguintes
Causa: Estado implícito acumulado entre execuções sem representação formal
Bug de sequência #3: Segurança antes da lógica
Sintoma: Sistema "seguro" mas com resultados incorretos que nunca aparecem como erros
Causa: Tratamento de erro genérico suprimiu exceções que deveriam ter exposto bugs de lógica
🔄 Sequenciando seu próprio projeto
Mapear qualquer projeto nas quatro camadas e dividi-las em prompts atômicos é um processo mecânico. A dificuldade está em determinar a granularidade correta — cada prompt deve ser verificável em minutos, não horas.
O processo de sequenciamento
Regra de ouro da granularidade
Um projeto típico de plugin Claude Code tem 4-8 prompts. Abaixo de 4, cada prompt está fazendo demais. Acima de 8, a overhead de verificação começa a superar o benefício. Para projetos mais complexos, agrupe por subsistema — não exceda 8 prompts por subsistema.
✅ Resumo do Módulo 3.2
Próximo Módulo:
3.3 — Fail-Open e os Padrões de Segurança