Context engineering para devs: specs melhores para agentes de IA

Contexto não é despejar o projeto inteiro

O incidente não aconteceu por falta de tokens. Mais arquivos não significam mais clareza: um agente pode receber milhares deles e ainda não saber qual regra prevalece, qual comportamento é intencional ou quais áreas não deve alterar. Engenharia de contexto começa pela relevância e pela autoridade de cada fonte.

O pacote mínimo combina intenção de produto, contrato funcional e evidência do repositório. Cada camada responde a uma pergunta diferente:

• Por quê: objetivo, usuário, resultado e prioridade
• O quê: cenários, regras, dados, interfaces e critérios de aceite
• Como está hoje: arquitetura, padrões locais e dependências reais
• Como provar: comandos, testes e observáveis esperados

Separe contexto estável de contexto da tarefa

Princípios de arquitetura, segurança e estilo mudam devagar; requisitos de uma feature mudam mais rápido. Misturar tudo em um único prompt torna a atualização difícil e esconde conflitos. É melhor manter fontes estáveis versionadas e compor apenas o recorte necessário para cada mudança.

A spec ocupa a ponte entre os dois ritmos. Ela referencia guardrails duradouros, registra decisões específicas e deixa explícita a precedência quando duas instruções parecem competir.

Dê ao agente um contrato de trabalho

Uma tarefa robusta informa arquivos e sistemas em escopo, comportamento esperado, restrições, casos adversariais e verificação. O agente consegue explorar o código para descobrir detalhes de implementação sem precisar inventar a intenção.

O contrato também define a parada. Testes verdes são parte da evidência, mas não bastam quando o resultado é visual, operacional ou dependente de um artefato. A spec deve nomear o cenário real, a invocação e o observável que demonstram sucesso. Para uma empresa usando vários agentes, esse contrato vira a camada estável que evita refazer a mesma explicação em cada ferramenta.

• Limites claros para escrita e áreas somente leitura
• Exemplos que diferenciam o comportamento correto do fallback
• Falhas esperadas para entradas inválidas ou estado incompleto
• Artefatos de evidência que outra pessoa possa inspecionar

teoai como memória viva de contexto

O teoai é a camada onde o contexto da tarefa deixa de ser um prompt descartável e vira uma spec revisável. Ele reúne briefing, decisões, regras, critérios e evidências em um artefato que pode ser aprovado pelo time e reutilizado por diferentes agentes de código.

No caso da cobrança para contratos renovados, isso significa registrar a regra de negócio, a fonte da data de renovação, as exceções por plano, os arquivos relevantes e a forma de provar o resultado. O agente ainda explora o código, mas parte de uma fonte de autoridade que explica o que deve acontecer e por que aquela área do sistema está em escopo.

Esse é o motivo de o teoai fazer sentido para times que já estão usando IA no desenvolvimento. Quanto mais agentes entram no fluxo, mais valiosa fica uma camada de contexto estável, aprovada e portátil. O dev pode alternar ferramentas sem perder a referência da tarefa; o time pode revisar intenção e execução sem depender da conversa original.

Um fluxo repetível para preparar contexto

Um pacote de contexto útil começa com a pergunta que a mudança precisa responder, não com a busca pelo maior conjunto de arquivos possível. Primeiro, descreva o resultado e o limite; depois, localize as regras e os padrões que governam a área; por fim, escolha a evidência que poderá confirmar o comportamento.

Imagine uma alteração em cobrança que precisa aplicar uma nova regra apenas a contratos renovados. O agente precisa conhecer o evento que inicia o cálculo, a fonte da data de renovação, o arredondamento usado hoje, as exceções por plano e a forma de testar uma cobrança já existente. O repositório inteiro é ruído até que essas relações sejam mapeadas.

Depois da execução, o pacote não deve ser descartado. Registre quais arquivos eram realmente relevantes, qual pergunta apareceu tarde e qual teste capturou a regra. Em um fluxo com teoai, esse aprendizado volta para a spec e deixa a próxima mudança na mesma área partir de uma base melhor, sem transformar cada descoberta em um prompt privado.

