Engenharia de Contexto É Arquitetura: 650 Arquivos Depois

Meu CLAUDE.md começou com 50 linhas. Seis meses depois, havia se transformado em uma arquitetura distribuída de 650 arquivos em sete camadas. A evolução revelou que engenharia de contexto não é engenharia de prompts com mais arquivos. É arquitetura de software para um substrato onde a memória se degrada a cada token.

Contexto não é um arquivo de configuração. É o substrato arquitetural que determina o que um agente de IA pode pensar, o que ele lembra e o que esquece. Toda outra decisão de design é consequência do contexto. O que segue são seis meses de engenharia de contexto em produção para o Claude Code: a arquitetura, as falhas e o sistema que sobreviveu a elas.

Resumo

O artigo de Böckeler sobre engenharia de contexto (martinfowler.com, 2026)¹ e o framework de pensamento claro de Miessler² avançam a conversa, mas ambos subestimam o que o uso em produção exige. Engenharia de contexto requer projetar um sistema onde as instruções certas chegam ao agente no momento certo, e as instruções erradas nunca são carregadas. Meu sistema usa nove regras, 40 skills, 19 agentes, 84 hooks e 14 arquivos de configuração distribuídos em uma hierarquia de sete camadas. A arquitetura não está nos arquivos em si, mas em quais arquivos são carregados quando e o que é excluído.

---

Contexto Não É um Arquivo

O post semanal “como escrever um CLAUDE.md” erra o ponto. Escrever um bom CLAUDE.md é necessário e insuficiente, da mesma forma que escrever bom código é necessário e insuficiente para construir um bom sistema. Arquitetura é a estrutura que determina como os componentes interagem. Em sistemas de agentes, o contexto é essa estrutura.

Meu primeiro CLAUDE.md era um monólito: 200 linhas cobrindo padrões de código, estrutura do projeto, preferências, correções, filosofia, credenciais e estado dos projetos ativos. Funcionou por um mês. Então três coisas aconteceram simultaneamente:

1. O arquivo ultrapassou 300 linhas e começou a entrar em conflito consigo mesmo (a regra A dizia “mantenha simples”, a regra B dizia “adicione tratamento de erros completo”)
2. O contexto do projeto A vazou para o projeto B (regras específicas de iOS poluindo uma sessão de desenvolvimento web)
3. O agente gastava tokens lendo instruções irrelevantes para a tarefa atual

Os sintomas apontam para problemas arquiteturais, não problemas de documentação: acoplamento, vazamento de escopo e desperdício de recursos. As mesmas forças conduzem decisões de arquitetura de software.³

---

As Sete Camadas

Após seis meses de refatoração, meu sistema de contexto se consolidou em uma hierarquia de sete camadas. Cada camada serve a um propósito distinto e é carregada em um momento específico:

Camada	Conteúdo	Quando Carrega	Quantidade
1. Core	CLAUDE.md: filosofia, projetos ativos, correções	Início de cada sessão	Um arquivo, 205 linhas
2. Rules	Restrições específicas de domínio (design de API, segurança, testes, git)	Início de cada sessão	Nove arquivos
3. Skills	Módulos de conhecimento reutilizáveis com procedimentos e exemplos	Sob demanda (invocados ou ativados automaticamente por hooks)	40 diretórios
4. Agents	Especificações de revisores/geradores especializados	Sob demanda (via ferramenta Task)	19 arquivos
5. Hooks	Injeção automática de contexto em eventos do ciclo de vida	Orientado por eventos (início de sessão, pré-commit, pós-ferramenta)	84 scripts
6. Config	Parâmetros numéricos (limites, orçamentos, thresholds)	Referenciados por hooks e skills	14 arquivos JSON
7. State	Rastreamento em tempo real (linhagem de agentes, calibração de confiança, custos)	Referenciado por hooks	36 arquivos

O insight crítico é a separação de camadas. Rules são carregadas em toda sessão porque se aplicam universalmente. Skills são carregadas sob demanda porque são específicas de domínio. Hooks disparam em eventos porque o timing importa. Carregar todos os 650 arquivos no início da sessão esgotaria a janela de contexto antes de o agente ler a primeira mensagem do usuário.⁴

---

Três Falhas Que Moldaram a Arquitetura

Falha 1: O CLAUDE.md Monolítico

Meu CLAUDE.md original continha regras de iOS, regras web, padrões de design de API, convenções de git, gerenciamento de credenciais e princípios filosóficos — tudo em um único arquivo. O agente lia tudo isso em cada sessão, mesmo quando estava construindo um projeto web que nunca tocaria em SwiftUI.

