Custom Instructions Claude Code — Guia completo para personalizar seu agente

Sumário

• O problema com instruções genéricas
• O que são custom instructions no Claude Code?
• CLAUDE.md na prática: como criar e organizar
• Exemplos reais: React, Python, Go
• Como versionar e compartilhar
• Boas práticas e armadilhas comuns
• FAQ
• Leve suas custom instructions para o próximo nível

O problema com instruções genéricas

Claude Code é treinado para escrever código funcional em qualquer linguagem e framework popular. Isso é impressionante, mas também cria um problema sutil: sem orientação específica, o agente toma decisões que podem não alinhar com o estilo do seu time ou as convenções do seu projeto.

Por exemplo, se o time usa type em vez de interface no TypeScript por padrão, ou prefere snake_case em vez de camelCase nas respostas de uma API, o Claude Code provavelmente vai gerar o oposto — a menos que alguém diga explicitamente o contrário. Cada vez que você corrige manualmente uma escolha de estilo que deveria ser óbvia, perde tempo e consistência.

Desenvolvedores experientes relatam que a personalização do Claude Code reduz correções manuais em até 40% depois que as regras certas são estabelecidas. O ganho não está apenas no tempo economizado em cada correção, mas na consistência do código gerado — especialmente em projetos com múltiplos contribuidores ou agents rodando simultaneamente.

Sem um mecanismo de custom instructions, cada desenvolvedor precisa repetir as mesmas orientações em cada sessão, o que é inviável. É aí que o CLAUDE.md entra.

O que são custom instructions no Claude Code?

Custom instructions são diretrizes persistentes que você fornece ao Claude Code para moldar seu comportamento. Diferente de prompts avulsos que você digita no terminal, essas instruções ficam salvas e são carregadas automaticamente sempre que o agente é iniciado no contexto do projeto.

Existem dois níveis de escopo:

• Global (CLAUDE.md na home directory): instruções que valem para todos os projetos. Ideal para preferências pessoais — editor, formato de commit, estilo de código que você segue independentemente do projeto.
• Por projeto (CLAUDE.md na raiz do projeto): instruções específicas daquele repositório. Ideal para regras do time, convenções do framework, configurações de linter, caminhos de diretório e documentação interna.

O arquivo CLAUDE.md usa Markdown simples, sem sintaxe proprietária. O Claude Code lê o arquivo no início de cada sessão e mantém as instruções como contexto durante toda a interação. Você pode usar seções, listas, tabelas e blocos de código — tudo o que o Markdown oferece.

Além do CLAUDE.md, o Claude Code aceita CLAUDE_GLOBAL.md (aplicado globalmente antes do arquivo local) e instructions passados via parâmetro na CLI. A prioridade de resolução segue esta ordem:

1. CLAUDE_GLOBAL.md na home directory
2. CLAUDE.md na raiz do projeto
3. Instruções passadas via linha de comando

Isso significa que instruções mais específicas sobrescrevem as mais genéricas — exatamente o que você espera de um sistema de configuração por cascata.

CLAUDE.md na prática: como criar e organizar

Criar um CLAUDE.md é trivial: um arquivo de texto na raiz do seu projeto. O conteúdo, no entanto, exige estrutura para ser útil. Um arquivo bagunçado confunde o agente tanto quanto nenhum arquivo.

Estrutura recomendada

Organize seu CLAUDE.md em seções claras. Cada seção cobre um aspecto do comportamento:

O que colocar em cada seção

Stack e Framework: Liste as tecnologias principais e versões. O Claude Code pode inferir parte disso do package.json, mas instruções explícitas evitam ambiguidades — especialmente com bibliotecas novas ou versões incomuns.

Convenções de Código: Seja específico. Em vez de "escrever código limpo", diga "usar early return em vez de if-else aninhados" ou "preferir map sobre forEach quando transformar arrays". O agente entende bem regras concretas.

Estrutura de Diretórios: Informe onde cada tipo de arquivo deve ser criado ou modificado. Isso evita que o agente crie componentes na raiz ou coloque testes em pastas erradas.

Testes: Especifique o framework, padrão de nomenclatura e localização dos testes. Sem isso, o agente pode criar testes em formatos que seu pipeline de CI não reconhece.

Commits: Defina o padrão de mensagens de commit. Útil se você usa Conventional Commits ou ferramentas de changelog automatizado.

