Claude Code

O que é Claude Code

Claude Code é o CLI oficial da Anthropic — um agente de terminal que entende seu codebase e executa tarefas de engenharia de software via linguagem natural. Diferente de um chat, ele tem ferramentas reais: lê e edita arquivos, roda comandos shell, faz buscas no código, gerencia git, chama APIs externas via MCP.

A arquitetura é agentic: em vez de responder uma mensagem e parar, ele planeja, age, observa o resultado e itera até concluir a tarefa — com aprovação sua nos passos que precisam.

Instalação e Autenticação

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# macOS (Homebrew)
brew install --cask claude-code
brew upgrade claude-code        # não auto-atualiza

# Windows (WinGet)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode

# Autenticação
claude auth login               # Login padrão (claude.ai)
claude auth login --sso         # Força SSO corporativo
claude auth login --console     # Usa Anthropic Console / API Key
claude auth logout
claude auth status              # exit 0 = autenticado, 1 = não autenticado

# CI/CD — token de longa duração
claude setup-token

# Atualização
claude update                   # Atualiza para latest
claude install stable           # Versão estável específica
claude install 2.1.89           # Versão exata

Modos de Uso

Sessão interativa

claude                          # Abre sessão interativa
claude "corrija o bug no auth"  # Inicia com prompt direto
claude -c                       # Continua última conversa desta pasta
claude -r                       # Picker para resumir sessão anterior
claude -r "nome-da-sessao"      # Retoma sessão específica pelo nome
claude -n "minha-sessao"        # Inicia nomeando a sessão

Modo não-interativo (-p / --print)

Ideal para scripts, CI/CD e pipelines. Executa, imprime e sai.

claude -p "o que faz este arquivo?"
cat src/auth.ts | claude -p "encontre vulnerabilidades"
claude -c -p "adicione testes para o código que discutimos"

# Formatos de output
claude -p "query" --output-format text          # padrão
claude -p "query" --output-format json          # machine-readable
claude -p "query" --output-format stream-json   # streaming

# Controle de execução
claude -p "query" --max-turns 3
claude -p "query" --max-budget-usd 2.00
claude -p "query" --no-session-persistence

Flags da CLI

Modelo e performance

--model claude-sonnet-4-6       # Modelo específico
--model claude-opus-4-7
--effort low|medium|high|max    # Nível de esforço / raciocínio
--fallback-model claude-haiku-4-5  # Fallback se modelo sobrecarregado
--betas interleaved-thinking    # Ativar extended thinking

Permissões

--permission-mode default       # Pergunta na primeira vez
--permission-mode acceptEdits   # Auto-aceita edições de arquivo
--permission-mode plan          # Só leitura; mostra plano antes
--permission-mode bypassPermissions  # Pula tudo (só em containers)
--allowedTools "Bash(npm *) Read Edit"
--disallowedTools "Bash(rm *)"

Sistema e contexto

--system-prompt "Seja conciso"
--system-prompt-file ./prompt.txt
--append-system-prompt "Responda em PT-BR"
--add-dir ../shared-lib         # Adiciona pasta ao contexto
--settings ./.claude/custom-settings.json
--mcp-config ./mcp.json
--strict-mcp-config             # Usa APENAS os MCPs do arquivo

Debug

--debug api,hooks               # Categorias: api, hooks, mcp
--debug "!statsig,!file"        # Exclui categorias
--debug-file /tmp/claude.log
--verbose                       # Output turn-a-turn completo

Comandos Slash

Digitados dentro da sessão interativa:

Sessão e contexto

Configuração

Ferramentas de desenvolvimento

Utilitários

Permissões

O sistema de permissões controla o que Claude pode fazer sem pedir aprovação. É a camada de segurança mais importante para uso em automação.

Modos de permissão

Cicle entre eles com Shift+Tab durante a sessão:

