Engenharia de contexto para agentes de codificação

A engenharia de contexto é o trabalho de decidir o que um agente de codificação vê antes de agir. É a maior vantagem que você tem sobre a qualidade da saída, porque um modelo viável só é tão bom quanto o que é fornecido a ele.

No Jira, o contexto de que um agente precisa já faz parte do ticket. O ticket traz a meta e os critérios de aceitação, e o Teamwork Graph o conecta ao código, às decisões e aos documentos relacionados, para que um agente atue com base na intenção real em vez de um prompt em branco. Esse contexto fica compartilhado com a sua equipe e não escondido em arquivos locais de uma única máquina.

Este guia aborda o que é engenharia de contexto, por que a janela de contexto é a verdadeira restrição para agentes de codificação e como é possível estruturar o contexto no Jira para que os agentes tenham o que precisam sem que você tenha que incluir tudo à mão a cada prompt. Na prática, se resume a algumas ações no ticket que você já gerencia:

• Entregue ao agente a meta, não apenas um prompt. Escreva o ticket do Jira como a especificação, com os critérios de aceitação usados para avaliar o agente.

• Deixe que o gráfico forneça o contexto relacionado. Ao usar o ticket como ponto de partida para o prompt, o Teamwork Graph o expande para os documentos, decisões e o contexto relacionado à tarefa.

• Mantenha os padrões compartilhados e atualizados. As convenções ficam no Confluence, com todos os agentes e colegas de equipe usando a mesma fonte.

• Dê a qualquer agente a mesma camada de contexto. O mesmo contexto organizacional chega a todos os agentes de codificação, como Claude Code, Cursor, Codex, GitHub Copilot, Jira Coding Agent e outros.

O que é engenharia de contexto?

Engenharia de contexto é a prática de decidir com propósito quais informações um modelo vê em cada etapa, para que um agente de codificação tenha o que precisa para trabalhar do jeito certo. Essa informação é mais do que o prompt: é a base de código, seus padrões, dependências, histórico do git, definições de ferramentas, metas e critérios de aceitação. Fazer a curadoria desse conjunto para cada tarefa é o novo trabalho.

Engenharia de prompt significa que você faz a curadoria das informações e as adiciona a uma única instrução. Engenharia de contexto significa que o sistema oferece o que o agente precisa em uma tarefa de várias etapas: o que é incluído, o que é recuperado, o que é resumido e o que fica de fora, para que o agente possa encontrar o restante conforme precisar.

É importante observar que mais contexto não significa sempre um contexto melhor:

• Contexto de alto sinal é a informação que de fato ajuda na tarefa em questão

• Contexto de baixo sinal é o conteúdo desatualizado, que não se refere ao tópico ou duplicado que o modelo ainda precisa ler

Conforme uma janela de contexto se enche de tokens de baixo sinal, as respostas ficam mais lentas e menos precisas, mesmo que o modelo não tenha mudado. Essa degradação é chamada de deterioração de contexto, o declínio gradual na saída à medida que a janela de contexto se enche de tokens obsoletos, de baixo sinal ou contraditórios. Uma boa engenharia de contexto trata tanto de remover o contexto obsoleto quanto de adicionar o contexto certo.

Por que a janela de contexto é a restrição para os agentes de codificação?

Um modelo de código só consegue raciocinar sobre o que se encaixa na janela de contexto, que é pequena em comparação com a sua base de código, sua documentação e o histórico da sua equipe. Um agente apto ainda pode lançar um código incorreto ou inseguro quando suas convenções, arquitetura ou decisão por trás de uma tarefa nunca chega à janela.

Quando a coleta de contexto fica a cargo do agente, alguns modos de falha se repetem:

• O agente se desvia em uma tarefa longa porque a decisão tomada no início é retirada da janela de contexto à medida que novos tokens de menor sinal se acumulam.

• Ele recupera em excesso, trazendo muito mais para a janela do que utiliza e gastando o orçamento de tokens com ruído.

• Ele nunca vê um padrão que você não tenha apresentado, então lança um código que quebra um padrão que o resto da equipe segue.

• Trabalha bem sozinho, mas não faz ideia do que o resto da equipe, ou outro agente, está fazendo na mesma área.

Em vez disso, facilitar o acesso ao contexto certo permite que o agente encontre o que precisa por conta própria à medida que avança, assim seus prompts podem continuar de alto nível em vez de precisar especificar cada convenção e decisão à mão.

Como fazer a engenharia de contexto para agentes de codificação no Jira?

