Módulo 1.1 — O que é o Claude Code | Engenharia com Claude Code

🤖 Claude Code como ferramenta de engenharia

O Claude Code não é um chatbot com interface bonita. É um CLI que executa o modelo Claude diretamente no seu terminal, com acesso completo ao sistema de arquivos, processos e ferramentas do seu ambiente de desenvolvimento. A diferença é fundamental: enquanto um chat responde em texto, o Claude Code age.

⚡ A diferença que muda tudo

Quando você pede ao Claude Code para "adicionar testes ao módulo de pagamentos", ele não descreve como fazer — ele lê os arquivos existentes, entende a estrutura, escreve o código e salva os arquivos. Tudo no mesmo prompt.

•Chat tradicional: "Aqui está como você poderia adicionar testes..." → você implementa
•Claude Code: Lê os arquivos → escreve os testes → salva → roda os testes → reporta resultado

✓ O que o Claude Code FAZ

✓Lê, cria e edita arquivos no seu filesystem
✓Executa comandos bash (git, npm, tests)
✓Encadeia múltiplas ações em sequência
✓Verifica resultados e ajusta conforme necessário

✗ O que ele NÃO é

✗Não é um REPL interativo (sem persistência por padrão)
✗Não tem interface gráfica nativa
✗Não aprende entre sessões automaticamente
✗Não executa código arbitrário sem permissão

💡 Dica Prática

Quando você formular um prompt, pense em termos de resultados observáveis: "Crie o arquivo X com o conteúdo Y" é mais eficaz que "me ajude a criar X". O Claude Code prefere instruções que pode verificar.

🔄 O loop de conversa — turnos e ferramentas

O Claude Code opera em um loop de turnos síncronos. Em cada turno: recebe input, decide quais ferramentas chamar, aguarda os resultados e decide o próximo passo. Esse loop continua até o Claude determinar que a tarefa está concluída — ou até ser interrompido.

🔄 O loop em detalhes

Input: Seu prompt é inserido no context window junto com o histórico da sessão e o conteúdo dos arquivos referenciados

Decisão: O modelo decide se responde em texto ou chama uma ferramenta (Bash, Read, Edit, Write)

Execução: A ferramenta executa (aqui os hooks são disparados) e o resultado vai de volta para o context window

Iteração: O modelo processa o resultado e decide o próximo passo — ou finaliza se a tarefa estiver completa

📊 Por que isso importa para hooks

Hooks são executados no momento exato da etapa 3 — antes ou depois da execução da ferramenta. Entender o loop explica:

• Por que PreToolUse pode bloquear uma ação (a ferramenta ainda não rodou)
• Por que PostToolUse não pode desfazer (a ferramenta já rodou)
• Por que o hook recebe context window no payload do evento

🛠️ Ferramentas nativas: Bash, Read, Edit, Write

O Claude Code tem quatro ferramentas fundamentais que são as primitivas de toda ação que ele executa. Cada hook que você escrever vai interceptar o uso de uma ou mais dessas ferramentas — por isso é essencial saber o que cada uma faz.

🖥️ Bash

Executa comandos shell. O mais poderoso e o mais arriscado — pode fazer qualquer coisa que você pode fazer no terminal.

git commit -m "feat: add tests"
npm run test
find . -name "*.ts" -type f

📖 Read

Lê o conteúdo de arquivos. Usado para entender o contexto antes de editar ou antes de tomar decisões.

Read("/src/components/Button.tsx")
Read("/package.json")
Read("./CLAUDE.md")

✏️ Edit

Modifica partes específicas de arquivos existentes. Usa old_string/new_string para edições precisas e cirúrgicas.

Edit(file, old_string, new_string)
# Substitui exatamente um trecho
# Falha se old_string não for único

📝 Write

Cria ou sobrescreve arquivos completos. Usado para novos arquivos ou rewrites totais de conteúdo.

Write("/path/to/file.ts", content)
# Cria se não existe
# Sobrescreve se existe

💡 Hookando pelo nome da ferramenta

