Início
Módulo 1 de 6

Fundamentos do
Claude Code

Arquitetura, CLAUDE.md, Permissões, Skills e Hooks

Workshop Claude Code • 3 horas • Luiz Couto

Agenda de hoje

10 min

Abertura

Agenda, checklist de setup, recap da inaugural

30 min

Bloco 1: Arquitetura & Modelos

Agent loop, Opus/Sonnet/Haiku, custos, contexto

40 min

Bloco 2: CLAUDE.md & Auto-Memory

Hierarquia, boas práticas, exercício principal

15 min

Demo ao vivo

CLAUDE.md bom vs ruim — o efeito na prática

10 min

Intervalo

Pausa para café

30 min

Bloco 3: Permissões & Segurança

Modelo de permissões, configuração, best practices

25 min

Bloco 4: Skills & Slash Commands

Built-in, custom, .claude/commands/

25 min

Bloco 5: Hooks & Automações

PreToolUse, PostToolUse, session history

5 min

Encerramento

Recap, preview do Módulo 2

Antes de começar

Checklist de Setup

  • Node.js 18+ instalado
  • Claude Code CLI instalado globalmente
  • API Key da Anthropic ou Claude Max ativo
  • Git configurado
  • Projeto do exercício clonado

Setup do projeto

$ git clone https://github.com/coutoluizf/workshop-claude-code-exercises.git
$ cd workshop-claude-code-exercises/modulo-01
$ npm install && npm test

Os testes vão mostrar 2 falhas — é intencional. Vamos corrigir juntos.

Recap da aula inaugural

Vimos

Na inauguração

Evolução dos coding assistants (4 gerações), por que Claude Code se destaca, demo ao vivo de Agent Teams com 4 agentes em paralelo.

Hoje

Mão na massa. Vamos configurar, explorar e construir usando o Claude Code num projeto real (API Hono).

01

Arquitetura & Modelos

30 minutos

Como o Claude Code funciona

Você (Terminal)
Claude Code CLI
File System
Bash / Shell
MCPs

Terminal-first: Claude Code roda no seu terminal e interage diretamente com o sistema de arquivos, shell e ferramentas externas via MCPs.

O Agent Loop

  • Receber: Entende o pedido do usuário
  • Pensar: Analisa contexto e planeja ações
  • Agir: Executa ferramentas (ler, escrever, bash)
  • Observar: Avalia o resultado da ação
  • Iterar: Repete até completar a tarefa
Receber
Pensar
Agir
Observar
Iterar

Isso é o que diferencia um agent de um chatbot. Claude Code não apenas responde — ele executa.

Os 3 modelos

Opus 4.6

Mais capaz

Raciocínio avançado, tarefas complexas, multi-step. O modelo padrão do Claude Code.

Sonnet 4.5

Equilíbrio

Rápido e capaz. Bom custo-benefício para tarefas do dia-a-dia.

Haiku 4.5

Mais rápido

Respostas instantâneas. Ideal para tarefas simples e de baixa complexidade.

Quando usar qual modelo

Cenário Modelo Por quê
Refactoring complexo Opus 4.6 Precisa entender todo o sistema
Bug fix pontual Sonnet 4.5 Rápido e preciso para escopo limitado
Gerar boilerplate Haiku 4.5 Código repetitivo, velocidade importa
Arquitetura de sistema Opus 4.6 Decisões complexas com trade-offs
Renomear variáveis Haiku 4.5 Tarefa mecânica
Code review Sonnet 4.5 Bom equilíbrio entre análise e custo

Trocando de modelo

# Via slash command (dentro da sessão)
> /model sonnet

# Via flag ao iniciar
$ claude --model sonnet

# Fast mode (toggle, mesmo modelo, output mais rápido)
> /fast

# Forçar Opus para uma tarefa complexa
$ claude --model opus

Consciência de custos

$15
Opus / 1M tokens
$3
Sonnet / 1M tokens
$0.25
Haiku / 1M tokens

