Pasta .claude/: Domine md, Skills e Comandos Personalizados

Um guia completo sobre CLAUDE.md, comandos personalizados, habilidades (skills), agentes e permissões, e como configurá-los adequadamente. Conheça a Anatomia da pasta .claude/

A maioria dos usuários do Claude Code trata a pasta .claude como uma caixa preta. Eles sabem que ela existe. Eles a viram aparecer na raiz do projeto. Mas eles nunca a abriram, muito menos entenderam o que cada arquivo dentro dela faz.

Isso é uma oportunidade perdida.

A pasta .claude é o centro de controle de como o Claude se comporta no seu projeto. Ela guarda suas instruções, seus comandos personalizados, suas regras de permissão e até a memória do Claude através das sessões. Uma vez que você entenda o que vive onde e por quê, pode configurar o Claude Code para se comportar exatamente da maneira que sua equipe precisa.

Este guia percorre toda a anatomia da pasta, desde os arquivos que você usará diariamente até aqueles que você configurará uma vez e esquecerá.

Dois pastas, não uma

Antes de mergulhar, vale a pena saber algo antecipadamente: na verdade, existem dois diretórios .claude, não um. O primeiro vive dentro do seu projeto e o segundo vive no seu diretório home:

• A pasta ao nível do projeto segura a configuração da equipe. Você a envia para o git. Todos na equipe recebem as mesmas regras, os mesmos comandos personalizados e as mesmas políticas de permissão.

• A pasta global ~/.claude/ segura suas preferências pessoais e o estado local da máquina, como histórico de sessões e auto-memória.

CLAUDE.md: O manual de instruções do Claude

Este é o arquivo mais importante em todo o sistema. Quando você inicia uma sessão do Claude Code, a primeira coisa que ele lê é o CLAUDE.md. Ele o carrega diretamente no prompt do sistema e o mantém em mente durante toda a conversa.

Simplificando: o que quer que você escreva no CLAUDE.md, o Claude seguirá.

• Se você disser ao Claude para sempre escrever testes antes da implementação, ele o fará.

• Se você disser “nunca use console.log para tratamento de erros, use sempre o módulo de logger personalizado”, ele respeitará isso todas as vezes.

Um CLAUDE.md na raiz do seu projeto é a configuração mais comum. Mas você também pode ter um em ~/.claude/CLAUDE.md para preferências globais que se aplicam a todos os projetos, e até mesmo um dentro de subdiretórios para regras específicas de pastas. O Claude lê todos eles e os combina.

O que realmente pertence ao CLAUDE.md

A maioria das pessoas escreve demais ou de menos. Aqui está o que funciona.

Escreva:

• Comandos de build, teste e lint (npm run test, make build, etc.)

• Decisões arquiteturais fundamentais (“usamos um monorepo com Turborepo”)

• “Gotchas” não óbvios (“O modo estrito do TypeScript está ativado, variáveis não utilizadas são erros”)

• Convenções de importação, padrões de nomenclatura, estilos de tratamento de erro

• Estrutura de arquivos e pastas para os módulos principais

Não escreva:

• Qualquer coisa que pertença a uma configuração de linter ou formatador

• Documentação completa que você já pode linkar

• Parágrafos longos explicando teoria

Mantenha o CLAUDE.md abaixo de 200 linhas. Arquivos mais longos que isso começam a consumir muito contexto e a adesão do Claude às instruções realmente cai.

Aqui está um exemplo minimalista mas eficaz:

# Project: Acme API

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Jest)
npm run lint         # ESLint + Prettier check
npm run build        # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

Isso tem aproximadamente 20 linhas. Dá ao Claude tudo o que ele precisa para trabalhar produtivamente neste código sem clarificações constantes.

CLAUDE.local.md para sobreposições pessoais

Às vezes você tem uma preferência que é específica para você, não para toda a equipe. Talvez você prefira um executor de testes diferente, ou queira que o Claude sempre abra arquivos usando um padrão específico.

Crie o CLAUDE.local.md na raiz do seu projeto. O Claude o lê junto com o CLAUDE.md principal, e ele é automaticamente ignorado pelo git para que seus ajustes pessoais nunca parem no repositório.

A pasta rules/: instruções modulares que escalam

O CLAUDE.md funciona muito bem para um projeto único. Mas uma vez que sua equipe cresce, você acaba com um CLAUDE.md de 300 linhas que ninguém mantém e todos ignoram.

A pasta rules/ resolve isso.

Cada arquivo markdown dentro de .claude/rules/ é carregado junto com seu CLAUDE.md automaticamente. Em vez de um arquivo gigante, você divide as instruções por assunto:

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

Cada arquivo permanece focado e fácil de atualizar. O membro da equipe que cuida das convenções de API edita api-conventions.md. A pessoa dona dos padrões de teste edita testing.md. Ninguém pisa no pé do outro.

O poder real vem das regras com escopo de caminho (path-scoped rules). Adicione um bloco de frontmatter YAML a um arquivo de regra e ele só ativa quando o Claude está trabalhando com arquivos correspondentes:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules

- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

O Claude não carregará este arquivo quando estiver editando um componente React. Ele só carrega quando está trabalhando dentro de src/api/ ou src/handlers/. Regras sem um campo paths carregam incondicionalmente, em cada sessão.

A pasta commands/: seus comandos slash personalizados

Fora da caixa, o Claude Code tem comandos slash integrados como /help e /compact. A pasta commands/ permite que você adicione os seus próprios.

Cada arquivo markdown que você solta em .claude/commands/ torna-se um comando slash.

Um arquivo chamado review.md cria /project:review. Um arquivo chamado fix-issue.md cria /project:fix-issue. O nome do arquivo é o nome do comando.

