Progressive Disclosure em Context Engineering

Progressive Disclosure é uma estratégia para carregar contexto aos poucos, conforme o agente de IA realmente precisa daquela informação.

Em vez de colocar todo o conhecimento no prompt inicial, você organiza o contexto em camadas e deixa o agente abrir cada parte sob demanda.

O que é Progressive Disclosure

Progressive Disclosure significa revelar informações de forma progressiva.

No contexto de agentes de IA, isso quer dizer começar com instruções essenciais e carregar detalhes adicionais apenas quando eles forem necessários.

Essa abordagem evita que o agente receba contexto demais logo no início da tarefa.

O agente começa com uma visão geral, entende o objetivo e consulta arquivos, referências, instruções ou exemplos específicos conforme avança.

Um exemplo simples:

AGENTS.md
references/
├── frontend.md
├── backend.md
└── testing.md

O AGENTS.md pode explicar que existem referências específicas para frontend, backend e testes.

Se a tarefa envolve apenas frontend, o agente não precisa carregar backend.md.

Ele abre somente o que faz sentido para aquele trabalho.

Para que Serve Progressive Disclosure

Progressive Disclosure serve para controlar melhor o contexto entregue ao agente.

Modelos de linguagem têm uma janela de contexto limitada.

Mesmo quando essa janela é grande, contexto demais pode atrapalhar.

Informações irrelevantes competem com as informações importantes.

Isso aumenta a chance de decisões ruins, respostas genéricas ou implementação fora do escopo.

Com Progressive Disclosure, você mantém o contexto inicial pequeno e direcionado.

Depois, o agente busca detalhes quando a tarefa exige.

Essa prática torna o trabalho mais previsível e reduz o ruído dentro da conversa.

Progressive Disclosure em Context Engineering

Context engineering é a prática de estruturar o contexto para melhorar a qualidade da resposta de um agente de IA.

Progressive Disclosure é uma das formas mais úteis de aplicar context engineering em projetos reais.

A ideia central é simples.

O agente não precisa saber tudo o tempo todo.

Ele precisa saber onde encontrar o contexto certo no momento certo.

Isso muda a forma como organizamos instruções.

Em vez de criar um único arquivo enorme com todas as regras, podemos criar um arquivo principal pequeno que aponta para documentos mais específicos.

Por exemplo:

# AGENTS.md

## Visão Geral

Este projeto usa Astro para o blog e MDX para os artigos.

## Referências sob demanda

- Leia `docs/writing.md` ao criar ou editar artigos.
- Leia `docs/testing.md` ao alterar código de build ou componentes.
- Leia `docs/deploy.md` apenas quando a tarefa envolver publicação.

Esse formato cria um mapa de contexto.

O agente recebe orientação suficiente para começar, mas não carrega documentação que não será usada.

Por que Progressive Disclosure é Útil com Agentes de IA

Agentes de IA trabalham melhor quando o contexto é relevante, claro e bem delimitado.

Progressive Disclosure ajuda nesses três pontos.

Primeiro, ele reduz distrações.

O agente não precisa processar regras que não pertencem à tarefa atual.

Segundo, ele melhora a precisão.

Quando o agente carrega uma referência específica, aquela informação tende a ter mais peso no raciocínio.

Terceiro, ele facilita manutenção.

Você pode atualizar um documento específico sem mexer em todo o conjunto de instruções.

Isso é importante em projetos com múltiplos domínios, como frontend, backend, infraestrutura, testes, documentação e design system.

Quando Usar Progressive Disclosure com AGENTS.md

Use Progressive Disclosure com AGENTS.md quando o projeto tiver muitas regras, muitos domínios ou instruções que não se aplicam a todas as tarefas.

O AGENTS.md deve funcionar como ponto de entrada.

Ele não precisa carregar todo o conhecimento do projeto.

Ele precisa orientar o agente sobre o que ler, quando ler e por que aquele arquivo importa.

Um bom uso seria:

## Roteamento de Contexto

- Para alterações em componentes, leia `docs/frontend.md`.
- Para mudanças de API, leia `docs/backend.md`.
- Para novos artigos, leia `docs/content-style.md`.
- Para correções de CI, leia `docs/ci.md`.

Esse tipo de seção transforma o AGENTS.md em um índice operacional.

O agente usa o arquivo para decidir qual contexto carregar antes de agir.

Como Estruturar Progressive Disclosure

Comece separando o que é sempre necessário do que é condicional.

O contexto sempre necessário deve ficar no AGENTS.md.

O contexto condicional deve ir para arquivos específicos.

Uma estrutura eficiente pode ser:

AGENTS.md
docs/
├── content-style.md
├── frontend.md
├── backend.md
├── testing.md
└── deployment.md

No AGENTS.md, mantenha apenas o mapa:

## Contexto sob Demanda

Leia `docs/content-style.md` somente ao criar, revisar ou editar posts.

Leia `docs/frontend.md` somente ao alterar componentes, estilos ou páginas.

Leia `docs/testing.md` somente quando a tarefa envolver testes ou validação.

Essa separação deixa o contexto mais limpo.

Também evita que o agente carregue detalhes de deploy ao escrever um artigo, ou regras editoriais ao corrigir um teste.

Boas Práticas para Progressive Disclosure

Escreva arquivos pequenos e específicos.

Use nomes claros.

Explique quando cada arquivo deve ser lido.

Evite referências profundas demais.

O ideal é que o AGENTS.md aponte diretamente para os documentos necessários.

Também evite duplicar a mesma regra em vários lugares.

Se uma instrução vale para todo o projeto, deixe no AGENTS.md.

Se vale apenas para um domínio, coloque no arquivo daquele domínio.

Essa organização reduz conflito entre instruções.

Conclusão

Progressive Disclosure ajuda agentes de IA a carregar contexto sob demanda, mantendo o prompt mais limpo e relevante.

Ele torna o context engineering mais prático, principalmente em projetos com muitas regras e áreas diferentes.

Quando usado com AGENTS.md, Progressive Disclosure transforma o arquivo principal em um mapa de contexto.

O agente começa com o essencial, encontra o detalhe certo quando precisa e trabalha com menos ruído durante a execução.