Configuração do Claude Code

Problema: As sessões novas do Claude Code dão respostas genéricas porque não sabem nada sobre o teu projeto.

Vitória Rápida: Coloca um CLAUDE.md na raiz do teu projeto e a próxima sessão lê-o antes de escreveres uma palavra.

Resultado: As respostas deixam de soar como um tutorial genérico e começam a corresponder à tua stack real.

Três ficheiros fazem a maior parte do trabalho. O CLAUDE.md dá contexto ao Claude. Os servidores MCP dão-lhe ferramentas. Os comandos slash dão-lhe fluxos de trabalho. Configura uma vez, reutiliza em todo o lado.

Criar os Ficheiros de Configuração

Dois comandos para começar:

touch CLAUDE.md                    # Raiz do projeto - obrigatório
mkdir -p .claude/commands          # Fluxos de trabalho personalizados - opcional

É o esqueleto completo. Agora preenche-o.

CLAUDE.md (Obrigatório)

Coloca este ficheiro na raiz do projeto. O Claude lê-o no início de cada sessão:

# [Project Name] - Development Context

## What This Project Does

[2-sentence description of your app's purpose]

## Tech Stack & Version

- Frontend: React 18.2.0 with TypeScript 5.0
- Backend: Node.js with Express or Next.js App Router
- Database: PostgreSQL 15 with Prisma ORM
- Styling: Tailwind CSS 3.4

## File Structure

src/
├── app/ # Next.js pages (App Router)
├── components/ # Reusable UI components
├── lib/ # Utilities and configurations
└── types/ # TypeScript definitions

## Current Sprint Goals
- [ ] User authentication system
- [ ] Dashboard with user data
- [ ] API endpoints for CRUD operations

## Never Touch Without Permission
- package.json dependencies (ask first)
- Database migrations (explain changes)
- Production environment variables

Verificação de Sucesso: O Claude menciona a tua stack e os objetivos do sprint na próxima resposta, sem ser pedido.

Servidores MCP (Funcionalidades Avançadas)

Os servidores MCP (Model Context Protocol) adicionam ferramentas reais ao Claude. Coloca-os nas tuas definições globais em ~/.claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {
        "ACCESS_DIRECTORIES": "/Users/yourname/projects"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

O que isso te dá:

• Leitura e escrita direta de ficheiros
• Pesquisa em repositórios GitHub
• Acesso à documentação do projeto
• Reconhecimento de padrões no teu código

Verificação de Sucesso: O Claude já consegue abrir ficheiros e aceder ao GitHub sem precisares de colar nada.

Comandos Slash (Fluxos de Trabalho Reutilizáveis)

Qualquer ficheiro markdown em .claude/commands/ torna-se um comando slash. Dás nome ao ficheiro e ganhas o comando de graça.

Fluxo de Depuração (.claude/commands/debug.md):

# Debug Workflow

When debugging:

1. Reproduce the error in isolation
2. Check browser console and network tab
3. Add console.logs to trace execution
4. Test with minimal data
5. Check recent changes in git log
6. Ask before suggesting major architecture changes

Geração de Testes (.claude/commands/test.md):

# Test Generation Guidelines

For new functions:

1. Write unit tests with Jest/Vitest
2. Test happy path and edge cases
3. Mock external dependencies
4. Use descriptive test names
5. Aim for 80% coverage on critical paths

Utilização: Escreve /debug ou /test em qualquer sessão e o Claude executa o fluxo de trabalho.

Verificação de Sucesso: O Claude segue sempre os mesmos passos documentados.

Correções de Configuração Comuns

Quando o CLAUDE.md ficar pesado, divide-o. Mantém o ficheiro raiz curto e aponta para o resto:

# Main CLAUDE.md (keep short)

See also:

- .claude/database-schema.md (detailed schema)
- .claude/api-patterns.md (endpoint conventions)

O Sistema de Âmbitos do settings.json

Para além do CLAUDE.md, o Claude Code usa ficheiros settings.json para permissões, variáveis de ambiente, modelos padrão e comportamento de ferramentas. Quatro âmbitos acumulam-se, e o mais específico ganha:

Precedência, de cima para baixo: Gerido > Argumentos da linha de comandos > Local > Projeto > Utilizador. As definições geridas ganham sempre, para que a política da empresa seja sempre respeitada.

Adiciona $schema no topo do teu settings.json e o VS Code, Cursor, ou qualquer editor com suporte a JSON schema vai completar automaticamente e validar enquanto escreves:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

O Claude Code também regista cada edição de definições com timestamp e mantém as cinco cópias de segurança mais recentes, por isso uma gravação errada não te custa nada.

Categorias Principais de Definições

Cada categoria tem o seu próprio guia dedicado. Versão resumida:

• Permissões. Controla quais ferramentas o Claude usa, quais ficheiros lê, quais comandos executa. As regras ficam em allow, deny e ask.
• Sandbox. Isola comandos bash do teu sistema de ficheiros e rede, aplicado ao nível do OS. Ativa com /sandbox ou sandbox.enabled.
• Atribuição. Mantém ou remove o trailer Co-Authored-By em commits e PRs. Commits e PRs configuram-se separadamente.
• Plugins. Integra skills, agentes, hooks e servidores MCP de marketplaces. Controlado por enabledPlugins e extraKnownMarketplaces.
• Modelo. Define um padrão via a chave model em vez de passar --model sempre.
• Linha de Estado. Coloca uso de contexto em tempo real, ramo git, nome do modelo ou custo numa barra persistente.
• Atalhos de Teclado. Reconfigura teclas com /keybindings, que escreve em ~/.claude/keybindings.json.

Variáveis de Ambiente Essenciais

As variáveis de ambiente dão-te o controlo mais fino sobre o Claude Code. Define-as no teu perfil do shell, passa-as inline, ou coloca-as dentro da chave env no settings.json. As que valem a pena conhecer:

Três formas de as aplicar. Inline para uma sessão única:

ANTHROPIC_MODEL=claude-sonnet-4-20250514 claude

Persistente, adicionando a ~/.bashrc ou ~/.zshrc:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80
export MAX_THINKING_TOKENS=10000

Ou incorpora-as no settings.json para que se apliquem em cada execução:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
    "MAX_THINKING_TOKENS": "10000"
  }
}

