O padrão não pode morar no prompt

O modo de falha não é sintaxe

Um agente de código produz saída plausível mais rápido do que um revisor consegue conferir. Esse é o problema inteiro, e a primeira vez que ele aparece você diagnostica errado, porque procura pelo erro que compilador pega.

O erro que importa é outro. É um caminho de arquivo inventado com confiança. É a API de uma biblioteca na major errada, escrita com a segurança de quem leu a documentação. É uma métrica sem fonte, que passa por três revisões porque parece o tipo de número que alguém mediu. Nada disso quebra o build. Tudo isso chega em produção.

Quando eu rodava desenvolvimento assistido por agentes em mais de vinte repositórios, esse modo de falha deixou de ser um incidente e virou uma taxa. Ele não ficava contido em um projeto: se acumulava a cada projeto novo, porque cada projeto novo começava do zero.

O padrão era propriedade do prompt

A parte que levei mais tempo para ver é que o problema não era de qualidade. Era de propriedade.

A qualidade do trabalho do agente era propriedade do prompt. Ou seja: de quem por acaso escreveu aquele prompt, naquele dia, com a paciência que tinha naquela hora. Um bom prompt produzia bom código. O mesmo pedido na segunda-feira seguinte, escrito por outra pessoa ou pela mesma pessoa com menos tempo, produzia outra coisa.

Não havia como declarar um padrão uma vez e fazer toda sessão futura obedecê-lo. E, o que é pior, não havia como saber depois se a sessão obedeceu.

Um padrão que vive no prompt não é um padrão. É um hábito, e hábito não sobrevive a pressão de prazo.

A IA não lê mentes. Ela lê documentação.

Essa é a primeira das duas frases que sustentam o framework, e ela é a fácil. Quanto mais estruturado e completo o contexto, mais consistente o resultado. Ninguém discute.

A segunda frase é a que faz trabalho:

Engenharia de contexto é achar o menor conjunto possível de tokens de alto sinal que maximizam a probabilidade do resultado desejado.

As duas juntas formam uma tensão, e é essa tensão que define o desenho. A primeira empurra para documentar mais. A segunda proíbe que documentar mais signifique carregar mais em todo turn. Uma janela de contexto cheia de doutrina irrelevante não é um agente bem informado: é um agente com menos espaço para o problema dele.

A saída não é escrever menos. É escrever em camadas e carregar sob demanda. O agente recebe o índice, não o acervo, e desce quando o trabalho pede.

Três camadas, cada uma respondendo o que a anterior não responde

Camada	Pergunta	Dono
Negócio	Por que isso existe?	Time de negócio
Produto	O que está sendo construído, e para quem?	Time de produto
Engenharia	Como se constrói, e como se opera?	Time de engenharia

A base é Domain-Driven Design, e a herança que importa é a linguagem ubíqua: um conceito, um termo, uma definição. Um glossário de domínio é o documento mais barato de escrever e o que mais reduz invenção, porque a maior parte do que um modelo inventa é vocabulário.

O que a divisão em camadas compra não é organização. É dono. Uma camada sem dono declarado é uma camada que ninguém atualiza, e doutrina desatualizada é pior que doutrina ausente: ela é obedecida.

Dois diretórios: o que a IA sabe, e como ela age

Aqui está a decisão estrutural do framework.

.contexts/   o que a IA sabe    conhecimento
.claude/     como a IA age      executor

.contexts/ é a fonte única de verdade, em Markdown puro, sem nada específico de ferramenta. .claude/ é a interface que o agente carrega de fato: skills descobertas por demanda, agentes especializados que declaram cada um quais contextos precisam ler, hooks ligados a eventos do ciclo de vida da sessão.

E a regra que faz os dois funcionarem: a camada operacional referencia por caminho, ela nunca repete.

O motivo é o que acontece quando você repete. Uma rule copiada dentro de uma skill cria duas versões do mesmo padrão. As duas ficam certas por algumas semanas. Depois uma muda, e a que sai do lugar é sempre a cópia, porque quem edita a doutrina edita a fonte. Aí o agente carrega a cópia velha e obedece com precisão a um padrão que já foi revogado. Referência por caminho não tem esse modo de falha.

Antialucinação é rule, não etapa de revisão

Essa é a inversão que mais custou para acertar.

O instinto é tratar invenção como problema de revisão: gera, depois confere. Não funciona, porque o volume de saída de um agente é maior que a banda de revisão de um humano. Se conferir é a etapa seguinte, ela é a etapa que se corta quando o prazo aperta.

Então grounding é rule, e ela é imperativa: todo caminho de arquivo, todo símbolo, toda versão de biblioteca é confirmada em disco antes de ser citada. Não depois. A verificação precede a geração.

Isso é o inverso de como o modelo quer trabalhar, e é por isso que precisa ser rule e não recomendação. Um modelo tem uma resposta plausível disponível de graça e a verificação custa uma chamada de ferramenta. Sem uma regra que inverta a ordem, o barato ganha sempre.

O preço de uma rule sempre-ativa