Regras de permissão (settings.json)

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git add *)",
      "Read",
      "Edit(src/**/*.ts)",
      "WebFetch(domain:github.com)",
      "mcp__memory__*"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Edit(~/.ssh/**)"
    ],
    "defaultMode": "default"
  }
}

Sintaxe de padrões:

• Bash(npm *) — qualquer comando começando com npm
• Bash(git * main) — git com main no final
• Edit(src/**/*.ts) — editar qualquer .ts dentro de src/
• mcp__servidor__* — todas as ferramentas de um MCP server
• WebFetch(domain:github.com) — fetch apenas neste domínio

Dica: Para CI/CD com acesso irrestrito em ambiente controlado, use --dangerously-skip-permissions. Para produção, prefira uma lista explícita de allow.

settings.json

Existe em múltiplos escopos com precedência crescente:

~/.claude/settings.json              # usuário global
.claude/settings.json                # projeto (commitado)
.claude/settings.local.json          # projeto local (gitignored)
--settings <path>                    # linha de comando (maior prioridade)

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",

  "model": "claude-sonnet-4-6",
  "effortLevel": "high",

  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm run *)", "Read", "Edit"],
    "deny": ["Bash(rm -rf *)"]
  },

  "autoMemoryEnabled": true,

  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },

  "hooks": { },

  "enabledPlugins": {
    "context7@claude-plugins-official": true
  }
}

Hooks

Hooks são scripts ou comandos que o Claude Code executa automaticamente em pontos específicos do ciclo de vida — antes de usar uma ferramenta, depois, ao iniciar a sessão, etc. São a forma de criar validações, logging, bloqueios e automações sem modificar o prompt.

Ciclo de vida

Configuração no settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/validate-bash.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/session-start.sh"
          }
        ]
      }
    ]
  }
}

Tipos de hook

command — executa script shell. Recebe JSON no stdin, comunica via exit code e stdout JSON:

#!/bin/bash
# ~/.claude/hooks/validate-bash.sh
# Bloqueia rm -rf

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

if [[ "$COMMAND" == *"rm -rf"* ]]; then
  echo '{"decision":"block","reason":"rm -rf não permitido"}'
  exit 2   # exit 2 = bloqueia a ação
fi

exit 0     # exit 0 = permite

http — chama endpoint HTTP:

{
  "type": "http",
  "url": "http://localhost:8080/hooks/pre-tool",
  "headers": { "Authorization": "Bearer $TOKEN" },
  "allowedEnvVars": ["TOKEN"]
}

prompt — usa um modelo para validar:

{
  "type": "prompt",
  "prompt": "Este comando é destrutivo? $ARGUMENTS",
  "model": "claude-haiku-4-5-20251001"
}

Output JSON de um hook

{
  "continue": true,
  "decision": "block",
  "reason": "Explicação do bloqueio",
  "suppressOutput": false,
  "systemMessage": "Mensagem adicionada ao contexto"
}

Exemplo: log de todos os comandos Bash

#!/bin/bash
# ~/.claude/hooks/log-bash.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
echo "[$(date)] BASH: $COMMAND" >> ~/.claude/bash-history.log
exit 0

MCP — Model Context Protocol

MCP permite que Claude Code use ferramentas externas: banco de dados, APIs, navegadores, sistemas de arquivos adicionais. É um protocolo padronizado para expor capacidades ao modelo.

Adicionar servidor MCP

# Via CLI
claude mcp add --transport stdio meu-servidor node /path/to/server.js
claude mcp add --transport sse github-mcp https://api.example.com/sse
claude mcp add --transport http mem0 https://mcp.mem0.ai/mcp

# Gerenciar
claude mcp list
claude mcp remove meu-servidor
claude mcp test meu-servidor

Configuração via arquivo

