Governação de IA Multi-Repo

Passei semanas a construir ficheiros de contexto para IA. Metade estava a mentir.

Não intencionalmente. Os ficheiros estavam correctos quando os escrevi. Depois as coisas mudaram — actualizações de stack, migrações de esquema, pivots de negócio — e ninguém actualizou a documentação.

A IA continuava a ler o contexto antigo. Eu continuava a receber respostas confiantes e erradas.

A pior parte: não dei por isso de imediato. Os outputs pareciam razoáveis. Os erros eram subtis. Quando os detectei, já tinha construído em cima de uma base falsa.

Essa é a falha de que ninguém fala. Não "a IA alucinou" — não alucinou. Leu exactamente o que lhe dei. O problema foi que o que lhe dei estava desactualizado.

Estava a gerir cinco projectos em paralelo na altura — um site de hotelaria, uma app de gestão financeira, um site institucional, um pitch deck, um portefólio pessoal. Cada um tinha o seu próprio contexto de IA. Cada um desviava ao seu próprio ritmo. Não havia nenhum sistema a ligar nada disto.

A primeira coisa que construí foi a coisa errada: mais documentação.

Mais detalhe, mais estrutura, mais cobertura. Ajudou durante uma semana. Depois esses ficheiros também começaram a desviar-se.

A segunda coisa que construí ficou mais perto: uma matriz de gatilhos. Cada tipo de mudança — nova rota, actualização de esquema, nova dependência, mudança de modelo de negócio — mapeada para o documento exacto que tem de ser actualizado. No mesmo PR. Não como seguimento. A tarefa não está concluída até a documentação reflectir a realidade.

Isso travou o desvio nos projectos individuais.

Mas propagar isto por cinco repositórios expôs o gap seguinte. Regras genéricas não sobrevivem ao contacto com domínios específicos. A app financeira precisava de um documento de modelo de dados. O site de hotelaria precisava de uma especificação de portal. O pitch deck precisava de uma camada de afirmações verificadas — porque um investidor a perguntar "de onde vem este número?" não é o momento para descobrir que o teu ficheiro de contexto era optimista.

O que acabei por perceber: há dois tipos de contexto. Contexto que pertence a um template partilhado — regras base, padrões de arquitectura, cadência de verificações de saúde. E contexto que pertence ao repositório — decisões de domínio, anomalias de dados, afirmações verificadas. Misturá-los estraga os dois.

A maioria das pessoas que enfrenta este problema assume que precisa de melhores ferramentas de IA. O que geralmente precisa é de melhor disciplina de manutenção.

O ficheiro de contexto não é documentação. É um contrato entre nós e o modelo. Quando se quebra, o modelo não avisa. Simplesmente continua.

Se estás a construir com assistentes de IA em mais do que um projecto, a pergunta que vale a pena fazer agora — antes de te custar caro — é: quem actualiza o contexto quando algo muda, e como sabem que precisa de ser actualizado?

O template é open source — link nos comentários.

Fontes

• ai-product-architecture-template (open source, GitHub): https://github.com/gtcuco-personal/ai-product-architecture-template