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 é arquitetura de software para um substrato em que a memória se degrada a cada token, e não engenharia de prompts com mais arquivos.
O contexto determina o que um agente de IA pode pensar, o que ele lembra e o que esquece. Todas as outras decisões de design vêm depois dele. 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.
Engenharia de contexto para agentes de IA é a prática de projetar sistemas que entregam as instruções certas ao agente no momento certo, garantindo ao mesmo tempo que instruções irrelevantes nunca sejam carregadas. Ela vai além de escrever um bom arquivo de prompt: exige uma arquitetura em camadas em que regras, skills, hooks, configurações e arquivos de estado são carregados, cada um, em eventos específicos do ciclo de vida. O que fica de fora importa tanto quanto o que entra, porque cada token irrelevante desloca contexto de que o agente realmente precisa para acertar.
Resumo
O artigo de Böckeler sobre engenharia de contexto (martinfowler.com, 2026)1 e o framework de pensamento claro de Miessler2 avançam a conversa, mas ambos subestimam o que o uso em produção exige. Engenharia de contexto requer projetar um sistema em que 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 está em quais arquivos são carregados e quando. O que fica de fora importa tanto quanto o que entra.
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.
O que começou com 50 linhas virou um monólito: meu primeiro CLAUDE.md tinha 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 ao mesmo tempo:
- O arquivo passou de 300 linhas e começou a contradizer a si mesmo (a regra A dizia “mantenha simples”, a regra B dizia “adicione tratamento de erros completo”)
- O contexto do projeto A vazou para o projeto B (regras específicas de iOS poluindo uma sessão de desenvolvimento web)
- O agente gastava tokens lendo instruções irrelevantes para a tarefa atual
Os sintomas apontam para problemas de arquitetura, não de documentação: acoplamento, vazamento de escopo e desperdício de recursos. As mesmas forças conduzem as decisões de arquitetura de software.3
As sete camadas
Após seis meses de refatoração, meu sistema de contexto se consolidou em uma hierarquia de sete camadas. Cada camada tem um propósito distinto e é carregada em um momento específico:
| Camada | Conteúdo | Quando carrega | Quantidade |
|---|---|---|---|
| 1. Núcleo | CLAUDE.md: filosofia, projetos ativos, correções |
Início de toda sessão | Um arquivo, 205 linhas |
| 2. Regras | Restrições específicas de domínio (design de API, segurança, testes, git) | Início de toda sessão | Nove arquivos |
| 3. Skills | Módulos de conhecimento reutilizáveis com procedimentos e exemplos | Sob demanda (invocadas ou ativadas automaticamente por hooks) | 40 diretórios |
| 4. Agentes | Especificações de revisores e geradores especializados | Sob demanda (via ferramenta Task) | 19 arquivos |
| 5. Hooks | Injeção automática de contexto em eventos do ciclo de vida | Orientados por eventos (início de sessão, pre-commit, post-tool) | 84 scripts |
| 6. Configuração | Parâmetros numéricos (limiares, orçamentos, limites) | Referenciada por hooks e skills | 14 arquivos JSON |
| 7. Estado | 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. As regras são carregadas em toda sessão porque se aplicam universalmente. As skills são carregadas sob demanda porque são específicas de domínio. Os hooks disparam em eventos porque o momento 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.4
Um exemplo concreto de cada camada:
Layer 1 (Core): ~/.claude/CLAUDE.md — philosophy, active projects, corrections
Layer 2 (Rules): ~/.claude/rules/security.md — "Validate ALL user input at boundaries"
Layer 3 (Skills): ~/.claude/skills/fastapi/SKILL.md — endpoint patterns, Pydantic models
Layer 4 (Agents): ~/.claude/agents/security-reviewer.md — OWASP-focused review spec
Layer 5 (Hooks): ~/.claude/hooks/pre-commit-check.sh — blocks commits with TODO/FIXME
Layer 6 (Config): ~/.claude/config/thresholds.json — {"max_spawn_children": 12}
Layer 7 (State): ~/.claude/state/agent-lineage.json — tracks active agent tree
Cada arquivo da hierarquia tem uma única responsabilidade e um gatilho de carregamento claro. O hook (camada 5) dispara no pre-commit, seja qual for o tipo de projeto. A skill (camada 3) só é carregada quando começa uma tarefa de FastAPI. Essa distinção determina o custo em tokens.
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 toda sessão, mesmo construindo um projeto web que nunca tocaria em SwiftUI.
O custo: o contexto irrelevante consumia cerca de 4.000 tokens por sessão, segundo minha estimativa. Ao longo de 50 sessões, isso soma aproximadamente 200.000 tokens gastos com instruções que o agente nunca usou.
A solução: extrair o conteúdo específico de domínio para arquivos em rules/. rules/security.md é carregado em toda sessão (segurança vale para tudo). rules/ios-security.md é carregado apenas quando a sessão envolve projetos iOS. O post sobre gerenciamento da 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 o FastAPI 0.115, com padrões diferentes. A skill ensinava silenciosamente convenções ultrapassadas. O agente produzia código funcional que não correspondia à base de código atual.
O custo: uma depuração de 45 minutos para descobrir 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: as skills referenciam documentação versionada e incluem datas de “última verificação”. Mais importante: o ciclo de qualidade exige que o código gerado siga os padrões já existentes na base de código, uma verificação metacognitiva que detecta a defasagem de skills seja qual for o 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”. Isoladamente, as duas eram razoáveis. Juntas, produziam saídas inconsistentes (às vezes minimalistas, às vezes superdimensionadas), dependendo de qual instrução o agente priorizava 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, o que tornava o sistema pouco confiável. Estas são as instruções conflitantes reais:
# In CLAUDE.md (Layer 1):
- Prefer simple solutions. Avoid over-engineering.
# In skills/fastapi/SKILL.md (Layer 3):
- Add thorough error handling with retry logic and circuit breakers
for all external API calls.
Isoladamente, as duas estão corretas. “Prefira soluções simples” é um bom conselho geral. “Adicione lógica de retry para chamadas externas” é um bom conselho específico de domínio. Mas um agente que lê as duas às vezes pula a lógica de retry (seguindo o princípio da simplicidade) e às vezes superdimensiona uma função simples (seguindo a instrução de tratamento de erros).
A solução: estabelecer uma hierarquia de precedência clara. O CLAUDE.md define princípios (“prefira simplicidade”). As regras definem restrições (“valide toda entrada do usuário”). As skills definem procedimentos (“é assim que se constrói um endpoint FastAPI”). Quando entram em conflito, vence a camada mais específica: o procedimento de uma skill se sobrepõe à orientação de um princípio na tarefa específica que a skill cobre. A resolução espelha a forma como linguagens de programação tratam escopo: o local se sobrepõe ao global.5 A correção para o exemplo acima é acrescentar uma ressalva à skill: “Adicione lógica de retry para chamadas a APIs externas (isto se sobrepõe ao princípio geral de simplicidade em código dependente de rede, porque chamadas externas falham de forma intermitente e retries não são superdimensionamento).”
Orçamento de contexto como restrição arquitetural
A janela de contexto não é infinita. A janela padrão de 200 mil tokens do Claude6 parece grande até você medir o que a consome. (Existe uma versão beta de 1 milhão de tokens, ativada por um header da API, que aumenta o orçamento proporcionalmente, mas não elimina os trade-offs: carregar 650 arquivos esgotaria até 1 milhão de tokens.)
| Consumidor | Tokens típicos | % da janela |
|---|---|---|
| Prompt do sistema + CLAUDE.md + regras | 8.000-12.000 | 4-6% |
| Histórico da conversa | 20.000-80.000 | 10-40% |
| Leituras de arquivo (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/agente (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 acompanhei entre agosto de 2025 e fevereiro de 2026.7 Uma sessão intensa de 90 minutos pode esgotar a janela apenas com leituras normais de arquivos e interações com ferramentas. Note que a janela de 200 mil é a capacidade total de entrada; a atenção efetiva do modelo, a parcela à qual ele atende com alta fidelidade, é um número diferente e menor. A disciplina de orçamento de contexto importa mesmo quando o uso total de tokens está bem abaixo do limite, porque instruções no início de um contexto longo recebem atenção mais confiável do que instruções no meio. O orçamento de contexto impõe trade-offs arquiteturais:
Sempre carregar a filosofia central, as correções ativas e as regras de segurança. As três são baratas (4-6% do orçamento) e se aplicam universalmente. O custo de carregá-las quando não são necessárias é desprezível. O custo de omiti-las quando são necessárias é uma saída incorreta.
Carregar sob demanda skills, especificações de agentes e documentação de referência. Cada skill custa 5-15% da janela e se aplica a um único domínio. Carregá-las apenas quando relevantes preserva o orçamento para o trabalho real. O gatilho para carregar uma skill é o tipo de tarefa, não o tipo de sessão: uma sessão de desenvolvimento web que esbarra em uma migração de banco de dados precisa da skill de banco de dados, mesmo que ela não tenha sido carregada na inicialização.
Nunca carregar documentos de handoff obsoletos, configurações descontinuadas ou estado histórico. Todo arquivo obsoleto consome orçamento sem melhorar a saída. Pior: contexto obsoleto degrada ativamente a saída ao ensinar padrões ultrapassados. O padrão de engenharia composta exige a poda periódica do contexto que já não justifica seu custo em tokens.
O orçamento de contexto espelha o trade-off que orienta a indexação de bancos de dados, as estratégias de cache e o gerenciamento de memória no software tradicional.8 A restrição é outra (tokens em vez de bytes), mas a disciplina arquitetural é idêntica.
Propagação de contexto em sistemas multiagente
Quando o agente principal cria um subagente pela ferramenta Task, a escolha de qual contexto propagar orienta todas as outras decisões de design. Meu sistema de deliberação multiagente usa 10 agentes de pesquisa. Cada agente precisa de contexto suficiente para avaliar de forma independente, mas contexto compartilhado em excesso causa o problema de convergência documentado no post sobre boids: agentes que compartilham contexto demais chegam a 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 em si |
| Histórico da conversa | Não | Independência exige isolamento |
| Descobertas de outros agentes | Não (até a síntese) | Evita convergência prematura |
| Procedimentos de skills | Seletivamente | Apenas skills relevantes para o papel do agente |
A arquitetura Ralph resolve um problema relacionado: a propagação de contexto ao longo do tempo (iterações), e não entre agentes (processos paralelos). Ambas compartilham o mesmo princípio: propagar restrições e princípios, isolar detalhes de implementação.
Propagação na prática
Um exemplo concreto deixa o trade-off claro. Quando o agente principal cria um subagente revisor de segurança, o prompt da Task inclui:
## Propagated Context
- Core philosophy: Quality is the only variable (from CLAUDE.md)
- Security rules: OWASP Top 10, input validation at boundaries (from rules/security.md)
- Task: Review the authentication endpoint changes in app/auth.py
## NOT Propagated
- The main agent's conversation history (50+ messages about UI layout)
- Findings from the architecture reviewer (would bias security analysis)
- The FastAPI skill (irrelevant to a security-focused review)
O revisor de segurança recebe 2.000 tokens de contexto em vez de 40.000. Ele avalia o código segundo critérios de segurança, sem a distração das decisões de UI nem o viés das conclusões de outro agente. O isolamento produz uma avaliação independente. Se o revisor de segurança e o revisor de arquitetura apontam o mesmo problema de forma independente, a descoberta merece mais confiança do que se um revisor tivesse visto o relatório do outro e concordado.
Medindo a qualidade do contexto
A contagem de tokens é uma métrica indireta. A verdadeira medida da qualidade do contexto é: o agente produz a saída correta na primeira tentativa?
Depois de acompanhar 50 sessões, identifiquei três sinais de qualidade:
Taxa de acerto na primeira tentativa. Com que frequência a primeira resposta do agente não exige correção? Com o CLAUDE.md monolítico, a taxa era de cerca de 60%. Depois da arquitetura de sete camadas, subiu para aproximadamente 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).9
Aqui está um antes e depois representativo do registro de acompanhamento. A tarefa é idêntica: “adicionar rate limiting a um endpoint de API”.
Antes (CLAUDE.md monolítico, julho de 2025). A primeira resposta do agente importou uma biblioteca de rate limiting que o projeto não usava (ele seguiu um exemplo da skill desatualizada de FastAPI, carregada junto com regras de iOS, regras de segurança e 150 linhas de conteúdo sem relação). A correção: “use a classe RateLimiter existente em app/middleware.py”. Uma correção, classificada como “erro factual: falta de contexto da base de código”.
Depois (arquitetura de sete camadas, novembro de 2025). Mesmo tipo de tarefa, outro endpoint. A primeira resposta do agente usou o middleware RateLimiter existente, seguiu a convenção de nomes de parâmetros dos endpoints vizinhos e citou a origem do padrão: “seguindo o padrão de rate limiting em app/middleware.py:42”. Nenhuma correção necessária. A skill de FastAPI (camada 3) foi carregada sob demanda e continha os padrões atuais; as regras de iOS não foram carregadas porque a sessão não envolvia iOS.
Para acompanhar isso você mesmo: marque cada sessão do agente em um registro como “aceita” ou “corrigida” depois da primeira resposta e calcule a proporção mensalmente. Não é preciso ter granularidade fina: tendências direcionais ao longo de mais de 20 sessões são mais úteis do que porcentagens exatas.
Tipo de correção. Quando o agente precisa de correção, o erro é factual (API errada, padrão errado) ou de julgamento (abordagem errada, prioridade errada)? Erros factuais indicam contexto ausente: faltava ao agente a informação necessária para produzir a resposta certa. Erros de julgamento indicam contexto conflitante ou ambíguo: o agente tinha a informação, mas ponderou mal instruções concorrentes. A distinção importa porque a correção é diferente: erros factuais exigem acrescentar contexto (uma nova regra ou skill), enquanto erros de julgamento exigem esclarecer o contexto (resolver um conflito entre camadas existentes). Acompanhar os 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 de a tarefa chegar à metade, a arquitetura de contexto está carregando material irrelevante demais. Meu sistema de hooks inclui um monitor de pressão de contexto que alerta quando a utilização passa de 70%.
Uma sessão passo a passo: o que carrega e quando
Um passo a passo concreto mostra como as sete camadas interagem durante uma tarefa real. O cenário: peço ao Claude Code para “adicionar rate limiting ao endpoint /api/ab/event” no projeto blakecrosley.com.
Início da sessão (0 s). O Claude Code carrega a camada 1 (CLAUDE.md, 205 linhas, ~800 tokens) e a camada 2 (todos os 9 arquivos de regras, ~3.200 tokens). Contexto total consumido: ~4.000 tokens (2% da janela de 200 mil). O agente agora conhece minha filosofia de código, meus requisitos de segurança, minhas convenções de design de API e meu fluxo de git, seja qual for o pedido.
Início da tarefa (2 s). O agente lê a tarefa e a identifica como uma modificação de endpoint FastAPI. A camada 5 (hooks) dispara: o hook UserPromptSubmit injeta a data atual e o contexto da sessão (~200 tokens). O agente não carrega a skill de SwiftUI, as regras de segurança de iOS nem a skill de prompts do Midjourney. Esses arquivos existem, mas são irrelevantes. Deixá-los de fora economiza ~8.000 tokens.
Leituras de arquivo (5-30 s). O agente lê app/main.py, o código do endpoint existente e o arquivo de testes. Cada leitura de arquivo consome 5.000-15.000 tokens de contexto. Depois de ler três arquivos: ~30.000-50.000 tokens consumidos (15-25% da janela).
Ativação de skill (se necessário). Se o agente precisar de padrões específicos de FastAPI, ele carrega a camada 3 (skills/fastapi/SKILL.md, ~2.500 tokens). A skill é carregada porque a tarefa exige, não porque a sessão começou. Se fosse uma tarefa só de CSS, a skill de FastAPI nunca seria carregada.
Implementação e verificação (30 s-5 min). O agente escreve o código, roda os testes e relata os resultados. Ao fim da tarefa, o consumo de contexto costuma ficar entre 60.000 e 100.000 tokens (30-50% da janela). O orçamento restante comporta perguntas de acompanhamento, correções ou uma segunda tarefa na mesma sessão.
A observação-chave: as camadas 1 e 2 consomem 2% da janela e valem para toda tarefa. O conteúdo das camadas 3 a 7 é carregado seletivamente e consome 5-25% apenas quando relevante. Se todos os 650 arquivos fossem carregados no início da sessão, consumiriam aproximadamente 150.000-200.000 tokens, sem deixar quase nenhum espaço para o trabalho real.
O padrão de arquitetura distribuída
Nada no sistema de sete camadas é exclusivo de agentes de IA. Ele espelha padrões de software consagrados:
| Padrão de software | Equivalente em contexto |
|---|---|
| Variáveis de ambiente | CLAUDE.md central (sempre carregado, global) |
| Arquivos de configuração | Regras (carregadas na inicialização, específicas de domínio) |
| Bibliotecas/módulos | Skills (carregadas sob demanda, autocontidas) |
| Microsserviços | Agentes (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 configuração (parâmetros numéricos compartilhados) |
O paralelo não é metafórico. As mesmas forças (acoplamento, coesão, escopo, ciclo de vida) conduzem a decisões arquiteturais idênticas.10 Engenharia de contexto é engenharia de software para um substrato em que a “memória” é um recurso escasso e degradável, em vez de abundante e persistente.11
Uma validação independente dessa arquitetura vem do projeto obra/superpowers, que chegou por conta própria a uma estrutura multicamada semelhante para o contexto do Claude Code: princípios centrais em um arquivo global, skills de domínio carregadas sob demanda e procedimentos de verificação separados das instruções de comportamento.12 A convergência sugere que a arquitetura em camadas não é uma escolha de design idiossincrática, mas uma resposta natural às restrições do substrato.
Principais conclusões
Para engenheiros que constroem sistemas de agentes:
-
Projete o contexto como arquitetura de software, não como documentação. O que carrega quando, o que se sobrepõe a quê e o que se propaga para subagentes determinam o comportamento do agente mais do que qualquer instrução individual. Aplique a mesma disciplina de separação de responsabilidades que você usa no código.
-
Separe as camadas por ciclo de vida. Regras universais carregam em toda sessão. Conhecimento específico de domínio carrega sob demanda. O estado de cada 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 que escalam fluxos de trabalho com IA:
-
Trate a janela de contexto como um orçamento. Prompts do sistema, leituras de arquivo 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 corte o que não justifica seus tokens.
-
As regras de propagação determinam a qualidade multiagente. Subagentes precisam de princípios compartilhados para ter consistência e de estado isolado para ter independência. Propagar contexto demais causa convergência. Propagar de menos causa incoerência.
Exercício: audite seu sistema de contexto. Crie esta estrutura de diretórios e preencha-a com suas instruções existentes:
mkdir -p .claude/{rules,skills,agents,hooks,config,state}
# Move domain-specific sections from CLAUDE.md into rules/
# Move reusable procedures into skills/
# Move agent specs into agents/
Depois responda: quais arquivos carregam em toda sessão quando deveriam carregar sob demanda? Quais arquivos sob demanda estão faltando? Registre as respostas em um log simples: marque cada sessão como “correta na primeira tentativa” ou “precisou de correção” e revise a proporção depois de 20 sessões.
Perguntas frequentes
Como devo estruturar arquivos de contexto para agentes de programação com IA?
Extraia o conteúdo específico de domínio para arquivos separados quando ele passar de 20-30 linhas e quando for irrelevante em pelo menos algumas sessões. Se você escrever regras específicas de iOS e regras específicas de web no mesmo CLAUDE.md, o agente lê as duas, seja qual for o projeto atual. Mantenha as restrições universais (regras de segurança, padrões de código, princípios filosóficos) no arquivo central. Mova os padrões específicos de domínio (endpoints FastAPI, convenções de SwiftUI, consultas a banco de dados) para arquivos sob demanda, carregados apenas quando a tarefa exige.
Como saber quando uma skill ficou desatualizada?
Há dois sinais: o agente produz código que funciona, mas não segue os padrões atuais da base de código, ou o agente faz referência a APIs ou padrões de uma versão antiga de um framework. Adicione uma data de “última verificação” a cada skill e revise-a a cada trimestre. Mais importante: o ciclo de qualidade (o código gerado segue os padrões existentes?) detecta a defasagem de skills seja qual for o conteúdo da skill.
Qual é o tamanho certo para um orçamento de contexto?
Para uma janela de 200 mil tokens, reserve 4-6% para o prompt do sistema e as regras (sempre carregados), deixe 40-60% para o histórico da conversa e as leituras de arquivo (o trabalho em si) e destine 10-15% para skills sob demanda e contexto de agentes. Se a pressão de contexto passar de 70% antes de a tarefa chegar à metade, você está carregando material irrelevante demais. As porcentagens exatas dependem da complexidade da tarefa: uma refatoração de vários arquivos consome mais contexto do que a correção de um bug em uma única função.
Como lidar com instruções conflitantes entre camadas?
Aplique precedência por escopo: vence a camada mais específica. Skills (escopo local) se sobrepõem às regras (escopo de módulo), que se sobrepõem ao CLAUDE.md (escopo global). Ao descobrir um conflito, torne a resolução explícita em vez de contar com o modelo para resolvê-lo de forma probabilística. Adicione uma nota na camada mais específica: “Isto se sobrepõe ao princípio geral X neste contexto específico porque Y.”
Este post se baseia em Gerenciamento da 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 Multiagente e De Boids a Agentes.
-
Birgitta Böckeler, “Context Engineering for Coding Agents”, martinfowler.com, fevereiro de 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. O colega de Böckeler, Bharani Subramaniam, define engenharia de contexto como “curating what the model sees so that you get a better result” (curar o que o modelo vê para obter um resultado melhor). A definição está correta. Este post argumenta que a estrutura de como essa informação é organizada e entregue é uma disciplina arquitetural, não um exercício de documentação. ↩
-
Daniel Miessler, “How to Talk to AI”, danielmiessler.com, junho de 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler argumenta que a verdadeira habilidade por trás tanto da engenharia de prompts quanto da engenharia de contexto é o pensamento claro: a capacidade de articular exatamente o que você quer realizar. O enquadramento complementa este post, que se concentra na disciplina estrutural de organizar o contexto, e não em pensar com clareza sobre ele. ↩
-
O paralelo com arquitetura de software é deliberado. Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017, Part III (Design Principles) e Part V (Architecture). Martin identifica as mesmas forças: acoplamento, coesão e separação de responsabilidades. A diferença nos sistemas de contexto de IA é que a “memória” é efêmera e limitada, o que acrescenta uma restrição que a arquitetura tradicional não enfrenta. ↩
-
A contagem de 650 arquivos é uma medição do autor em fevereiro de 2026. Contexto global: ~400 arquivos (regras, skills, agentes, hooks, configurações, estado, docs, handoffs). Contexto específico do projeto (blakecrosley.com): ~250 arquivos (PRDs, docs, planos, workflows, configurações de i18n). Apenas uma fração é carregada em cada sessão. ↩
-
A resolução de escopo de variáveis em linguagens de programação (local, envolvente, global, embutido) é a analogia direta. A regra LEGB do Python define a mesma hierarquia: escopo local, escopo da função envolvente, escopo global, escopo embutido. Veja Python Software Foundation, “Execution Model”, seção 4.2.2, “Resolution of names”. docs.python.org/3/reference/executionmodel.html. Skills (escopo local) se sobrepõem às regras (escopo de módulo), que se sobrepõem ao CLAUDE.md (escopo global). A analogia falha um pouco porque o cumprimento de instruções por LLMs é probabilístico, não determinístico, mas o princípio arquitetural se mantém. ↩
-
Anthropic, “Models overview”, platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. Todos os modelos Claude atuais (Opus 4.6, Sonnet 4.6, Haiku 4.5) especificam uma janela de contexto de 200 mil tokens, com Opus 4.6 e Sonnet 4.6 suportando 1 milhão de tokens em beta. ↩
-
Medições de consumo de tokens de 50 sessões do Claude Code que acompanhei entre agosto de 2025 e fevereiro de 2026. Veja Gerenciamento da Janela de Contexto para a metodologia completa. ↩
-
A analogia entre orçamentos de tokens e hierarquias de memória segue o framework de Hennessy, J.L. e Patterson, D.A., Computer Architecture: A Quantitative Approach, 6ª edição, Morgan Kaufmann, 2017, Chapter 2 (Memory Hierarchy Design). O tratamento que Hennessy e Patterson dão a hierarquias de cache, localidade de referência e custo de acesso à memória em diferentes níveis se aplica diretamente à engenharia de contexto: o contexto necessário com frequência (cache L1 / regras centrais) carrega mais rápido, enquanto o contexto raramente necessário (disco / skills sob demanda) carrega apenas quando referenciado. ↩
-
A taxa de acerto na primeira tentativa é uma métrica aproximada, baseada na avaliação subjetiva do autor sobre se a primeira resposta precisou de correção. Não é um experimento controlado. A melhoria direcional (de 60% para 80%) é consistente entre tipos de sessão, mas não deve ser citada como medição precisa. ↩
-
James Lewis e Martin Fowler, “Microservices”, martinfowler.com, março de 2014. martinfowler.com/articles/microservices.html. Lewis e Fowler definem microsserviços como “a suite of small services, each running in its own process and communicating with lightweight mechanisms” (um conjunto de pequenos serviços, cada um executando em seu próprio processo e comunicando-se por mecanismos leves). As forças que eles identificam (deploy independente, governança descentralizada, contextos delimitados) se aplicam diretamente ao isolamento de agentes e à comunicação baseada em protocolos na arquitetura de contexto descrita aqui. ↩
-
O enquadramento “contexto como arquitetura” se inspira em Xu et al., “Everything is Context: Agentic File System Abstraction for Context Engineering”, arXiv, dezembro de 2025. arxiv.org/abs/2512.05470. O artigo propõe uma abstração de sistema de arquivos para gerenciar contexto em sistemas de IA generativa, tratando artefatos de conhecimento diversos, memória e ferramentas como contexto dentro de restrições de tokens. O framework teórico sustenta a arquitetura prática descrita aqui. ↩
-
obra/superpowers, github.com/obra/superpowers. O projeto superpowers organiza o contexto de agentes em instruções centrais, skills sob demanda e procedimentos de verificação, uma estrutura que convergiu com a arquitetura de sete camadas descrita aqui apesar de ter sido desenvolvida de forma independente. A convergência sustenta a tese de que o contexto em camadas é uma resposta arquitetural natural a janelas de contexto limitadas. ↩