A maioria dos utilizadores do Claude Code conhece
.claude/
a existência da pasta, mas nunca a abriu realmente. O engenheiro de IA Akshay preparou recentemente um guia completo, analisando a função de cada arquivo nesta pasta e como configurá-la para que o Claude trabalhe exatamente à sua maneira.
Duas pastas, não uma
Primeiro, é importante esclarecer um equívoco comum:
A pasta .claude/
existe em duas versões, não uma.
Nível de projeto (seu projeto/.claude/): armazena configurações compartilhadas pela equipa, submetidas ao Git, garantindo regras e comandos consistentes para todos.
Nível global (~/.claude/): preferências pessoais e configurações entre projetos, que afetam apenas a sua máquina.
CLAUDE.md: o arquivo mais importante
Sempre que inicia uma sessão de trabalho no Claude Code, o Claude primeiro lê
CLAUDE.md
e o carrega como prompt do sistema (system prompt), mantendo-se a cumprir as instruções nele contidas durante toda a conversa.
Conteúdo recomendado para incluir:
Comandos de build, teste, lint (como npm run test)
Decisões arquitetónicas importantes
Notas não óbvias (por exemplo, “TypeScript strict mode ativado, variáveis não utilizadas irão gerar erro”)
Normas de nomenclatura, estilos de tratamento de erros
O que não deve ser incluído: regras de configuração do linter, documentos completos, explicações teóricas longas.
Akshay recomenda manter o CLAUDE.md com até 200 linhas — além disso, a taxa de cumprimento das instruções pelo Claude diminui, pois consome demasiado contexto.
pasta rules/ : comandos modularizados, ideais para expansão em equipa
À medida que o CLAUDE.md fica mais extenso,
.claude/rules/
é a solução. Cada arquivo Markdown representa um ponto de atenção, como code-style.md, testing.md, api-conventions.md, e o Claude lê automaticamente todos esses arquivos.
Mais avançado ainda é o “regra de escopo por caminho”: ao adicionar metadados YAML no início de cada arquivo de regra, é possível fazer com que as regras só sejam carregadas ao processar ficheiros em caminhos específicos, evitando que regras irrelevantes ocupem o contexto.
pasta commands/ : comandos personalizados com barra
Cada arquivo Markdown em
.claude/commands/
se torna um comando com barra. review.md corresponde a /project:review, fix-issue.md a /project:fix-issue.
A funcionalidade mais prática é usar
!
na definição do comando para executar comandos shell e incorporar a saída — por exemplo, obter automaticamente o diff do git e inseri-lo no prompt, permitindo que o Claude “veja” realmente as alterações no código. Comandos pessoais em ~/.claude/commands/ podem ser usados em todos os projetos.
skills/ e agents/ : disparar automaticamente vs. definir sub-agentes
A principal diferença entre Skills e agents está na forma de ativação:
Skills: o Claude decide automaticamente, com base na conversa, se deve chamar uma skill, sem necessidade de comandos manuais. Cada skill tem seu próprio diretório e um arquivo SKILL.md, podendo incluir ficheiros de suporte.
Agents: definem personalidades de sub-agentes especializados, com prompts, permissões de ferramentas e configurações de modelo independentes. Para tarefas complexas, o Claude pode spawnar uma janela de contexto isolada para o agente executar, evitando encher o contexto principal com tokens.
Na secção
tools
dos agents,
tools
limita o comportamento do sub-agente — por exemplo, um agente de auditoria de segurança só precisa de permissões de leitura, sem capacidade de escrita. A opção model permite escolher um modelo mais leve para tarefas específicas, economizando custos.
settings.json: listas de permissões brancas e pretas
A configuração
.claude/settings.json
controla as ações permitidas ou proibidas ao Claude:
allow (lista branca): ações que podem ser executadas sem confirmação (exemplo: npm run *, git *)
deny (lista negra): ações completamente bloqueadas (exemplo: rm -rf *, leitura de .env)
Operações fora das listas: o Claude perguntará se deve continuar.
Configurações pessoais podem ser colocadas em
.claude/settings.local.json
, que é automaticamente ignorada pelo git e não será submetida ao repositório.
Por onde começar?
A recomendação prática de Akshay é: primeiro, executar
/init
para gerar o CLAUDE.md inicial, configurar o settings.json com permissões básicas, e criar uma ou duas comandos personalizados mais usados — o restante pode ser adicionado gradualmente à medida que o uso evolui.
A ideia principal é:
A pasta .claude/
é o seu contrato com o Claude: quem você é, qual é o projeto, e quais regras deve seguir. Quanto mais bem configurada, menos tempo será gasto a corrigir o Claude.
Este artigo explica tudo sobre a pasta .claude/: o centro de controlo do Claude Code, com análise completa do CLAUDE.md, comandos, skills e permissões. Publicado originalmente na ABMedia.