Onde salvar cada arquivo

• Global: %USERPROFILE%\CLAUDE.md no Windows. Tudo que está aqui vale para qualquer projeto que você abrir com Claude Code.
• Projeto: ./CLAUDE.md na raiz do repositório. Versionado com o código, garantindo que todos no time usem as mesmas regras.

>

Exemplos reais: React, Python, Go

Cada stack tem necessidades específicas. Abaixo, exemplos reais de CLAUDE.md para três cenários comuns no desenvolvimento moderno.

React + Next.js (front-end)

Python (back-end / data science)

/src

/models/ — SQLAlchemy models

/schemas/ — Pydantic schemas (request/response)

/routes/ — Endpoints FastAPI

/services/ — Lógica de negócio

/core/ — Config, DB session, security

Go (microservices / CLI)

/cmd/api/ — Entry point da API

/internal/

/handler/ — HTTP handlers

/service/ — Business logic

/repository/ — Data access

/model/ — Domain types

/pkg/ — Código compartilhável

>

Como versionar e compartilhar suas instruções

O grande diferencial do CLAUDE.md em relação a outras formas de personalização do Claude Code é que ele é versionado. Isso significa que as regras do projeto ficam no repositório e viajam com o código.

Versionamento com Git

Adicione CLAUDE.md ao seu repositório como qualquer outro arquivo de configuração:

Quando um novo desenvolvedor clonar o repositório, ele já terá as instruções corretas. Se as regras mudarem, o histórico do Git mostra quem alterou o quê e quando. Para mudanças que afetam o comportamento do agente, vale a pena usar o mesmo fluxo de code review que você usa para código.

Compartilhamento entre times

Se sua organização usa múltiplos repositórios, considere:

1. Template de repositório: Crie um repositório template com CLAUDE.md básico que cada equipe adapta.
2. Submódulo ou symlink: Para times grandes, um CLAUDE.md central referenciado via symlink mantém consistência sem duplicação.
3. CLAUDE_GLOBAL.md para padrões corporativos: Regras de compliance, segurança e nomenclatura da empresa vão no global; regras de projeto vão no local.

Sincronização com ferramentas de time

Algumas equipes usam scripts que copiam um CLAUDE.md central sempre que o repositório é clonado ou atualizado via hook post-checkout. Isso garante que ninguém trabalhe com regras desatualizadas. O Orquestra oferece sincronização automática de configuration entre múltiplos projetos — útil quando você gerencia vários repositórios com regras diferentes.

Boas práticas e armadilhas comuns

Um CLAUDE.md bem escrito acelera o desenvolvimento. Um mal escrito pode piorar os resultados. Aqui estão as práticas que funcionam e os erros que você deve evitar.

Boas práticas

Seja específico e mensurável. Regras vagas como "escreva código limpo" não ajudam. Prefira "não use any no TypeScript; crie tipos explícitos" ou "toda função pública deve ter docstring". O agente entende melhor restrições concretas.

Mantenha o arquivo atualizado. Quando o time muda de versão de framework ou adota uma nova biblioteca, atualize o CLAUDE.md. Instruções desatualizadas geram código que não compila. Inclua a revisão do CLAUDE.md no checklist de code review.

Use exemplos de código. Em vez de descrever o padrão, mostre:

class UserNotFoundError(Exception):

pass

raise Exception("user not found")

Balance entre regras demais e de menos. Um arquivo de 200 linhas com regras contraditórias confunde o agente. Comece com 10-15 regras essenciais e adicione conforme necessário. O ponto ideal é onde o agente raramente precisa de correções manuais.

Teste as regras. Depois de atualizar o CLAUDE.md, peça ao agente para executar uma tarefa típica do projeto e veja se ele segue as regras. Ajuste o que não funcionar. Trate o CLAUDE.md como código — ele merece testes e iteração.

Armadilhas comuns

Regras contraditórias entre global e local. Se o CLAUDE_GLOBAL.md diz "use tabs" e o CLAUDE.md do projeto diz "use spaces", o agente pode entrar em conflito. Revise os dois arquivos periodicamente para garantir consistência.

Excesso de regras de baixo valor. Listar cada detalhe do linter que já está no eslint.config.js ou pyproject.toml é redundante e desperdiça tokens de contexto. Foque no que as ferramentas automáticas não capturam: decisões arquiteturais, convenções de time, padrões de nomeação.