// .claude/mcp.json
{
  "servers": {
    "postgres": {
      "command": "node",
      "args": ["/path/to/postgres-mcp.js"],
      "env": {
        "DATABASE_URL": "$DATABASE_URL"
      }
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

claude --mcp-config ./.claude/mcp.json
claude --mcp-config ./.claude/mcp.json --strict-mcp-config  # só estes MCPs

Permissões de ferramentas MCP

{
  "permissions": {
    "allow": [
      "mcp__postgres__query",
      "mcp__puppeteer__*",
      "mcp__memory__*"
    ],
    "deny": [
      "mcp__postgres__execute_ddl"
    ]
  }
}

Skills (Comandos Customizados)

Skills são comandos / customizados — automações reutilizáveis que encapsulam fluxos de trabalho específicos. Ficam em arquivos SKILL.md.

Localização

~/.claude/skills/<nome>/SKILL.md   # pessoal — disponível em todos os projetos
.claude/skills/<nome>/SKILL.md     # projeto — commitado com o repo

Estrutura de uma skill

---
name: criar-feature
description: Cria uma feature completa com branch, código e PR
argument-hint: "[nome-da-feature]"
arguments: "feature_name"
allowed-tools: "Bash(git *) Bash(gh *) Edit Read Write"
model: sonnet
effort: high
---

Você irá criar uma feature completa para "$feature_name":

1. Crie o branch: !`git checkout -b feature/$feature_name`
2. Implemente o código necessário
3. Escreva os testes
4. Crie o PR: !`gh pr create --title "feat: $feature_name"`

Frontmatter completo

---
name: minha-skill
description: "O que ela faz — usado para trigger automático"
argument-hint: "[arg1] [arg2]"
arguments: "arg1 arg2"              # nomes para $arg1, $arg2
user-invocable: true                # aparece como /minha-skill
allowed-tools: "Bash(npm *) Edit Read"
model: sonnet                       # sonnet, opus, haiku ou inherit
effort: high
context: fork                       # roda em subagent isolado
paths:                              # carrega só esses arquivos no contexto
  - "src/**/*.ts"
  - "tests/**/*.test.ts"
---

Injeção de contexto dinâmico

---
name: check-tests
---

Status atual do projeto:
!`npm test -- --reporter=compact 2>&1 | tail -20`

Versões:
```!
node --version
npm --version

Analise os falhas e corrija.

### Variáveis disponíveis

| Variável | Valor |
|----------|-------|
| `$ARGUMENTS` | Todos os argumentos como string |
| `$0`, `$1`, `$2` | Argumento por índice |
| `$nome` | Argumento nomeado (via frontmatter `arguments`) |
| `${CLAUDE_SESSION_ID}` | ID da sessão atual |
| `${CLAUDE_EFFORT}` | Nível de esforço atual |
| `${CLAUDE_SKILL_DIR}` | Diretório da skill |

---

## Memória e CLAUDE.md

### CLAUDE.md

Arquivo de instruções persistentes que o Claude lê no início de cada sessão. Funciona como um README para o agente — define convenções, restrições, contexto do projeto.

**Hierarquia de carregamento (menor → maior precedência):**

/etc/claude-code/CLAUDE.md # managed (Linux) ~/.claude/CLAUDE.md # usuário global ./CLAUDE.md # projeto raiz ./CLAUDE.local.md # projeto local (gitignored) src/CLAUDE.md # subpasta (carregado se relevante)

**Imports dentro do CLAUDE.md:**

```markdown
@README.md
@docs/arquitetura.md
@~/.claude/regras-pessoais.md

# Max 5 níveis de profundidade recursiva

Regras com escopo por path (frontmatter):

---
paths:
  - "src/api/**/*.ts"
  - "tests/**/*.test.ts"
---

# Estas regras só se aplicam a arquivos TypeScript no src/api/ e tests/

- Sempre usar async/await, nunca callbacks
- Cada função pública deve ter JSDoc

Auto Memory

Sistema de memória persistente em SQLite ou arquivos que o Claude mantém automaticamente entre sessões. Armazena preferências do usuário, contexto de projeto, feedback.

# Desabilitar
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude
# ou no settings.json:
# "autoMemoryEnabled": false

Por padrão fica em ~/.claude/projects/<projeto>/memory/. Os primeiros 200 linhas de MEMORY.md são injetados automaticamente no início de cada sessão.

Atalhos de Teclado

Gerais

Edição (Readline)

Vim Mode ("editorMode": "vim" no settings)

Ativa modo vim no campo de input. Suporta motions (w, b, e, f, t), objetos de texto (iw, i", i(), operadores (d, c, y) e modos (i, a, v, V).

Integração com IDEs

VS Code

code --install-extension anthropic.claude-code

@-Mentions no VS Code:

@arquivo.ts              # arquivo inteiro
@arquivo.ts#10-25        # linhas 10 a 25
@pasta/                  # pasta inteira
@documento.pdf 1-5       # páginas 1 a 5 de PDF

Atalhos no VS Code:

settings.json do VS Code:

{
  "claude-code.useTerminal": false,
  "claude-code.initialPermissionMode": "default",
  "claude-code.preferredLocation": "panel",
  "claude-code.autosave": true,
  "claude-code.respectGitIgnore": true
}

JetBrains (IntelliJ, WebStorm, PyCharm…)

Instale o plugin Claude Code via Marketplace. Funciona da mesma forma que o VS Code com suporte a @-mentions de arquivos abertos no editor.

CI/CD e Automação

Uso em pipelines

# .github/workflows/review.yml
- name: Claude Code Review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude auth login --console
    claude -p "revise o PR e liste problemas críticos" \
      --output-format json \
      --max-turns 5 \
      --no-session-persistence

Modo headless seguro

# Token de longa duração para CI
claude setup-token               # gera token; salve em secrets

# Execução sem prompt de permissão (em container isolado)
claude -p "query" --dangerously-skip-permissions

# Com budget para evitar custos excessivos
claude -p "query" --max-budget-usd 1.00 --max-turns 10

Subagents (delegação paralela)

# Definir agentes customizados dinamicamente
claude --agents '{
  "reviewer": {
    "description": "Revisa código para segurança e performance"
  },
  "tester": {
    "description": "Escreve e roda testes"
  }
}'

Worktrees para paralelismo

# Trabalho paralelo em branches isoladas
claude -w feature-auth           # cria worktree isolado
claude --tmux -w feature-auth    # com sessão tmux separada

Variáveis de Ambiente

ANTHROPIC_API_KEY=sk-...                    # API key (para console auth)
CLAUDE_CODE_DEBUG_LOGS_DIR=/tmp/logs        # Diretório de logs de debug
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1           # Desativa auto memory
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1      # Desativa tasks em background
CLAUDE_CODE_ENABLE_TELEMETRY=1              # Telemetria (habilitada por padrão)
CLAUDE_CODE_SIMPLE=1                        # Modo bare/simples
CLAUDE_CODE_USE_POWERSHELL_TOOL=1           # Força PowerShell no Windows
CLAUDE_CODE_TASK_LIST_ID=meu-projeto        # ID da task list

Diagnóstico e Troubleshooting

# Verificar instalação
claude --doctor
claude auth status
claude --version

# Debug detalhado
claude --debug api,hooks,mcp
claude --debug "!statsig"          # exclui categoria
claude --verbose                   # output completo turn-a-turn
claude --debug-file /tmp/debug.log

# Problemas de terminal
/terminal-setup                    # reconfigura keybindings
CLAUDE_CODE_USE_POWERSHELL_TOOL=1  # Windows PowerShell

Referência Rápida

# Iniciar
claude                             # sessão interativa
claude "prompt"                    # com prompt inicial
claude -c                          # continua última sessão
claude -p "query"                  # não-interativo (script/CI)

# Modelo
claude --model claude-opus-4-7
claude --effort high

# Permissões
claude --permission-mode acceptEdits
claude --allowedTools "Bash(npm *) Read Edit"

# Contexto
claude --add-dir ../shared
claude --mcp-config ./mcp.json

# Debug
claude --debug api
claude --verbose

# Atualizar
claude update
claude --version