Existem cerca de 70 variáveis de ambiente. A referência de definições tem a lista completa, e o guia de configuração do terminal cobre quebras de linha e notificações.

Configuração Global vs. de Projeto

Definições Globais (~/.claude/settings.json):

• Configurações de servidores MCP
• Preferências pessoais e modelos padrão
• Padrões de código universais

Definições de Projeto (raiz do projeto):

• CLAUDE.md. Contexto e regras do projeto.
• .claude/commands/. Comandos slash personalizados.
• .claude/settings.json. Permissões partilhadas pela equipa, hooks e servidores MCP.
• .claude/settings.local.json. As tuas substituições pessoais para este projeto (no gitignore).

Precedência resumida: Gerido > Local > Projeto > Utilizador. Executa /init e o Claude escreve um CLAUDE.md inicial por ti.

A trabalhar num monorepo ou a partilhar padrões entre repos? O flag --add-dir permite ao Claude carregar ficheiros CLAUDE.md de diretórios adicionais.

Próximos Passos

O Claude Code está agora configurado. A partir daqui:

• Constrói o teu primeiro projeto com a configuração definida
• Aprende técnicas de controlo do terminal
• Explora estratégias de gestão de contexto
• Adiciona mais servidores MCP da lista popular
• Consulta o guia de resolução de problemas se algo travar

Dica Pro: Mantém o CLAUDE.md atualizado. A stack muda, as prioridades mudam, os objetivos do sprint rodam. Atualiza o ficheiro quando isso acontecer. O Claude é tão preciso quanto o contexto que lhe forneces.