O custo: Contexto irrelevante consumia aproximadamente 4.000 tokens por sessão. Ao longo de 50 sessões, isso totaliza 200.000 tokens gastos com instruções que o agente nunca utilizou.

A solução: Extrair conteúdo específico de domínio em arquivos rules/. rules/security.md é carregado em toda sessão (segurança se aplica a tudo). rules/ios-security.md é carregado apenas quando a sessão envolve projetos iOS. O post sobre gerenciamento de janela de contexto documenta a economia de tokens que motivou essa decisão.

Falha 2: Skills Que Ficaram Desatualizadas

Criei uma skill fastapi com exemplos do FastAPI 0.109. Três meses depois, o projeto usava FastAPI 0.115 com padrões diferentes. A skill silenciosamente ensinava convenções ultrapassadas. O agente produzia código funcional que não correspondia à base de código atual.

O custo: Uma sessão de depuração de 45 minutos rastreando por que um novo endpoint usava um padrão de injeção de dependência diferente de todos os outros endpoints. O padrão veio da skill desatualizada, não da base de código.

A solução: Skills referenciam documentação versionada e incluem datas de “última verificação”. Mais importante, o ciclo de qualidade exige que o código gerado corresponda aos padrões existentes na base de código — uma verificação metacognitiva que detecta a defasagem de skills independentemente do conteúdo da skill.

Falha 3: Regras Conflitantes em Camadas Diferentes

O CLAUDE.md dizia “prefira soluções simples”. Uma skill dizia “adicione tratamento de erros completo com lógica de retry e circuit breakers”. Ambas eram razoáveis isoladamente. Juntas, produziam saída inconsistente (às vezes minimalista, às vezes super-engenheirada) dependendo de qual instrução o agente priorizava mais em determinado turno.

O custo: Qualidade de saída imprevisível. O mesmo tipo de tarefa produzia níveis de qualidade diferentes entre sessões, tornando o sistema não confiável.

A solução: Estabelecer uma hierarquia de precedência clara. O CLAUDE.md define princípios (“prefira simplicidade”). Rules definem restrições (“valide toda entrada do usuário”). Skills definem procedimentos (“aqui está como construir um endpoint FastAPI”). Quando conflitam, a camada mais específica prevalece: o procedimento de uma skill sobrepõe a orientação de um princípio para a tarefa específica que a skill cobre. A resolução espelha como linguagens de programação lidam com escopo: local sobrepõe global.⁵

---

Orçamento de Contexto Como Restrição Arquitetural

A janela de contexto não é infinita. Os 200 mil tokens da janela de contexto do Claude⁶ parecem bastante até você medir o que os consome:

Consumidor	Tokens Típicos	% da Janela
Prompt do sistema + CLAUDE.md + rules	8.000-12.000	4-6%
Histórico de conversa	20.000-80.000	10-40%
Leitura de arquivos (por arquivo)	5.000-20.000	2,5-10%
Saídas de ferramentas (por chamada)	1.000-10.000	0,5-5%
Contexto de skill/agent (sob demanda)	3.000-15.000	1,5-7,5%

As medições de consumo de tokens vêm de 50 sessões do Claude Code que rastreei entre agosto de 2025 e fevereiro de 2026.⁷ Uma sessão intensiva de 90 minutos pode esgotar a janela por meio de leituras normais de arquivos e interações com ferramentas. O orçamento de contexto impõe trade-offs arquiteturais:

Sempre carregar a filosofia central, correções ativas e regras de segurança. Todos os três são baratos (4-6% do orçamento) e universalmente aplicáveis.

Carregar sob demanda skills, especificações de agentes e documentação de referência. Cada um custa 5-15% da janela por skill e se aplica a um único domínio. Carregá-los apenas quando relevante preserva o orçamento para o trabalho real.

Nunca carregar documentos de handoff obsoletos, configurações descontinuadas ou estado histórico. Todo arquivo obsoleto consome orçamento sem melhorar a saída. O padrão de engenharia composta exige poda periódica de contexto que não mais justifica seu custo em tokens.

O orçamento de contexto espelha o trade-off que guia a indexação de banco de dados, estratégias de cache e gerenciamento de memória em software tradicional.⁸ A restrição é diferente (tokens em vez de bytes), mas a disciplina arquitetural é idêntica.

---

Propagação de Contexto em Sistemas Multi-Agente

Quando o agente principal gera um subagente via a ferramenta Task, escolher qual contexto propagar determina toda outra decisão de design. Meu sistema de deliberação multi-agente usa 10 agentes de pesquisa. Cada agente precisa de contexto suficiente para avaliar independentemente, mas contexto compartilhado em excesso causa o problema de convergência documentado no post sobre boids: agentes que compartilham contexto demais produzem conclusões idênticas.

