Claude Código Cheat Sheet: Guia Completo para Desenvolvedores Iniciantes

Se você está se aprofundando no Claude Code, o poderoso assistente de codificação com IA da Anthropic, ter uma referência clara é essencial. Esta Folha de Consulta do Claude Code é destinada a desenvolvedores que desejam um guia prático e amigável para iniciantes, cobrindo configuração, fluxos de trabalho, e dicas avançadas. Ao final, você se sentirá mais confiante usando o Claude Code em seu ambiente local ou como parte de seus processos de CI/CD.

O Que É Claude Code?

Claude Code é uma ferramenta de codificação com IA baseada em CLI da Anthropic. Ela permite que desenvolvedores gerem, refatorem, testem e documentem código usando os modelos avançados de Claude. Em vez de uma interface de chat simples, o Claude Code se comporta como um IDE de IA: ele entende a estrutura do seu repositório, aplica salvaguardas definidas em arquivos de configuração, pode executar comandos bash e se integra a fluxos de trabalho Git.

Instalar Claude Code:

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

# Windows:
irm https://claude.ai/install.ps1 | iex

# NPM:
npm install -g @anthropic-ai/claude-code

# Homebrew:
brew install --cask claude-code

Começar a usar o Claude Code:

cd your-project
claude

Componentes Chave do Claude Code — Sua Folha de Consulta

Aqui estão os blocos de construção e recursos essenciais que você vai querer conhecer ao começar a usar o Claude Code:

1. CLAUDE.md — Manifesto do Agente

• O arquivo CLAUDE.md é a “constituição” para o seu agente: ele define como Claude se comporta em seu repositório.
• Use-o para documentar ferramentas aprovadas, fluxos de trabalho comuns e restrições.
• Melhor prática: Mantenha-o curto, focado nas principais salvaguardas e evite incorporar documentos muito grandes.

# MyProject CLAUDE.md

## Project Overview  
This is a Node.js + Express REST API for a task management application.  

## Technology Stack  
- Backend: Node.js (ES6), Express  
- Database: PostgreSQL  
- Testing: Jest  
- Linting & Style: ESLint, Prettier

## Development Commands  
- `npm install` — Install dependencies  
- `npm run dev` — Start development server  
- `npm run test` — Run all tests  
- `npm run lint` — Run linter  

## Coding Standards  
- Use 2-space indentation.  
- Always use `async / await` instead of `.then()` chains.  
- Functions must have JSDoc comments.  
- Prefer composition over inheritance.

## Git Workflow  
- Feature branches must follow this pattern: `feature/FOO`  
- Use `git rebase` instead of `merge` for updating branches.  
- When committing: write descriptive commit messages that follow the Conventional Commits format.

## File Structure Guidance  
- `src/` — Your main application code  
- `tests/` — Test files  
- `scripts/` — Utility or setup scripts  
- `migrations/` — Database migrations  

## Known Issues / Workarounds  
- `db.connect()` sometimes times out; in that case, retry twice.  
- For large JSON payloads, use streaming to avoid memory issues.

## Memory / Style Preferences  
- Always ask for clarification if the request is ambiguous.  
- Do not generate new `.md` files unless explicitly instructed.  
- Include a `co-authored-by Claude` line in generated commits.

2. Gerenciamento de Contexto

a. Use **/context** para inspecionar o uso de tokens da sua sessão atual do Claude.

b. Comandos para reiniciar ou reduzir o contexto:

• /clear + /catchup: Limpa toda a conversa e depois recarrega os arquivos de um commit ou branch.
• Um fluxo de “Documentar e Limpar”: faça Claude despejar seu plano em um arquivo Markdown, limpar a memória e depois recarregar a partir desse arquivo.

3. Comandos de Barra

• Comandos de barra são atalhos para prompts predefinidos.
• Exemplos:

• Mantenha os comandos de barra mínimos e focados; não dependa deles para todas as tarefas.

4. Modo de Planejamento

• Use o modo de planejamento ao iniciar tarefas complexas. Claude irá delinear um plano antes de escrever o código.
• Você pode então revisar, editar ou aprovar esse plano antes de pedir a Claude para executá-lo.
• Ideal para grandes trabalhos de feature, refatoração ou mudanças arquitetônicas.

5. Subagentes & Delegação de Tarefas

• O Claude Code suporta **subagentes**, permitindo que você delegue partes do trabalho a “clones” do agente principal.
• Shrivu prefere uma arquitetura “Mestre-Clone”: o agente principal gera clones via Task(...), em vez de usar subagentes especializados e rígidos.
• Isso preserva a flexibilidade, evitando a fragmentação do contexto.
• Acesse os subagentes do Claude Code usando o comando de barra: /agents.

6. Claude Skills vs. MCP — Qual a Diferença?

a. As **Claude Skills** são “módulos” pré-construídos que ensinam Claude *como* executar tarefas específicas. Elas são escritas em Markdown ou código, e carregam apenas quando necessário. Você pode usar as Skills para definir fluxos de trabalho como formatar relatórios, resumir dados ou impor o estilo da sua equipe.

b. O **Model Context Protocol (MCP)**, por outro lado, é um protocolo para conectar Claude a dados e ferramentas externas — como bancos de dados, seu código-base ou sistemas de negócios. É como um “adaptador universal” que permite a Claude acessar e agir sobre recursos externos sem integrações personalizadas por ferramenta.

c. Principais Diferenças:

1. Propósito:

• Skills codificam *conhecimento procedural*.
• MCP lida com *conectividade de ferramentas e dados*.

2. Eficiência de Token:

• Skills carregam apenas quando necessário, usando relativamente poucos tokens.
• As definições de ferramentas do MCP podem ocupar um espaço significativo de tokens se muitas estiverem habilitadas.

