Não cole a documentação inteira no prompt: dê ao agente uma fonte de verdade

Eu conheço bem a tentação: abrir a documentação da API, copiar o README, juntar dois exemplos de código e colocar tudo no prompt. Parece uma forma segura de dar contexto ao agente.

O problema aparece alguns dias depois. Uma página foi atualizada, o exemplo copiado ainda usa a versão anterior e as instruções do repositório entram em conflito com um tutorial. O agente recebe bastante texto, mas não sabe qual trecho tem autoridade. A resposta sai convincente e o erro só aparece no runtime.

Aumentar a janela de contexto não resolve essa mistura. Para trabalhar com APIs que mudam, o agente precisa saber onde buscar a informação atual, como registrar a origem e o que fazer quando a fonte não cobre a dúvida.

Texto disponível não é fonte de verdade

Tudo o que entra no prompt tende a ganhar o mesmo peso, embora tenha naturezas bem diferentes. Uma regra do projeto pode continuar válida por meses. A assinatura de um método externo pode mudar amanhã. Um log da execução atual talvez só seja útil nos próximos dez minutos.

Quando essas informações viram um bloco único, três problemas ficam escondidos:

• não há indicação clara de qual versão está sendo usada;
• • trechos antigos continuam circulando porque ainda parecem plausíveis;
• • uma resposta bem escrita pode misturar fato documentado e suposição sem avisar.

Também existe um custo de manutenção. Cada pessoa monta seu próprio pacote de contexto, atualiza uma parte e esquece outra. A equipe passa a revisar prompts enormes em vez de revisar a decisão que levou ao código.

Uma fonte oficial consultada sob demanda deixa esse fluxo mais fácil de conferir porque preserva a origem da resposta. A Developer Knowledge API do Google e seu servidor MCP, por exemplo, oferecem consulta a um corpus oficial de documentação; o método AnswerQuery chegou à disponibilidade geral em julho de 2026. Isso é útil, mas a cobertura não é universal e uma resposta aterrada ainda pode ser insuficiente para a tarefa.

A consulta ajuda a responder "de onde veio esta afirmação?". Ela não responde sozinha "esta implementação funciona no meu projeto?".

Separe o conhecimento do agente por função

Eu prefiro tratar o contexto como três camadas com ritmos de mudança diferentes.

1. Instruções do repositório

Convenções de código, arquivos permitidos, comandos de teste e critérios de aceite devem ficar perto do projeto e ser versionados com ele. Esse é um bom lugar para uma skill curta ou um arquivo de instruções que o agente carrega ao montar o repositório.

Alguns runtimes gerenciados já carregam skills mantidas no próprio projeto. A ideia é mais importante do que o formato específico: se a regra muda junto com o código, ela precisa participar do histórico, da revisão e da responsabilidade do time.

Esse arquivo não deve virar uma enciclopédia. Ele pode registrar coisas operacionais, como:

## Integrações externas
- Consulte a documentação oficial antes de alterar uma chamada de API.
- Registre URL e versão ou data relevante no resultado.
- Não troque dependências sem aprovação.

## Validação
- Rode o teste de integração afetado.
- Se a documentação não cobrir o caso, marque a hipótese como não validada.

Skills também envelhecem. Ter a instrução no Git facilita perceber e corrigir esse envelhecimento; não garante que alguém fará a revisão.

2. Documentação externa mutável

A documentação que muda com o fornecedor deve ser consultada durante a tarefa. Pode ser por API, MCP, busca restrita a um domínio oficial ou outro conector com origem identificável. O contrato precisa nomear quais fontes são aceitas e quais dados devem acompanhar a resposta.

No mínimo, eu guardaria:

• a URL consultada;
• • a data ou versão relevante, quando disponível;
• • o trecho que sustenta a decisão;
• • qualquer lacuna de cobertura;
• • a distinção entre fato encontrado e hipótese do agente.

Isso evita um erro comum: transformar "não encontrei na documentação" em "provavelmente funciona assim". Se a fonte não responde, o agente pode pedir revisão, preparar um experimento pequeno ou parar como bloqueado. Usar a memória do modelo para preencher a lacuna não deveria ser o fallback silencioso.

3. Estado da execução

Objetivo, hipótese atual, arquivos alterados e resultados dos testes pertencem à sessão. Esses dados são temporários, mas precisam acompanhar o trabalho quando ele passa para outra pessoa ou agente.

Aqui entram perguntas bem concretas: qual endpoint está sendo integrado, que decisão foi tomada, qual limite ainda não foi testado e por que a execução parou. Um trace, ou rastro de execução, ajuda a investigar o caminho do agente, e plataformas já começam a reunir ferramentas, skills, clientes MCP e observabilidade no mesmo runtime. Ainda assim, o resultado final deve ser legível sem exigir que o revisor assista à sessão inteira.