API (pay-per-use)

Paga pelo que usar. Ideal para times que querem controle granular de custos. Cada modelo tem preço diferente.

Claude Max ($200/mês)

Uso ilimitado de Opus. Compensa se você usa mais de ~13M tokens/mês. Boa opção para heavy users.

Context Window: 200K tokens

  • 200K tokens de contexto padrão (~150K palavras)
  • Compactação automática quando se aproxima do limite
  • CLAUDE.md sempre presente (não é compactado)
  • /compact para compactar manualmente

Context management é tão importante que dedicamos o Módulo 2 inteiro a isso.

O que cabe em 200K?

  • ~500 arquivos de código lidos
  • ~50 ferramentas executadas
  • ~2 horas de sessão contínua
  • Varia conforme tamanho dos arquivos
Exercício 1 5 min

Explorar e encontrar o bug

Instruções

  • Abra o terminal na pasta do projeto clonado:
$ cd workshop-claude-code-exercises/modulo-01
  • Rode claude para iniciar uma sessão
  • Peça: "Explore este projeto e me diga o que ele faz"
  • Depois peça: "Rode os testes e me explique as falhas"
  • Troque para Sonnet com /model sonnet e repita

O que observar

  • Como o agent loop aparece no terminal
  • Quais ferramentas Claude usa automaticamente
  • Claude consegue identificar o bug sozinho?
  • Diferença de velocidade entre Opus e Sonnet

O projeto é uma API Hono de tarefas com um bug intencional. 2 testes falham — é proposital.

O que vocês observaram?

Perguntas para discussão

  • Quais ferramentas o Claude usou automaticamente?
  • Ele encontrou o bug sem você pedir?
  • Perceberam diferença entre Opus e Sonnet?

Pontos-chave

  • Claude lê arquivos proativamente
  • Cada ação é uma iteração do agent loop
  • O modelo certo depende da tarefa
02

CLAUDE.md & Auto-Memory

40 minutos

Hierarquia de memória

~/.claude/CLAUDE.md
Global (todos os projetos)
./CLAUDE.md
Projeto (commitado no repo)
.claude/settings.local
Privado (não commitado)
  • Global: Preferências pessoais que valem para todos os projetos
  • Projeto: Convenções do time, stack, padrões
  • Privado: Config pessoal que não vai pro repo

Claude lê todos os níveis e os combina. Projeto sobrescreve Global. Privado sobrescreve Projeto.

O que colocar e não colocar

Sim

Colocar no CLAUDE.md

  • Stack técnico e versões
  • Convenções de código do time
  • Estrutura de pastas importante
  • Padrões de nomes (branches, commits)
  • Comandos de build/test/deploy
  • Informações de negócio relevantes
Não

Evitar no CLAUDE.md

  • Senhas, tokens, API keys
  • Instruções genéricas ou óbvias
  • Texto excessivamente longo (+200 linhas)
  • Informações que mudam toda semana
  • Tutoriais completos (usar links)
  • Coisas que o modelo já sabe

Exemplo real de CLAUDE.md

# Meu Projeto

## Stack
- Runtime: Node.js 22 + TypeScript 5.9
- Framework: Next.js 15 (App Router)
- DB: PostgreSQL via Drizzle ORM
- Deploy: Vercel

## Convenções
- Sempre usar async/await, nunca .then()
- Testes com Vitest, mínimo 80% coverage
- Commits em português, formato: tipo: descrição
- Branches: feat/xxx, fix/xxx, chore/xxx

## Comandos
- Build: npm run build
- Test: npm test
- Deploy: vercel deploy --prod

Auto-Memory: como funciona

  • Diretório persistente em ~/.claude/projects/
  • MEMORY.md é carregado automaticamente em toda sessão
  • Claude atualiza sozinho conforme aprende sobre o projeto
  • Pode criar arquivos por tópico (debugging.md, patterns.md)
  • Sobrevive entre sessões — memória de longo prazo

