Uma base de conhecimento para todos os seus agentes de IA

Quando comecei a usar o Claude Code a sério, fiz o que todo mundo faz: criei um CLAUDE.md em cada repositório com convenções do projeto, notas de stack e pegadinhas. Funcionou, mais ou menos. Mas alguma coisa continuava me frustrando.

A cada sessão nova, o agente redescobria as mesmas coisas. MusicKit não funciona no simulador, de novo. CloudKit exige propriedades opcionais em todo @Model, de novo. O vault do Ansible é um blob único criptografado que o git não consegue mesclar, de novo. Eu ficava escrevendo os mesmos comentários no meu issue tracker repetidamente, ou dependendo do agente lembrar de coisas que ele não conseguia.

O problema é que o CLAUDE.md é a ferramenta errada para isso. Ele é ótimo para convenções estáveis de projeto: decisões de arquitetura, estrutura de diretórios, comandos de build. Ele é ruim em acumular o conhecimento bagunçado e conquistado na prática que você constrói durante o trabalho de verdade, comportamento de rate limit que você observou, uma estratégia de cache que funcionou, uma pegadinha que te custou duas horas.

Esse conhecimento precisa morar em algum lugar que um agente consiga achar na próxima sessão, sem você ter que enfiar tudo no arquivo que devia ser um documento de convenções.

O padrão: um cofre, muitos projetos

Montei um único vault do Obsidian versionado em git em ~/Repos/vdaluz-kb/. Todo projeto aponta para ele. As notas usam frontmatter YAML com um campo projects: para registrar a proveniência:

---
date: 2026-06-06
type: source
source: MusicKit / Apple Music catalog
tags: [musickit, apple-music, ios, swift]
projects: [deep-cut-atlas]
---

O campo projects: é proveniência, não filtro de escopo. Um agente em qualquer repositório pode rodar grep -ri "musickit" e achar a nota, independente de qual projeto a escreveu originalmente. Padrões que atravessam projetos (comportamento de merge do vault do Ansible, rotação de chave SSH) também moram lá, marcados com todos os projetos afetados.

A estrutura é simples:

vdaluz-kb/
  patterns/       # recurring patterns and data source quirks
  infrastructure/ # service gotchas, runbooks, host-specific notes
  alerts/         # daily alert review findings

Sem diretórios por projeto. A proveniência mora no frontmatter, não na árvore de pastas.

Conectando um projeto

O CLAUDE.md de cada projeto ganha uma seção curta sobre a KB:

## Knowledge base
Durable findings live in the central KB at ~/Repos/vdaluz-kb/.

- Before implementing anything: grep -ri "<topic>" ~/Repos/vdaluz-kb/
- Saving new findings: write to ~/Repos/vdaluz-kb/patterns/<slug>.md
  with frontmatter projects: [this-project], then commit and push
- Issue-scoped notes: go in the issue tracker, not the KB

Essa é a integração completa. O agente sabe que precisa checar antes de implementar, e sabe onde salvar quando aprende algo que vale a pena guardar.

O que vai na KB, no tracker, e no CLAUDE.md

Levei um tempo para acertar isso. A regra a que cheguei: o CLAUDE.md guarda convenções estáveis (arquitetura, stack, comandos de build, restrições críticas) e muda raramente. A KB guarda conhecimento durável mas descoberto na prática, pegadinhas, comportamento de rate limit, modos de falha conhecidos, padrões que se repetem entre issues, e muda quando você aprende algo novo. O issue tracker guarda notas específicas de cada issue, decisões, passos de investigação, evidência de um pedaço específico de trabalho, e é efêmero por design.

Um bom teste: “alguém mexendo nisso daqui a seis meses precisaria saber disso?” Se sim, KB. Se só é relevante para o trabalho que você está fazendo agora, fica no issue.

A armadilha da fragmentação

O issue que motivou isso originalmente pedia para eu montar um vault do Obsidian por repositório dentro do projeto iOS Deep Cut Atlas, espelhando o que eu tinha feito para o homelab. Mas, quando cheguei nele, o vault por projeto do homelab já tinha sido consolidado na KB central. Montar um segundo vault por repositório teria refragmentado exatamente o que eu acabara de unificar.

O fix certo foi conectar o Deep Cut Atlas à KB existente e alimentá-la com o que eu já sabia de investigações anteriores. Dois arquivos, dois commits, pronto.

A lição: quando você tem vários projetos ativos, repositórios de conhecimento por repositório viram um fardo de manutenção. Um cofre é suficiente. Proveniência no frontmatter vence estrutura de pastas sempre.