Separar as camadas reduz conflitos. A regra do projeto informa como trabalhar. A fonte externa informa como a API funciona agora. O estado da execução mostra o que aconteceu desta vez.

Um contrato mínimo para consulta

Não é necessário construir uma plataforma interna antes de melhorar o workflow. Um contrato pequeno, usado em uma integração real, já expõe onde faltam decisões.

Imagine uma tarefa para adicionar um método de uma API ao backend. Eu passaria ao agente algo próximo disto:

objetivo: adicionar a consulta de status de um recurso
escopo:
  arquivos_permitidos:
      - src/integrations/provider.ts
        - tests/provider.test.ts
        fonte_externa:
          tipo: documentacao_oficial
           consulta_obrigatoria: true
            registrar:
                - url
                    - versao_ou_data
                       - limite_de_cobertura
                       mudanca:
                         preferencia: menor_diff_revisavel
                         validacao:
                           - teste_de_integracao_afetado
                            - revisao_do_diff
                            parada:
                              - documentacao_ambigua
                               - fonte_indisponivel_sem_cache_aprovado
                                - necessidade_de_trocar_dependencia
                                ```
                                
                                O formato é ilustrativo. O valor está nas escolhas explícitas.
                                
                                A skill do repositório delimita arquivos e testes. A ferramenta de consulta recupera a documentação atual. O agente registra a proveniência, faz uma alteração pequena e executa a validação. Se encontrar uma lacuna, devolve o ponto exato em vez de preencher o espaço com confiança artificial.
                                
                                Mudanças pequenas podem parecer mais lentas no início, principalmente quando o agente seria capaz de reescrever a integração inteira. Na revisão, o ganho aparece rápido: fica mais fácil relacionar uma decisão documental ao trecho alterado, testar a hipótese e reverter o patch se necessário.
                                
                                ## Grounding ajuda, mas não compila seu código
                                
                                Uma resposta baseada em fonte oficial continua sujeita a limites. A documentação pode estar ambígua, atrasada ou cobrir apenas parte dos produtos. O conector pode ficar indisponível. A consulta adiciona latência. E o agente pode interpretar corretamente a página, mas adaptar o exemplo de forma errada ao seu código.
                                
                                Por isso, a proveniência precisa terminar em validação, não em confiança automática.
                                
                                Para uma integração pequena, eu cobraria quatro saídas:
                                
                                1. link e versão ou data usados na decisão;
                                2. resumo curto do que a documentação realmente confirma;
                                3. diff restrito à menor superfície necessária;
                                4. teste executado, resultado observado e cenário que ficou sem cobertura.
                                
                                Se a fonte estiver fora do ar, o fallback também precisa estar definido. Uma opção é usar um snapshot aprovado, com data visível, e marcar a execução como dependente de documentação possivelmente desatualizada. Outra é parar e retomar depois. O pior caminho é consultar a memória do modelo sem avisar e apresentar a resposta como se viesse da versão atual.
                                
                                Ferramentas demais criam outro problema. Dar acesso simultâneo a várias buscas, servidores MCP e catálogos aumenta o alcance, mas torna mais difícil explicar qual fonte venceu um conflito. É melhor começar com poucas ferramentas identificadas, permissões estreitas e um registro simples de cada consulta relevante.
                                
                                ## Um fluxo para experimentar amanhã
                                
                                Escolha uma integração pequena e faça o teste no trabalho real:
                                
                                1. Mantenha no repositório uma instrução curta com escopo, convenções e comando de teste.
                                2. Defina uma fonte oficial consultável e os metadados de proveniência que o agente deve devolver.
                                3. Peça a menor mudança que confirme a integração.
                                4. Exija a separação entre fato documentado, suposição e resultado observado.
                                5. Revise o diff e repita a validação adequada ao risco.
                                
                                Depois da primeira execução, olhe para o atrito. Se o agente consultou páginas demais, restrinja a fonte. Se a skill local ficou longa, remova explicações que já moram no código. Se o resumo final trouxe links, mas não deixou claro qual afirmação cada um sustentava, ajuste o formato do recibo.
                                
                                Não tente dar ao agente todo o conhecimento que talvez seja útil. Dê a ele instruções estáveis, uma rota confiável até a documentação atual e uma obrigação clara de provar o comportamento no projeto. O prompt fica menor, e a revisão deixa de depender de descobrir qual versão estava escondida dentro dele.
                                
                                ## Fontes
                                
                                - [Google Developer Knowledge — release notes](https://developers.google.com/knowledge/release-notes?hl=en)
                                - [Claude Platform — release notes](https://platform.claude.com/docs/en/release-notes/overview)
                                - [What’s new in Microsoft Foundry — Build Edition](https://devblogs.microsoft.com/foundry/whats-new-in-microsoft-foundry-build-2026/)