Arquitetura Context-First
Como estruturar um Context Index, montar Context Packets e estabelecer práticas de engenharia de contexto para equipes agênticas.
Visão Geral
A Arquitetura Context-First é um padrão estrutural que trata o contexto como o principal artefato de engenharia em um fluxo de trabalho agêntico. Em vez de depender de prompts ad-hoc e documentação dispersa, as equipes constroem um Context Index — uma coleção estruturada e versionada de especificações, padrões, exemplos e registros históricos que os agentes consomem antes de gerar qualquer código.
O insight central por trás deste padrão é que a qualidade da saída do agente é limitada pela qualidade do contexto. Um modelo capaz com contexto ruim produz resultados ruins. Um modelo menos capaz com contexto bem estruturado o supera consistentemente. Context Engineering é a disciplina de projetar, manter e entregar contexto para maximizar a eficácia do agente.
Problema
Equipes que adotam agentes de IA encontram um padrão de degradação previsível:
- Qualidade de saída inconsistente. A mesma tarefa atribuída ao mesmo agente produz resultados diferentes em dias diferentes porque o contexto é fornecido de forma distinta a cada vez — diferentes arquivos mencionados, diferentes frases, diferentes premissas deixadas implícitas.
- Documentação dispersa. O conhecimento do projeto vive em READMEs, páginas de wiki, threads do Slack, comentários de código e nas cabeças dos engenheiros. Nenhuma fonte única agrega o que um agente precisa para realizar seu trabalho corretamente.
- Alucinação por lacunas de contexto. Quando os agentes carecem de informações sobre restrições de arquitetura, convenções de nomenclatura ou contratos de API, eles preenchem a lacuna com suposições plausíveis, porém incorretas. Esses erros sutis passam pela revisão inicial e surgem como bugs mais tarde.
- Amnésia de sessão. As sessões dos agentes são efêmeras. O conhecimento fornecido em uma sessão não é transferido para a próxima. Os engenheiros perdem tempo fornecendo o mesmo contexto repetidamente.
- Falha de escala. O que funciona para um desenvolvedor conversando com um agente falha quando uma equipe executa vários agentes em paralelo. Sem uma fonte de contexto compartilhada, os agentes produzinentais implementações conflitantes.
Solução
Construa um Context Index como a única fonte de verdade da qual todos os agentes se baseiam. O Context Index é uma estrutura de diretórios dentro do repositório que organiza o contexto em categorias bem definidas. Para cada unidade de trabalho, monte um Context Packet — um subconjunto curado do Context Index escopado para uma tarefa específica — que o agente recebe junto com sua Live Spec.
O papel de Context Architect é o proprietário do Context Index. Esta pessoa (ou papel combinado) é responsável por auditar, estruturar, manter e evoluir o contexto ao longo do tempo. O contexto é tratado como código: é versionado, revisado em pull requests, testado para obsolescência e medido quanto à sua eficácia.
Os cinco componentes de um Context Index são:
- Coleção de Live Spec — Contratos comportamentais, critérios de aceitação e mapas de tarefas para o trabalho atual e planejado
- Constituição do Sistema — Regras de todo o projeto que se aplicam a cada tarefa: padrões de codificação, restrições de framework, políticas de segurança, convenções de nomenclatura
- Contexto da Base de Código — Definições de tipo, contratos de API, registros de decisão de arquitetura, mapas de dependência
- Contexto Histórico — Decisões passadas, abordagens obsoletas, armadilhas conhecidas, registros de migração
- Golden Samples — Implementações exemplares que demonstram a qualidade, estrutura e estilo esperados
Implementação
Considerações
- • **Higher Spec-to-Code Ratio.** When agents receive well-structured context, a larger proportion of their output directly implements the specification rather than improvising around context gaps.
- • **Fewer Rescue Missions.** Teams with a maintained Context Index report fewer cases where agent output requires significant human intervention to salvage. The [[rescue-mission]] rate drops because agents start from a better foundation.
- • **Compound improvement.** Unlike prompts (which are ephemeral), the Context Index accumulates value over time. Each spec authored, each golden sample added, and each constitution rule documented improves every future agent run.
- • **Onboarding acceleration.** New team members and new agents both benefit from the same Context Index. The ramp-up period shortens because project knowledge is explicit and structured rather than tribal.
- • **Measurable quality.** The [[spec-to-code-ratio]] and [[eval-harness]] pass rates provide objective data on context effectiveness. Teams can identify and fix specific context gaps rather than guessing at prompt improvements.
- • **Initial setup effort.** Building the Context Index from scratch requires significant upfront work — auditing existing sources, writing documentation, selecting golden samples. Teams should start with one domain and expand incrementally.
- • **Maintenance burden.** Context must stay current with the codebase. Without the monthly Context Hygiene cycle, the Context Index becomes a liability instead of an asset. The [[context-architect]] role must have dedicated time for this work.
- • **Context window limits.** Even well-curated context competes for space in the model's [[token-budget]]. Teams must make deliberate decisions about what to include and what to leave out for each task. This requires judgment and iteration.
- • **Cultural adoption.** Engineers accustomed to direct coding may view context authoring as overhead rather than engineering. Teams must reframe context as a first-class artifact — as important as code and tests.
- • **Tooling gaps.** The ecosystem for context management is still maturing. Teams may need to build custom tooling for context assembly, token budgeting, and staleness detection until standard tools emerge.