Capítulo 8 — Quatro camadas de contexto

Contexto não é sinônimo de prompt

Um prompt é apenas uma das superfícies pelas quais informação chega ao modelo.

Quando um agente trabalha em software real, ele também depende de:

• regras de domínio;
• arquitetura;
• arquivos do repositório;
• documentação;
• ferramentas;
• estado da tarefa;
• decisões anteriores;
• testes;
• logs;
• permissões;
• memória operacional.

Isso muda a pergunta.

Não é mais:

“qual prompt eu devo escrever?”

É:

“qual informação precisa estar disponível, em que momento, para qual agente, com qual duração e com quais limites?”

Esse é o problema de Context Engineering.

A pilha de contexto

García organiza Context Engineering em três componentes centrais: contexto sources, contexto management e contexto orchestration. Evaluation, observability, governance e operations atuam como um harness transversal ao conjunto. ¹

Essa arquitetura ajuda a separar três perguntas que costumam ser misturadas:

1. de onde vem a informação?
2. como ela é selecionada, escrita, comprimida ou isolada?
3. como agentes e sistemas usam essa informação durante a execução?

Essas perguntas não são equivalentes.

Ter uma fonte disponível não significa que ela deva entrar inteira na janela ativa.

Ter contexto ativo não significa que ele deva permanecer depois da tarefa.

Ter memória persistente não significa que ela seja relevante para todo agente.

O erro dos dois extremos

Contexto insuficiente faz o agente adivinhar.

Contexto excessivo pode esconder o que realmente importa.

Hua et al. formulam o Minimal Sufficiency Principle: o valor do contexto está na suficiência para a tarefa, não no volume. O mesmo trecho apresenta Semantic Continuity como preservação da continuidade de significado, não mera continuidade de dados. ²

No método deste livro, isso produz duas regras simultâneas:

não carregue tudo.

não corte o significado necessário para decidir corretamente.

Essas regras entram em tensão.

Reduzir contexto demais remove relações importantes.

Acumular contexto demais mistura:

• histórico obsoleto;
• decisões já superadas;
• detalhes não relacionados;
• exceções de outras tarefas;
• instruções conflitantes.

Context Engineering é a disciplina de administrar essa tensão.

Quatro camadas para software

Para tornar o problema operacional, este livro usa quatro camadas.

Essa divisão é método deste livro.

Ela não é apresentada como taxonomia retirada de uma única fonte.

As quatro camadas são:

1. Contexto de Domínio
2. Contexto Persistente do Projeto
3. Contexto da Tarefa
4. Contexto Operacional

Cada uma tem origem, duração e risco diferentes.

Camada 1 — Contexto de Domínio

É o significado do problema.

Inclui:

• Ubiquitous Language;
• invariantes;
• regras de negócio;
• estados;
• relações entre conceitos;
• Bounded Contexts;
• exceções importantes.

Essa camada responde:

“o que estas palavras e regras significam neste sistema?”

Ela deve mudar mais devagar que a tarefa.

Quando uma regra de domínio muda, a consequência pode atravessar Specs, código, testes e dados.

Por isso, o Contexto de Domínio não deve ser reescrito informalmente em cada prompt.

Ele precisa ter fontes de verdade recuperáveis.

No nosso Companion, DOMAIN.md é uma implementação dessa ideia.

Não substitui documentação de domínio completa.

Serve para condensar o subconjunto necessário à mudança.

Camada 2 — Contexto Persistente do Projeto

É o conjunto de informações estáveis que ensinam como aquele repositório funciona.

Pode incluir:

• arquitetura;
• convenções;
• comandos;
• estrutura de diretórios;
• ferramentas;
• decisões arquiteturais;
• políticas;
• instruções para agentes;
• contratos compartilhados.

Essa camada responde:

“como trabalhamos neste sistema?”

Ela vive melhor em artefatos versionados que em instruções repetidas manualmente.

Exemplos:

• AGENTS.md;
• ADRs;
• CONTRIBUTING;
• runbooks;
• schemas;
• documentação de arquitetura;
• skills.

Camada 3 — Contexto da Tarefa

É o recorte temporário necessário para executar uma mudança específica.

Vem principalmente da Spec e da decomposição.

Pode incluir:

• outcome;
• escopo;
• fora de escopo;
• arquivos afetados;
• interfaces relevantes;
• acceptance criteria;
• exemplos;
• testes relacionados;
• decisões desta mudança;
• dependências imediatas.