Rules se dividem em duas: sempre-ativas, carregadas em todo turn, e path-scoped, carregadas quando o arquivo que está sendo tocado bate o glob.

O corte parece administrativo e é econômico. Uma rule sempre-ativa custa tokens em toda interação, para sempre. Então o preço de promover uma rule para sempre-ativa é deliberadamente alto, e a pergunta que decide é uma só: isso precisa valer mesmo quando o agente não sabe que precisa?

Segurança precisa. Validação de entrada precisa. Convenção de commit precisa, porque o agente não sabe que vai commitar até commitar. Regra de acessibilidade não precisa: ela vale quando se toca um componente, e o glob sabe disso melhor que eu.

Sem esse corte, o framework tem um caminho de degradação óbvio e silencioso. Toda rule nova parece importante para quem a escreve, todas viram sempre-ativas, e em seis meses metade da janela de contexto é doutrina que não se aplica ao arquivo aberto.

Imposição mecânica, ou não é imposição

Doutrina escrita é sugestão até que algo a recuse.

Um hook de pré-ferramenta rejeita commit que não siga Conventional Commits. Um hook de parada alerta sobre afirmação sem grounding. E o que eu mais gosto: um hook de início de sessão reinjeta a skill de bootstrap depois de cada compactação de contexto.

Esse último resolve um defeito que eu não tinha antecipado. Sessão longa comprime contexto, e o que se perde primeiro é justamente a instrução do começo, porque ela está mais longe. O agente segue trabalhando, com a mesma confiança, sob nenhum padrão. Nada sinaliza. Perder contexto não pode zerar o padrão em silêncio, e a única forma de garantir isso é um evento de ciclo de vida, não uma boa prática.

Onde a imposição pode ser mecânica, ela é. Onde não pode, é rule, e a rule é escrita como imperativo, não como conselho.

O que este framework não faz

Aqui está a parte que costuma faltar em texto sobre framework próprio.

O DDC tem duas leituras, e elas não descrevem a mesma coisa. A especificação geral tem quatro camadas: as três acima mais Operações, que carrega processo por departamento, handoffs entre áreas, SLAs internos, ferramentas, rituais, infraestrutura, monitoramento e incidentes. O que eu rodo em repositório de código tem três, e dobra a metade técnica de Operações para dentro de Engenharia.

A metade técnica sobrevive bem a essa dobra. Infraestrutura, ambientes, monitoramento com threshold por sinal, severidade de incidente, on-call, post-mortem: tudo isso é processo de engenharia e mora em Engenharia sem forçar nada.

A metade organizacional não sobrevive. Processo de marketing, de vendas, de jurídico, handoff entre áreas, SLA entre áreas, ritual de empresa: nada disso tem casa numa árvore de três camadas dentro de um repositório de código. E nem deveria ter. Um repositório de código não é lugar de calendário editorial.

O custo dessa dobra se mede na tabela da própria especificação, que lista de quais camadas cada área depende:

Área	Camadas de que depende	Atendida pela leitura de três camadas?
Produto	Negócio, Produto, Engenharia	Sim
Engenharia	Produto, Engenharia, Operações	Sim, a Operações dela foi dobrada para dentro
Marketing	Negócio, Produto, Operações	Não
Vendas	Negócio, Produto, Operações	Não
Jurídico	Negócio, Operações	Não
Suporte	Produto, Operações	Não
Sucesso	Produto, Negócio, Operações	Não

Duas de sete.

Então a frase honesta é esta: o framework que eu rodo é um framework de engenharia. O framework que eu especifiquei é um framework de empresa. Mesmo nome, e a diferença é uma camada.

Escrever isso é mais útil do que escolher entre as duas, porque a escolha muda dependendo de quem adota. Um time de engenharia que adotar a leitura de quatro camadas vai carregar processo de área que não é dele. Uma empresa que adotar a de três vai descobrir a lacuna quando marketing pedir contexto e não tiver onde procurar.

O que ainda está aberto

Três coisas.

A primeira é se a camada de Operações vira quarta camada aqui, ou artefato separado, ou se os dois escopos passam a ter nomes diferentes. As três resolvem, com custos diferentes.

A segunda é medição de impacto. O framework tem um roteiro de implementação cujo último passo é medir tempo economizado e qualidade, e é o passo que eu não fiz. O que existe medido é inventário: quanta doutrina, quantos repositórios, quanto histórico legível. Isso está contado em /method, com o recorte de cada número escrito ao lado. Não é a mesma coisa que provar produtividade, e trocar um pelo outro seria exatamente o tipo de número que este framework existe para impedir.

A terceira é o que sempre fica aberto num framework que roda em produção: a doutrina que foi escrita antes de existir contra-exemplo. Toda rule aqui nasceu de um defeito real, e as que ainda não custaram nada são as que eu menos confio.

O sistema que serve este texto foi construído dentro do framework, sob gate de build, com teste que recusa afirmação sem prova. Não é a demonstração mais espetacular disponível. É a que eu consigo mostrar.