Os agentes leem seu repositório. Isso cobre a maior parte do que eles precisam — mas não as decisões que ficam na mente das pessoas, em uma wiki ou em uma conversa de dois anos atrás.
Contexto do projeto é onde você inclui o restante.
O que o Coroid determina sozinho
Somente a partir do repositório, os agentes podem ver:
- as linguagens, frameworks e bibliotecas em uso
- como o projeto é construído, testado e executado
- padrões existentes — como os erros são tratados, como os módulos são estruturados e como as coisas são nomeadas
- o que depende do quê
Você não precisa documentar nada disso. Reescrever essas informações é um esforço desperdiçado e corre o risco de ficar desatualizado em relação ao código, que é a fonte mais confiável.
O que ele não consegue inferir
O código mostra o que você fez, nunca porquê:
- uma biblioteca escolhida em vez de uma alternativa óbvia por um motivo que ainda é válido
- um padrão que parece duplicação, mas é uma separação deliberada
- um módulo que ninguém deve tocar sem falar com uma equipe específica
- convenções que vocês combinaram, mas ainda não aplicaram em lugar algum
- restrições externas ao código-fonte — conformidade, contratos, uma migração em andamento
Isso é o que pertence ao contexto do projeto. O teste é simples: alguém que lesse apenas o repositório conseguiria descobrir isso? Se sim, deixe de fora. Se não, anote.
Adicionando contexto
Anexe documentos, políticas e referências na seção de Contexto do projeto. Notas de arquitetura, registros de decisões, guias de estilo e contratos do API funcionam bem aqui.
Um bom contexto é curto e específico. Um guia de integração de 40 páginas escrito para humanos é majoritariamente narrativo; os três parágrafos que indicam restrições reais são os que importam. Extraia esses trechos.
Contexto por tarefa
O contexto anexado ao projeto se aplica a tudo. Para algo relevante a uma única tarefa — um chamado, um documento de design, um relatório de cliente — anexe-o à própria tarefa.
Mantenha o contexto do projeto para o que é verdadeiramente permanente. Uma nota específica de tarefa no contexto do projeto vira ruído em todas as tarefas futuras.
Mantendo-o atualizado
Um contexto desatualizado é pior do que nenhum contexto, porque os agentes o tratam como autoritativo. Quando uma convenção mudar, atualize o contexto na mesma alteração que modifica o código.
Se você perceber que corrige a mesma coisa repetidamente nos comentários de retrabalho, isso é um sinal de que algo está faltando no contexto — ou de que algo nele está errado.