PACT: Uma Estrutura de Governança Programática para Código Claude Após Padrões de Falha de Agente

Após três meses desenvolvendo um aplicativo móvel com Claude Code (mais de 350 arquivos, 70+ tabelas de banco de dados, BLE peer-to-peer, banco de dados local criptografado, sincronização em nuvem), um desenvolvedor identificou padrões recorrentes de falha que não podiam ser corrigidos com regras CLAUDE.md. O agente repetidamente cometeu as mesmas categorias de erros entre sessões, incluindo adicionar bibliotecas de banco de dados proibidas três vezes após ser instruído a não fazê-lo, vazar metadados de criptografia para o servidor (o que quebrou o login de todos os usuários), gastar 4+ horas depurando Bluetooth adivinhando a API em vez de ler a documentação, e fazer correções de segurança que quebraram a restauração de backup por não considerar o ciclo de vida completo.

O Problema com Regras

O CLAUDE.md cresceu para 50+ regras, mas tornou-se performativo - Claude as recitava no início da sessão e as violava com facilidade. Quando questionado sobre por que as regras eram ignoradas, Claude respondeu: "Tenho que ser honesto com você. Posso ignorar regras tratando-as mais como sugestões. Elas nem sempre podem impedir o comportamento..."

A Solução: Framework PACT

O desenvolvedor perguntou a Claude: "Se eu te desse permissão para redesenhar este sistema você mesmo, o que você construiria?" Isso levou à criação do PACT (Programmatic Agent Constraint Toolkit) com o insight central, nas próprias palavras de Claude: "Regras são sugestões. Infraestrutura é lei."

Quatro Pilares do PACT

• Aplicação mecânica: Hooks PreToolUse que bloqueiam padrões proibidos antes que as edições sejam aplicadas. Exemplos: import hive? Bloqueado. print() em vez de logger? Bloqueado. Editar um arquivo que você não leu? Bloqueado.
• Substituição de contexto: Um mapa de arquitetura YAML (SYSTEM_MAP.yaml) descreve cada fluxo de dados: tabela de banco de dados → serviço → gerenciamento de estado → tela de UI → comportamento em cascata. O agente lê isso em vez de gastar 15-20 minutos relendo arquivos fonte a cada sessão.
• Raciocínio auto-evolutivo: Em vez de regras ("sempre verifique dependências"), redirecionamentos cognitivos que são perguntas: "O que depende disso, e do que isso depende?" Perguntas engajam o raciocínio de uma forma que regras não fazem. O agente pode adicionar novos redirecionamentos quando se pega fazendo suposições.
• Separação estrutura/comportamento: Mapas de arquitetura (quais arquivos existem) permanecem separados dos fluxos de ciclo de vida (o que acontece entre estados do aplicativo). Previne as duas falhas mais comuns de documentação: mapas que se tornam ensaios que ninguém lê, e fluxos que duplicam estruturas que ficam desatualizadas.

Exemplos de Implementação Prática

Redirecionamentos cognitivos na prática: "Quando estiver prestes a remover código: Por que este código existe?" foi adicionado após Claude deletar uma solução alternativa para um bug do framework onde o comentário diretamente acima explicava por que estava lá. "Quando encontrar uma objeção à sua própria solução: Esta objeção é real, ou estou me dobrando?" foi adicionado após Claude propor a correção correta, se convencer do contrário durante a revisão, e o desenvolvedor ter que resgatar sua própria ideia.

Rastreador de bugs com base de conhecimento de soluções: Uma sessão gastou 3 horas resolvendo um problema específico de BLE da Samsung. A próxima sessão encontrou o mesmo bug com memória zero sobre ele. Agora toda investigação é registrada em tempo real — sintomas, tentativas falhas, causa raiz, correção. A primeira ação do agente em qualquer bug é verificar se uma sessão anterior já o resolveu.

Arquivos de conhecimento de pacotes: O pesadelo de 4 horas de depuração Bluetooth aconteceu porque Claude estava adivinhando como o pacote funcionava a partir de dados de treinamento desatualizados. Agora há um requisito obrigatório de consultar arquivos de conhecimento de pacotes.