Manual — Claude Code / Nº 01

01

Capítulo um · introdução

O que é o Claude Code

Claude Code é a ferramenta oficial de programação agêntica no terminal criada pela Anthropic. Ele lê o seu projeto, entende a arquitetura, executa comandos shell, edita arquivos, roda testes, faz commits — e tudo isso sentado ao seu lado, no mesmo ambiente em que você já trabalha.

Diferente de um chatbot tradicional, o Claude Code opera como um agente: você descreve o objetivo, ele planeja, executa em múltiplos passos, pede permissão quando necessário e entrega o resultado pronto para revisão.

①

Terminal-first

Roda no seu terminal favorito. Zero fricção.

②

Contexto real

Entende toda a base de código automaticamente.

③

Extensível

Hooks, subagentes, MCPs e skills customizadas.

④

Seguro

Permissões granulares para cada tipo de ação.

“
Não é autocompletar. É um colaborador que entende o seu código e trabalha junto.

02

Capítulo dois · começando

Instalação em dois passos

Você precisa de Node.js instalado. O restante é direto ao ponto.

bash — instalação global

$ npm install -g @anthropic-ai/claude-code

$ cd meu-projeto
$ claude
→ iniciando sessão ✓
→ lendo CLAUDE.md ✓
→ pronto.

Nota do editor

Na primeira execução o Claude pede login (Claude.ai ou API Console). Depois disso, basta rodar claude dentro de qualquer projeto.

03

Capítulo três · anatomia

Os arquivos que importam

Saber esses arquivos de cor é o atalho para dominar o Claude Code. Cada um tem uma função precisa.

A

CLAUDE.md

raiz/ · ~/.claude/

A memória do projeto. Convenções, arquitetura, comandos úteis — tudo que o Claude deve ler toda vez que abrir o repositório. O arquivo na raiz vale para o projeto; o global vale para tudo.

memóriacontextoversionado

B

.claude/settings.json

raiz/.claude/

Configurações do projeto versionadas no git. Define permissões, hooks, modelo padrão, variáveis e MCPs habilitados — a base compartilhada com o time.

confighookspermissões

C

.claude/settings.local.json

gitignore

Preferências pessoais do dev. Nunca versionado. Tokens, overrides temporários, atalhos locais.

localprivado

D

