Protocolo P.R.O.C.E.D.

Identidade do operador

Você é o arquiteto do sistema. Não escreve código primeiro: escreve protocolo. Não chuta lógica de negócio: levanta os requisitos. Trata o agente de IA como executor competente, mas que precisa de regras explícitas, dados estruturados e supervisão em decisões caras.

A missão é construir automações determinísticas (que repetem o mesmo resultado) sobre uma camada probabilística (o LLM). Isso só funciona se a lógica de negócio estiver fora do modelo — em arquivos, em regras versionadas, em scripts atômicos. O LLM decide o quê fazer; os scripts garantem como fazer sempre igual.

Princípio mestre: confiabilidade vence velocidade. Protocolo vence improviso.

Setup obrigatório

Antes de qualquer linha de código, crie a estrutura de memória do projeto. São 4 arquivos, cada um com função distinta:

A regra de bloqueio

Você está proibido de escrever scripts antes de:

1. As 5 perguntas de Pergunta (P) estarem respondidas
2. O schema de dados (entrada/saída em JSON) estar escrito em CLAUDE.md
3. O plano em tarefas.md estar aprovado

Sem esses três, não existe código. Existe achismo.

Por que esses arquivos importam

CLAUDE.md é a lei — não muda sem motivo. Os outros três são memória — mudam o tempo todo. A separação evita o erro mais comum: misturar regra com log, e perder rastro tanto de uma coisa quanto da outra.

Princípios operacionais

Quatro regras que governam o comportamento do agente em todas as etapas. Sem elas, o protocolo vira teatro burocrático.

1. Reversível vs. irreversível

Decisão reversível (renomear arquivo local, tentar uma abordagem, criar um teste) → executa direto.

Decisão irreversível (escolher banco de dados, definir sistema de auth, alterar schema em produção, deletar dados, fazer deploy, push em main) → para, alinha, espera ordem explícita.

O critério é simples: se desfazer custa caro, peça autorização antes.

2. Stack default, não modinha

Fixe um conjunto de ferramentas-padrão em CLAUDE.md (ex: Next.js + Supabase + Vercel + Railway). Use por padrão. Só desvie quando o problema exige desvio — e justifique no evolucao.md.

Trocar de stack a cada projeto multiplica o tempo de setup, fragmenta conhecimento e cria dívida técnica que ninguém mantém.

3. Verificação real, não cosmética

"Compilou" não significa "funciona". tsc passar não prova nada para o usuário final.

• Frontend: subir servidor de dev e testar no navegador.
• Backend: disparar request real no endpoint, não só rodar typecheck.
• Se não for possível testar, o agente avisa antes de declarar pronto, em vez de fingir que está.

4. Isolamento e ordens explícitas

O agente atua só no escopo do projeto atual. Não toca em outros repos, projetos cloud, portas, recursos paralelos. Ações destrutivas (deploy em produção, drop de tabela, force push) só acontecem com ordem direta do usuário — nunca por inferência, nunca por "achou que era o próximo passo lógico".

P — Pergunta (Descoberta)

Antes de construir, levante os requisitos com 5 perguntas obrigatórias:

1. Desfecho primário — qual é o único resultado que define sucesso? Se você não consegue responder em uma frase, o projeto não está claro o suficiente.
2. Integrações — quais sistemas externos entram (Slack, Hotmart, Notion, Supabase, APIs)? As credenciais existem e estão acessíveis?
3. Fonte da verdade — onde os dados primários moram? Banco? Planilha? API de terceiro? Definir isso evita duplicação e inconsistência.
4. Entrega — formato e destino final do output? Mensagem no Slack? Linha no Sheets? Página no Notion? E-mail HTML?
5. Regras de comportamento — tom de voz, restrições, e principalmente: o que o sistema nunca pode fazer?

A lei do dado antes do código

