Contexto Estendido. Os agentes também precisam de tomar notas

O propósito deste post é descrever uma estratégia de ampliação de contexto no desenvolvimento de projetos complexos com agentes. Mas como não só os LLMs precisam de contexto para compreender ideias, começo com um pouco de contexto para humanos.

Se tens pressa e passas do contexto prévio, avança e não te preocupes, ninguém saberá que tiveste este mini ataque de preguiça 😬

Contexto para humanos

A aparição dos agentes nos assistentes de código tem representado um salto enorme no desenvolvimento de software assistido por IA.

O primeiro que chama a atenção é a sua capacidade para iterar de forma automática sobre as suas próprias respostas, criar/modificar ficheiros e executar comandos na terminal. Mas creio que a habilidade que realmente marca a diferença é que são capazes de indexar e analisar o código de um projeto, incluídas as dependências entre ficheiros e as relações entre os seus componentes.

Se os assistentes nos permitiam trabalhar a nível ficheiro, com a aparição dos agentes passámos a trabalhar a nível arquitetura. Agora a IA não só nos ajuda na escrita/correção de partes do nosso código, como nos assiste na construção de projetos completos (a uma velocidade que às vezes dá vertigem).

Mas este aumento na complexidade das tarefas desenvolvidas provoca algo que antes era difícil de ver, levamos ao limite a janela de contexto dos próprios agentes. Desenvolver um projeto completo requer muitas tarefas, pelo que chegado a um ponto o agente começa a esquecer partes da conversa, tornando muito difícil (por não dizer impossível) manter a coerência do trabalho que estamos a realizar.

Quando isto acontece o mais normal é abrir um novo chat para reiniciar a janela de contexto, mas, como levamos o agente ao ponto em que estávamos? Como fazer-lhe recordar o que já tinha construído e o que lhe falta por desenvolver?

No meu caso estou a usar uma estratégia a que cheguei a partir das minhas interações com Cursor primeiro e GitHub Copilot Agent Mode depois e a que chamo Contexto Estendido. Vale, sei que não sou muito original, mas creio que exprime decentemente a ideia 🤓

Contexto estendido (usando markdowns como memória)

Esta estratégia baseia-se no armazenamento de ficheiros markdown com informação do projeto numa pasta chamada context/

A ideia é criar uma memória a que o agente (ou nós) pode recorrer em todo o momento permitindo-lhe saber em que ponto está e o que lhe falta por fazer.

Graças a esta memória podemos dividir o trabalho em tarefas pequenas e usar tantos chats quantos sejam necessários para evitar alcançar o limite da janela de contexto. Mantendo desta forma a coerência e qualidade do trabalho de princípio a fim.

Esquema de trabalho

Na seguinte imagem resume-se o esquema de trabalho.

Chat 0

1. Prompt para criar um perito sintético na tecnologia do projeto: papel, experiência, stack técnico, forma de raciocínio e formato de resposta. Finalizado com um "não escrevas código ainda".
2. Prompt onde pedimos que:
   • analise o código do projeto,
   • gere um relatório da sua análise,
   • e o guarde em formato .md dentro da pasta context/ com um 00- à frente do nome do ficheiro. Se o relatório não nos agradar de todo, podemos iterar sobre ele até ficarmos satisfeitos.
3. Prompt onde:
   • indicamos o que queremos fazer (requisitos),
   • pedimos que gere um plano mestre,
   • e o guarde em formato .md dentro da pasta context/ com um 01- à frente do nome do ficheiro. Tal como com a análise, podemos iterar sobre ele até ficarmos satisfeitos.

Chat 1

1. Mesmo prompt para criação de perito sintético.
2. Prompt pedindo que leia e interiorize a análise do projeto.
3. Prompt pedindo que leia e interiorize o plano mestre.
4. Prompt pedindo que execute o ponto 1 do plano mestre.
5. Iteração normal até terminar o ponto 1.
6. Prompt pedindo que documente o trabalho desenvolvido no ponto 1. num .md dentro de context/ seguindo a numeração atual e que marque o ponto como resolvido no plano mestre.

Chat n

1. Mesmo prompt para criação de perito sintético
2. Prompt pedindo que leia e interiorize a análise do projeto
3. Prompt pedindo que leia e interiorize o plano mestre
4. Prompt pedindo que execute o ponto n do plano mestre
5. Iteração normal até terminar o ponto n.
6. Prompt pedindo que documente o trabalho desenvolvido no ponto n. dentro do .md de documentação criado anteriormente e que marque o ponto como resolvido no plano mestre.

Evidentemente, este esquema trata-se de uma base de trabalho que pode ser modificada em função das necessidades de cada projeto e que espero melhorar com o tempo. Ainda assim, nesta primeira versão, já aporta algumas vantagens relativamente a não usar nenhuma estratégia.

Vantagens do contexto estendido

1. Evitamos a perda de contexto: o agente pode consultar os ficheiros quando precisar de recordar de onde vem e para onde vai.
2. Continuidade: podemos fechar o computador e retomar o trabalho dias depois sem perder o fio.
3. Colaboração: outros membros da equipa podem entender facilmente o estado do projeto e continuá-lo (com os seus agentes).
4. Documentação automática: ao finalizar, temos já uma documentação estruturada.
5. Facilita a divisão de tarefas: orientando o trabalho para metodologias ágeis e sprints.

Terminando

Resulta irónico que nesta imitação do pensamento humano que representam os modelos de linguagem, não só tenhamos copiado as suas capacidades, como também as suas limitações. E entre elas está uma muito humana: o esquecer. Assim que tal como os imperfeitos humanos, os imperfeitos LLMs também precisam de tomar notas. Isso sim, se são em markdown melhor, adoram o markdown!

Já agora, fazes tomar notas aos teus agentes ou tens alguma outra estratégia na altura de desenvolver projetos complexos? Se trabalhas de outra forma, adoraria conhecer a tua experiência 😊