Achei a ideia muito bacana, mas não acha que implementação atual acaba causando Context Rot e piorando o resultado? Dá uma olhada nesse artigo aqui, ele mostra bem o quanto a qualidade das LLMs diminue quando se tem uma janela de contexto mais cheia ao invés de aumentar, o que parece ser um pouco contra intuitivo.

O artigo mostra principalmente o impacto das similaridades e distrações, algo muito comum em codebases um pouco maiores, e em estruturas de documentação como a que você apresentou. Mas não só isso, quando você tem diversos arquivos .md, e o modelo tem que ficar constantemente usando tool calls pra ler eles, a janela de contexto aumenta muito rápidamente, ainda mais se você tiver usando um modelo que usa raciocínio profundo, pois adoram gastar token e pensar antes da realização de cada tool call. A menos que os arquivos "centrais" tenham instruções específicas com o caminho exato de cada arquivo, e preferênciamente o range de linhas onde a informação está, ele vai acabar queimando tokens, aumentando a janela de contexto, e você chega cada vez mais perto do Context Rot.

Eu ultimamente tenho usado um AGENTS.md conciso e direto, com instruções de comportamento, como ele deve agir e como deve ser o código que ele retorna, e um AGENTS.md local, que diz ao modelo, de forma bem resumida, a estrutura de pastas e arquivos, um pouco sobre o aplicativo, e edge-cases (caso haja). Além da qualidade da resposta geralmente ser um pouco melhor, porque eu sou específico nas regras que quero que ele siga, ele raramente erra, porque o contexto está fresco. Pra manter essa consistência, também é legal sempre criar novas sessões, mas acho que isso já é manjado.

Acho que seria muito legal o projeto suportar uma versão mais resumida, porque apesar de eu prefirir documentos um pouco mais concisos, ainda tenho uma baita preguiça de fazer eles kkkkkkkk. Os documentos que uso, geralmente faço com o chat do Claude mesmo, e preciso de algumas iterações pra chegar em um documento final. Creio que se você colocasse um suporte pra criação de um arquivo .md com explicações do projeto e um de comportamento (que o usuário pode deixar local ou mover pra uma pasta global, a depender da preferência dele), não só teria mais adoção e ficaria um projeto mais completo, como os resultados aumentariam drásticamente.

Mas realmente é um projeto muito bacana que vai ajudar muitos devs preguiçosos como eu kkkkkk