No Jira, você transforma o próprio ticket no contexto: a intenção fica no ticket, o conhecimento relacionado é conectado pelo Teamwork Graph, e padrões e decisões duradouros são extraídos do Confluence e do Loom, onde cada agente e colega de equipe consulta a mesma fonte. O Jira vai além dos arquivos locais em uma única máquina, chegando às metas, às decisões e conversas em andamento e ao histórico de todo o ticket. O que mantém todas essas informações compartilhadas, assim o contexto em que um agente atua fica estruturado, atualizado e consistente para toda a equipe.

A engenharia de contexto se baseia em três princípios:

1. Selecionar as informações certas

2. Manter as informações estruturadas

3. Seguir utilizando as informações

1. Seleção e recuperação: escreva o ticket conforme a especificação

A seleção consiste em escolher o menor conjunto de contexto de alto sinal para uma tarefa, enquanto a recuperação se trata de buscar os fatos certos sob demanda, em vez de despejar tudo na janela de uma só vez. No Jira, ambos começam com o ticket.

• Como funciona no Jira: coloque a meta na descrição e os critérios de aceitação em um checklist. Dá ao agente a intenção e o critério pelo qual vai ser avaliado, em uma estrutura que ele consegue ler. Em seguida, atribua o ticket a um agente conectado. Ele começa pelo ticket e pelo contexto vinculado, não por toda a base de código. A discussão com o agente para refinar essa especificação faz parte do trabalho: ele lê grandes volumes com rapidez e ajuda você a encontrar as lacunas antes de começar.

• Em breve: o Jira Planner transforma ideias em planos prontos para agentes e tickets com o contexto já anexado. Entre na lista de espera.

2. Contexto compartilhado: não cole o ticket, vincule

A estrutura e o formato são fundamentais: molde o contexto para que um agente possa se orientar e mantenha conectado em vez de copiado. O Teamwork Graph é o que disponibiliza o contexto relacionado sem a necessidade de montar tudo a cada vez.

• Como funciona no Jira: vincule o ticket a tickets relacionados, ao código e às páginas do Confluence que contêm a especificação, a RFC ou o registro de decisões. O agente herda o contexto relacionado à tarefa, não apenas o texto do ticket. Um passo a passo no Loom também vale: uma reprodução de bug gravada ou lógica de design leva a transcrição e resumo para o gráfico, para que uma explicação que você daria a um colega de equipe se torne um contexto que um agente pode ler. Oferece os "fatos corretos recuperados" do seu trabalho real e não de um armazenamento de vetores separado que você precisa criar e manter.

3. Persistência: mantenha padrões e decisões onde eles se acumulam

A persistência, ou memória, tem o propósito de manter fatos duradouros disponíveis entre as sessões para que o agente não comece do zero toda vez. Os três pontos a considerar são: o que o agente mantém durante uma tarefa, o que ele deve manter entre as tarefas e o que ele pode consultar quando necessário.

• Como funciona no Jira: convenções, decisões de arquitetura e padrões preferidos ficam no espaço compartilhado do Confluence, onde toda a equipe e cada agente consultam a mesma fonte pelo gráfico, em vez de uma cópia na máquina de uma pessoa que mais ninguém pode ver. Conforme o ticket passa pelo sistema, o gráfico fica mais rico, assim o próximo agente tem mais informações para se basear. O contexto se acumula à medida que o ticket é concluído, sem nenhuma etapa manual extra para a pessoa desenvolvedora.

Duas coisas mantêm isso funcionando para toda a equipe: uma camada de contexto que todo agente pode usar e uma governança que a mantém confiável e autorizada.

Uma camada de contexto para qualquer agente

O contexto que você cria só tem valor se todas as ferramentas puderem usar. Ensinar seus padrões de novo para cada agente é a maneira mais rápida de deixar o contexto degradado.

• Como funciona no Jira: dê a qualquer agente de codificação o mesmo contexto organizacional por meio de dois caminhos. A CLI do Teamwork Graph dá ao seu agente de codificação acesso direto a esse contexto e às suas ferramentas pelo terminal. Configure uma vez e seu agente vai poder consultar o gráfico enquanto trabalha. O servidor Atlassian Rovo MCP faz o mesmo para clientes MCP, como Claude, Cursor, Codex e GitHub Copilot. O Teamwork Graph é o que armazena tudo: tickets, decisões, documentos e código conectados como uma única camada que pode ser consultada. Você cria o contexto uma vez e o utiliza com qualquer modelo que execute o ticket.

Governança: mantenha o contexto confiável e com permissão para ser visto

O contexto só é útil se for atual e o agente tiver permissão para ver. A governança mantém a camada compartilhada confiável à medida que mais agentes a utilizam.

• Como funciona no Jira: os agentes herdam as mesmas permissões que a sua equipe já usa como linha de base, então um agente vê o que o usuário por trás dele pode ver, e nada mais, e pode ter seu escopo ainda mais definido com regras específicas do agente. Para saber como o acesso, a aprovação e a auditoria se integram, consulte Barreiras de proteção e segurança de engenharia agêntica no Jira.