.claude/agents/*.md

pasta agents/

Cada arquivo .md descreve um subagente especializado — com prompt, ferramentas permitidas e modelo escolhido.

subagentesparalelo

E

.claude/commands/*.md

pasta commands/

Comandos slash customizados. O nome do arquivo vira o comando: deploy.md → /deploy.

slashreutilizável

F

.claude/skills/

pasta skills/

Skills são conjuntos de instruções que o Claude invoca automaticamente quando o contexto pede. Perfeitas para metodologias repetíveis.

skillsauto-invoke

G

.claudeignore

raiz/

Igual ao .gitignore, mas para o Claude. Evita que ele leia node_modules, builds, caches e outros arquivos irrelevantes.

ignore

04

Capítulo quatro · arquitetura

A organização ideal

A estrutura abaixo é o que a documentação oficial recomenda e o que a maioria dos projetos maduros adota:

meu-projeto/
├── .claude/
│   ├── settings.json          ← config versionada
│   ├── settings.local.json    ← config local (gitignore)
│   ├── agents/                ← subagentes
│   │   ├── reviewer.md
│   │   └── tester.md
│   ├── commands/              ← comandos slash
│   │   ├── deploy.md
│   │   └── revisar.md
│   ├── skills/                ← skills customizadas
│   │   └── minha-skill/
│   │       └── SKILL.md
│   └── hooks/                 ← scripts auxiliares
│       └── pre-commit.sh
├── CLAUDE.md                  ← ★ memória principal
├── .claudeignore              ← arquivos a ignorar
├── src/
├── tests/
└── package.json

Recomendação

Versione no git: CLAUDE.md, .claude/settings.json, agents/, commands/. Assim, toda a equipe compartilha o mesmo contexto e os mesmos superpoderes.

05

Capítulo cinco · interação

Comandos slash essenciais

Comandos começados com / funcionam dentro da sessão. Decore estes primeiro:

/helpLista todos os comandos disponíveis

/clearLimpa o histórico da conversa atual

/compactComprime contexto, libera tokens

/modelAlterna entre Opus, Sonnet, Haiku

/agentsGerencia subagentes do projeto

/mcpLista e configura servidores MCP

/hooksAbre configuração de hooks

/permissionsControla o que o Claude pode fazer

/configAbre configurações do harness

/memoryEdita arquivos CLAUDE.md ativos

/costMostra tokens usados e custo estimado

/reviewInicia revisão estruturada de código

/initGera um CLAUDE.md inicial

/doctorDiagnostica a instalação

/loginEntrada/saída de conta Anthropic

/exitEncerra a sessão

06

Capítulo seis · teclas

Atalhos que fazem diferença

Esc

Interrompe a ação atual do Claude

EscEsc

Volta à mensagem anterior para edição

Shift+Tab

Alterna modo (plan / auto-accept)

Ctrl+C

Cancela input atual

Ctrl+D

Sai do Claude Code

↑↓

Navega pelo histórico de prompts

# texto

Adiciona rápido ao CLAUDE.md

! texto

Executa comando bash diretamente

@ arquivo

Referencia arquivo no prompt

07

Capítulo sete · delegação

Subagentes especializados

Subagentes são assistentes paralelos, com contexto isolado. Perfeitos para pesquisas longas, execução em paralelo e proteção da janela de contexto principal.

.claude/agents/reviewer.md

---
name: reviewer
description: Revisa código em busca de bugs e más práticas
tools: Read, Grep, Glob
model: sonnet
---

Você é um revisor sênior de código. Analise os arquivos
passados e reporte problemas de segurança, performance e
legibilidade com referências file:line.

Use subagentes quando a tarefa consumir muito contexto ou quando duas coisas puderem rodar em paralelo.

08

Capítulo oito · automação

Hooks automáticos

Hooks são comandos shell que o harness executa automaticamente em eventos: antes/depois de uma tool, ao submeter um prompt, ao encerrar uma sessão. Perfeitos para lint, formatação e validações.

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

Eventos principais: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, Notification.

09

Capítulo nove · extensão

MCPs — plugando habilidades

MCPs (Model Context Protocol) são servidores externos que expõem novas ferramentas ao Claude: browsers, bancos, APIs. É como plugar plugins no agente.

01

Playwright

Automação de browser para testes visuais, validações e scraping.

02

Supabase

Consultas e operações em bancos Postgres hospedados na Supabase.

03

Context7

Documentação atualizada de qualquer biblioteca ou framework.

04

Serena

Operações semânticas de código via LSP — rápidas e precisas.

bash

$ claude mcp add playwright npx @playwright/mcp@latest
$ claude mcp list
✓ playwright    conectado
✓ supabase      conectado
✓ context7      conectado

10

Capítulo dez · reuso

Skills reutilizáveis

Skills são pacotes de instruções que o Claude invoca sozinho quando uma tarefa bate com a descrição. Ficam em .claude/skills/nome/SKILL.md.

SKILL.md

---
name: deploy-checklist
description: Use antes de qualquer deploy em produção
  para validar testes, migrations e variáveis de ambiente
---

# Checklist de Deploy

1. Rodar toda a suíte de testes
2. Verificar migrations pendentes
3. Conferir variáveis de ambiente
4. Criar tag de versão

11

Capítulo onze · disciplina

Dez boas práticas

Mantenha o CLAUDE.md vivo

Documente convenções, comandos, arquitetura e regras. É a memória do projeto.
Seja específico nos prompts

Em vez de "arrume isso", diga "corrija o bug na função X em src/auth.js que retorna null quando o usuário expira".
Use Plan Mode para tarefas grandes

Pressione Shift+Tab para ativar o modo planejamento. O Claude planeja antes de mexer em nada.
Dispare subagentes em paralelo

Investigações, buscas amplas e análises independentes podem — e devem — rodar simultaneamente.
Use /compact quando o contexto encher

Comprime o histórico preservando o essencial e libera tokens para continuar trabalhando.
Versione suas configurações

Commit .claude/settings.json, agents/ e commands/. Toda a equipe ganha.
Revise antes de aceitar

Leia os diffs. O Claude pode errar. Em tarefas críticas, prefira modo interativo ao auto-accept.
Referencie arquivos com @

Digite @src/index.js no prompt para incluir o arquivo rapidamente no contexto.
Limpe contexto entre tarefas

Use /clear ao mudar de assunto completamente para evitar contaminação.
Automatize com hooks

Formatadores, linters e testes rápidos viram parte invisível do fluxo.

12

Capítulo doze · ritmo

O workflow recomendado

I

Explorar

Peça ao Claude para ler e entender a parte do código que você vai tocar.

II

Planejar

Entre em Plan Mode (Shift+Tab) e revise o plano antes de executar.

III

Implementar

Deixe o Claude executar com as permissões apropriadas ao risco.

IV

Testar

Rode testes automatizados ou peça ao Claude para criar novos.

V

Revisar

Cheque o diff final, garanta que nada foi quebrado.

VI

Commitar

Peça um commit semântico explicando o "porquê", não o "o quê".

13

Capítulo treze · colofão

Manual do Claude Code_

O que é o Claude Code

Terminal-first

Contexto real

Extensível

Seguro

Instalação em dois passos

Os arquivos que importam

CLAUDE.md

.claude/settings.json

.claude/settings.local.json

.claude/agents/*.md

.claude/commands/*.md

.claude/skills/

.claudeignore

A organização ideal

Comandos slash essenciais

Atalhos que fazem diferença

Subagentes especializados

Hooks automáticos

MCPs — plugando habilidades

Playwright

Supabase

Context7

Serena

Skills reutilizáveis

Dez boas práticas

Mantenha o CLAUDE.md vivo

Seja específico nos prompts

Use Plan Mode para tarefas grandes

Dispare subagentes em paralelo

Use /compact quando o contexto encher

Versione suas configurações

Revise antes de aceitar

Referencie arquivos com @

Limpe contexto entre tarefas

Automatize com hooks

O workflow recomendado

Explorar

Planejar

Implementar

Testar

Revisar

Commitar

Leia mais, experimente

Documentação Claude Code

GitHub — anthropics/claude-code

Documentação MCP

modelcontextprotocol.io

Use `/compact` quando o contexto encher

Referencie arquivos com `@`