O Guia Completo de Configuração do Claude Code (2026)

Acabou de instalar o Claude Code. Escreveu claude no terminal e... funciona. Lê os seus ficheiros, executa comandos, escreve código. Bastante fixe.

Mas eis a questão: está a deixar 90% do potencial da ferramenta por explorar.

Na nossa análise de mais de 800 configurações em jeanclaudecode.ai, a pontuação média é 3,2 em 10. A maioria das pessoas instala o Claude Code, talvez escreva umas linhas de instruções, e pára por aí. Dez minutos de configuração separam um chatbot básico de um verdadeiro parceiro de programação.

Vamos resolver isso agora mesmo.

O ficheiro que muda tudo

Crie um ficheiro chamado CLAUDE.md na raiz do seu projeto. É isso. É a coisa mais importante que vai fazer hoje.

touch CLAUDE.md

O CLAUDE.md é a primeira coisa que o Claude lê quando inicia uma sessão. Pense nele como um briefing — está a dizer ao Claude com quem está a trabalhar, como é o projeto e quais são as regras.

Aqui está um mínimo para começar. Abra o CLAUDE.md e cole isto:

# O Meu Projeto

## Stack Técnica
- Next.js 15, TypeScript, PostgreSQL

## Comandos
- `npm run dev` — servidor de desenvolvimento
- `npm run test` — executar testes
- `npm run build` — build de produção

## Regras
- Sempre executar testes antes de dizer que uma tarefa está concluída
- Nunca modificar ficheiros em src/legacy/

Cinco linhas de stack técnica. Três comandos. Duas regras. É tudo o que precisa para começar.

Experimente agora. Abra o Claude Code e peça: "Lê o meu CLAUDE.md e diz-me que projeto é este." O Claude deve descrever o seu projeto de volta. Se o fizer, está pronto. Se não, verifique que o ficheiro está na raiz do projeto (não dentro de uma subpasta).

Acabou de dar ao Claude algo que falta a 68% dos setups: noção básica do projeto.

Construir a partir daí: o CLAUDE.md que os melhores setups usam

Esse ficheiro mínimo funciona. Mas os setups com pontuação 7+ na nossa análise vão mais longe. Eis o que acrescentam — e porque é que cada secção importa.

Secção de arquitetura (encontrada em 78% dos melhores setups)

O Claude não sabe onde os seus ficheiros estão. Sem um mapa, adivinha — e adivinha mal. Acrescente isto:

## Arquitetura
- src/app/ — Páginas e rotas API do App Router
- src/lib/ — Utilitários partilhados e cliente de base de dados
- src/components/ — Componentes React (testes colocalizados)

Agora quando diz "cria uma nova rota API", o Claude coloca-a em src/app/api/ em vez de inventar uma localização aleatória.

Secção de convenções (65% dos melhores setups)

Tem opiniões sobre como o código deve ser. O Claude não as conhece a não ser que as diga:

## Convenções
- Mensagens de commit imperativas, minúsculas, sem ponto
- Um componente por ficheiro, apenas exports nomeados
- Todas as rotas API validam entrada com esquemas zod

Seja específico. "Escreve código limpo" não dá nada ao Claude. "Usa zod para toda a validação de entrada da API" dá-lhe uma regra concreta para seguir.

Secção de problemas conhecidos (apenas 34% dos melhores setups — a maior oportunidade desperdiçada)

Esta é a secção que a maioria das pessoas salta, e é a que mais frustração evita:

## Problemas Conhecidos
- O handler do webhook do Stripe precisa de parsing `raw` do body — não usar middleware express.json() em /api/webhooks/stripe
- Safari não suporta `structuredClone` em workers — usar o polyfill em src/lib/clone.ts
- O ambiente de CI tem 4 GB de RAM — testes que excedam isto falham silenciosamente (OOM)

Sempre que o Claude comete um erro que já viu antes, acrescente-o aqui. Com o tempo, esta torna-se a secção mais valiosa do ficheiro — um registo vivo de "não pises esta mina."

