Engenharia de contexto para times de desenvolvimento

Engenharia de contexto é a prática de escolher e manter as informações que vão orientar uma tarefa com inteligência artificial. Para uma equipe de desenvolvimento, a decisão não é “juntar tudo para o modelo entender melhor”. É separar o que muda a implementação, de onde essa informação veio, quem pode confirmá-la e até quando ela vale. Sem isso, a IA pode amplificar o ruído que já existia no processo.

Quando contexto demais atrapalha tanto quanto contexto de menos

Uma tarefa chega com uma descrição aparentemente suficiente: alterar uma regra, ajustar um fluxo, corrigir uma exceção. No repositório, porém, a história é menos limpa. Existe uma decisão antiga em uma issue, uma exceção discutida em comentário de pull request, uma regra descrita em uma planilha e uma restrição operacional que só uma pessoa costuma lembrar.

Antes da inteligência artificial, esse cenário já gerava retrabalho. Com IA, ele ganha outra dimensão. O modelo não sabe, por si só, qual informação é vigente, qual é histórica, qual foi superada e qual é apenas opinião registrada em algum lugar. Se tudo entra no pedido como se tivesse o mesmo peso, a saída pode parecer coerente e ainda assim estar orientada por contexto errado.

Mais contexto não é automaticamente melhor contexto.

A primeira decisão da equipe deve ser editorial, não técnica: escolher o que deve orientar a tarefa. Essa escolha exige critério. Uma documentação longa e desatualizada pode atrapalhar mais do que ajudar. Um comentário curto, mas escrito pela pessoa responsável pela regra, pode ser decisivo. Um teste automatizado pode valer mais do que uma descrição ambígua em uma página esquecida.

A adoção de IA só chega ao desenvolvimento quando vira critério de tarefa. Conteúdos como como criar uma estratégia de inteligência artificial conectada ao negócio ajudam a enquadrar a adoção. Mas, no fluxo do time, a decisão continua sendo separar contexto útil de ruído.

O que conta como contexto em uma tarefa de desenvolvimento

A Anthropic define engenharia de contexto como a seleção e manutenção das informações disponíveis ao modelo durante a inferência. Esse conjunto pode incluir instruções, ferramentas, dados externos e histórico, dentro de uma janela limitada.

Aplicada ao desenvolvimento, essa definição precisa sair do abstrato. Contexto pode ser:

a descrição da tarefa;
os arquivos do repositório que serão lidos ou alterados;
testes existentes;
decisões de arquitetura registradas;
comentários de revisão relevantes;
regras de negócio vigentes;
restrições de ambiente;
permissões da ferramenta ou do agente;
histórico de incidentes ou correções relacionadas;
critérios de aceite definidos pela equipe.

O problema é que esses itens não têm a mesma autoridade. Código em produção, teste automatizado, documentação de produto, comentário de revisão e memória oral não devem entrar no mesmo saco. Cada um tem uma origem, um responsável e um grau diferente de validade.

A janela de contexto limitada reforça essa disciplina. Como não cabe tudo, alguém precisa decidir. E mesmo quando a ferramenta permite anexar muita coisa, a pergunta continua sendo a mesma: essa informação melhora a decisão de implementação, teste ou revisão desta tarefa específica?

Se a resposta for não, ela pode ficar como referência lateral. Mas não deveria orientar a alteração.

A matriz mínima: informação, origem, responsável e validade

Uma forma simples de organizar engenharia de contexto em equipes de desenvolvimento é registrar quatro dimensões antes de pedir, revisar ou integrar uma mudança assistida por IA:

informação: qual é exatamente o item que deve orientar a tarefa;
origem: de onde ele veio;
responsável: quem ou qual artefato pode confirmar, corrigir ou revogar o item;
validade: em que versão, produto, ambiente ou regra essa informação ainda se aplica.

Essa matriz não precisa virar burocracia. Ela pode estar no corpo da issue, no template da tarefa, no comentário que acompanha o pull request ou no documento operacional do time. O ponto não é criar mais um repositório de documentos. É impedir que informação sem procedência seja tratada como instrução.

Um critério prático ajuda: se a equipe não consegue dizer de onde veio uma informação, ela deve ser marcada como hipótese. Hipótese pode orientar investigação, mas não deveria orientar implementação automática. Se não existe responsável, a informação pode até ser útil, mas precisa ser usada com cautela. Se a validade é incerta, a equipe precisa resolver a dúvida antes de entregar a mudança como se fosse segura.