Essa camada responde:

“o que preciso saber agora para entregar esta unidade de trabalho?”

Ela deve ser menor que o contexto total do projeto.

A tarefa não precisa carregar tudo que existe.

Precisa carregar o que é necessário para agir sem inventar.

É aqui que Minimal Sufficiency se torna prática.

Camada 4 — Contexto Operacional

É o que só existe durante ou depois da execução.

Inclui:

• logs;
• métricas;
• traces;
• resultado de testes;
• estado de CI;
• health checks;
• deploy IDs;
• incidentes;
• rollback;
• custos;
• evidências runtime.

Essa camada responde:

“o que está acontecendo de fato?”

Ela impede que o agente trabalhe apenas com intenção e documentação enquanto ignora o estado real do sistema.

Em operações, o contexto muda continuamente.

Por isso, precisa ser consultado sob demanda e ter timestamp/proveniência.

As camadas não devem virar um documento gigante

Separar camadas não significa concatená-las.

O objetivo é permitir composição seletiva.

Para uma tarefa pequena de UI:

• Domain: vocabulário e regra relevante;
• Project: convenções de frontend;
• Task: componente, comportamento e acceptance criteria;
• Operations: build e screenshot.

Para uma migração de banco:

• Domain: invariantes dos dados;
• Project: arquitetura de persistência;
• Task: schema alvo, sequência e compatibilidade;
• Operations: métricas, migration logs e rollback.

A quantidade muda.

A estrutura permanece.

Context isolation

Hua et al. discutem contexto isolation como forma de reduzir contexto pollution, separando janelas, instruções e permissões por função ou camada de trabalho. ³

Essa ideia é particularmente útil depois da decomposição do capítulo anterior.

Se duas tarefas são realmente independentes, elas não precisam compartilhar toda a mesma janela.

Cada unidade pode receber:

• seu objetivo;
• seu contrato;
• seus arquivos;
• suas ferramentas;
• suas permissões;
• sua evidência esperada.

O isolamento reduz contaminação entre tarefas.

Mas ele só funciona quando o handoff é explícito.

Isolamento sem contrato vira perda de informação.

Contrato sem isolamento pode virar excesso de contexto.

Contexto deve ser refreshable

Um contexto útil não é apenas correto no momento em que foi criado.

Ele precisa poder ser atualizado.

Isso é importante porque software muda.

Um arquivo de instruções pode ficar obsoleto. Uma arquitetura pode mudar. Uma Spec pode ser refinada. Um deploy pode alterar o estado operacional. Um incidente pode invalidar uma prática anterior.

No nosso método, cada camada precisa ter uma estratégia de atualização:

Domínio

Atualizar quando regras, termos ou invariantes mudarem.

Projeto

Atualizar junto com decisões arquiteturais, tooling e convenções.

Tarefa

Atualizar durante Specify → Verify → Refine.

Operação

Atualizar continuamente por telemetria e eventos de runtime.

Contexto sem ciclo de atualização se transforma em dívida.

Contexto também é uma superfície de confiança

Injetar informação no agente muda seu comportamento.

Portanto, contexto é também superfície de segurança.

Perguntas necessárias:

• quem pode escrever instruções persistentes?
• qual fonte tem precedência?
• um arquivo externo pode alterar política?
• um agente pode carregar secrets?
• dados de produção podem entrar na tarefa?
• contexto de um cliente pode contaminar outro?

Context Engineering não é apenas otimização de tokens.

Também é controle de origem, escopo, retenção e permissões.

O CONTEXT.md

O artefato operacional deste capítulo é CONTEXT.md.

Ele não tenta armazenar todo o projeto.

Sua função é compor o contexto mínimo suficiente para uma tarefa.

Campos principais:

• Goal;
• Minimum sufficient contexto;
• Stable instructions;
• Relevant architecture;
• Allowed ferramentas / surfaces;
• Forbidden actions;
• Sources;
• Context budget.

O ponto mais importante é o último.

Context budget obriga a decidir o que pode ficar fora.

Sem essa decisão, contexto tende a crescer por acumulação.

Cada erro leva a adicionar mais uma instrução. Cada incidente adiciona mais uma exceção. Cada tarefa reaproveita o pacote inteiro.

Depois de algum tempo, o agente recebe tudo porque ninguém sabe mais o que remover.