O schema de entrada e saída em JSON precisa estar escrito em CLAUDE.md antes de qualquer script. Não é detalhe — é o que torna a automação determinística. Sem schema, o LLM inventa formato a cada execução, e o sistema fica imprevisível.

Pesquisa antes de construir

Antes de codar, varra GitHub, docs oficiais e fóruns por soluções existentes. Reinventar SDK, parser ou cliente que já existe é desperdício — e pior: é menos confiável do que a versão mantida pela comunidade.

R — Reconhecimento (Conectividade)

Antes de construir lógica em cima das integrações, prove que cada conexão funciona isoladamente.

Handshake mínimo

Para cada serviço externo, escreva um script mínimo que faz uma chamada e confirma resposta válida. Exemplos:

• Notion: criar uma página de teste e ler de volta
• Supabase: rodar select 1 e confirmar conexão
• API externa: fazer um GET em endpoint público de status

Se o handshake falhar, não avance. Lógica complexa em cima de conexão quebrada não é progresso — é dívida técnica acumulando.

Verificação completa

• Cada credencial do .env testada isoladamente, não em conjunto
• Limites de rate-limit conhecidos e anotados em achados.md
• Erros conhecidos da API (códigos, mensagens) mapeados
• Se a integração precisar de auth complexa (OAuth, refresh tokens), o fluxo inteiro testado antes da lógica de negócio

O — Organização (Arquitetura em 3 camadas)

LLMs são probabilísticos por natureza. Lógica de negócio precisa ser determinística por exigência. A separação em 3 camadas resolve essa tensão.

Camada 1 — Protocolos (/protocolos/)

Documentos .md em linguagem natural que descrevem como cada tarefa deve ser feita. Cada protocolo cobre:

• Objetivo da tarefa
• Entradas esperadas (com schema)
• Lógica passo a passo
• Saída esperada (com schema)
• Casos de borda e como tratar cada um

Regra de ouro: mudou a lógica? Atualize o protocolo antes do código. O protocolo é a fonte da verdade; o código é só a implementação dela.

Camada 2 — Roteamento (decisão)

A camada de raciocínio. Recebe o pedido do usuário, identifica qual protocolo se aplica, qual ferramenta chamar, em qual ordem, e passa os dados adiante.

Não executa tarefas complexas sozinha. A função dela é decidir e despachar, não processar.

É aqui que o LLM brilha: interpretação de intenção, escolha contextual, encadeamento. A lógica determinística fica nas Camadas 1 e 3.

Camada 3 — Ferramentas (/ferramentas/)

Scripts Python (ou Node, ou outra coisa) atômicos — cada um faz uma coisa só, e faz bem. Características obrigatórias:

• Determinísticos: mesma entrada, mesma saída
• Testáveis: dá pra rodar isoladamente com input mockado
• Sem efeito colateral oculto: o que faz está documentado
• Segredos no .env, nunca hardcoded
• Arquivos intermediários em /.tmp/, descartáveis

Por que separar assim

Quando a lógica de negócio está dentro do prompt do LLM, o sistema muda de comportamento sem aviso a cada release de modelo. Quando está fora — em scripts versionados — o comportamento é estável, auditável e corrigível.

C — Curadoria (Refinamento da entrega)

Funcionar não é o mesmo que entregar. O output precisa estar apresentável antes de subir pra produção.

O que checar antes de declarar pronto

• Formatação do payload: blocos do Slack montados certo, layouts do Notion com hierarquia, HTML de e-mail testado em cliente real (não só no preview do código)
• UI/UX: se houver dashboard ou frontend, CSS limpo, layout intuitivo, loading states, mensagens de erro claras
• Feedback antes do deploy: mostrar o resultado renderizado para o usuário e esperar aprovação antes de subir

Um sistema que funciona mas entrega resultado feio ou mal estruturado é tratado pelo usuário como sistema quebrado. A diferença entre "protótipo" e "produto" mora aqui.

E — Execução (Deploy e gatilhos)

Levar a lógica do ambiente local para produção, com automação ligada.

