Se você usa o Claude Code com frequência, provavelmente já viveu esse ciclo frustrante: explica o projeto, recebe boas respostas, fecha a sessão — e na próxima tem que começar tudo do zero de novo. Sem memória, sem continuidade, sem contexto.

O problema não é o Claude Code. O problema é que ninguém está alimentando ele da forma certa.

Neste artigo vou te mostrar exatamente o sistema que uso para resolver isso: uma arquitetura de documentação viva, conectada ao Claude Code via Obsidian, que faz o modelo ler o contexto do seu projeto automaticamente antes de qualquer resposta. O resultado? Respostas mais precisas, menos tokens gastos e zero repetição de contexto entre sessões.

Por Que a Abordagem Convencional Falha

A maioria das pessoas documenta projetos de uma dessas duas formas:

Um único arquivo .md gigante com tudo dentro — fácil de criar, impossível de usar bem. O Claude precisa processar um contexto imenso para responder qualquer pergunta, mesmo as mais simples. Gasta tokens desnecessários e a qualidade da resposta cai.

Vários arquivos .md separados por funcionalidade — já é melhor, mas ainda tem um problema sério. Quando você pede uma mudança, o Claude lê todos os arquivos para entender o sistema, mesmo aqueles que não têm nenhuma relação com o que você quer fazer. Lento, caro e impreciso.

O que precisamos é de uma documentação granular e interconectada: arquivos pequenos, bem escritos, que se referenciam entre si. Assim, quando você pede uma alteração no sistema de pagamentos, o Claude acessa apenas os arquivos relevantes — pagamentos, créditos, banco de dados — e descarta o resto.

É exatamente isso que vamos construir.

A Arquitetura: Obsidian como Cérebro Externo

O Obsidian é perfeito para isso porque:

Funciona 100% local com arquivos Markdown puros
Suporta links internos entre arquivos ([[Nome do Arquivo]])
Tem um ecossistema de plugins que permite expor o vault via MCP (Model Context Protocol)
Permite criar uma "base de conhecimento viva" com visualização de conexões entre documentos

A ideia é simples: o Obsidian vira a memória permanente do Claude Code. Cada módulo, feature e decisão do seu projeto tem um arquivo .md próprio no vault, e esses arquivos se conectam entre si. O Claude Code acessa esse vault antes de qualquer resposta e navega apenas pelo que é relevante.

Passo a Passo: Configurando o Sistema

Pré-requisito: Instalar o Obsidian

Se você ainda não tem o Obsidian instalado, faça isso primeiro. Ele é open source e gratuito. O plano pago deles oferece sincronização em nuvem, mas existe uma forma de ter isso sem gastar nada — cubro tudo isso, da instalação até a configuração da nuvem gratuita, neste vídeo: Como instalar o Obsidian e configurar a sincronização em nuvem de graça.

Passo 1: Criar um Vault para o Projeto

No Obsidian, um "vault" é basicamente uma pasta que ele monitora. Crie um vault separado para cada projeto que você tiver. Isso é importante porque cada vault vai rodar em uma porta diferente, evitando conflitos.

Abra o Obsidian
Vá em Gerenciar cofres
Clique em Criar novo e dê um nome relacionado ao projeto (ex: MeuProjeto)
Selecione o caminho onde ele ficará salvo

Passo 2: Instalar o Plugin BRAT

O BRAT (Beta Reviewers Auto-update Tester) é um plugin do Obsidian que permite instalar plugins não oficiais — ou seja, aqueles que ainda não estão na loja oficial.

Dentro do vault recém-criado, vá em Configurações → Plugins não oficiais
Habilite os plugins não oficiais
Clique em Procurar e pesquise por BRAT
Instale e ative o plugin

Passo 3: Instalar o Plugin Claude Code MCP

Esse é o plugin que cria a ponte entre o Obsidian e o Claude Code via protocolo MCP.

Repositório oficial: https://github.com/iansinnott/obsidian-claude-code-mcp

Com o BRAT instalado, vá em suas configurações
Clique em Add Plugin
Cole a URL do repositório: https://github.com/iansinnott/obsidian-claude-code-mcp
Selecione sempre a última versão disponível
Clique em Add Plugin

Depois de instalado, o plugin vai aparecer na lista como Claude Code MCP.

Passo 4: Configurar a Porta do Plugin

⚠️ Atenção: esta etapa é crítica se você tiver múltiplos vaults.

Cada vault precisa rodar em uma porta diferente. Se dois vaults estiverem na mesma porta, haverá conflito e erro.

Nas configurações do plugin Claude Code MCP, encontre o campo de porta
A porta padrão é 22360
Se esse vault for o único, pode deixar assim
Se você já tiver outro vault com essa porta, mude para 22361, 22362, 22363, etc.