d. Caso de Uso:

• Use as Skills para ensinar a Claude fluxos de trabalho específicos do domínio (por exemplo, “ao escrever relatórios de status, sempre inclua X, Y, Z”).
• Use o MCP quando Claude precisar *ler/escrever dados*, chamar APIs ou acessar sistemas externos como Git ou um banco de dados.

Na prática, os dois funcionam melhor juntos: o MCP dá a Claude acesso aos seus dados, e as Skills ensinam a Claude como usar esses dados de forma estruturada e repetível.

6. Hooks

a. Hooks são sua maneira de aplicar regras automaticamente.

b. Dois tipos comuns:

• Bloqueio na submissão: Por exemplo, um hook PreToolUse pode bloquear git commit a menos que os testes tenham sido aprovados.
• Hooks de dica: Não bloqueadores; eles fornecem orientação ou sugestões sem interromper a execução.

c. Evite hooks de “bloqueio na escrita” — permitir que Claude complete seu plano e depois validar é mais estável.

# Example Hook in .claude/settings.toml

[[hooks]]
# The event that triggers the hook.
event = "PostToolUse" 

# (Optional) Conditions for the hook to run.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# The shell command to execute.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optional) Whether to run the command in the background.
run_in_background = false 

7. SDK de CLI

• O **SDK do Claude Code** permite que você automatize as interações com Claude: útil para processamento em lote, construção de ferramentas internas ou prototipagem de agentes.
• Use-o para executar refatorações paralelas, gerar código a partir de modelos ou como um agente leve dentro de fluxos de trabalho de CI/CD.

Instalação:

# Typescript:
npm install @anthropic-ai/claude-agent-sdk

# Python:
pip install claude-agent-sdk

8. GitHub Actions (GHA) do Claude Code

• Você pode integrar o Claude Code diretamente no GitHub Actions.
• Use-o para gerar pull requests automaticamente, aplicar padrões de código ou executar verificações baseadas em CLAUDE.md como parte do seu pipeline de CI.
• Como os logs são armazenados, você pode auditar o comportamento do agente e melhorar seu arquivo CLAUDE.md ao longo do tempo.

9. Configurações & Configuração

a. Em settings.json, você pode configurar:

• Proxy (HTTPS_PROXY) — útil para depurar o tráfego da CLI.
• Tempos Limite (MCP_TOOL_TIMEOUT, BASH_MAX_TIMEOUT_MS) — aumente-os se você executar tarefas longas.
• Chave de API (ANTHROPIC_API_KEY) — use sua chave da Anthropic ou um script auxiliar.
• Permissões — controle quais ferramentas do sistema o Claude Code tem permissão para executar.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

Recursos Avançados & Dicas de Produtividade

1. Troca de Modelo: Escolha Claude 4 Sonnet ou Opus dependendo da sua tarefa. Sonnet é rápido e eficiente em termos de custo; Opus é mais capaz para mudanças complexas e multi-arquivo.
2. Modos de Pensamento (Dica): Alguns usuários ajustam o modo de raciocínio de Claude para think, think hard, think harder, ou ultrathink para controlar a profundidade do raciocínio.
3. Comandos Personalizados: Defina comandos de barra reutilizáveis em .claude/commands com placeholders dinâmicos ($argument). Ótimo para testar, construir ou revisar.
4. Histórico de Sessões: Use claude --resume ou claude --continue para retomar sessões antigas. Claude armazena todo o histórico de sessões localmente.
5. Ciclo de Feedback: Revise o comportamento do agente via logs do GitHub Action ou dados de sessões históricas e atualize seu CLAUDE.md para corrigir mal-entendidos ou impor melhores salvaguardas.

Perguntas Frequentes (FAQ)

Q1. Qual é o propósito do CLAUDE.md?
Resp: O CLAUDE.md atua como o manifesto do agente. Ele define regras, ferramentas e convenções para o Claude Code seguir. Ajuda a padronizar o comportamento em seu repositório.

Q2. Devo usar subagentes ou apenas tarefas simples?
Resp: Use subagentes se você quiser fluxos de trabalho modulares estritos. Mas muitos consideram o padrão **Mestre-Clone** (usando Task(...)) mais flexível — você mantém o contexto enquanto delega subtarefas.

Q3. Como reinicio uma sessão do Claude sem perder tudo?
Resp: Use /clear para redefinir o chat e, em seguida, /catchup para carregar arquivos do seu branch Git para que Claude tenha o contexto completo novamente.

Q4. O que são hooks e por que preciso deles?
Resp: Hooks aplicam regras ou verificações quando Claude realiza commits. Por exemplo, um hook de bloqueio na submissão pode garantir que os testes passem antes que um commit Git seja permitido.

Q5. Como posso integrar o Claude Code ao CI/CD?
Resp: Use o Claude Code GitHub Action para executar tarefas, validar código, gerar pull requests ou aplicar suas salvaguardas de CLAUDE.md em pipelines automatizados.

Conclusão

Esta **Folha de Consulta do Claude Code** oferece uma visão geral prática e estruturada de como usar o Claude Code de forma eficaz. Desde a escrita de um arquivo CLAUDE.md bem elaborado até o aproveitamento de comandos de barra, subagentes, hooks e integração com CI — esses padrões formam uma base sólida para usar o Claude Code como um parceiro de desenvolvimento confiável e alimentado por IA.

Ao dominar esses recursos, novos desenvolvedores podem se integrar rapidamente, e engenheiros mais experientes podem otimizar seus fluxos de trabalho, impor salvaguardas e escalar a produtividade assistida por Claude. O Claude Code é mais do que apenas uma ferramenta de geração de código — é um sistema programável e com capacidade de agente que se adapta às necessidades da sua equipe.