Por que o seu Claude Code é pior que o de todo mundo

A maioria das pessoas que usa Claude Code nunca abriu essa pasta.

Sabe que ela existe. Viu aparecer na raiz do projeto. Ignorou.

Isso é erro de iniciante disfarçado de pressa. A .claude/ não é metadado de ferramenta é onde você define como o Claude se comporta. Quem entende isso tem um assistente calibrado. Quem ignora fica repetindo instrução em toda sessão.

Dois diretórios, não um

Antes de qualquer coisa: existem duas pastas .claude/, não uma.

A do projeto vive na raiz do repositório. É commitada. Todo o time herda as mesmas regras, comandos e políticas de permissão.

A global vive em ~/.claude/. É sua. Preferências pessoais, histórico de sessões, memória automática.

Entender essa distinção resolve metade das confusões sobre “por que o Claude se comporta diferente em projetos diferentes.”

CLAUDE.md: o arquivo que mais importa

Quando você inicia uma sessão, o Claude lê o CLAUDE.md primeiro. Ele vai direto pro system prompt e fica lá durante toda a conversa.

O que você escreve aqui, ele segue.

Sem truque. Sem API especial. É contexto injetado, e contexto injetado no início da conversa tem peso real.

O que colocar:

• –Comandos de build, test e lint
• –Decisões arquiteturais não óbvias
• –Armadilhas do projeto (”TypeScript strict mode ativo, variáveis não usadas são erro”)
• –Convenções de import, naming, tratamento de erro
• –Estrutura de pastas dos módulos principais

O que não colocar:

• –Configuração que já existe em linter/formatter
• –Documentação que você pode linkar
• –Parágrafos longos explicando teoria

Limite: 200 linhas. Acima disso, o Claude começa a perder aderência às instruções. Contexto tem custo.

Exemplo funcional:

# Acme API

## Comandos
npm run dev      # Dev server
npm run test     # Jest
npm run lint     # ESLint + Prettier
npm run build    # Build de produção

## Arquitetura
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- Handlers em src/handlers/
- Tipos compartilhados em src/types/

## Convenções
- Zod para validação de request em todo handler
- Retorno sempre { data, error }
- Nunca expor stack trace pro cliente
- Usar módulo logger, não console.log

## Cuidado
- Testes usam DB local real, não mock. Rodar `npm run db:test:reset` antes
- TypeScript strict: sem imports não usados, nunca

20 linhas. Claude tem o que precisa.

CLAUDE.local.md: suas preferências sem contaminar o time

Preferência pessoal que não é do projeto vai aqui. Automaticamente no .gitignore. Ninguém mais vê.

rules/: instruções modulares que escalam

Quando o CLAUDE.md começa a ficar com 300 linhas que ninguém mantém e vai chegar lá, é hora de fragmentar.

Cada arquivo .md dentro de .claude/rules/ é carregado automaticamente junto com o CLAUDE.md:

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

O poder real está no escopo por path. Com frontmatter YAML, uma regra só ativa quando o Claude está trabalhando em arquivos específicos:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# Regras de API

- Handlers retornam { data, error }
- Zod para validação de body
- Nunca expor detalhes internos de erro pro cliente

Editando um componente React? Essa regra não carrega. Só ativa dentro de src/api/ e src/handlers/. Regras sem paths carregam em toda sessão.

Quando o CLAUDE.md começa a inchar, é aqui que você migra.

commands/: seus comandos customizados

Todo arquivo .md dentro de .claude/commands/ vira um slash command.

review.md → /project:review fix-issue.md → /project:fix-issue

Exemplo direto.claude/commands/review.md:

---
description: Revisar diff da branch antes de mergear
---
## Arquivos alterados

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

## Diff completo

!`git diff main...HEAD`

Revisar as mudanças acima em:
1. Qualidade de código
2. Vulnerabilidades de segurança
3. Cobertura de teste faltando
4. Problemas de performance

Feedback específico e acionável por arquivo.

A sintaxe !`` `` ` ` `` executa shell e injeta o output antes do Claude processar. É isso que faz commands serem úteis de verdade, não só texto salvo.

Passando argumentos:

---
description: Investigar e corrigir issue do GitHub
argument-hint: [número-do-issue]
---
Olhar a issue #$ARGUMENTS nesse repo.

!`gh issue view $ARGUMENTS`

Entender o bug, rastrear a causa raiz, corrigir, e escrever
um teste que teria capturado isso.

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

Commands pessoais vão em ~/.claude/commands/ e aparecem como /user:nome-do-command em qualquer projeto.

skills/: workflows que o Claude invoca sozinho

A diferença entre commands e skills é o gatilho.

Command: você digita o slash. Skill: o Claude lê a conversa, reconhece que o momento bate com a descrição da skill, e invoca sozinho.

Estrutura:

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

O SKILL.md usa frontmatter para descrever quando usar:

---
name: security-review
description: Auditoria de segurança. Usar ao revisar código para
  vulnerabilidades, antes de deploys, ou quando segurança é mencionada.
allowed-tools: Read, Grep, Glob
---
Analisar o codebase para vulnerabilidades:

