Como pedir para o Claude Code seguir o padrão de um arquivo que já existe no projeto

Descrever a convenção do time em palavras é chato, longo e quase sempre incompleto

Mostrar um arquivo bom do próprio repositório leva dois segundos

E o Claude Code trabalha melhor assim: quando você aponta um caminho de arquivo no prompt com @, ele lê aquele arquivo antes de responder

Apontar custa menos que explicar, e a documentação oficial do Claude Code orienta exatamente isso: referenciar arquivos específicos, citar restrições e apontar padrões de exemplo, em vez de descrever onde o código mora

Quanto mais precisa a instrução, menos correção depois

Bora ver como fazer isso direito?

O que você precisa antes de começar

Pouca coisa, se liga:

• Claude Code aberto no diretório do projeto (a sessão precisa enxergar o repo)
• pelo menos UM arquivo que você olha e pensa "esse aqui tá do jeito que eu quero"
• o caminho desse arquivo, ou paciência de meio segundo pra usar a tab-completion, que o Claude Code oferece pra encontrar e apontar arquivos ou pastas em qualquer ponto do repositório

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

Um aviso antes de seguir, e esse é o mais importante de todos

Se o arquivo de referência for ruim, o resultado sai ruim junto

Você não tá pedindo qualidade, tá pedindo semelhança

Então escolha com carinho 🙂

Passo a passo: usar um arquivo existente como referência de padrão

1. Escolha o arquivo de referência olhando três critérios: recente, revisado por alguém e da MESMA camada do que você vai criar. Controller olha controller, teste olha teste, serviço olha serviço

O erro comum deste passo: pegar o arquivo mais famoso do projeto em vez do mais parecido. O arquivo lendário de 900 linhas que ninguém mexe há dois anos não é molde, é fóssil

2. Referencie com @ dentro do prompt, colando o caminho completo a partir da raiz do repo

Crie o handler de recuperação de senha seguindo @src/auth/login.ts

Se você não lembra o caminho exato, usa a tab-completion e deixa o próprio Claude Code completar pra você

O erro comum deste passo: digitar o caminho de cabeça, errar uma pasta e achar que o padrão "não funcionou". Ele não leu nada, só isso

3. Diga O QUE copiar, com nome e sobrenome. "Siga o padrão" é vago demais e cada um entende uma coisa por padrão

Seja específico: estrutura do arquivo, ordem das funções, convenção de nomes, formato do retorno de erro, estilo de asserção nos testes

Use @src/auth/login.ts como referência de ESTRUTURA:
mesma ordem de imports, mesma assinatura de função exportada,
mesmo formato de objeto de erro e mesma convenção de nomes

O erro comum deste passo: pedir "igual a esse arquivo" e ganhar uma cópia com o nome trocado

4. Diga o que NÃO copiar, e essa parte quase todo mundo esquece

Regra de negócio do outro domínio, dados de exemplo, imports que só fazem sentido naquele contexto, tudo isso tem que ficar de fora explicitamente

Não traga a regra de negócio de login, não traga os imports
específicos de sessão e não reaproveite as mensagens de texto
daquele arquivo

O erro comum deste passo: assumir que "é óbvio" que a regra de negócio não entra. Não é óbvio pra ninguém, nem pra humano em code review

5. Aponte mais de um arquivo quando o padrão for a interseção entre eles. Dá pra usar o @ várias vezes na mesma mensagem, a própria documentação mostra o formato @file1.js and @file2.js

Isso ajuda MUITO quando um arquivo sozinho tem manias próprias: com dois ou três exemplos, o que se repete entre eles é a convenção de verdade

Siga o que é comum entre @src/users/routes.ts e @src/orders/routes.ts

O erro comum deste passo: jogar seis arquivos de camadas diferentes e esperar que ele adivinhe qual é a régua

6. Rode em plan mode antes de deixar ele editar qualquer coisa. Shift+Tab entra no modo de planejamento, e o prefixo /plan vale pra um único prompt

Nesse modo ele pesquisa e propõe as mudanças sem aplicar, as edições ficam bloqueadas até você aprovar o plano

Aí você lê o plano e confere se o que ele ENTENDEU por padrão bate com o que você quis dizer

Quando o plano aparece, você escolhe entre "Yes, and use auto mode", "Yes, manually approve edits" ou "No, keep planning"

E Shift+Tab de novo sai do plan mode sem aprovar nada

O erro comum deste passo: aprovar em modo automático de primeira num arquivo que você nem leu direito. Na dúvida, aprova revisando edição por edição

Quando ele copia o que não devia: como corrigir na hora

Acontece, e os sintomas são sempre os mesmos três

O primeiro: veio a regra de negócio do arquivo de exemplo junto, tipo validação de senha aparecendo num módulo de relatório

O segundo: arrastou imports que não têm nada a ver com o novo arquivo

O terceiro, e o mais sorrateiro: pegou um caso MUITO específico daquele arquivo e generalizou como se fosse convenção do projeto inteiro

