Estrutura do Vault e depuração

Organize um vault markdown como uma segunda memória pesquisável. Classifique os quatro modos de falha quando Claude faz algo inesperado.

STATE.md e MEMORY.md contêm o que cada sessão precisa. Um vault markdown (Obsidian ou qualquer pasta) contém todo o resto: notas de estratégia, transcrições de reuniões, diários de projeto, pesquisa, análise competitiva.

O vault se transforma em memória institucional: decisões que você tomou há seis meses e por quê, materiais de referência que informam o trabalho atual, padrões que abrangem projetos. Conecte-o via um MCP do Obsidian ou do sistema de arquivos e Claude pode pesquisar tudo sob demanda. Sem o vault, esse conhecimento existe apenas na sua cabeça ou enterrado em documentos antigos.

Por que markdown é melhor que um banco de dados: arquivos simples são pesquisáveis, versionados com git, abrem em qualquer editor e sobrevivem a cada mudança de ferramenta. Uma estrutura de trabalho:

~/notes/

├── STATE.md # Sempre carregado

├── MEMORY.md # Índice, sempre carregado

├── STRATEGY-DIGEST.md # Resumos de documentos de estratégia

├── strategy/ # Documentos completos, lidos sob demanda

├── projects/ # Notas de projeto datadas

├── resources/

└── reference/A chave de escalabilidade é o padrão de resumo: quando você escreve um documento de estratégia de 1.000 palavras, escreva um resumo de 3 frases ao lado e indexe o resumo em MEMORY.md. Claude lê cerca de 50 tokens no início da sessão em vez dos aproximadamente 1.500 do documento completo. Em 25 documentos de estratégia, isso são 1.250 tokens versus 37.500, e as sessões permanecem rápidas.

Quando Claude faz algo inesperado, verifique quatro modos de falha em ordem, do mais comum ao menos comum:

Memória obsoleta: STATE.md diz uma coisa, a realidade diz outra. Claude seguiu suas instruções perfeitamente; as instruções estavam erradas. Pergunte "Mostre-me seu STATE.md" primeiro, sempre.

Contexto ausente: o arquivo relevante nunca foi carregado, então Claude fez uma suposição razoável. Carregue o arquivo explicitamente e pergunte novamente.

Ferramenta indisponível: um MCP está inativo ou um hook bloqueou um comando, e Claude contornou-o mal. Verifique a disponibilidade da ferramenta antes de culpar o raciocínio.

Alucinação: a causa mais rara. Verifique primeiro: procure a função, verifique se o endpoint existe. A maioria das "alucinações" acaba sendo uma das três primeiras.

Uma pergunta de diagnóstico por modo de falha:

Memória obsoleta: "O que seu STATE.md diz sobre [tópico]?" Conteúdo de três sessões atrás significa estado obsoleto.

Contexto ausente: "Quais arquivos você tem carregados sobre [tópico]?" Nenhum arquivo relevante significa carregar o correto.

Ferramenta indisponível: "Que ferramentas você tem disponíveis agora?"

Alucinação: "Procure por [função/endpoint] e mostre-me o que você encontra."

A sequência leva dois minutos e encontra a causa quase sempre. Pular direto para "Claude alucinou" geralmente atrasa a correção real reescrevendo código que não precisava ser reescrito.

Prevenção é melhor que depuração. Os hábitos:

Atualização do STATE.md no final da sessão. Elimina 80% dos problemas de memória obsoleta.

Arquive projetos enviados em arquivos project_* datados.

Auditoria mensal do MEMORY.md: confirme se cada ponteiro ainda aponta para um arquivo existente.

Resuma cada documento com mais de 500 palavras.

Escreva as decisões no momento da decisão, não no final da semana. A captura retroativa perde o raciocínio.

Antes de arquivar as notas do projeto, extraia as lições duráveis em entradas feedback_*. O projeto se torna história; as lições permanecem ativas.

Um vault com 10 documentos bem mantidos é melhor que um com 200 obsoletos. Qualidade e atualidade superam o volume.

Com um MCP do Obsidian ou do sistema de arquivos, o vault se torna uma base de conhecimento viva:

Arqueologia de decisões: "Pesquise no vault por que escolhemos Postgres em vez de MySQL." Uma busca manual de 10 minutos se torna 15 segundos.

Detecção de padrões: "Encontre todas as menções de problemas de limitação de taxa ou erros 429 em todos os projetos." Claude mostra uma causa raiz comum espalhada por cinco arquivos de projeto.

Consulta de referência: "Encontre as informações de contato nas notas do fornecedor." Recuperação instantânea de arquivos não indexados.

A qualidade da pesquisa depende da consistência da nomenclatura: project_[nome]_[data].md e feedback_[regra].md são melhores do que o que parecia natural na época. As convenções de nomenclatura são o índice que você constrói antes de precisar dele.

Todos os quatro modos verificados estão limpos e a saída ainda está errada? Duas causas que parecem alucinação, mas não são.

Ordenação do contexto: quando arquivos carregados entram em conflito, o conteúdo carregado posteriormente tende a vencer. Se notas antigas do projeto contradizem STATE.md, atribua autoridade explicitamente: "STATE.md é a verdade atual. Ele substitui qualquer coisa nas notas do projeto."

Colisões de restrições: CLAUDE.md diz "parametrize todo o SQL", então Claude reescreve o SQL durante o que você pretendia como uma refatoração apenas de estilo. Não é um bug; defina o escopo explicitamente: "Apenas estilo, não altere os padrões SQL."

O diagnóstico para ambos: "Quais instruções você está seguindo que governam [esta decisão]? Liste as regras em ordem de prioridade." Você encontrará uma fonte obsoleta, uma regra conflitante ou uma lacuna no CLAUDE.md. Tudo corrigível.

Um vault markdown com arquivos de resumo escala sua segunda memória; os resumos mantêm as sessões rápidas, os documentos completos carregam sob demanda. Quando Claude se comporta mal, classifique em ordem: memória obsoleta, contexto ausente, ferramenta indisponível, alucinação, e sempre comece com "mostre-me seu STATE.md." Alimente o vault no momento da decisão e ele se acumula em valor a cada semana.