As regras de propagação:

Tipo de Contexto	Propagado?	Por quê
Filosofia central	Sim	Consistência entre agentes
Regras de domínio	Sim	Padrões de qualidade compartilhados
Instruções específicas da tarefa	Sim	O trabalho real
Histórico de conversa	Não	Independência requer isolamento
Descobertas de outros agentes	Não (até a síntese)	Previne convergência prematura
Procedimentos de skills	Seletivamente	Apenas skills relevantes para o papel do agente

A arquitetura Ralph resolve um problema relacionado: propagação de contexto ao longo do tempo (iterações), não entre agentes (processos paralelos). Ambos compartilham o mesmo princípio: propague restrições e princípios, isole detalhes de implementação.

---

Medindo a Qualidade do Contexto

Contagem de tokens é uma métrica proxy. A verdadeira medida de qualidade do contexto é: o agente produz a saída correta na primeira tentativa?

Após rastrear 50 sessões, identifiquei três sinais de qualidade:

Taxa de sucesso na primeira tentativa. Com que frequência a primeira resposta do agente não requer correção? Com o CLAUDE.md monolítico, a taxa era de aproximadamente 60%. Após a arquitetura de sete camadas, subiu para cerca de 80%. A melhoria veio da remoção de contexto irrelevante (menos distrações) e da adição de skills específicas de domínio (conhecimento mais relevante).⁹

Tipo de correção. Quando o agente precisa de correção, o erro é factual (API errada, padrão errado) ou uma questão de julgamento (abordagem errada, prioridade errada)? Erros factuais indicam contexto ausente. Erros de julgamento indicam contexto conflitante ou ambíguo. Rastrear tipos de correção revela qual camada precisa de atenção.

Pressão de contexto ao concluir a tarefa. Quanto do orçamento de contexto resta quando a tarefa termina? Se a janela está 90% cheia antes da tarefa estar pela metade, a arquitetura de contexto está carregando material irrelevante em excesso. Meu sistema de hooks inclui um monitor de pressão de contexto que alerta quando a utilização ultrapassa 70%.

---

O Padrão de Arquitetura Distribuída

Nada no sistema de sete camadas é exclusivo de agentes de IA. Ele espelha padrões de software estabelecidos:

Padrão de Software	Equivalente em Contexto
Variáveis de ambiente	CLAUDE.md central (sempre carregado, global)
Arquivos de configuração	Rules (carregadas na inicialização, específicas de domínio)
Bibliotecas/módulos	Skills (carregadas sob demanda, autocontidas)
Microsserviços	Agents (isolados, comunicando-se por protocolos)
Manipuladores de eventos	Hooks (acionados por eventos do ciclo de vida)
Banco de dados	Arquivos de estado (persistentes, consultáveis)
Contratos de API	Schemas de config (parâmetros numéricos compartilhados)

O paralelo não é metafórico. As mesmas forças (acoplamento, coesão, escopo, ciclo de vida) conduzem decisões arquiteturais idênticas.¹⁰ Engenharia de contexto é engenharia de software para um substrato onde a “memória” é um recurso escasso e degradável, em vez de abundante e persistente.¹¹

---

Principais Conclusões

Para engenheiros construindo sistemas de agentes:

• Projete contexto como arquitetura de software, não como documentação. O que carrega quando, o que sobrepõe o quê e o que propaga para subagentes determina o comportamento do agente mais do que qualquer instrução individual. Aplique a mesma disciplina de separação de responsabilidades que você usa para código.

• Separe camadas por ciclo de vida. Regras universais carregam em toda sessão. Conhecimento específico de domínio carrega sob demanda. Estado por sessão permanece transitório. Misturar ciclos de vida em um único arquivo cria os problemas de acoplamento que a arquitetura de software existe para resolver.

Para equipes escalando fluxos de trabalho com IA:

• Trate a janela de contexto como um orçamento. Prompts do sistema, leituras de arquivos e saídas de ferramentas consomem a janela de 200 mil tokens. Toda instrução persistente compete com a memória de trabalho. Meça o que você carrega e elimine o que não justifica seus tokens.

• Regras de propagação determinam a qualidade multi-agente. Subagentes precisam de princípios compartilhados para consistência e estado isolado para independência. Propagar contexto demais causa convergência. Propagar de menos causa incoerência.

---

Este post se baseia em Gerenciamento de Janela de Contexto (economia de tokens) e O Sistema Ralph (memória no sistema de arquivos). O sistema de hooks do Claude Code implementa a camada de automação. Para padrões de coordenação de agentes, veja Deliberação Multi-Agente e Boids para Agentes.

---