Uma Camada de Governança de 7 Arquivos para Prevenir o Desvio de Sessão de LLM

Um desenvolvedor no r/LocalLLaMA compartilhou uma solução para impedir que assistentes de codificação baseados em LLM, como o Claude, desfaçam silenciosamente decisões arquiteturais entre sessões. Em vez de tratar as sessões de LLM como conversas, agora as tratam como processos sem estado que precisam de um protocolo.

O Problema Central

Cada sessão de LLM começa com memória zero. Você reexplica, o modelo reinterpreta e ele se desvia com confiança. O desenvolvedor observou: "Você nem vai perceber até estar bem dentro do projeto, talvez três ou quatro arquivos adiante, ou quem sabe até na última parte do projeto."

A Camada de Governança de 7 Arquivos

A solução não é um prompt melhor, mas uma camada de governança que qualquer modelo pode ler e operar imediatamente dentro dela. O sistema usa sete arquivos, cada um com uma preocupação específica, sem sobreposição:

• active_context.md - Controlador da sessão, define o que está no escopo no momento
• contracts.md - Lei comportamental, esquemas de dados, valores de enumeração, comportamento exigido
• agent_core.md - Disciplina de execução, como operar, validar, relatar
• agent_project.md - Intenção do projeto, por que este sistema existe, resultados esperados
• decisions.md - Registro de ADR, escolhas não óbvias e por que foram aceitas
• build_plan.md - Roteiro do módulo, ordem de implementação e entregas
• state.md - Diário vivo, o que foi feito, o que mudou, o que resta

Decisões de Design Principais

O desenvolvedor explicou duas separações críticas:

Separar contracts.md de agent_core.md: "Quando um conflito comportamental aparecia, o modelo não tinha como saber a qual camada deferir. Era uma regra de esquema ou uma preferência de execução? Quando estão separados, a hierarquia é inequívoca, os contratos sempre vencem."

Incluir decisions.md: "Quase pulei isso ('Vou lembrar'). Três semanas depois, não conseguia reconstruir por que escolhemos Postgres em vez de SQLite para um módulo específico. O registro ADR existe exatamente porque 'Vou lembrar' não é um protocolo."

O Loop Operacional

Toda sessão segue esta ordem, sem exceções:

1. Ler active_context.md → extrair o que está no escopo
2. Reaterrar contra contracts.md → regras comportamentais travadas
3. Confirmar restrições operacionais de agent_core.md + agent_project.md
4. Verificar decisions.md → não reverter escolhas aceitas
5. Executar apenas o que active_context.md autoriza, conforme build_plan.md
6. Validar com testes — não declarar como concluído sem evidências
7. Atualizar state.md com resultados factuais
8. Se uma nova decisão não trivial foi tomada, registrá-la em decisions.md

Impacto no Fluxo de Trabalho

O bloqueio de escopo do active_context.md provou ser particularmente valioso: "Antes disso, eu começava uma sessão para corrigir um bug e acabava refatorando um módulo não relacionado porque 'estava ali mesmo'. Parecia produtivo......... e era."