No settings.json, você registra hooks com um matcher de nome de ferramenta. Por exemplo, um hook de PreToolUse com matcher "Bash" intercepta todas as execuções de shell — você pode então inspecionar o comando e decidir se bloqueia.

⚙️ Arquivos de configuração: settings.json e CLAUDE.md

Toda a personalização do Claude Code passa por dois arquivos: settings.json para configurações estruturadas (hooks, comandos, permissões) e CLAUDE.md para instruções em texto natural injetadas no contexto de cada sessão.

📄 Estrutura do settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-commit.sh"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm *)"],
    "deny": ["Bash(rm -rf *)"]
  }
}

📋 Exemplo de CLAUDE.md

# Projeto: Sistema de Pagamentos

## Ao iniciar qualquer sessão
Leia `.memory/MEMORY.md` antes de responder qualquer coisa.

## Regras de código
- TypeScript estrito — nunca use `any`
- Testes obrigatórios para toda nova função pública
- Commits sempre em inglês, formato Conventional Commits

## Estrutura do projeto
- `src/` — código fonte
- `tests/` — testes unitários e de integração
- `.claude/hooks/` — hooks do Claude Code

💡 Local vs Global

Existem dois settings.json: .claude/settings.json (específico do projeto, commitado no repo) e ~/.claude/settings.json (global, para todas as sessões). O CLAUDE.md também pode existir em múltiplos níveis — o Claude Code os concatena todos.

📁 O contexto de projeto — por que o Claude sabe onde está

Quando você inicia o Claude Code em um diretório, ele usa esse diretório como âncora de contexto. Lê os arquivos de configuração locais, passa o cwd para cada ferramenta executada e prioriza arquivos próximos ao diretório de trabalho nas buscas de contexto.

🗂️ Hierarquia de configuração

1. ~/.claude/settings.json — configuração global do usuário (carregado sempre)

2. .claude/settings.json — configuração do projeto (sobrescreve global)

3. CLAUDE.md — instruções em texto (concatenados, não sobrescritos)

4. CLAUDE.md em subdiretórios — instruções específicas de módulo/área

⚠️ Cuidado com o contexto errado

Se você iniciar o Claude Code no diretório home (~) em vez do diretório do projeto, ele não vai carregar o settings.json do projeto — os hooks e comandos registrados localmente não estarão disponíveis. Sempre inicie no diretório raiz do projeto.

🚀 Primeiros passos — instalação e primeiro prompt técnico

Instalar o Claude Code requer Node.js 18+ e uma chave de API da Anthropic. A instalação é via npm global, e a autenticação é feita por variável de ambiente ou pelo comando de login interativo.

Instalar

npm install -g @anthropic-ai/claude-code
claude --version  # Verifica a instalação

Autenticar

# Opção 1: Variável de ambiente
export ANTHROPIC_API_KEY="sk-ant-..."

# Opção 2: Login interativo
claude login

Primeiro prompt técnico

# No diretório do seu projeto:
claude

# Prompt de teste:
"Leia o package.json e me diga quais
dependências de produção estão declaradas"

O Claude vai usar a ferramenta Read no package.json e retornar uma análise real das dependências.

💡 Primeiro prompt ideal para testar hooks

Para verificar que hooks estão funcionando, use um prompt que acione a ferramenta que o hook intercepta: "Execute: echo 'hook test'". Se o hook de PreToolUse Bash estiver ativo, ele rodará antes do echo.

✅ Resumo do Módulo 1.1

✓

Claude Code é um agente, não um chat — ele age no filesystem com ferramentas reais

✓

O loop de turnos — input → decisão → execução → iteração → finalização

✓

Quatro ferramentas fundamentais — Bash, Read, Edit, Write são os blocos de construção

✓

settings.json + CLAUDE.md — os dois arquivos que controlam comportamento e instruções

✓

Contexto de projeto — sempre inicie no diretório raiz para carregar as configurações corretas

✓

Instalação e autenticação — npm global + ANTHROPIC_API_KEY são os requisitos mínimos

Próximo Módulo:

1.2 — Hooks: o Sistema de Eventos — como interceptar ações do Claude Code com scripts externos

← Voltar para Trilha 1 Próximo: Hooks →