Ignorar a localização do arquivo. Colocar o CLAUDE.md em um subdiretório em vez da raiz do projeto faz com que o agente não o encontre. O Claude Code procura especificamente por ./CLAUDE.md.

Instruções como um romance. Parágrafos longos diluem as regras importantes. Use listas, tópicos e blocos de código. O agente processa melhor informações estruturadas.

Esquecer de versionar. Se o CLAUDE.md não está no repositório, cada desenvolvedor precisa configurar manualmente. Isso anula o propósito de consistência e escala mal com o time.

FAQ

O que é CLAUDE.md no Claude Code?

CLAUDE.md é um arquivo Markdown na raiz do projeto que contém instruções personalizadas para o Claude Code. Ele define regras de código, convenções de time, estrutura de diretórios e preferências de framework que o agente segue automaticamente em todas as interações dentro daquele projeto.

Qual a diferença entre CLAUDE.md e CLAUDE_GLOBAL.md?

CLAUDE_GLOBAL.md fica na home directory do usuário e se aplica a todos os projetos. CLAUDE.md fica na raiz do projeto e vale apenas para aquele repositório. As instruções locais sobrescrevem as globais em caso de conflito. Ambos são carregados automaticamente quando o Claude Code inicia.

Custom instructions consomem tokens do contexto?

Sim. O conteúdo do CLAUDE.md é adicionado ao contexto do agente, consumindo tokens de entrada. Por isso é recomendado manter o arquivo conciso — entre 10 e 30 regras bem escritas valem mais que 100 regras genéricas. Um arquivo de 2 a 3 KB tem impacto mínimo no custo por sessão.

Dá para usar custom instructions com outros agentes além do Claude Code?

Sim. Ferramentas como Codex CLI e OpenCode também aceitam arquivos de instrução no projeto. O Orquestra permite gerenciar instruções centralizadamente e sincronizar regras entre múltiplos agentes no mesmo canvas — você define as regras uma vez e todos os agentes as seguem.

Preciso editar o CLAUDE.md sempre que troco de framework?

Sim, e isso é um benefício, não um problema. O CLAUDE.md deve refletir o estado atual do projeto. Quando o time atualiza o framework, altera o design system ou muda convenções, o arquivo deve ser atualizado junto — de preferência no mesmo pull request que aplica as mudanças no código.

Como testar se minhas custom instructions estão funcionando?

Peça ao Claude Code para executar uma tarefa típica do projeto e observe se ele segue as regras definidas. Você também pode perguntar diretamente: "Quais regras deste projeto você está seguindo?" — o agente consegue listar as instruções que carregou do CLAUDE.md.

Leve suas custom instructions para o próximo nível

As custom instructions Claude Code são uma das ferramentas mais subestimadas por quem está começando com agentes de IA. Um CLAUDE.md bem estruturado transforma o agente de um assistente genérico em um membro do time que conhece as regras, respeita as convenções e entrega código consistente — sem que você precise repetir as mesmas instruções toda vez.

Comece pequeno: crie um CLAUDE.md com 5 regras essenciais do seu projeto atual e observe a diferença na qualidade das sugestões. Depois expanda conforme o time sentir necessidade. O importante é começar.

Quer gerenciar múltiplos projetos com regras diferentes sem se perder? O Orquestra foi feito para desenvolvedores que usam Claude Code, Codex e OpenCode no mesmo fluxo de trabalho no Windows. Conecte seus agentes, sincronize instruções e trabalhe em um canvas infinito com todas as ferramentas que você já conhece.

Baixe o Orquestra para Windows 11 e organize seus agentes com custom instructions centralizadas. A versão gratuita suporta quantos projetos você quiser.

Links relacionados:

• Claude Code e Codex no Windows — Guia completo
• Claude Code vs OpenCode — Comparativo técnico
• Planos e preços do Orquestra

Imagens sugeridas

1. Diagrama de precedência — fluxo de resolução de instruções: CLAUDE_GLOBAL.md → CLAUDE.md local → CLI flags, com indicação de qual sobrescreve qual
2. Três painéis de exemplo — trechos de CLAUDE.md lado a lado para React, Python e Go destacando as regras específicas de cada stack
3. Screenshot do terminal — Claude Code rodando em um projeto com CLAUDE.md configurado, respondendo com base nas regras