Diferença chave: CLAUDE.md é instrução (você escreve). Auto-Memory é aprendizado (Claude escreve).

O que Claude salva na memória

  • Padrões confirmados em múltiplas interações
  • Decisões arquiteturais do projeto
  • Preferências do usuário
  • Soluções para problemas recorrentes

Auto-Memory na prática

# Sessão 1: Você corrige um bug
> "Fix the auth bug in login.ts"
# Claude descobre que o projeto usa Zod para validação

# Claude salva em MEMORY.md:
# "Validação usa Zod schemas em src/schemas/"

# Sessão 2: Você pede uma nova feature
> "Add email validation to signup"
# Claude já sabe usar Zod e onde ficam os schemas
# → Resultado melhor, mais rápido

Quanto mais você usa Claude Code no mesmo projeto, melhor ele fica.

Demo: CLAUDE.md + Auto-Memory

O que vou mostrar

  • O CLAUDE.md deste projeto (real)
  • O diretório de Auto-Memory
  • Como Claude usa essas informações
  • Como pedir para Claude lembrar algo
$ cat CLAUDE.md
$ ls ~/.claude/projects/
$ cat ~/.claude/projects/.../MEMORY.md
Exercício 2 — Principal 20 min

CLAUDE.md + corrigir o bug

Instruções (no projeto Hono)

  • No terminal dentro de modulo-01/, peça ao Claude: "Crie um CLAUDE.md para este projeto"
  • Revise e ajuste o que Claude gerou
  • Agora peça: "Corrija o bug que faz os testes falharem"
  • Rode npm test — todos devem passar
  • Compare: a correção usou info do CLAUDE.md?

Resultado esperado

  • CLAUDE.md criado com stack Hono + Cloudflare
  • Bug corrigido — POST /tasks valida title
  • 7/7 testes passando

CLAUDE.md é o arquivo mais impactante para produtividade com Claude Code.

Anti-patterns do CLAUDE.md

Muito vago
# Meu Projeto
Esse é um projeto web.
Use boas práticas.
Faça código limpo.

Claude já sabe fazer "código limpo". Isso não adiciona informação.

Muito verboso
# 500 linhas de documentação
# Tutorial completo de React
# Todos os endpoints da API
# Histórico de todas as decisões
...

Informação demais dilui o que é importante. Limite ~200 linhas.

Regra de ouro: Inclua apenas o que você explicaria a um novo dev no primeiro dia.

Discussão & Q&A

Para refletir

  • O que vocês colocaram no CLAUDE.md?
  • Claude sugeriu algo que vocês não tinham pensado?
  • A correção do bug foi melhor com CLAUDE.md?

Takeaways

  • CLAUDE.md = instrução (você escreve)
  • Auto-Memory = aprendizado (Claude escreve)
  • Ambos melhoram com o tempo
Demo

CLAUDE.md bom vs ruim

15 minutos — ao vivo

O efeito na prática

Sem CLAUDE.md

Resultado genérico

  • Claude adivinha o stack
  • Não segue convenções do time
  • Pode usar ferramentas erradas
  • Precisa de mais correções
Com CLAUDE.md

Resultado alinhado

  • Sabe o stack exato
  • Segue padrões do time
  • Usa as ferramentas certas
  • Código pronto para merge

Vamos ver ao vivo: mesmo pedido, dois contextos diferentes. Observem a diferença de qualidade.

10:00

Intervalo

Voltamos em 10 minutos

03

Permissões & Segurança

30 minutos

Modelo de permissões

Default

Pede permissão

Claude pergunta antes de executar cada ação (ler, escrever, bash). Recomendado para iniciantes.

Allowed

Lista de permitidos

Você define quais ferramentas são auto-aprovadas. Equilíbrio entre segurança e produtividade.

Bypass

Tudo liberado

Claude executa sem perguntar. Rápido, mas use com cuidado. Ideal para projetos pessoais.

O que Claude Code pode fazer

Read