Anote a URL completa que aparece (ex: http://localhost:22361) — você vai precisar dela no próximo passo.

Passo 5: Estruturar a Documentação no Vault

Essa é a parte mais importante de todo o sistema. A qualidade das respostas do Claude Code vai ser diretamente proporcional à qualidade da sua documentação.

Eu uso esta estrutura de pastas dentro do vault:

MeuProjeto/
├── MeuProjeto.md          ← MOC (Map of Content) — arquivo principal
├── Autenticação.md
├── Banco de Dados.md
├── API.md
├── Sistema de Pagamentos.md
├── Frontend.md
└── Tarefas/               ← pasta para tasks e anotações do dia a dia

Cada arquivo de funcionalidade deve ter uma seção de conexões com outros arquivos usando a sintaxe de links internos do Obsidian:

## Integrações

Este módulo se conecta com:
- [[Sistema de Pagamentos]]
- [[Banco de Dados]]
- [[API]]

É exatamente essa malha de conexões que permite ao Claude navegar pelo vault de forma inteligente, lendo apenas o que é relevante.

Passo 6: Gerar a Documentação Inicial com Claude Code

Se você já tem um projeto rodando mas ainda não tem documentação, não precisa escrever tudo na mão. Use o próprio Claude Code para isso.

Antes de rodar qualquer prompt, é importante entender o padrão de documentação que recomendo. Ele é simples de criar e fácil de manter — e é exatamente o que você vai pedir ao Claude para seguir.

O padrão de documentação do vault

Cada arquivo do vault deve começar com um frontmatter no topo, seguido do conteúdo:

---
tags: [backend, frontend, agente, autenticação]   # categoria do conteúdo
relacionado: [[Arquivo Relacionado]], [[Outro Arquivo]]   # wiki-links internos
status: ativo | em-revisão | depreciado
tipo: feature | decisão | arquitetura | endpoint | componente
versao: 1.0.0
---

Regras de nomenclatura e escrita:

Nome do arquivo: PascalCase com espaços — ex: Sistema de Pagamentos.md
Idioma: Português em títulos e texto; código e identificadores em inglês
Conteúdo: descrever o comportamento atual, nunca o histórico de mudanças
Sem seções "antes/depois" — use o histórico do Git para rastrear o passado, não o vault

Estrutura sugerida para cada funcionalidade:

# Nome da Feature

Descrição clara do que faz e por que existe.

## Como funciona

Fluxo completo, com referência aos módulos envolvidos.

## Arquivos principais

Lista dos arquivos de código relevantes.

## Integrações

Quais outros módulos, serviços ou agentes essa feature aciona ou depende.

## Configuração

Variáveis de ambiente, flags, repositórios envolvidos.

## Observações importantes

Edge cases, limitações conhecidas, decisões não-óbvias.

Prompt para gerar a documentação do projeto existente

Com o padrão definido, use o prompt abaixo dentro do Claude Code. Ele vai percorrer o seu projeto e criar toda a documentação no vault seguindo exatamente esse formato:

Percorra o projeto inteiro e documente cada módulo e funcionalidade de forma separada, 
criando um arquivo .md individual para cada um no vault do Obsidian.

Siga obrigatoriamente estas regras:

1. Cada arquivo deve começar com o frontmatter:
---
tags: [categorias relevantes]
relacionado: [[Arquivos conectados]]
status: ativo
tipo: feature | arquitetura | decisão | endpoint | componente
versao: 1.0.0
---

2. Nome dos arquivos em PascalCase com espaços (ex: "Sistema de Pagamentos.md")

3. Cada arquivo deve seguir esta estrutura:
# Nome do Módulo
Descrição do que faz e por que existe.
## Como funciona
## Arquivos principais
## Integrações
## Configuração
## Observações importantes

4. Use [[wiki-links]] para conectar arquivos relacionados entre si
5. Documente o estado atual — sem histórico de mudanças
6. Crie também um arquivo MOC (Map of Content) principal com o nome do projeto, 
   listando todos os módulos e suas conexões

O vault está localizado em: [CAMINHO DO SEU VAULT AQUI]

Substitua [CAMINHO DO SEU VAULT AQUI] pelo caminho real da pasta do vault no seu sistema.

Revise os arquivos gerados para garantir que a documentação está precisa. O Claude vai fazer um bom trabalho, mas você conhece o projeto — vale a pena uma leitura antes de avançar.

Passo 7: Criar o Arquivo `CLAUDE.md`

O CLAUDE.md é o ponto de entrada de cada sessão. Ele fica na raiz do seu projeto e diz ao Claude Code como se comportar: onde está o vault, quais protocolos seguir, como estruturar a documentação.

Prompt para gerar o CLAUDE.md personalizado:

Use o prompt abaixo no Claude Code. A única coisa que você precisa alterar antes de rodar é o campo da porta/URL do vault:

# Agente Gerador de CLAUDE.md

## Identidade e Propósito

Você é um agente especializado em criar e manter arquivos `CLAUDE.md` para projetos de software. 
Seu trabalho é produzir um arquivo de contexto vivo que sirva como o **cérebro externo** do 
Claude Code durante o desenvolvimento — não uma documentação estática, mas um guia operacional 
que o Claude seguirá ativamente em cada sessão de trabalho.

Antes de gerar qualquer conteúdo, você **obrigatoriamente** deve ler a documentação existente 
no vault do Obsidian conectado. O vault é a fonte de verdade do projeto. O `CLAUDE.md` que 
você vai gerar é um reflexo fiel e condensado dessa documentação, não uma suposição sua sobre 
o sistema.

---

## Protocolo de Execução

Siga estas etapas em ordem. Não pule nenhuma.

### Etapa 1 — Leitura do vault

Usando as ferramentas MCP do Obsidian disponíveis:

1. Liste todos os arquivos no vault do projeto
2. Leia obrigatoriamente os seguintes arquivos (se existirem):
   - MOC principal
   - Arquitetura do sistema
   - Todos os arquivos de features existentes
   - Banco de dados, autenticação, APIs, deploy
   - Frontend, componentes, design system
   - Qualquer arquivo de decisões arquiteturais (ADRs)
3. Se houver arquivos que você ainda não leu e que parecem relevantes, leia-os também
4. Só avance para a Etapa 2 depois de ter lido **toda** a documentação relevante

### Etapa 2 — Leitura do código (se acessível)

Examine a estrutura de pastas do projeto para confirmar o que a documentação descreve e 
identificar lacunas.

### Etapa 3 — Geração do CLAUDE.md

Gere o arquivo seguindo o formato padrão com:
- Referência ao vault conectado (porta e localização)
- Mapa da documentação por tipo de tarefa
- Protocolo obrigatório antes e depois de qualquer alteração
- Padrão de documentação no vault
- Arquitetura geral extraída do vault
- Comandos essenciais do projeto
- Regras críticas
- Lacunas de documentação identificadas
- Active Context para atualização manual a cada sessão

**Vault conectada:** `http://localhost:<PORTA>`  ← SUBSTITUA PELA SUA PORTA AQUI
**Localização da documentação:** `<CAMINHO COMPLETO DO VAULT>`  ← SUBSTITUA AQUI

⚠️ Atenção: Antes de rodar esse prompt, substitua <PORTA> pela porta que você configurou no Passo 4 (ex: 22361) e <CAMINHO COMPLETO DO VAULT> pelo caminho real no seu sistema.

Passo 8: Testar se Está Funcionando

Com o CLAUDE.md criado, abra uma nova sessão do Claude Code e teste:

Liste toda a documentação do projeto.

Se tudo estiver funcionando, o Claude vai acessar o vault automaticamente e trazer os arquivos da documentação. A partir desse momento, qualquer alteração que você pedir vai primeiro consultar o vault, navegar pelos arquivos conectados e só então propor mudanças.

Como Funciona na Prática

Vamos imaginar que você quer migrar o gateway de pagamento do Stripe para outro provider.

Antes desse sistema: você precisaria explicar toda a arquitetura do projeto, como o sistema de créditos funciona, como está integrado com o banco de dados, etc. E na próxima sessão, repetiria tudo de novo.

Com esse sistema: você simplesmente pede a mudança. O Claude lê o CLAUDE.md, acessa o vault, encontra o arquivo de Sistema de Pagamentos, vê que ele está linkado com Sistema de Créditos e Banco de Dados, lê esses arquivos também, entende o estado atual do sistema — e só então propõe a implementação.

Sem repetição de contexto. Sem sessões que esquecem tudo. Sem tokens desperdiçados com informação irrelevante.

Mantendo o Sistema Vivo

O grande diferencial dessa arquitetura é que ela se mantém atualizada — mas isso requer uma disciplina simples: toda vez que o Claude fizer uma alteração no código, ele também deve atualizar o vault.

O CLAUDE.md gerado pelo prompt já instrui o Claude a fazer isso automaticamente:

Feature nova → criar novo arquivo .md no vault
Alteração existente → atualizar o arquivo relevante
Decisão arquitetural → criar arquivo em Decisões/ e referenciar no MOC principal

O Git guarda o passado do código. O vault guarda o estado atual do sistema. Nunca o contrário.

Dica: Um Vault por Projeto

Se você tiver múltiplos projetos, crie um vault separado para cada um e configure-os em portas diferentes. Você pode ter, por exemplo:

Projeto A → porta 22360
Projeto B → porta 22361
Notas pessoais → porta 22362

Cada projeto tem seu CLAUDE.md apontando para a porta correta do vault correspondente. O Claude Code sabe exatamente onde buscar o contexto dependendo do projeto em que está trabalhando.

Conclusão

Essa arquitetura mudou completamente a forma como eu trabalho com o Claude Code. Não é só uma questão de economizar tokens — é sobre ter um assistente que realmente entende o projeto, que lembra das decisões tomadas, que sabe quais módulos se conectam e que entrega respostas de qualidade consistente sessão após sessão.

O custo de implementar é baixo: algumas horas para configurar e documentar o projeto pela primeira vez. O retorno é acumulativo: cada sessão fica mais precisa, cada resposta mais contextualizada.

Se você implementar, conta nos comentários como foi — e se já usava alguma variação disso, me conta também.