Quando o Hélio entendeu a lógica de criar e executar processos, surgiu uma pergunta natural: como corrigir quando o resultado não está certo? Abrir uma nova conversa e explicar tudo de novo? Mandar mensagens inline na conversa existente?
A resposta que uso é diferente: anotar diretamente no arquivo. Com uma tag específica para isso.
Como funciona a <nota>
A <nota> é uma tag que você insere em qualquer arquivo Markdown do ambiente. Ela funciona como instrução inline — uma correção ou melhoria que você quer que o Claude aplique.
A regra de escopo é única: a <nota> sempre se refere ao trecho imediatamente anterior a ela no arquivo. Você não aponta para outro lugar, não usa atributos — só escreve a nota logo abaixo do trecho que quer alterar.
Depois que o Claude integra a nota, ela é removida. Nota = instrução a executar. Quando foi executada, some.
O que torna uma nota boa
A diferença entre uma nota que gera resultado e uma que gera retrabalho está na precisão.
Notas boas contextualizam o problema, corrigem com direção, e atualizam o que vem depois:
<nota>
O parágrafo cita IOF como opcional. IOF aplica em todas as
compras com cartão internacional — corrija e atualize a
etapa 3 para incluir essa verificação.
</nota><nota>
A cor de destaque deveria ser o azul-marinho da marca
(#1B2A4E). Atualize aqui e registre em
`identidade-da-marca/CLAUDE.md`.
</nota><nota>
Você assumiu que o aluno usa Mac. Adicione variação Windows
na próxima execução desse prompt.
</nota>Notas ruins são genéricas e não dão direção:
<nota>errado</nota><nota>muda isso</nota><nota>não gostei</nota>A diferença não é sobre formalidade — é sobre utilidade. Uma nota ruim obriga o Claude a adivinhar o que você quis dizer. Uma boa elimina essa adivinação.
A instrução de integração
Quando você termina de anotar, a instrução para integrar é direta:
O `./Financeiro/CLAUDE.md` contém várias anotações que fiz
visando melhorar o processo. As anotações são sempre
relacionadas ao conteúdo diretamente anterior a elas.
Integre-as ao conteúdo do arquivo.O Claude lê o arquivo, localiza cada <nota>, aplica a instrução no trecho anterior, e remove a tag. O arquivo sai revisado e limpo.
A regra de escopo única
A <nota> tem um escopo: o trecho imediatamente anterior.
Se você precisa deixar uma observação sobre o documento inteiro, ou sobre uma seção específica lá atrás, escreva em prosa diretamente — ou use outra tag com nome diferente (<pendente>, <questao-aberta>). A <nota> tem semântica específica: instrução para integrar no próximo trecho que veio antes.
Manter essa regra simples sem exceções é o que torna o sistema confiável. O aluno aprende uma regra e usa em qualquer arquivo.
Por que anotar no arquivo e não no chat
Mandar uma mensagem no chat explicando o que precisa mudar tem um custo: você precisa dar contexto. “No terceiro parágrafo do CLAUDE.md do Financeiro, onde fala sobre IOF…” — e mesmo assim pode haver ambiguidade.
A nota no arquivo elimina esse custo. Ela fica ao lado do trecho. O contexto é o próprio conteúdo que ela precede. Não tem como o Claude confundir onde a instrução se aplica.
Para processos com muitos ajustes a fazer, é possível anotar tudo de uma vez antes de pedir a integração. Todas as correções centralizadas, uma única rodada de integração.
Estou ministrando mentorias para profissionais de diversas áreas que estão começando nessa ideia. Se não quer percorrer esse caminho sozinho, é só me chamar.