Contexto é arquitetura de informação, trate seu agente como um humano

A maior parte da frustração com agente de IA vem de um mal-entendido:

As pessoas acham que estão escrevendo instrução. Estão projetando o ambiente de trabalho de alguém.

Prompt é o pedido. Contexto é tudo que a pessoa tem a disposição pra atender aquele pedido.

Se você contratasse um desenvolvedor sênior amanhã e desse a ele só uma frase: "arruma o bug do checkout", sem acesso ao repositório, sem saber a convenção do time, sem entender o domínio, ele também entregaria porcaria. E ninguém culparia a inteligência dele.

Com agente é idêntico. Como eu organizo hoje, em camadas:

Permanente. Regra que vale sempre. Convenção de código, arquitetura, o que nunca pode ser feito nesse projeto. Escrito uma vez, lido toda vez.

Do domínio. (DDD na prática) O que as palavras significam aqui dentro. "Reserva" no meu produto de viagem não é a mesma coisa que "reserva" num sistema de restaurante. Sem isso, o agente acerta a sintaxe e erra o negócio.

Da tarefa. Só o que importa pra essa mudança específica. Aqui é onde a maioria erra pro outro lado: joga o repositório inteiro achando que mais contexto é melhor contexto. Não é. Ruído compete com sinal.

De estado. Onde a tarefa parou, o que já foi tentado, o que foi descartado e por quê. É o que impede o agente de refazer o caminho errado que ele mesmo já percorreu ontem.

A ideia é organizar documentação pra um time que vai crescer.

Documentação ruim faz humano perguntar. Contexto ruim faz o agente inventar.

Como você está dando contexto pro seu agente hoje?