Como fazer o Claude Code seguir o padrão do seu projeto em vez de inventar do zero?

Fala aí, beleza? Agente que nunca viu o teu projeto entrega código genérico, e isso é o esperado

O Claude Code não adivinha o padrão da tua base

Ele responde com o que está no contexto da sessão, e só

Se ninguém mostrou como o teu projeto nomeia um service, como trata erro, qual é a cara de um componente teu, ele vai propor a solução mais média que existe no mundo

Aí você reescreve tudo na mão e fica com a sensação de que a IA não serve pro teu caso

Serve sim, o que falta é MATERIAL

Neste post eu vou te mostrar como entregar esse material de referência (um arquivo real do projeto, um padrão que já existe na base, uma regra escrita) e como apontar pra ele dentro do pedido, pra ferramenta seguir o que você já tem em vez de inventar do zero 🙂

O que você precisa antes de começar

Nada de setup gigante aqui, é bem pouca coisa:

• Claude Code aberto no diretório do projeto
• Um material que REPRESENTE o padrão: um arquivo concreto da tua base ou a regra já escrita
• Cinco minutos de paciência pra escolher o arquivo certo em vez do primeiro que aparecer

Vale entender uma coisa antes de seguir: o Claude Code lê instruções, configurações, skills, subagents e memória a partir do diretório do projeto e do ~/.claude na tua home

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Se você está no Windows, esse ~/.claude é o %USERPROFILE%\.claude

Ou seja, dá pra deixar material valendo só naquele projeto ou material valendo pra você em qualquer projeto

Sem material bom, o resto não resolve

Se o arquivo que você escolher for justamente aquele legado esquisito que ninguém quer copiar, adivinha o que vai sair do outro lado? Isso mesmo, mais legado esquisito haha

Passo a passo: fazer o Claude Code seguir o que você já tem

1. Escolha o arquivo que representa o padrão

Tem que ser um arquivo concreto, de preferência um que você teria orgulho de mostrar em code review

E arquivo mesmo, não pasta: referenciar um diretório com @ retorna a LISTAGEM dos arquivos, não o conteúdo deles

O erro comum deste passo: apontar @src/services/ achando que o Claude vai ler a pasta toda, e depois estranhar que ele continuou inventando

2. Referencie o arquivo no prompt com @

Digitou @, abre o menu de sugestão de caminho

Tab ou Enter aceita o caminho destacado, e aí você dá Enter de novo pra enviar a mensagem

O autocomplete também funciona se você digitar um token com barra, tipo ./src/ ou ~/: aparece o dropdown de arquivos e diretórios e o Tab aceita

Quando você referencia um arquivo assim, o Claude lê o arquivo antes de responder, que é exatamente o que a gente quer

O erro comum deste passo: apertar Enter pra escolher o caminho e achar que já mandou o pedido, quando na verdade você só aceitou a sugestão

3. Referencie mais de um arquivo quando o padrão está espalhado

Às vezes o padrão não mora em um arquivo só: tem o service, tem o teste dele, tem o tipo

Dá pra citar vários na mesma mensagem, no formato do exemplo oficial da documentação: @file1.js and @file2.js

O erro comum deste passo: exagerar na dose e mandar meia dúzia de arquivos "por garantia"

Cada arquivo referenciado entra no contexto, então mande dois ou três representativos e pare por aí

4. Escreva o pedido citando a restrição e apontando o exemplo

Essa é a virada de chave do post

A documentação de boas práticas orienta justamente isso: referenciar arquivos específicos, citar as restrições e apontar pros padrões de exemplo

Ou seja, em vez de descrever de novo a solução que você quer, você mostra a solução que já existe

Cria o service de pagamento seguindo exatamente o padrao de
@src/services/user-service.ts e @src/services/user-service.test.ts

Restricoes: mesma estrutura de pastas, mesmo formato de erro,
mesma forma de injetar dependencia
Nao introduza biblioteca nova

Repare que o pedido não explica COMO tratar erro

O arquivo já explica, e explica melhor do que você escreveria em três linhas de prompt

O erro comum deste passo: redescrever a arquitetura inteira no prompt e só jogar o @ no final como enfeite

5. Valide a proposta antes de qualquer edição com o plan mode

O plan mode é um modo de permissão em que o Claude pesquisa e propõe, sem editar os arquivos fonte: ele lê, busca, roda comandos de exploração e depois apresenta um plano pra aprovação

Pra entrar nele, Shift+Tab cicla entre os modos de permissão no CLI (default, acceptEdits, plan e os que estiverem habilitados), ou você prefixa o pedido com /plan

É o mesmo espírito de fazer o Claude rodar os testes de verdade em vez de aceitar um "pronto, funcionou" sem prova: primeiro ver o que ele pretende fazer, depois liberar

O erro comum deste passo: ler o plano na diagonal

Se o plano não menciona o arquivo de referência em lugar nenhum, ele não vai seguir o teu padrão, ele vai seguir o que achou bonito

6. Transforme o que se repete em instrução persistente

Se você está colando a mesma restrição em todo prompt, ela não é pedido, é regra do projeto

Lugar de regra é no CLAUDE.md, um arquivo markdown que o Claude Code lê no início de toda sessão

O comando /init conduz a criação do CLAUDE.md do projeto

Os escopos são estes: projeto em ./CLAUDE.md ou ./.claude/CLAUDE.md, e usuário em ~/.claude/CLAUDE.md, além da política gerenciada pela organização