Agora vamos adicionar permissões (para que o Claude pare de perguntar por cada coisinha)

De raiz, o Claude pede permissão antes de executar qualquer comando shell. Cada. Único. Comando. Cansa depressa.

A solução: crie um ficheiro de definições que diga ao Claude o que pode fazer sem perguntar.

mkdir -p .claude

Agora crie .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm run test*)",
      "Bash(npm run build)",
      "Bash(npm run lint*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

A lista allow diz "vai em frente, não perguntes." A lista deny diz "nunca faças isto, mesmo que eu acidentalmente te diga para fazer."

Importante: Nunca ponha "Bash(*)" na lista allow. Isso dá ao Claude acesso total ao shell sem qualquer proteção. Seja específico sobre o que é permitido.

Experimente executar o Claude Code agora. Peça-lhe para verificar o git status ou executar testes. Repare como ele simplesmente... faz? Sem nenhum popup de permissão. Esse fluxo é o que separa os setups que as pessoas abandonam dos setups que usam todos os dias.

Adicionar rules que se ativam automaticamente

Pode estar a pensar: "Devo pôr todas as minhas convenções de código no CLAUDE.md?" Podia. Mas há uma forma mais inteligente.

Rules são ficheiros markdown que se ativam com base nos ficheiros que o Claude está a editar. Quando o Claude edita um ficheiro .tsx, carrega as suas rules de frontend. Quando toca num ficheiro de migração, carrega as rules de base de dados. Quando está a trabalhar em CSS, não perde tempo a ler as suas convenções de SQL.

Crie o diretório de rules:

mkdir -p .claude/rules

Aqui está uma rule de frontend. Guarde como .claude/rules/frontend.md:

---
globs: ["*.tsx", "*.jsx", "*.css"]
---

- Usar exports nomeados, não exports por defeito
- Cada componente deve ter um ficheiro .test.tsx correspondente
- Apenas CSS modules — sem estilos inline exceto para valores dinâmicos
- Todas as imagens precisam de texto alt (requisito de acessibilidade)

E uma rule de base de dados — guarde como .claude/rules/database.md:

---
globs: ["*.sql", "**/migrations/**", "**/prisma/**"]
---

- Nunca modificar ficheiros de migração existentes
- Todas as queries devem usar inputs parametrizados — nunca concatenação de strings
- Incluir lógica de rollback em cada migração

A linha globs no topo é o gatilho. Quando o Claude lê ou edita qualquer ficheiro que corresponda a esse padrão, a rule carrega automaticamente. Sem tokens extra desperdiçados quando não é relevante.

Veja o que construiu

Eis como o seu projeto deve ficar agora:

seu-projeto/
├── CLAUDE.md                          # O briefing do seu projeto
├── .claude/
│   ├── settings.json                  # Permissões (commitado, partilhado com a equipa)
│   └── rules/
│       ├── frontend.md                # Ativa para .tsx, .jsx, .css
│       └── database.md                # Ativa para .sql, migrações
├── .gitignore
└── src/
    └── ...

Mais uma coisa — acrescente esta linha ao seu .gitignore:

# Definições locais do Claude Code
.claude/settings.local.json

Esse ficheiro settings.local.json é para preferências pessoais (como o seu modelo preferido). Não deve estar no controlo de versões. O settings.json normal? Faça commit — é configuração de equipa partilhada.

Verificar que tudo funciona

Abra o Claude Code e experimente isto:

> Lê o meu CLAUDE.md e diz-me que projeto é este. Que rules vês?

O Claude deve descrever o seu projeto, listar as rules que encontrou em .claude/rules/, e confirmar as permissões do settings.json. Se conseguir, está feito. Se algo faltar, verifique que os ficheiros estão nos sítios certos.

Também pode avaliar o seu setup com o nosso analisador — verifica as quatro camadas (CLAUDE.md, definições, rules, estrutura de diretórios) e diz-lhe exatamente o que está a funcionar e o que falta.