Aqui está um exemplo simples. Crie .claude/commands/review.md:

---
description: Review the current branch diff for issues before merging
---
## Changes to Review

!`git diff --name-only main...HEAD`

## Detailed Diff

!`git diff main...HEAD`

Review the above changes for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance concerns

Give specific, actionable feedback per file.

Agora execute /project:review no Claude Code e ele injeta automaticamente o diff real do git no prompt antes de o Claude vê-lo. A sintaxe ! com crases executa comandos shell e incorpora a saída. Isso é o que torna esses comandos genuinamente úteis em vez de apenas texto salvo.

Passando argumentos para comandos

Use $ARGUMENTS para passar texto após o nome do comando:

---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS in this repo.

!`gh issue view $ARGUMENTS`

Understand the bug, trace it to the root cause, fix it, and write a
test that would have caught it.

Rodar /project:fix-issue 234 alimenta o conteúdo da issue 234 diretamente no prompt.

Comandos pessoais vs. de projeto

Comandos de projeto em .claude/commands/ são commitados e compartilhados com sua equipe. Para comandos que você quer em todos os lugares independentemente do projeto, coloque-os em ~/.claude/commands/. Esses aparecem como /user:nome-do-comando.

Habilidades (skills/): fluxos de trabalho reutilizáveis sob demanda

Você agora sabe como os comandos funcionam. Habilidades parecem similares na superfície, mas o gatilho é fundamentalmente diferente. Aqui está a distinção:

Skills são fluxos de trabalho que o Claude pode invocar por conta própria, sem você digitar um comando slash, quando a tarefa corresponde à descrição da habilidade. Comandos esperam por você. Habilidades observam a conversa e agem quando o momento é certo.

Cada habilidade vive em seu próprio subdiretório com um arquivo SKILL.md:

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

O SKILL.md usa frontmatter YAML para descrever quando usá-lo:

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for
  vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

Report findings with severity ratings and specific remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

Quando você diz “revise este PR em busca de problemas de segurança”, o Claude lê a descrição, reconhece que ela combina e invoca a habilidade automaticamente.

A principal diferença dos comandos: as habilidades podem agrupar arquivos de suporte junto com elas. A referência @DETAILED_GUIDE.md acima puxa um documento detalhado que vive logo ao lado do SKILL.md. Comandos são arquivos únicos. Habilidades são pacotes.

Agentes (agents/): personas de subagentes especializados

Quando uma tarefa é complexa o suficiente para se beneficiar de um especialista dedicado, você pode definir uma persona de subagente em .claude/agents/. Cada agente é um arquivo markdown com seu próprio prompt de sistema, acesso a ferramentas e preferência de modelo.

Exemplo de code-reviewer.md:

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
  checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer with a focus on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scale

Quando o Claude precisa de uma revisão de código, ele gera este agente em sua própria janela de contexto isolada. O agente faz seu trabalho, comprime as descobertas e reporta de volta. Sua sessão principal não fica entulhada com milhares de tokens de exploração intermediária.

settings.json: permissões e configuração do projeto

O arquivo settings.json dentro de .claude/ controla o que o Claude tem e não tem permissão para fazer. É onde você define quais ferramentas o Claude pode rodar, quais arquivos pode ler e se ele precisa perguntar antes de executar certos comandos.

O arquivo completo se parece com isto:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

A linha $schema habilita o preenchimento automático e validação inline no VS Code ou Cursor. A lista allow contém comandos que rodam sem o Claude pedir confirmação. A lista deny contém comandos que são bloqueados inteiramente. Se algo não estiver em nenhuma das listas, o Claude pergunta antes de prosseguir.

A pasta global ~/.claude/

Você não interage com esta pasta frequentemente, mas é útil saber o que há nela.

• ~/.claude/CLAUDE.md carrega em cada sessão do Claude Code, em todos os seus projetos. Bom lugar para seus princípios de codificação pessoais ou estilo preferido.

• ~/.claude/projects/ armazena transcrições de sessões e auto-memória por projeto. O Claude Code salva notas automaticamente conforme trabalha: comandos que descobre, padrões que observa, insights de arquitetura. Estes persistem entre sessões. Você pode navegar e editá-los com /memory.

• ~/.claude/commands/ e ~/.claude/skills/ seguram comandos e habilidades pessoais disponíveis em todos os projetos.

Uma configuração prática para começar

Se você está começando do zero, aqui está uma progressão que funciona bem:

1. Passo 1. Execute /init dentro do Claude Code. Ele gera um CLAUDE.md inicial ao ler seu projeto. Edite-o para o essencial.

2. Passo 2. Adicione .claude/settings.json com regras de allow/deny apropriadas para sua stack. No mínimo, permita seus comandos de execução e negue leituras de .env.

3. Passo 3. Crie um ou dois comandos para os fluxos de trabalho que você mais faz. Revisão de código e correção de issues são bons pontos de partida.

4. Passo 4. Conforme seu projeto cresce e seu CLAUDE.md fica lotado, comece a dividir as instruções em arquivos .claude/rules/. Escope-os por caminho onde fizer sentido.

5. Passo 5. Adicione um ~/.claude/CLAUDE.md com suas preferências pessoais.

A ideia central

A pasta .claude é realmente um protocolo para dizer ao Claude quem você é, o que seu projeto faz e quais regras ele deve seguir. O CLAUDE.md é seu arquivo de maior alavancagem. Acerte nele primeiro. Tudo o mais é otimização.

• Google Stitch: Crie Interfaces Incríveis com IA em Minutos

• 50 Dicas do Claude Code: Melhores Práticas para Usar Todo Dia

• Chrome DevTools MCP: Guia para Agentes de IA Autônomos