1. SQL injection e XSS
2. Credenciais expostas
3. Configurações inseguras
4. Gaps em autenticação e autorização

Relatório com severidade e passos específicos de remediação.
Referência @GUIA_DETALHADO.md para nossos padrões.

Skills podem empacotar arquivos de suporte. O @GUIA_DETALHADO.md é puxado automaticamente por estar na mesma pasta.

Skills pessoais em ~/.claude/skills/ - disponíveis em todos os projetos.

agents/: subagentes especializados

Quando uma tarefa é complexa o suficiente para precisar de um especialista dedicado, você define um subagente em .claude/agents/.

.claude/agents/
├── code-reviewer.md
└── security-auditor.md

Exemplo: code-reviewer.md:

---
name: code-reviewer
description: Revisor de código experiente. Usar PROATIVAMENTE ao revisar
  PRs, verificar bugs, ou validar implementações antes de mergear.
model: sonnet
tools: Read, Grep, Glob
---
Você é um revisor sênior focado em corretude e manutenibilidade.

Ao revisar:
- Sinalizar bugs, não só estilo
- Sugerir correções específicas, não melhorias vagas
- Verificar edge cases e gaps no tratamento de erro
- Levantar problemas de performance só quando importam em escala

O Claude spawna esse agente em uma context window isolada. O agente trabalha, comprime os achados, reporta de volta. Sua sessão principal não fica soterrada com milhares de tokens de exploração intermediária.

O campo tools restringe o que o agente pode fazer. Um auditor de segurança só precisa de Read, Grep e Glob. Sem escrita. A restrição é intencional.

O campo model deixa você usar um modelo mais barato em tarefas focadas. Haiku resolve a maioria das explorações read-only. Guarda Sonnet e Opus para o que realmente precisa.

Agentes pessoais em ~/.claude/agents/.

settings.json: permissões e o que o Claude pode ou não fazer

{
  "$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.*)"
    ]
  }
}

allow → roda sem pedir confirmação. deny → bloqueado completamente, sem negociação. Fora das duas listas → o Claude pergunta antes.

O meio-termo é intencional. Você não precisa antecipar todo comando possível. Só bloquear o destrutivo e liberar o rotineiro.

settings.local.json para overrides pessoais que não vão pro repo.

~/.claude/: sua camada global

~/.claude/CLAUDE.md carrega em toda sessão, em todos os projetos. Seus princípios pessoais de código, padrões que você quer em qualquer codebase.

~/.claude/projects/ transcrições de sessão e auto-memória por projeto. O Claude salva notas para si mesmo conforme trabalha: comandos que descobriu, padrões que observou, insights de arquitetura. Persistem entre sessões. Você gerencia com /memory.

Você raramente precisa tocar nisso manualmente. Mas saber que existe explica por que o Claude “lembra” de coisas que você nunca disse diretamente.

A estrutura completa

seu-projeto/
├── CLAUDE.md                  # Instruções do time (commitado)
├── CLAUDE.local.md            # Seus overrides pessoais (gitignored)
│
└── .claude/
    ├── settings.json          # Permissões + config (commitado)
    ├── settings.local.json    # Overrides pessoais (gitignored)
    │
    ├── commands/              # Slash commands customizados
    │   ├── review.md          # → /project:review
    │   ├── fix-issue.md       # → /project:fix-issue
    │   └── deploy.md          # → /project:deploy
    │
    ├── rules/                 # Instruções modulares
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/                # Workflows auto-invocados
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # Subagentes especializados
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                  # Suas instruções globais
├── settings.json              # Suas configurações globais
├── commands/                  # Seus commands pessoais
├── skills/                    # Suas skills pessoais
├── agents/                    # Seus agentes pessoais
└── projects/                  # Histórico + auto-memória

Por onde começar

1. Rode /init dentro do Claude Code. Ele gera um CLAUDE.md starter lendo seu projeto. Edite até o essencial.

2. Adicione .claude/settings.json com allow/deny apropriados pro seu stack. No mínimo: libera seus comandos de run, bloqueia leitura de .env.

3. Crie um ou dois commands para os workflows que você mais repete. Code review e fix de issue são bons pontos de entrada.

4. Quando o CLAUDE.md começar a inchar, fragmente em .claude/rules/. Escopeia por path onde fizer sentido.

5. Adicione ~/.claude/CLAUDE.md com suas preferências pessoais. “Sempre escrever tipos antes de implementação.” “Preferir padrões funcionais sobre class-based.” O que for seu.

Skills e agents entram quando você tem workflows complexos recorrentes que valem a pena empacotar.

A pasta .claude/ é um protocolo para dizer ao Claude quem você é, o que seu projeto faz e quais regras ele deve seguir.

CLAUDE.md é onde começa. Tudo o mais é otimização.

Configure uma vez, refine conforme cresce, trate como infraestrutura porque é o que é. Sente que está ficando para trás? Clique no botão abaixo e veja como se reposicionar nesse novo mercado.

Blainer Costa Product Designer e especialista em IA. Fundador da AI Creators Brazil.