Como transformar notas do Obsidian em um brief para o Claude Code

Semana passada eu deixei uma nota de umas 2000 palavras parada no Obsidian e, no dia seguinte, pedi pro Claude Code: “arruma aquele botão do checkout”.

O que voltou foi a correção do botão, mais um ajuste no espaçamento do cabeçalho, uma reordenação dos links do rodapé e, de quebra, uma faxina na convenção de nomes do CSS. Um diff espalhado por três arquivos. Eu não pedi nada disso. E sabe por quê aconteceu? Porque eu colei a nota inteira. Até um “isso aqui também me incomoda” que eu tinha rabiscado três dias antes foi lido com o mesmo peso da tarefa de hoje.

A nota não tem culpa. A culpa foi minha, por achar que dava pra “entregar do jeito que estava”. Uma nota longa é ótima pra registrar, mas péssima como ordem de serviço. Hoje eu vou escrever o formato que fecha esse buraco: o passo a passo pra transformar uma nota do Obsidian num brief curto.

Pontos principais

• Colar a nota inteira faz a IA não distinguir um rabisco antigo da instrução de hoje, e ela expande para tarefas que você nunca pediu.
• Você entrega só quatro coisas: “o que já é fato”, “o que ficou decidido”, “o que ainda não sei” e “a próxima ação”. Some a isso “onde não mexer” e “a prova de que terminou”.
• Mantenha o critério de conclusão pequeno. Foque em um arquivo, uma tela, um comando, e só avance depois de ver o build passar e tirar o screenshot.
• O prompt-modelo e um código curto que converte a nota em brief estão prontos pra copiar e colar.
• Delegue à IA “escrever, procurar, corrigir”. Quem decide “escopo, prioridade e se pode publicar” é você. Misturar isso é receita de acidente.

Por que colar tudo faz a tarefa inchar

O Claude Code é rápido pra agir. E é justamente por isso que, se a primeira entrada vem larga, ele corre largo a toda velocidade.

Notas têm camadas de tempo. O fato de hoje, “o botão quebra em duas linhas”, e o palpite de uma semana atrás, “pensando bem, a paleta também está datada”, aparecem como bullets na mesma lista. Uma pessoa lê isso com data e contexto e separa; a IA que recebeu o texto colado não sabe qual instrução ainda está viva. Resultado: por gentileza, ela mexe em tudo.

Tem mais um detalhe. As notas misturam “o que foi decidido” com “o que ainda está em dúvida”. Quando a parte da dúvida é lida como instrução, a IA decide sozinha por um dos lados e segue. Isso é o mais perigoso. Por isso, antes de entregar, você precisa fazer uma triagem, uma única vez, do lado humano.

Você entrega só quatro coisas

O eixo da triagem é simples: basta separar nos quatro grupos abaixo.

1. Fato: o que você confirmou de verdade. “Na tela de 375px o botão quebra em duas linhas”, “a URL pública está certa” e coisas com as quais qualquer um concorda ao olhar.
2. Decisão: o que já foi decidido. Como “o PDF gratuito fica antes do material pago”, um rumo já discutido e que não muda mais.
3. Dúvida: o que ainda não sei. “Não sei qual componente carrega o espaçamento do botão” e outros buracos que você não quer que a IA preencha por conta própria.
4. Próxima ação: a única coisa a fazer agora. Concreto até o fim: “identificar o componente, aplicar a menor mudança de CSS possível e verificar na largura de celular”.

A isso some mais dois itens. Onde não mexer (ex.: não tocar nos arquivos de autenticação desta vez) e a prova de que terminou (ex.: o build passa, screenshot na largura de celular). Esses seis itens são o conteúdo do brief.

O que importa na triagem é não apagar a “Dúvida”. Quando você deixa registrado, honestamente, o que não sabe, a IA faz perguntas em vez de chutar. Se você apaga a dúvida e escreve como se fosse fato, ela avança em cima de uma premissa errada.

O que delegar à IA e o que você decide

Antes de tudo, trace a linha entre o que pode delegar e o que você precisa segurar. Se isso fica vago, mesmo com brief o resultado oscila.

Etapa	Delego à IA	Eu decido
Escopo	-	Em qual arquivo/tela focar
Investigação	Procurar componentes e código	A prioridade do que procurar
Implementação	Escrever a menor mudança	O limite do que pode mudar
Verificação	Rodar build e testes	A decisão final de publicar ou não