E se liga nisso, porque muita gente entende errado: todos os arquivos encontrados são CONCATENADOS no contexto, do escopo mais amplo pro mais específico

Um não sobrescreve o outro

Pra navegar e abrir esses arquivos de memória sem sair da sessão, usa o /memory

O erro comum deste passo: escrever a regra no escopo de usuário achando que é do projeto, e aí ela te acompanha em TODO projeto que você abrir

Qual formato usar para cada tipo de material

Nem todo material merece o mesmo lugar

Esse é o mapa que eu uso pra decidir:

Sobre o CLAUDE.md: a documentação recomenda manter cada arquivo abaixo de 200 linhas

O motivo é bem pragmático: arquivo longo consome mais contexto e ainda reduz a aderência às instruções

É aquele paradoxo chato, quanto mais você escreve, menos ele obedece

E quando a regra vale só pra uma pasta?

Aí entram as rules, que são arquivos de instrução modulares em .claude/rules/, e o momento em que elas carregam depende do frontmatter

O pulo do gato é o frontmatter YAML com o campo paths e padrões glob:

---
paths:
  - "src/api/**/*.ts"
---

Uma rule assim carrega quando o Claude lê um arquivo que casa com o padrão, não a cada uso de ferramenta

E rule SEM o campo paths carrega sempre junto com o CLAUDE.md, valendo pra todos os arquivos

Tome cuidado aqui: esquecer o paths é o jeito mais fácil de transformar uma regrinha de API em peso morto em todas as sessões

E se o material for muito longo?

Se o CLAUDE.md começou a crescer, o conteúdo de referência pode sair dali e virar skill ou ser dividido em arquivos dentro de .claude/rules/

Uma skill no Claude Code é um arquivo SKILL.md dentro do diretório dela: .claude/skills/<nome>/SKILL.md no projeto, ou ~/.claude/skills/<nome>/SKILL.md no escopo de usuário

Detalhe muito massa: ao adicionar, editar ou remover uma skill nesses lugares, o Claude Code detecta a mudança dentro da sessão atual, sem precisar reiniciar

É o mesmo caminho que você usaria pra montar um agente de SEO com o material do teu blog dentro, só que aqui o conteúdo é o padrão de código da casa

Mais dois comportamentos que vale ter na cabeça:

• Quando você referencia um arquivo com @, o Claude também adiciona ao contexto o CLAUDE.md do diretório daquele arquivo e dos diretórios pais
• Quando um arquivo de memória do projeto importa com @path um arquivo FORA do diretório de trabalho, o Claude Code pede aprovação

O custo de contexto desse material (e como não estourar a janela)

Agora a parte que todo mundo esquece: material de referência é contexto, e contexto tem preço

Quando eu gravei o vídeo sobre queima de tokens, a dica que eu coloquei como fundamental em todo projeto foi justamente ter um CLAUDE.md bem feito, concentrando as regras de negócio e as partes críticas

O raciocínio é simples de enxergar com um exemplo: imagina a regra "todas as funções devem ser comentadas"

Sem o arquivo, o Claude vai abrir os arquivos do projeto pra inferir esse padrão sozinho, e gasta token nessas idas e voltas

Com a informação escrita ali, ele encontra no teu material e não sai procurando em outro lugar

No vídeo eu mostro o meu arquivo na tela e faço questão de falar do outro lado da moeda: encher o CLAUDE.md de informação cria o mesmo problema ao contrário, porque o arquivo inteiro vira input e queima token à toa

Enxuto, só com o que interessa

E tem um detalhe que quebra a expectativa de muita gente: dividir o conteúdo em imports @path dentro do CLAUDE.md ajuda a ORGANIZAR, mas não reduz contexto, porque os arquivos importados carregam no início da sessão do mesmo jeito

Quem economiza de verdade é rule com paths, que carrega sob demanda quando o arquivo casado é lido

Quer ver o tamanho do estrago? Roda /context

Ele mostra o que está ocupando a janela de contexto da sessão: histórico da conversa, conteúdo de arquivos, saídas de comando, CLAUDE.md, auto memory, skills carregadas e instruções de sistema

E sim, auto memory é coisa diferente do CLAUDE.md

São dois mecanismos: o CLAUDE.md você escreve, e a auto memory são notas que o próprio Claude escreve a partir das tuas correções e preferências

Os dois são carregados no início de cada conversa

Outra coisa que eu recomendo por experiência própria e que entra na mesma conta: cole só o TRECHO relevante do erro, não o log inteiro

Na maioria dos casos a primeira linha, aquela que aponta o arquivo, já resolve a parada

O vídeo é sobre economia de token, mas no fundo é a mesma conversa deste post: o que você entrega de material é o que define se ele consulta a tua referência ou sai vasculhando o projeto pra descobrir padrão sozinho

Conclusão

O agente segue o que você MOSTRA, não o que você imagina que ele já sabe

Recapitulando o caminho: escolhe um arquivo concreto que represente o padrão, referencia com @ no prompt, cita a restrição em vez de redescrever a solução, valida no plan mode antes de liberar edição, e o que se repetir vira CLAUDE.md ou rule com paths

Teu próximo passo, bem concreto: roda /init pra criar o CLAUDE.md do projeto, separa um arquivo de referência e faz o MESMO pedido duas vezes, uma sem @ e outra com @

A diferença entre as duas respostas costuma explicar sozinha o post inteiro 😀

Depois roda /context pra ver quanto esse material está pesando e ajusta o tamanho do arquivo

Faça o teste e me conta o resultado, até o próximo post!