• Definir resultado, escopo de escrita e condições de parada
• Mapear donos e fontes de autoridade para regras conflitantes
• Selecionar arquivos, exemplos, contratos e dependências diretamente relevantes
• Explicitar hipóteses e perguntas que o agente não pode resolver sozinho
• Executar a menor mudança que satisfaça os cenários aprovados
• Capturar testes, artefatos e decisões novas para a próxima iteração

Contexto para empresas e devs

Em escala empresarial, contexto precisa sobreviver a fronteiras de equipe. Um serviço pode obedecer a um padrão de autenticação da plataforma, a uma regra de retenção definida por dados e a uma convenção local do repositório. O pacote da tarefa deve apontar para essas fontes, explicitar precedência e evitar colar cópias que envelhecem em velocidades diferentes.

Para devs, isso significa poder abrir uma mudança e entender por que aqueles arquivos foram escolhidos, quais padrões são obrigatórios e quais decisões ainda podem ser exploradas. Um agente bem contextualizado reduz trabalho de busca, mas a pessoa desenvolvedora continua responsável por avaliar acoplamento, legibilidade, migração e impacto operacional.

A divisão entre contexto estável e contexto da tarefa também melhora a revisão. Arquitetura e segurança podem manter guardrails reutilizáveis; o time de produto pode revisar o comportamento específico; a equipe que implementa pode detalhar tarefas sem reescrever princípios que valem para todos os serviços.

• Guardrails globais versionados e referenciados, não duplicados em cada prompt
• Contrato funcional específico ligado à área real de mudança
• Responsáveis por revisar produto, arquitetura, segurança e operação
• Recortes distintos para trabalho em múltiplos repositórios
• Evidência de execução acessível a quem não escreveu o pacote de contexto

Limitações e quando não usar

Mais contexto não compensa uma pergunta ruim. Se o objetivo é “melhorar a arquitetura” sem delimitar comportamento, risco ou decisão, nenhum conjunto de arquivos tornará a tarefa verificável. Comece reduzindo a ambição para uma mudança que possa ser observada e revisada.

Context engineering também não deve virar controle centralizado de cada escolha local. Guardrails precisam cobrir riscos reais; impor instruções globais para detalhes que pertencem ao time aumenta conflitos e incentiva as pessoas a ignorar o pacote inteiro. A autoridade deve ser proporcional ao impacto.

Em uma investigação exploratória, o conjunto relevante pode mudar várias vezes. Nesse caso, registrar hipóteses e resultados é mais honesto que congelar um contrato prematuro. A spec ganha forma quando o time aprende o suficiente para dizer o que será construído e como saberá que funcionou.

• Não substitui conhecimento do domínio, revisão humana ou observabilidade
• Não transforma todos os arquivos do repositório em contexto obrigatório
• Não garante que um agente seguirá uma instrução conflitante ou sem autoridade
• Não vale como cerimônia completa para mudanças triviais e reversíveis

Perguntas e respostas

Pergunta: devo incluir todo o repositório para o agente ter contexto suficiente? Resposta: não. Inclua o caminho da decisão: contratos, implementações vizinhas, testes, configurações e padrões que influenciam a mudança. Contexto irrelevante aumenta custo e pode esconder a fonte de autoridade.

Pergunta: o que fazer quando duas fontes de contexto discordam? Resposta: não deixe o agente decidir por frequência ou proximidade. Registre a precedência, peça revisão ao dono da regra e atualize a fonte estável ou o contrato da tarefa para que o conflito não reapareça silenciosamente.

Pergunta: como medir se o pacote de contexto melhorou o trabalho? Resposta: observe retrabalho, perguntas repetidas, falhas de aceite e tempo gasto encontrando arquivos. Combine esses sinais com uma revisão qualitativa: o time consegue explicar a decisão e reproduzir a verificação sem depender da conversa original?