Como mostra a tabela, “procurar, escrever, rodar” é o forte da IA. Já “até onde ir” e “pode publicar?” ficam com você. Escreva essa linha no brief, e mesmo que a IA tente esticar o escopo, ela mesma freia.

Prompt-modelo para copiar e colar

Primeiro selecione a nota do jeito que está e cole abaixo deste pedido. É o uso em que a própria triagem fica a cargo da IA.

Organize a nota do Obsidian abaixo em um brief curto para o Claude Code.
Use apenas os títulos a seguir e descarte o resto.

- Fato: só o que está confirmado
- Decisão: rumo que não muda mais
- Dúvida: não preencha por conta própria, deixe como desconhecido
- Próxima ação: a única coisa a fazer agora, de forma concreta
- Onde não mexer: arquivos ou funções que não devem ser tocados desta vez
- Prova: como saber que terminou (build, screenshot etc.)

Reúna palpites antigos e conversa solta em um bloco separado de "notas de referência" e não misture com as instruções.

Releia o brief gerado e confira só duas coisas: se nenhuma “Dúvida” virou “Fato” e se a “Próxima ação” ficou reduzida a uma só. Se estiver tudo certo, cole isso no CLAUDE.md ou no comentário da issue e peça a implementação. Como escrever um bom CLAUDE.md está detalhado em claude-md-best-practices.

Código para validar a conversão da nota em brief

Antes do trabalho manual, deixo um código pequeno só pra você sentir a estrutura no corpo. Roda em Node.js. Ele guarda a nota separada nos seis itens acima e monta um único brief pra entregar ao Claude Code.

// Guarda a nota separada em "fato, decisão, dúvida, próxima ação"
const note = {
  title: "O botão do checkout quebra de linha no celular",
  facts: ["Na tela de 375px o botão quebra em duas linhas", "A URL pública está correta"],
  decision: "O PDF gratuito fica antes do material pago",
  unknowns: ["Não sei qual componente carrega o espaçamento do botão"],
  nextAction: "Identificar o componente, aplicar a menor mudança de CSS e verificar na largura de celular",
  doNotTouch: ["Arquivos de autenticação"],
  proof: ["O build passa", "Screenshot na largura de 375px"],
};

// Monta os seis itens em um único texto de brief
function toBrief(item) {
  return [
    `Objetivo: ${item.nextAction}`,
    `Fato: ${item.facts.join(" / ")}`,
    `Decisão: ${item.decision}`,
    `Dúvida (não preencher por conta própria): ${item.unknowns.join(" / ")}`,
    `Onde não mexer: ${item.doNotTouch.join(" / ")}`,
    `Prova: ${item.proof.join(" / ")}`,
  ].join("\n");
}

// Porteiro que checa, por máquina, se faltou triagem
function checkBrief(item) {
  const missing = [];
  if (item.facts.length === 0) missing.push("Fato");
  if (item.unknowns.length === 0) missing.push("Dúvida");
  if (!item.nextAction) missing.push("Próxima ação");
  if (missing.length) {
    throw new Error(`Triagem incompleta: ${missing.join(", ")}`);
  }
  return true;
}

checkBrief(note);
console.log(toBrief(note));

A checkBrief parece boba, mas é o coração disso. Se você tentar emitir o brief com “Fato” vazio, “Dúvida” vazia ou “Próxima ação” vazia, ela trava aqui. Proibir o “cola e pronto” já no nível do código reduz o acidente de uma nota tosca escorrer direto pra IA. Cole a saída no comentário da issue ou na nota de handoff e você reaproveita o mesmo critério no próximo trabalho. Como montar essa nota de handoff está em claude-code-session-handoff-template.

Onde isso funciona bem

1. Ao pedir a melhoria de um artigo Se você joga “deixa esse artigo melhor”, a IA tende a reescrever o texto inteiro. Então, no brief, escreva “entregue só a intenção de busca e a política de CTA” e “reescrever o corpo inteiro é proibido”. O fato é o título atual, a decisão é o rumo do funil, a dúvida é qual parágrafo está fraco e a próxima ação é corrigir um único heading. Assim o diff fica pequeno e dá pra reverter num instante. A configuração da integração com o Obsidian em si está em claude-code-obsidian-integration.

