Imagine começar cada conversa com a IA do zero, re-explicando o que você constrói, quais ferramentas usa e como gosta de receber respostas. Cansativo e caro em tokens. O CLAUDE.md resolve isso: é um arquivo lido automaticamente no início de toda sessão, virando o contexto base do agente — a sua memória de projeto que não se apaga quando a conversa termina.
Diagrama ilustrativo — o CLAUDE.md é "injetado" no contexto do agente toda vez que você abre uma sessão, então ele já começa sabendo quem é, o que está construindo e como agir.
📌 CLAUDE.md como system prompt persistente
O que é
O CLAUDE.md é um arquivo em Markdown que fica na raiz do seu projeto e define o papel, o contexto e as preferências sob as quais o agente vai operar. Quando você abre uma sessão de trabalho naquela pasta, o agente lê esse arquivo antes de qualquer coisa — ele se torna o "system prompt" do projeto, ou seja, a instrução base que molda todo o comportamento da IA dali pra frente.
O que é?System prompt — a instrução de fundo que diz à IA quem ela é e como agir, sempre ativa por trás da conversa. Markdown — um jeito simples de escrever texto com títulos (#), listas e ênfase, sem precisar de programação. Sessão — uma "rodada" de trabalho com o agente, do momento em que você abre até fechar.
A palavra-chave é persistente. Uma conversa comum se apaga: feche a janela e o agente esquece tudo. O CLAUDE.md não — ele vive no disco, é versionado junto com o projeto e é lido de novo a cada sessão. Por isso a melhor analogia é uma constituição: um documento curto e estável que governa como o projeto funciona, ao qual o agente sempre obedece, independente de quem (ou quando) está conversando com ele.
Por que aprender
Sem CLAUDE.md, todo dia começa do zero: você cola de novo o contexto, repete as suas regras, lembra das suas preferências. Com ele, o conhecimento do projeto fica gravado uma vez e reaproveitado infinitas vezes. É a diferença entre treinar um funcionário novo toda manhã e ter um veterano que já chega sabendo.
- •Zero re-explicação: o contexto entra sozinho em cada sessão.
- •Consistência: todas as sessões seguem as mesmas regras.
- •Base de tudo: os outros tópicos deste módulo refinam este arquivo.
Conceitos-chave
Arquivo .md no topo do projeto.
Não se apaga ao fechar a conversa.
Carregado no início de cada sessão.
Governa o comportamento do agente.
🧱 Anatomia do CLAUDE.md
O que é
Um bom CLAUDE.md tem cinco seções típicas: Papel (quem o agente é — ex.: "você é um assistente de workflows n8n"), Contexto (o que está sendo construído e por quê), Regras operacionais (como ele deve trabalhar), Estilo (preferências de comunicação) e Estrutura de pastas (onde as coisas ficam). Cada seção responde a uma pergunta diferente que a IA faria se estivesse chegando agora no projeto.
Diagrama ilustrativo — as cinco seções não são compartimentos isolados; juntas elas formam o "molde" completo a partir do qual o agente age.
Por que aprender
Você não precisa escrever essas seções à mão. O caminho vibe coding é pedir em linguagem natural: "crie um CLAUDE.md para um projeto que monta automações no n8n, com regras de procurar uma ferramenta antes de criar e manter o arquivo enxuto". A IA gera o esqueleto com as seções certas; você só revisa e ajusta. Conhecer a anatomia serve para você saber o que pedir e o que checar no resultado.
✓ Seções que toda anatomia tem
- ✓Papel: "você é um assistente de workflows n8n".
- ✓Contexto: o que o projeto é e qual o objetivo principal.
- ✓Regras + Estilo + Estrutura: como agir, como falar, onde ficam as coisas.
✗ O que polui a anatomia
- ✗Tutoriais passo a passo de tarefas específicas.
- ✗Documentação longa de uma única ferramenta.
- ✗Histórico de conversas e decisões antigas.
Conceitos-chave
Quem o agente é.
O que está sendo construído.
Como agir e como falar.
Em linguagem natural, não à mão.
⚙️ Regras operacionais
O que é
Regras operacionais são instruções curtas sobre como o agente deve trabalhar — não o que construir, mas a disciplina do dia a dia. Três regras valem ouro em quase todo projeto: procurar uma ferramenta existente antes de criar uma nova, aprender e se adaptar quando algo falha, e manter os workflows e arquivos sempre atualizados. São poucas linhas, mas mudam radicalmente o comportamento.
O que é?Ciclo de auto-melhoria — quando o agente, ao errar, ajusta sua própria forma de trabalhar (e até o próprio CLAUDE.md) em vez de só remendar a saída. Ferramenta (tool) — uma capacidade que o agente pode usar (ler arquivo, chamar API, rodar uma skill).
Essas regras são exatamente o que liga o ciclo de auto-melhoria. "Procure antes de criar" evita reinventar a roda e mantém o projeto limpo. "Aprenda ao falhar" faz o agente tratar um erro como informação, não como beco sem saída. "Mantenha tudo atualizado" garante que a documentação e os fluxos não fiquem desatualizados em relação ao que realmente existe. Juntas, elas transformam o agente de executor passivo em colaborador que melhora sozinho.
✓ Regras que ativam o ciclo
- ✓"Procure uma ferramenta existente antes de criar uma nova."
- ✓"Quando algo falhar, aprenda e adapte a abordagem."
- ✓"Mantenha workflows e arquivos sempre atualizados."
✗ Anti-padrões nas regras
- ✗Criar uma tool nova toda vez, ignorando o que já existe.
- ✗Insistir na mesma abordagem que já falhou.
- ✗Deixar a documentação desatualizada em relação ao real.
🎯 Dica prática
Escreva regras como princípios curtos e acionáveis, não como parágrafos. "Procure antes de criar" é melhor que três frases explicando o porquê. A IA segue regras enxutas com mais fidelidade — e elas ficam fáceis de encontrar no meio do arquivo.
Conceitos-chave
Reusar > recriar.
Erro vira ajuste.
Docs = realidade.
As regras ligam o ciclo.
✂️ Manter enxuto (< ~500 linhas)
O que é
Como o CLAUDE.md entra no contexto a cada sessão, ele compete por espaço com o resto da conversa. A regra prática: mantenha-o enxuto, abaixo de ~500 linhas. Um arquivo curto faz cada regra "pesar" mais; um arquivo longo dilui as instruções importantes no meio de texto demais, e o agente acaba "perdendo" justamente o que importa.
O que é?Contexto (janela de contexto) — o "espaço de memória de trabalho" do agente numa sessão; tudo que entra ali (incluindo o CLAUDE.md) ocupa lugar. Token — o pedacinho de texto que a IA conta; quanto mais linhas no arquivo, mais tokens gastos toda sessão.
Diagrama ilustrativo — quanto mais o arquivo ocupa, menos espaço sobra para a conversa, e mais fácil é a IA "não enxergar" uma regra importante perdida no meio do texto.
Por que aprender
Há um sintoma clássico: se o agente insiste em fazer algo errado mesmo havendo uma regra clara contra isso, o arquivo provavelmente está longo demais e a regra está se perdendo. A solução não é gritar a regra em maiúsculas — é cortar gordura. Tire o que não é de toda sessão, condense parágrafos em princípios, e a regra volta a ter peso. Ser conciso é uma decisão de engenharia, não preguiça.
🎯 Dica prática
Regra de bolso: se o CLAUDE.md não cabe em uma ou duas telas de rolagem, ele já está grande demais. Antes de adicionar qualquer coisa, pergunte: "isso é mesmo de toda sessão?". Se for de uma tarefa específica, o lugar dele é uma skill (próximo tópico).
Conceitos-chave
Ocupa contexto sempre.
Teto prático.
Regras se perdem.
Erra apesar da regra = corte.
🔀 CLAUDE.md vs skills — o que vai onde
O que é
A regra de roteamento mais importante deste módulo: o CLAUDE.md guarda só o que é de toda sessão (propósito do projeto, framework, objetivo principal, regras operacionais). Instruções específicas de uma tarefa — como "gerar uma fatura em PDF" ou "fazer scraping de um site" — pertencem a uma skill, carregada sob demanda, só quando a tarefa aparece.
O que é?Skill — um conjunto de instruções especializadas para uma tarefa, guardado num arquivo separado e carregado só quando precisa. Sob demanda (on demand) — só entra no contexto na hora em que é usado, em vez de ficar sempre carregado.
Diagrama ilustrativo — muitas skills (20 a 50) não incham o contexto, porque entram só quando a tarefa pede; um CLAUDE.md gigante incharia toda sessão.
Por que aprender
Enfiar tudo no CLAUDE.md estoura a janela de contexto: cada sessão carrega toneladas de instruções que talvez nem sejam usadas naquele dia. Skills resolvem isso por economia de carregamento. Você pode ter 20, 30, 50 skills sem inflar o contexto, porque cada uma só aparece quando a tarefa correspondente surge — diferente de um CLAUDE.md gigante, que pagaria o custo em todas as sessões.
✓ Vai no CLAUDE.md
- ✓Propósito do projeto e objetivo principal.
- ✓Framework e regras operacionais (de toda sessão).
- ✓Estilo de comunicação e estrutura de pastas.
✗ Não vai (vai em skill)
- ✗Passo a passo de uma tarefa pontual (ex.: gerar PDF).
- ✗Instruções de uma integração usada de vez em quando.
- ✗Receitas longas que só servem para um tipo de pedido.
Conceitos-chave
Só o sempre-presente.
Específico, sob demanda.
20–50 skills cabem.
Evita lotar o contexto.
💬 Iterar o arquivo conversando
O que é
O CLAUDE.md é um documento vivo. Você não precisa abrir um editor para mexer nele: basta pedir ao próprio agente. "Adicione uma seção sobre manter as explicações concisas", "remova a regra X que não usamos mais", "registre que este projeto usa Supabase". A IA edita o arquivo, e a mudança vale a partir da próxima sessão. O arquivo evolui junto com o projeto.
O que é?Documento vivo — um arquivo que você espera mudar com frequência, não algo escrito uma vez e congelado. Iterar — fazer pequenas melhorias em ciclos, validando a cada passo (a mesma mentalidade da Trilha 1).
Como o arquivo evolui
-
1
Sessão inicial: você pede um CLAUDE.md básico (papel, contexto, regras). O agente gera o esqueleto.
-
2
Surge um padrão: você nota que pede sempre respostas curtas. "Adicione uma seção dizendo para manter as explicações concisas."
-
3
O projeto cresce: entra uma nova ferramenta. "Registre que usamos Supabase para os dados." O contexto fica atual.
-
4
Hora de podar: o arquivo passou de ~500 linhas. "Mova as instruções da tarefa de faturas para uma skill e enxugue o CLAUDE.md."
Por que aprender
Tratar o CLAUDE.md como algo editável a qualquer momento, em linguagem natural, fecha o ciclo de auto-melhoria do módulo: toda vez que o agente erra por falta de uma regra, você adiciona a regra conversando; toda vez que o arquivo incha, você poda conversando. Não é um documento sagrado — é uma ferramenta de trabalho que você afia continuamente.
🎯 Objetivo: gerar um CLAUDE.md enxuto para o projeto
crie um CLAUDE.md na raiz para um projeto que <descreva o que você constrói>. Seções: Papel, Contexto, Regras operacionais, Estilo, Estrutura de pastas. Regras: procurar uma tool existente antes de criar; aprender ao falhar; manter sob ~500 linhas.
✅ Como verificar: abra o arquivo gerado; confira as 5 seções e que ele cabe em ~1 tela de rolagem.
📜 Esqueleto: um CLAUDE.md mínimo e enxuto
# Papel Você é um assistente de workflows n8n para este projeto. ## Contexto Construímos automações que conectam e-mail, planilhas e um banco Supabase. Objetivo principal: notificar a equipe sobre leads novos em tempo real. ## Regras - Procure uma tool/skill existente antes de criar uma nova. - Quando algo falhar, aprenda e adapte a abordagem. - Mantenha este arquivo sob ~500 linhas (tarefa específica vira skill). ## Estilo - Respostas curtas e diretas, em PT-BR. - Explique o "porquê" das decisões em 1 frase. ## Estrutura - /workflows → fluxos n8n exportados - /skills → instruções de tarefas específicas - /docs → notas e decisões do projeto
✅ Como verificar: cada seção tem 1–3 linhas; nenhum passo a passo de tarefa específica está aqui (isso vai em /skills).
Onde devem ficar as instruções passo a passo para "gerar uma fatura em PDF", uma tarefa que só aparece de vez em quando?
Conceitos-chave
Evolui com o projeto.
Em linguagem natural.
Errou? grave a regra.
Inchou? enxugue.
📌 Resumo do Módulo
Próximo Módulo:
2.2 — O Framework WAT a Fundo