Ler arquivos

  • Ler qualquer arquivo do projeto
  • Buscar por patterns (Glob/Grep)
  • Analisar imagens e PDFs
  • Ler notebooks Jupyter
Write

Modificar arquivos

  • Editar arquivos existentes
  • Criar novos arquivos
  • Editar notebooks
  • Refactoring multi-arquivo
Execute

Rodar comandos

  • Bash commands (git, npm, etc.)
  • Rodar testes
  • Build e deploy
  • Interagir com APIs via CLI

O prompt de permissão

╭──────────────────────────────────────╮
│ Claude wants to execute a command    │
│                                      │
│ $ npm test                          │
│                                      │
│ [Y]es / [N]o / [A]lways           │
╰──────────────────────────────────────╯

Y / N

Aceita ou rejeita esta execução específica

A (Always)

Adiciona à lista de permitidos para esta sessão

Configurando allowedTools

// .claude/settings.json
{
  "permissions": {
    "allowedTools": [
      "Read",            // Ler arquivos (seguro)
      "Glob",            // Buscar arquivos (seguro)
      "Grep",            // Buscar conteúdo (seguro)
      "Write",           // Criar/editar arquivos
      "Edit",            // Editar arquivos existentes
      "Bash(npm test)", // Só este comando bash
      "Bash(git *)"     // Todos os comandos git
    ]
  }
}

Use patterns com wildcard (*) para permitir famílias de comandos. Exemplo: Bash(npm *)

Best practices de segurança

Exercício 3 15 min

Configurar permissões + rodar testes

Instruções (no projeto Hono)

  • Ainda em modulo-01/, crie .claude/settings.json
  • Configure allowedTools com Read, Glob, Grep
  • Adicione Bash patterns para npm test e npm run dev
  • Peça ao Claude: "Rode os testes e corrija qualquer falha"
  • Observe quais ações Claude pede permissão e quais executa direto

Resultado esperado

  • Leitura de arquivos sem prompt
  • npm test roda sem prompt
  • Escrita em arquivos ainda pede permissão
  • Todos os 7 testes passando

Recap: Permissões

1

Default

Claude pede permissão para tudo. Seguro, mas lento.

2

allowedTools

Você define o que é auto-aprovado. Melhor produtividade.

3

Bypass

Tudo liberado. Rápido, mas use com responsabilidade.

Na prática: a maioria dos devs usa allowedTools com Read/Glob/Grep liberados e Bash parcialmente liberado.

04

Skills & Slash Commands

25 minutos

O que são Skills

  • Prompts reutilizáveis invocados com /comando
  • Built-in: vêm com o Claude Code
  • Custom: criados pelo time em .claude/commands/
  • Argumentos: aceitam $ARGUMENTS dinâmicos
  • Compartilháveis: commitados no repo, todo o time usa

Analogia: Skills são como aliases do bash, mas para o Claude. Transformam tarefas repetitivas em comandos de uma linha.

Slash commands built-in

Comando O que faz Quando usar
/init Gera CLAUDE.md para o projeto Início de qualquer projeto
/compact Compacta o contexto Sessão ficando lenta
/model Troca o modelo Trocar velocidade/capacidade
/review Code review do diff atual Antes de abrir PR
/help Lista todos os comandos Quando não lembrar um comando

Criando custom commands

# .claude/commands/pr-review.md

Analise o diff atual e forneça um code review detalhado.

Avalie:
- Bugs: problemas de lógica, edge cases
- Segurança: vulnerabilidades, dados expostos
- Performance: queries N+1, loops desnecessários
- Legibilidade: nomes, complexidade, DRY

Formato: lista priorizada por severidade.

# Uso: /pr-review

O arquivo .md na pasta .claude/commands/ vira automaticamente um slash command.

Exemplos práticos

/deploy-check

Pre-deploy checklist

Verifica testes, lint, tipos, env vars antes de deploy. Bloqueia se algo falhar.

/doc-component

Documentar componente