Os erros que arrastam os setups para baixo

Depois de rever centenas de setups, estes são os padrões que consistentemente pontuam baixo:

Instruções vagas. "Escreve código limpo" e "segue boas práticas" dão ao Claude zero informação útil. Compare: "valida entradas corretamente" (inútil) vs "Usa zod para toda a validação de entrada da API" (acionável).

Sem lista de permissões. Cada chamada de ferramenta requer aprovação manual, o programador fica frustrado, abandona o Claude Code, e conclui que não é produtivo. Cinco minutos de settings.json evitam isto completamente.

Tudo enfiado no CLAUDE.md. As suas convenções de base de dados não importam quando o Claude está a editar CSS. Mova instruções específicas de ficheiros para ficheiros rules — mantêm o contexto focado e poupam tokens.

Sem secção de arquitetura. Sem mapa de ficheiros, o Claude põe ficheiros nos diretórios errados, usa caminhos de import incorretos, e gera código que não encaixa no seu projeto. Uma secção de arquitetura de 5 linhas evita isto.

Sem .gitignore para definições locais. Membros da equipa sobrepõem preferências uns dos outros, ou pior, chaves de API acabam no controlo de versões.

Próximos passos

Tem uma base sólida. O seu CLAUDE.md conta ao Claude sobre o seu projeto, as suas definições mantêm-no produtivo, e as suas rules mantêm-no no caminho certo.

Pronto para mais? Aqui está para onde ir:

• Automatizar as coisas chatas — hooks que formatam código automaticamente, skills que executam workflows multi-passo com um comando slash, e quando usar qual
• Ligar o Claude às suas ferramentas — servidores MCP que permitem ao Claude consultar a sua base de dados, pesquisar issues no GitHub, e puxar erros do Sentry diretamente
• Manter a fatura sob controlo — números de custos reais, o truque do /compact, e quando o Opus vale o premium

Perguntas frequentes

Onde deve ficar o CLAUDE.md — na raiz do projeto ou no diretório .claude?

Na raiz do projeto. O Claude Code procura CLAUDE.md primeiro na raiz do diretório de trabalho. Também pode criar ~/.claude/CLAUDE.md para instruções globais que se aplicam a todos os seus projetos. Se ambos existirem, ambos são carregados — o global primeiro, depois o específico do projeto.

A equipa toda pode partilhar um CLAUDE.md?

Sim, e devem. O CLAUDE.md pertence ao repositório. É contexto partilhado — arquitetura do projeto, convenções, comandos. Para preferências pessoais (como o modelo que prefere ou aliases personalizados), use .claude/settings.local.json que fica gitignored.

Qual deve ser o tamanho do CLAUDE.md?

Os melhores setups que analisámos têm entre 100 e 500 linhas. Abaixo de 100 significa que provavelmente falta contexto crítico (arquitetura, convenções, problemas conhecidos). Acima de 500 significa que provavelmente inclui informação que pertence a ficheiros rules. O objetivo são instruções focadas e de alto sinal.

O Claude Code funciona sem nada disto?

Tecnicamente sim, mas mal. Sem CLAUDE.md, o Claude não tem conhecimento da estrutura do seu projeto, convenções ou restrições. Continua a gerar código, mas põe ficheiros nos sítios errados, usa padrões incorretos e ignora as regras específicas do seu projeto. Os nossos dados mostram que setups sem configuração têm pontuação média de 1,8/10. A configuração não é opcional se quer ganhos reais de produtividade.

Com que frequência devo atualizar o CLAUDE.md?

Sempre que o projeto muda: novas convenções, novas ferramentas, novos problemas conhecidos. Um bom hábito é acrescentar um item em "Problemas Conhecidos" sempre que o Claude comete um erro que não deveria acontecer de novo. Com o tempo, o CLAUDE.md torna-se um documento vivo que evita os mesmos erros de se repetirem — e esse é um dos usos de maior valor do ficheiro.