Context budget cria pressão para manutenção.

Context pack por tarefa

No fluxo completo:

DOMAIN.md
   +
project guidance
   +
SPEC.md
   +
task-specific files/contracts
   +
evidência de runtime on demand
        ↓
   CONTEXT.md / Context Pack
        ↓
      Agent Work

O pacote não precisa duplicar as fontes.

Pode apontar para elas.

Isso preserva source of truth e reduz divergência.

O que não deve entrar automaticamente

Uma boa disciplina também define exclusões.

Não carregue automaticamente:

• chats antigos;
• logs extensos;
• documentação irrelevante;
• arquivos vizinhos “só por garantia”;
• decisões revogadas;
• secrets;
• dumps de produção;
• todos os ADRs;
• todas as issues relacionadas;
• todos os resultados de busca.

Contexto precisa justificar sua presença.

A pergunta é:

qual decisão ou ação ficará pior se esta informação não estiver disponível?

Se não houver resposta clara, talvez ela deva permanecer fora e ser recuperada sob demanda.

Contexto ativo e contexto recuperável

Nem tudo precisa estar na janela.

Essa distinção é essencial.

Contexto ativo é o que precisa estar presente agora.

Contexto recuperável é o que pode ser buscado quando surgir uma condição específica.

Essa separação reduz volume sem apagar memória.

No nosso método, o repositório e as ferramentas funcionam como memória externa recuperável.

O agente recebe ponteiros e critérios para buscar, não necessariamente todo o conteúdo antecipadamente.

Do Context ao ambiente executável

Depois de Domain, Architecture, Spec, Decomposition e Context, a tarefa está semanticamente preparada. Ainda falta uma condição prática: o repositório precisa tornar suas regras e superfícies legíveis durante a execução.

Um bom Context perde valor se convenções, scripts, comandos, ownership e instruções do projeto estiverem espalhados ou implícitos.

Por isso, o próximo capítulo não pula diretamente para autonomia. Primeiro transforma o repositório em ambiente intencional e legível, capaz de sustentar o trabalho do agente sem depender da memória de uma conversa.

Fronteira de confiança

Contexto pode carregar instruções, dados e permissões implícitas. Cada pacote deve declarar fontes confiáveis, precedência, dados proibidos e limites de retenção. Informações externas não devem ganhar autoridade apenas porque entraram na janela.

Evidência exigida

O Context Pack deve ser revisável: fontes identificadas, escopo explícito e razão para cada bloco relevante. Quando contexto influencia uma decisão crítica, a provenance precisa permitir reconstruir de onde veio a informação.

Rollback e recuperação

Contexto persistente também precisa de rollback. Mudanças em AGENTS.md, skills, runbooks, políticas ou memória institucional devem ser versionadas para que uma instrução defeituosa possa ser revertida e o efeito possa ser rastreado.

Proveniência das fontes

Rastreabilidade deste capítulo:

• CLM-005 — Hua et al., suficiência e continuidade semântica;
• CLM-034 — García, contexto sources → management → orchestration + harness;
• CLM-035 — Hua et al., Minimal Sufficiency e Semantic Continuity;
• CLM-036 — Hua et al., functional contexto isolation.

As quatro camadas de contexto deste capítulo são método deste livro: Domain Context, Persistent Project Context, Task Context e Operational Context.

O comparável de Nissl aparece apenas como fonte limitada no mapa competitivo e não foi usado como autoridade factual.

Fontes de acesso limitado não foram usadas como autoridade factual neste capítulo.

Recursos complementares

Recursos relacionados:

• CONTEXT.md;
• futuro Context Pack Builder;
• DOMAIN.md;
• SPEC.md;
• Artifact Library;
• futura visualização de contexto ativo vs recuperável;
• futura comparação de contexto amplo vs minimal sufficient em Change Episodes.

---

Footnotes

1. Boni García, Context Engineering (MEAP, 2026), 1.1.2 The context engineering stack, p. 9. Rastreabilidade interna: CLM-034. ↩

2. Hua et al., Context Engineering 2.0 (2025), Typical Strategies in Era 1.0 and 2.0, p. 9. Rastreabilidade interna: CLM-035. ↩

3. Hua et al., Context Engineering 2.0 (2025), 5.3 Context Organization / Context Isolation, p. 12. Rastreabilidade interna: CLM-036. ↩