Crafting Context-Rich Prompts for Code Generation

1. Além do "Vibe Coding": A Necessidade de Contexto

Se você simplesmente alimentasse um LLM com o seu plano JSON e dissesse "implemente isso", os resultados seriam imprevisíveis. O modelo poderia:

• Alucinar funções ou APIs que não existem.
• Ignorar as convenções de nomenclatura e estilo do seu projeto.
• Produzir código que não se integra com a arquitetura existente.

Essa abordagem, às vezes chamada de "vibe coding", é adequada para prototipagem rápida, mas inadequada para ambientes de produção. Para construir um agente confiável, precisamos de uma abordagem mais sistemática.

A engenharia de contexto é o processo de projetar e fornecer esse ecossistema de informações ao LLM. Não se trata apenas de ajustar as palavras em um prompt, mas de tratar o próprio contexto como um recurso de engenharia.

2. A Anatomia de um Prompt de Alta Qualidade

Então, que informações compõem um "contexto rico" para a geração de código? Com base na sua experiência como desenvolvedor sênior, muitos desses elementos serão familiares, pois são os mesmos que você forneceria a um novo colega de equipe.

O artigo a seguir, de Addy Osmani, fornece um framework excelente para estruturar essas informações.

Vamos adaptar as "seis áreas principais" de Osmani para o nosso agente de codificação:

1. O Objetivo (O que construir):

   • Descrição da Tarefa: O texto do ticket do Jira.
   • Plano de Execução: Nosso plano JSON validado, que detalha os arquivos a serem modificados e as ações a serem tomadas.

2. Estrutura do Projeto:

   • Um mapa claro do repositório: "O código-fonte do backend em C# está em src/MyApi, os testes estão em tests/MyApi.Tests."
   • Isso guia o agente sobre onde criar novos arquivos e encontrar os existentes para modificação.

3. Estilo de Código e Regras de Arquitetura:

   • Exemplos de Código: A maneira mais eficaz de ensinar o estilo é mostrando. Inclua um trecho de um controller, serviço ou componente React existente que siga as melhores práticas do seu projeto.
   • Convenções: "Nomes de branch devem seguir o padrão feature/JIRA-123-description." "Use async/await para todas as operações de I/O."
   • Pilha de Tecnologia: Seja explícito sobre as versões e bibliotecas principais (ex: ".NET 8, Entity Framework Core, React 18 com Hooks, Dapper").

4. Testes:

   • Como executar os testes (dotnet test).
   • Onde os arquivos de teste devem ser criados.
   • Exemplos de testes unitários existentes.

5. Fluxo de Trabalho do Git:

   • Padrões de mensagem de commit.
   • Requisitos para Pull Requests (ex: "O corpo do PR deve conter um link para o ticket do Jira").

6. Limites (Boundaries):

   • O artigo de Osmani sugere um sistema de três níveis (Sempre faça, Pergunte primeiro, Nunca faça), que é extremamente útil para definir guardrails.
   • 🚫 Nunca faça: "Nunca faça commit de segredos ou chaves de API." "Não modifique o arquivo Startup.cs sem aprovação."
   • ⚠️ Pergunte primeiro: "Pergunte antes de adicionar uma nova dependência NuGet ou pacote NPM."
   • ✅ Sempre faça: "Sempre execute os testes unitários antes de criar um PR."

Reunir todo esse contexto manualmente para cada tarefa seria impraticável. Felizmente, existem frameworks e ferramentas para automatizar essa montagem.

3. Framework Prático: Product Requirement Prompts (PRPs)

O conceito de Product Requirement Prompt (PRP) formaliza a montagem de todo esse contexto em um único artefato abrangente que é então entregue ao agente para execução.

O fluxo de trabalho com PRP geralmente envolve duas etapas principais:

1. Geração do PRP: O agente, ou um processo separado, pega uma descrição de alto nível da tarefa e, usando o acesso à base de código e outras fontes de conhecimento, gera um prompt massivo e detalhado (o PRP). Este PRP inclui seções para o objetivo, arquivos a serem modificados, exemplos de código relevante, regras de arquitetura, etc.
2. Execução do PRP: Após a revisão e aprovação humana, este PRP abrangente é alimentado ao agente de codificação para gerar as modificações de código.

Essa abordagem estruturada é exatamente o que transforma a geração de código de uma aposta em um processo de engenharia.

4. Implementando a Construção do Contexto no seu Workflow Atlassian

Agora, vamos conectar esses conceitos ao seu objetivo de construir um agente no ecossistema Atlassian.

O Papel do AGENTS.md

Uma maneira direta de fornecer as "regras de arquitetura" e "estilo de código" é através de um arquivo AGENTS.md na raiz do seu repositório. O Rovo Dev (e outras ferramentas de agente do GitHub) é projetado para ler este arquivo automaticamente.

Para o seu projeto, você pode criar um AGENTS.md em cada um dos seus repositórios (backend, frontend, mobile) contendo:

• Um trecho de código exemplar (ex: um endpoint C# com injeção de dependência, um componente React com hooks).
• Instruções de build e teste.
• Padrões de nomenclatura.
• Regras sobre o que não modificar.

Montando o Prompt Final (o "PRP")

Seu agente Rovo, acionado pelo evento do Jira, será responsável por montar o prompt final (nosso PRP) antes de chamar o LLM para gerar o código. O processo se parecerá com isto:

1. Gatilho: O agente é ativado com o ID do ticket do Jira e nosso plano JSON aprovado.
2. Coleta de Contexto: O agente executa várias etapas para coletar informações:
   • Lê o AGENTS.md: Carrega as regras arquitetônicas do repositório de destino.
   • Recupera Código Existente (RAG): Com base no plano JSON, ele identifica os arquivos que precisam ser modificados e recupera seu conteúdo atual da base de código.
   • Recupera Regras de Negócio (RAG): Consulta as fontes de conhecimento (ex: Google Drive) para obter quaisquer regras de negócio relevantes para a tarefa.
   • Lê o Ticket do Jira: Extrai a descrição original e os critérios de aceitação.
3. Montagem do Prompt: O agente combina todas essas informações em um único prompt estruturado e abrangente, seguindo os princípios que discutimos. Ele instrui o LLM a usar o plano JSON como guia, aplicar as regras do AGENTS.md e seguir o estilo do código existente fornecido.
4. Geração de Código: Este prompt completo é enviado ao modelo de IA da Atlassian para gerar as alterações de código.

Conclusão

Nesta lição, você aprendeu a arte e a ciência de construir prompts eficazes para a geração de código. Deixamos para trás a abordagem de "vibe coding" e adotamos um processo de engenharia estruturado.

Principais Pontos:

• A geração de código de alta qualidade depende de um contexto rico e bem estruturado, um conceito conhecido como Engenharia de Contexto.
• Um prompt eficaz deve incluir um objetivo claro, regras de arquitetura, estilo de código, exemplos de código existente, estrutura do projeto e limites claros.
• O framework Product Requirement Prompt (PRP) oferece um método sistemático para montar e executar esses prompts de alto contexto, incluindo uma etapa de revisão humana.
• No seu ecossistema, o arquivo AGENTS.md é a ferramenta ideal para armazenar regras de arquitetura específicas do repositório, que o seu agente Rovo pode consumir automaticamente.

Na Próxima Lição

Agora que entendemos como pedir por código de maneira eficaz, as próximas lições focarão nos detalhes da geração para cada parte da sua pilha de tecnologia. A seguir, vamos nos concentrar no backend, abordando o resultado: Guiar o agente para gerar modificações de código para uma aplicação backend C#/.NET.