Checklist de deploy

1. Migração para nuvem — código em servidor, não em laptop
2. Gatilhos configurados — cron, webhook ou listener, conforme o caso
3. Variáveis de ambiente carregadas no ambiente de produção (não esquecer de nenhuma)
4. Monitoramento mínimo — como você saberá se quebrou? Logs estruturados, alerta em caso de erro, healthcheck endpoint
5. Rollback definido — se quebrar, como volta?

Limite operacional do agente em ações irreversíveis

O agente pode: versionar (git add/commit/push), rodar testes, preparar configs, escrever arquivos de deploy.

O agente não pode sem ordem direta: disparar deploy em produção (vercel --prod, railway up), alterar schema de banco em produção, tocar em recursos cloud que não sejam o atual, fazer push forçado em main.

A ordem precisa ser explícita e direta: "faz o deploy", "sobe pra produção agora". Inferência não conta.

Intermediário vs. entregável

• /.tmp/ é descartável: logs, dados crus, arquivos de passagem. Pode apagar a qualquer hora.
• Payload na nuvem (Sheets, banco, dashboard) é o entregável real. O projeto só está concluído quando o resultado chega ao destino final em produção, não quando "rodou na minha máquina".

D — Documentação (Loop de aprendizado)

Sistema que não aprende com a falha repete a falha. A documentação não é burocracia — é o que separa automação madura de gambiarra.

Após cada tarefa relevante

• evolucao.md recebe: o que foi feito, erros encontrados, decisões tomadas, testes rodados
• achados.md recebe: descobertas reutilizáveis ("API X exige header Y", "rate limit é 5 req/seg", "webhook do Z entrega duplicado às vezes")
• CLAUDE.md muda só quando: schema mudou, regra nova foi acordada, ou arquitetura foi alterada

Loop de autocorreção quando algo quebra

Quando uma ferramenta falha:

1. Analisar — ler o stack trace completo. Não chutar a causa.
2. Corrigir — ajustar o script com base no erro real, não no que você imagina que é.
3. Testar — confirmar que a correção resolve o caso e não introduz regressão.
4. Atualizar o protocolo — registrar o aprendizado no .md correspondente em /protocolos/, para que esse erro nunca mais apareça em projeto futuro.

O passo 4 é o que a maioria dos times pula. É exatamente o que diferencia equipe que melhora ao longo do tempo de equipe que tropeça nas mesmas pedras.

Hierarquia da memória

CLAUDE.md é a lei. Os arquivos de planejamento (tarefas.md, evolucao.md, achados.md) são a memória. Lei muda raramente; memória cresce todo dia.

Estrutura de pastas

projeto/
├── CLAUDE.md          # Constituição (schemas, regras, invariantes)
├── tarefas.md         # Plano de execução
├── evolucao.md        # Diário do projeto
├── achados.md         # Descobertas reutilizáveis
├── .env               # Credenciais (testadas em Reconhecimento)
├── /protocolos/       # Camada 1 — POPs em markdown
├── /ferramentas/      # Camada 3 — scripts atômicos
└── /.tmp/             # Bancada de trabalho descartável

Cartão de bolso

Os 4 erros que matam o projeto

1. Pular a Pergunta. Sem schema definido em CLAUDE.md, o código serve pro problema errado. Você só descobre isso quando já gastou horas escrevendo a coisa errada.
2. Misturar camadas. Lógica de negócio dentro do prompt do LLM = sistema que muda de comportamento sem aviso. Sempre fora do modelo, sempre em script versionado.
3. Verificar de forma cosmética. "Compilou" não é "funciona". Subir servidor, abrir navegador, disparar request — sem isso, você está entregando esperança, não software.
4. Não documentar erros. Cada falha não-documentada vira falha que se repete em outro projeto. O loop de Documentação (passo 4 do autocorrigir) é o que diferencia time que evolui de time que tropeça nas mesmas pedras.