Gera documentação padronizada para componentes React com props, exemplos e edge cases.

/add-endpoint

Nova rota + teste

Gera uma rota Hono com handler, validação e teste. Aceita $ARGUMENTS para o path.

Exercício 4 15 min

Criar /add-endpoint

Instruções (no projeto Hono)

  • No projeto modulo-01/, crie .claude/commands/add-endpoint.md
  • O prompt deve instruir Claude a gerar: rota Hono + handler + teste Vitest
  • Teste com: /add-endpoint PUT /tasks/:id
  • Verifique se a rota e o teste foram criados
  • Rode npm test — novo teste deve passar

Resultado esperado

  • Skill /add-endpoint criado
  • Rota PUT /tasks/:id na API Hono
  • Teste da nova rota passando

Bônus: commite o skill no repo. O time inteiro pode usar.

Skills vs Prompting ad-hoc

Ad-hoc

Digitar o prompt toda vez

  • Flexível, mas inconsistente
  • Cada pessoa faz diferente
  • Esquece detalhes importantes
  • Não compartilhável
Skills

Comando padronizado

  • Consistente — mesmo resultado sempre
  • Compartilhado via Git
  • Evoluído com o tempo
  • Onboarding instantâneo

Regra: Se você faz algo mais de 3 vezes, crie um skill.

05

Hooks & Automações

25 minutos

O que são Hooks

  • Shell commands que rodam automaticamente em eventos
  • PreToolUse: antes de Claude usar uma ferramenta
  • PostToolUse: depois de Claude usar uma ferramenta
  • Podem bloquear ações perigosas
  • Configurados em .claude/settings.json
// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx prettier --write $FILE"
      }
    ]
  }
}

Exemplos práticos

Auto-lint

PostToolUse: Write

# Roda Prettier em todo arquivo escrito
"command": "npx prettier --write $FILE"

Garante formatação consistente sem depender do Claude.

Segurança

PreToolUse: Bash

# Bloqueia comandos destrutivos
"command": "! echo $COMMAND | grep -q 'rm -rf'"

Previne execução acidental de comandos perigosos.

Hooks são a rede de segurança: garantem padrões automaticamente, mesmo quando você esquece de pedir.

Exercício 5 — Bônus 10 min

Hook: Session History

Instruções (no projeto Hono)

  • Ainda em modulo-01/, peça ao Claude: "Crie um hook PostToolUse que salva um log de todas as ações da sessão em .claude/sessions/"
  • O arquivo deve ter timestamp no nome (ex: session-2026-02-12-1430.md)
  • Cada entrada: hora, ferramenta usada, arquivo afetado
  • Faça algumas ações no projeto e veja o log sendo criado

Por que isso importa

  • Rastreabilidade: saber o que Claude fez e quando
  • Versionável: commita o histórico no Git
  • Auditoria: se algo deu errado, você tem o log

Pro tip: Guardar histórico de sessões é algo que poucos devs fazem — e faz toda a diferença.

Recap do Módulo 1

  • ✓  Arquitetura — agent loop, ferramentas, terminal-first
  • ✓  Modelos — Opus, Sonnet, Haiku e quando usar cada um
  • ✓  Custos — API vs Claude Max, preços por modelo
  • ✓  CLAUDE.md — hierarquia, boas práticas, anti-patterns
  • ✓  Permissões — modelo, allowedTools, segurança
  • ✓  Skills & Hooks — custom commands, session history

O que vocês construíram hoje: CLAUDE.md, corrigiram o bug, configuraram permissões, criaram um skill e um hook de session history. Tudo no projeto real.

Módulo 1 Completo

Até o Módulo 2!

Context Engineering & Agentic Sessions

Revise
Seu CLAUDE.md
Experimente
Custom commands no dia-a-dia
Traga dúvidas
Para a próxima sessão
luiz@couto.co • couto.co
Módulo 1 1 / 48
← → navegar  |  F fullscreen  |  N notas  |  D dark mode
Início