A causa é quase sempre a mesma: o prompt disse "igual a esse arquivo" sem delimitar o escopo da imitação

Sem recorte, tudo dentro do arquivo vira candidato a padrão

A solução: reescrever o pedido nomeando o recorte e reapontando o MESMO arquivo, agora com a lista do que fica de fora

Refaça usando @src/auth/login.ts apenas como molde de estrutura
e nomenclatura

Ignore a lógica de autenticação, os imports de sessão e as
constantes daquele módulo

E se ele já editou tudo?

Respira, tem volta

O Claude Code cria checkpoints automáticos do estado do código antes de cada prompt seu

Pra abrir o menu de rewind, aperta Escape duas vezes ou usa /rewind

Lá você escolhe restaurar só a conversa, só o código, ou os dois

A sessão guarda snapshots dos 100 checkpoints mais recentes, então não é infinito, beleza?

Tome cuidado com uma coisa: o checkpointing não rastreia arquivos modificados por comandos bash, só as edições feitas pelas ferramentas de edição do próprio Claude

Ou seja, rm, mv e cp rodados via bash não voltam pelo rewind

Os rm -rf da vida continuam sendo definitivos xD

Onde essa técnica rende mais

Criar um módulo novo espelhando um irmão já aprovado. Você tem um endpoint que passou em code review e ninguém reclamou

Ele é o melhor documento de convenção que o projeto tem, mesmo que ninguém tenha escrito uma linha de documentação

Aponta ele e pede o novo no mesmo formato

Escrever testes. Esse é o caso mais redondo de todos: ao gerar testes, o Claude examina os arquivos de teste existentes pra casar com o estilo, os frameworks e os padrões de asserção já em uso no projeto

Apontar o arquivo de teste que você considera exemplar só deixa esse trabalho mais preciso ainda

Padronizar arquivo antigo usando o novo como molde. Aqui a direção inverte: o arquivo bonito é o recente, e o alvo é o legado

É o mesmo raciocínio de refatorar sem reescrever o arquivo inteiro, com o recorte bem apertado pra não virar reescrita geral

Onboarding de convenção que ninguém documentou. Todo time tem aquele acordo tácito que só vive na cabeça de duas pessoas

É o mesmo aperto de quem precisa lidar com padrão de código de projeto antigo, onde a regra existe mas não está escrita em lugar nenhum

Apontar o arquivo resolve na hora, sem reunião

Quando o padrão para de ser prompt e vira regra no CLAUDE.md

Tem um sinal claro pra isso

Se você aponta o MESMO arquivo de referência toda semana, aquilo não é mais contexto de prompt, é convenção de projeto

E convenção de projeto tem lugar certo pra morar:

1. Coloque a regra no CLAUDE.md, que é o arquivo de instruções permanentes do projeto. Ele é markdown puro e é lido automaticamente no início de cada sessão naquele diretório

O arquivo de escopo de projeto fica na raiz do repositório

O erro comum deste passo: criar o arquivo numa subpasta aleatória e estranhar que "o Claude ignora"

2. Escreva o que ele precisa sempre saber: convenções de código, comandos de build, estrutura do projeto e regras do tipo "nunca faça X"

O erro comum deste passo: transformar o CLAUDE.md num romance. Regra clara e curta vence parágrafo bonito

3. Use /memory pra abrir e navegar os arquivos de memória de dentro da própria sessão, sem sair pro editor

4. Preferência que é SÓ sua vai no CLAUDE.local.md, na raiz do projeto. Ele é tratado igual ao CLAUDE.md e a recomendação é adicionar no .gitignore

O erro comum deste passo: versionar sua manha pessoal e empurrar ela pro time inteiro

5. Trate o arquivo como doc vivo de onboarding. A orientação oficial é adicionar uma linha por erro recorrente: quando o Claude erra a mesma coisa duas vezes, é sinal de que falta uma regra

E revisar de tempos em tempos apagando o que ficou obsoleto, porque instrução desatualizada é PIOR que nenhuma instrução

O erro comum deste passo: só escrever e nunca apagar, aí o arquivo vira um cemitério de regras que já não valem mais

Vale lembrar que o Claude Code lê CLAUDE.md, settings.json, hooks, skills, comandos, subagents, workflows e regras a partir do diretório .claude do projeto e do ~/.claude no diretório do usuário

Então a memória do projeto e a sua memória global convivem numa boa

Conclusão

A lógica toda cabe numa frase: instrução precisa gera menos correção, e apontar um arquivo é a forma mais barata de ser preciso

Você não precisa escrever um manual de estilo pra explicar como o time nomeia as coisas

O manual já está no repo, só falta apontar o caminho com @, dizer o que copiar e o que ignorar

O próximo passo prático é hoje mesmo: escolhe um arquivo do teu projeto que tu considera exemplar, usa ele no próximo prompt em plan mode e vê o que o Claude entendeu antes de deixar editar

Se você perceber que tá apontando o mesmo arquivo toda semana, promove aquilo pra regra no CLAUDE.md e para de repetir

Faça o teste e me conta como foi =)

até o próximo post!