2. Ao corrigir um bug O truque é separar o fato que você reproduziu da causa que ainda não conhece. “Em 375px o botão quebra” é fato; “qual componente carrega o espaçamento” é dúvida. Se você mistura isso e escreve “a causa deve ser no CSS”, a IA começa a corrigir em cima de um palpite errado. Entregue a dúvida como dúvida, e ela investiga isso primeiro.

3. Ao receber uma consulta sobre adoção A nota de operação do cliente você não mostra crua; separe em “o que vamos tocar desta vez”, “o que nunca tocar” e “o que verificar na próxima”. Não deixe a IA mexer sozinha em dados de produção ou na cobrança enquanto isso for dúvida. Só de escrever essa fronteira no brief, dá pra compartilhar a tela com tranquilidade durante a reunião.

Erros comuns e como corrigir

Os erros que eu cometi no começo cabem quase todos nestes três.

O primeiro foi colar o vault inteiro. Decisões antigas e restrições atuais se misturaram e a IA não sabia em qual acreditar. A correção é simples: antes de colar, faça a triagem nos seis itens acima. O palpite de três dias atrás vai pra um isolamento chamado “notas de referência”.

O segundo foi entregar só a decisão. Quando escrevi apenas “o PDF vai na frente”, a IA não entendeu o porquê e, em outro contexto, fez o contrário. Deixe o fato e a razão juntos, e a coisa se aplica em mais situações.

O terceiro foi deixar o critério de conclusão grande. Se você pede “organiza isso no geral”, a IA, gentilmente, alarga o escopo. Foque em um arquivo, uma tela, um comando, e só avance depois de ver o build e o screenshot. Só isso já reduz o tempo de reverter sem perder velocidade. Sobre como afunilar o prompt, veja também claude-code-prompt-engineering-advanced.

Perguntas frequentes

P. Não dá mais trabalho montar o brief do que colar a nota toda? Nas primeiras vezes parece que sim. Mas o tempo de reler e reverter o diff que inchou por causa do “joga e reza” pesa muito mais no longo prazo. Com o hábito, a triagem se faz em um minuto.

P. Posso deixar a triagem a cargo da IA também? Pode. O prompt-modelo acima é exatamente esse uso. Só que o brief gerado precisa de uma leitura humana, para conferir se nenhuma “Dúvida” virou “Fato”.

P. Qual a diferença entre o CLAUDE.md e o brief? O CLAUDE.md é o lugar das regras que não mudam ao longo do projeto; o brief é o pedido de um único trabalho desta vez. Se a “Decisão” de um brief aparece repetidas vezes, é o sinal de promovê-la para o CLAUDE.md.

P. Dá pra usar mesmo sem o Obsidian? Dá. Notion ou um simples bloco de texto também servem. O importante não é a ferramenta, e sim a ideia de separar em fato, decisão, dúvida e próxima ação.

P. Até onde delegar à IA e a partir de onde decidir? “Procurar, escrever, rodar” pode delegar tranquilo. “Até onde esticar o escopo” e “pode publicar?” ficam com você. O truque é escrever essa linha no brief. A base de como delegar à IA está em claude-code-for-non-engineers.

O que aconteceu quando testei de verdade

Depois do “acidente dos três arquivos que eu não pedi” lá do começo, passei a fazer a triagem nos seis itens sempre antes de colar a nota.

Refiz, de fato, a mesma correção do botão do checkout, dessa vez na forma de brief. O diff foi um arquivo, umas poucas linhas de CSS. Nem o cabeçalho nem o rodapé, nada que eu não tinha pedido, foi tocado. A checkBrief me travou uma vez, porque eu tentei emitir com a “Dúvida” vazia; depois de acrescentar “qual componente carrega o espaçamento”, entreguei, e acho que isso ajudou. A IA foi procurar esse componente primeiro.

Confirmei duas coisas. Que “deixar a dúvida registrada faz a IA investigar em vez de chutar”. E que “afunilar a próxima ação para uma só deixa o diff pequeno e fácil de reverter”. Em vez de caçar o prompt mais esperto, o minuto de triagem antes de entregar é, no fim, o caminho mais rápido. É essa a minha sensação hoje.

Quando você pegar o jeito da triagem e quiser rodar esse mesmo formato no time inteiro, eu tenho treinamento e consultoria para desenhar o processo junto com você.

Os pré-requisitos oficiais estão em Anthropic Claude Code getting started.