Como o Jira funciona com o resto da sua estrutura de contexto?

Hoje, a maior parte do contexto de um agente de codificação fica em uma única máquina: o repositório que ele tem aberto, alguns arquivos locais e tudo o que o desenvolvedor inseriu no prompt. Isso funciona quando o trabalho é individual, mas o contexto fica disperso, restrito a cada pessoa e não é preservado. O Jira e o Teamwork Graph reúnem o contexto relevante em uma única camada compartilhada, atualizada e governável, de onde toda a equipe e seus agentes podem obter informações.

Nada disso substitui seu agente de codificação, seu IDE ou sua configuração local. Eles continuam lidando com os detalhes de cada repositório e com o código em si. O Jira é a camada compartilhada que fica acima de tudo isso. Dessa forma, o contexto usado por todos fica estruturado, atualizado e o mesmo em toda a equipe.

Como oferecer contexto real ao seu primeiro agente no Jira

No fim das contas, a engenharia de contexto consiste em dar a um agente as ferramentas e informações para encontrar o que precisa por conta própria. O Jira e o Teamwork Graph são a camada de contexto compartilhado acessada por meio do MCP ou da CLI, assim, o trabalho passa a ser manter essa camada atualizada e conectada.

Comece com um ticket bem estruturado para ver a diferença entre um agente que faz suposições e um agente que trabalha com base na intenção.

1. Dê ao agente os critérios de avaliação. Escolha uma tarefa específica, de baixo risco e fácil de desfazer, como um refatoramento autocontido ou uma pequena correção de bug, e descreva a meta e os critérios de aceitação em uma checklist.

2. Faça o agente herdar o contexto em vez de inserir. Vincule o ticket ao código usando a chave do ticket na sua ramificação, confirmação ou pull request e inclua um link para o documento ou a decisão que deu origem a ele. O agente capta o contexto vinculado à tarefa, não apenas o texto do ticket.

3. Aponte para um padrão compartilhado. Vincule a convenção que ele deve seguir a uma página do Confluence, assim o próximo agente e o próximo colega de equipe usam a mesma fonte.

4. Atribua a um agente. O agente começa pelo ticket e seu contexto vinculado, um ponto de partida mais focado do que toda a base de código ou um prompt em branco.

5. Avalie com base nos critérios que o originaram. Confira o pull request com base nos critérios de aceitação definidos no ticket, assim a saída é avaliada de acordo com os critérios originais definidos para o agente.

6. Peça ao agente para fechar o ciclo. Peça para atualizar o ticket no final com um resumo da sessão, as principais decisões e concessões, e o pull request vinculado, para que o próximo colega de equipe ou agente continue de onde parou por meio do Teamwork Graph.

Execute alguns tickets dessa forma e o gráfico se preenche à medida que você avança: cada agente deixa um resumo, suas principais decisões e o pull request vinculado no ticket. Dessa forma, o próximo começa com uma visão mais completa do que o anterior. Isso é engenharia de contexto que se acumula em vez de zerar a cada execução.

Perguntas frequentes sobre engenharia de contexto

Qual é a diferença entre engenharia de contexto e engenharia de prompt?

A engenharia de prompt consiste em fazer a curadoria manual de informações relevantes para um único prompt. A engenharia de contexto consiste em implementar um sistema que fornece informações para um agente ao longo de uma tarefa de várias etapas, incluindo recuperação, estrutura, memória e a própria meta. Dessa forma, ele mostre os detalhes sob demanda conforme necessário.

Como os agentes de codificação de IA obtêm contexto do Jira?

Os agentes extraem contexto do ticket, da sua descrição e dos critérios de aceitação, e do Teamwork Graph, que conecta tickets, documentos e códigos relacionados. Dessa forma, o agente atua com base na intenção real, e não em um prompt em branco.

Por que os agentes de codificação produzem código errado mesmo com um bom prompt?

É raro um prompt carregar suas convenções, arquitetura ou a decisão por trás de uma tarefa. A maioria das falhas dos agentes decorre de problemas de contexto, não de falhas do modelo, e melhorar o contexto é mais eficaz do que melhorar a redação.

Ainda preciso de engenharia de contexto se o meu agente já lê meu repositório?

Sim. Um repositório informa a um agente o que é o código, mas não por que ele foi criado dessa forma, quais padrões seguir ou o que está acontecendo na equipe. A engenharia de contexto fornece o restante.

O que é deterioração de contexto?

A deterioração de contexto é a degradação gradual da saída de um agente à medida que sua janela de contexto se enche de tokens obsoletos, de baixo sinal ou contraditórios. As respostas ficam mais lentas e menos precisas, mesmo que o modelo não tenha mudado.