Checklist de pertinência do contexto

Pertinência: esta informação muda a decisão de implementação, teste ou revisão desta tarefa específica? Se não muda, remova do contexto principal.
Origem: a informação veio de código, teste, documentação, decisão registrada, comentário de revisão, regra de negócio ou pessoa responsável? Se a origem não aparece, trate como hipótese.
Responsável: existe alguém ou algum artefato oficial que possa confirmar, corrigir ou revogar essa informação? Se não existe, não use como base única para a mudança.
Validade: a informação ainda vale para a versão, produto, cliente, ambiente ou regra atual? Se não vale, marque como histórico.
Conflito: há outra fonte dizendo algo diferente sobre o mesmo ponto? Se houver, resolva o conflito antes de pedir a alteração.
Teste: a informação pode ser confirmada por teste automatizado, teste manual definido ou revisão objetiva? Se não puder, separe como decisão humana ou investigação.
Permissão: o agente ou ferramenta deve acessar essa informação e agir sobre ela neste ambiente? Se não deve, exclua do contexto operacional.

Esse checklist é uma aplicação prática. Ele não substitui descoberta de requisitos, decisão de arquitetura nem revisão humana. Ele apenas torna explícito o que muitas equipes deixam implícito.

Como escolher o contexto pertinente para uma mudança pequena

A engenharia de contexto fica mais difícil quando a tarefa é grande demais. Se a mudança mistura regra de negócio, refatoração, alteração visual, migração técnica e correção de comportamento, o contexto necessário também se espalha. A equipe passa a precisar de mais fontes, mais responsáveis e mais critérios de validade.

O DORA recomenda unidades de trabalho pequenas, independentes e testáveis para obter retorno sobre mudanças e revisar hipóteses mais cedo. A mesma fonte alerta para a dificuldade de revisar e integrar grandes mudanças geradas com IA.

Essa orientação não prova que uma tarefa pequena sempre terá melhor resultado com IA. Mas oferece um critério operacional: quanto menor e mais testável a mudança, mais claro tende a ser o conjunto de informações que deve orientá-la.

Em vez de pedir “ajuste o fluxo de descontos”, a equipe pode recortar a tarefa: “alterar a regra de desconto para pedidos com cupom promocional em um canal específico, preservando o comportamento existente nos demais canais”. Esse recorte muda a busca por contexto. Agora importam os arquivos da regra, os testes daquele fluxo, a decisão vigente sobre cupom, a pessoa ou área responsável pela regra e o critério de verificação.

Esse recorte exige uma capacidade organizacional específica: decidir escopo, origem e responsabilidade antes de aumentar a autonomia da ferramenta. O diagnóstico dessa capacidade pode ser pensado junto de temas como maturidade em IA, mas a prática começa em cada tarefa.

Exemplo fictício: alterar uma regra de desconto sem contaminar a tarefa

Imagine um exemplo fictício. Uma empresa de comércio eletrônico precisa alterar uma regra de desconto para pedidos feitos por um canal de parceiros. A tarefa chega assim: “Atualizar desconto de parceiros conforme regra nova. Ver docs e comentários antigos”.

No primeiro cenário, a equipe envia ao agente de programação uma pasta de documentação, algumas issues antigas, comentários de revisão e arquivos do módulo de checkout. Tudo parece relevante. Só que há conflito: uma página de documentação descreve a regra antiga, uma issue menciona uma exceção temporária, um comentário de pull request sugere uma mudança que nunca foi implementada e o teste atual confirma outro comportamento.

A IA pode produzir uma alteração plausível. Mas a equipe não sabe se ela seguiu a regra nova, a exceção antiga ou uma interpretação dos comentários. A revisão humana fica mais pesada porque precisa reconstruir o contexto depois do código pronto.

No segundo cenário, antes do pedido, a equipe organiza o contexto:

Informação: desconto de parceiros deve seguir a regra vigente para o canal específico.
Origem: regra registrada na documentação atual de produto e confirmada no teste existente que cobre o fluxo base.
Responsável: pessoa responsável pela regra comercial ou artefato oficial definido pela equipe.
Validade: aplica-se apenas ao canal de parceiros e à versão atual da regra.
Conflito: issue antiga marcada como histórica, porque descrevia uma exceção temporária.
Teste: atualizar ou criar teste que confirme o comportamento do canal afetado e preserve os demais.
Permissão: agente pode ler os arquivos do módulo e os testes relacionados, mas não deve alterar regras de outros canais.

Esse segundo pedido não garante uma saída correta. A hipótese a medir é mais modesta: a revisão tende a ficar mais objetiva quando o contexto usado na geração já separa fonte vigente, histórico e restrição de escopo. A equipe ainda precisa revisar código, testes e aderência à regra. A diferença é que a conversa deixa de ser “o que a IA entendeu?” e passa a ser “o contexto fornecido era correto, suficiente e autorizado?”.

Essa mudança de pergunta é pequena, mas altera a responsabilidade do processo.

Onde a revisão humana entra na engenharia de contexto

Revisão humana não deveria aparecer apenas no fim, como uma etapa de correção tardia. Em tarefas assistidas por IA, ela também precisa revisar o contexto antes e durante o trabalho.

A documentação do GitHub descreve recursos de agentes com ambientes e permissões distintos e ressalta supervisão humana e revisão das saídas. Para equipes de desenvolvimento, isso permite uma leitura prática: permissões, ambiente e revisão fazem parte do desenho do trabalho, não apenas da ferramenta.

Na prática, a revisão humana deve responder perguntas como:

o agente teve acesso apenas ao necessário para a tarefa?
alguma informação sensível, histórica ou não autorizada entrou no contexto operacional?
a fonte principal da regra estava clara?
havia conflito entre documentação, código e comentário de revisão?
o pedido separou instrução, hipótese e referência?
os testes usados para verificar a mudança correspondem à regra vigente?

Esse tipo de revisão exige julgamento. Não é uma formalidade para satisfazer governança. É a forma de impedir que a equipe terceirize para o modelo uma decisão que ainda pertence ao processo.

Também é aqui que liderança técnica e liderança de produto se encontram. Nem todo item de contexto é técnico. Uma regra de negócio, uma restrição operacional ou uma decisão de produto podem determinar o que o código deve fazer. Se essas informações entram sem responsável, a engenharia carrega uma ambiguidade que não tem como resolver sozinha.

Critério de fechamento: o contexto sobrevive à integração contínua

A última verificação é simples de formular e difícil de sustentar: o contexto usado na alteração ainda faz sentido quando a mudança encontra o código principal?

O DORA descreve integração contínua como integração frequente ao código principal, acompanhada de construção e testes automatizados. Também afirma que corrigir uma construção quebrada deve ter prioridade sobre novas mudanças.

Para engenharia de contexto, isso cria um critério de fechamento sobre a persistência do contexto, não sobre a divisão da tarefa. Antes de integrar uma alteração assistida por IA, a equipe deve verificar se:

a mudança continua dentro do escopo definido;
os testes correspondem à informação que orientou a implementação;
a documentação ou decisão usada como fonte segue válida;
conflitos descobertos durante a revisão foram resolvidos ou registrados;
a construção automatizada não foi quebrada;
uma falha de build interrompe novas mudanças até ser corrigida.

Esse critério não promete qualidade, velocidade ou redução de defeitos. Ele reduz uma incoerência comum: tratar contexto como algo útil para gerar código, mas descartável na hora de integrar.

Se a regra usada para orientar o agente não aparece em teste, revisão ou decisão registrada, ela continua frágil. Se uma exceção histórica entrou no pedido sem marcação, ela pode reaparecer como comportamento novo. Se a equipe não sabe quem responde por uma informação, ela provavelmente também não saberá quando essa informação deixar de valer.

Engenharia de contexto depende menos de confiança retórica na tecnologia e mais de confiança operacional na origem, na responsabilidade e na validade das informações que orientam o trabalho.

Na próxima tarefa assistida por IA, antes de pedir, revisar ou integrar a alteração, liste as informações que realmente orientam a mudança e marque origem, responsável e validade de cada uma. Se uma informação não passar por esse filtro, trate como hipótese ou retire do contexto operacional.

Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.

Leituras para continuar

Fontes

PRÓXIMA DECISÃO

Conversar sobre a aplicação na empresa

Conversa sobre o contexto da empresa de software

Conteúdo de dooop. O cadastro permite relacionar esta pauta à jornada do leitor e acompanhar o interesse pelo tema.