Módulo 1.2 — Como Claude Code Funciona

🔄 O fluxo de uma tarefa

Quando você digita algo no Claude Code, não é simplesmente uma mensagem enviada ao modelo. Existe um loop agente inteiro acontecendo: CC empacota contexto, envia ao modelo, recebe tool calls, executa-as, e itera até completar a tarefa.

🔄 O Loop Completo

1 Usuário digita: "Refatora a função auth() para usar async/await"

↓

2 Claude Code empacota: mensagem + CLAUDE.md + histórico da sessão

↓

3 Modelo LLM responde com tool call: Read("src/auth.js")

↓

4 CC executa a ferramenta e retorna o conteúdo do arquivo ao modelo

↓

5 Modelo lê o código e responde com Edit("src/auth.js", ...)

↓

6 CC aplica a edição e exibe a resposta final ao usuário

💡 Por que isso importa

Tarefas complexas podem ter 10, 20 ou 50 iterações de tool calls antes de terminar. É normal ver Claude Code "pensando" por alguns minutos em tarefas grandes. Cada iteração consome tokens — por isso a janela de contexto importa.

📄 Ferramentas disponíveis

Claude Code disponibiliza um conjunto de ferramentas nativas que o modelo pode invocar. Cada ferramenta tem um propósito específico e diferentes implicações de segurança.

Read

Leitura de Arquivos

Lê o conteúdo de qualquer arquivo do projeto. Operação somente leitura — nunca modifica nada.

            # Exemplo de uso pelo modelo:

            Read("src/components/Button.tsx")

            Read("package.json")

            Read("src/**/*.ts", offset=100, limit=50)

Edit

Edição de Arquivos

Substitui um trecho específico de um arquivo existente. Mais seguro que Write — não apaga o arquivo inteiro.

            # Substitui old_string por new_string no arquivo:

            Edit(

              file_path="src/auth.js",

              old_string="function login(user) {",

              new_string="async function login(user) {"

            )

Write

Criação/Sobrescrita de Arquivos

Cria um novo arquivo ou sobrescreve um existente com conteúdo completo. Usado para novos arquivos ou rewrites completos.

            # Cria ou sobrescreve completamente:

            Write(

              file_path="src/utils/format.ts",

              content="export function formatDate..."

            )

Bash

Execução de Comandos

Executa qualquer comando bash. A ferramenta mais poderosa — e a que pede confirmação por padrão. Pode rodar testes, instalar pacotes, git, etc.

            # Exemplos reais de uso:

            Bash("npm test")

            Bash("git diff HEAD")

            Bash("npm install axios")

            Bash("find . -name '*.test.ts'")

WebSearch

Busca na Web

Busca informações atualizadas na internet. Útil para documentação de API, erros de dependências e informações que não estão no projeto.

            # Busca informações externas:

            WebSearch("React 19 useTransition changes")

            WebSearch("axios 1.6 breaking changes")

💡 MCP expande as ferramentas

O Model Context Protocol (MCP) permite adicionar ferramentas externas: banco de dados, Slack, GitHub, Jira, e qualquer API. As trilhas avançadas cobrem MCP em detalhes.

🪟 Janela de contexto

A janela de contexto é o espaço de memória de trabalho do modelo. Tudo que ele "vê" durante a sessão — conversa, arquivos lidos, resultados de comandos — ocupa tokens nessa janela. Quando enche, informações antigas são descartadas.

O que ocupa tokens na janela

💬

Histórico de conversa

Todas as mensagens trocadas na sessão

📄

Conteúdo de arquivos

Cada arquivo lido via ferramenta Read

⚡

Resultados de comandos

Output de cada comando Bash executado

📊 Limites típicos por modelo

Modelo	Janela de Contexto	Aprox. em código
Claude Sonnet/Opus	200.000 tokens	~5.000 arquivos médios
Qwen3.5-397B	128.000 tokens	~3.000 arquivos médios
Llama 3.3 70B	128.000 tokens	~3.000 arquivos médios
Gemma 3 27B	8.192 tokens	~200 arquivos médios

💡 Dica: autoCompactThreshold

Configure no settings.json para compactar automaticamente quando atingir 75% da janela:

          {

            "autoCompactThreshold": 75

          }

Ou use /compact manualmente quando sentir a sessão pesada.

📝 O arquivo CLAUDE.md

CLAUDE.md é o arquivo de instruções persistentes do Claude Code. Ele é lido automaticamente no início de cada sessão e inserido no contexto do modelo — como um system prompt personalizado para o seu projeto.

Exemplo de CLAUDE.md básico

          # CLAUDE.md — Projeto: E-commerce API

          ## Stack

          - Node.js 20 + Express 5

          - PostgreSQL com Prisma ORM

          - TypeScript strict mode

          ## Convenções

          - Funções async/await (nunca callbacks)

          - Erros via Result type (nunca throw direto)

          - Testes em Jest, coverage mínimo 80%

          ## Estrutura

          - src/routes/ — apenas roteamento

          - src/services/ — lógica de negócio

          - src/repositories/ — acesso ao banco

          ## Importante

          - Nunca commitar .env

          - Rodar `npm test` antes de qualquer commit

✓ O que colocar no CLAUDE.md

✓Stack tecnológica e versões
✓Convenções de código do projeto
✓Estrutura de pastas importante
✓Comandos de build/test do projeto
✓Regras e restrições específicas

✗ O que NÃO colocar

✗Senhas ou chaves de API
✗Informações que mudam frequentemente
✗Todo o README do projeto (muito longo)
✗Exemplos de código extensos
✗Instruções para outras ferramentas

🔒 Permissões e segurança

Claude Code tem um sistema de permissões para proteger seu sistema. Por padrão, operações destrutivas precisam de confirmação. Você pode relaxar ou restringir essas permissões no settings.json.

Comportamento padrão por ferramenta

Ferramenta	Padrão	Risco
Read	Automático	Baixo
Edit / Write	Automático (com diff)	Médio
Bash	Pede confirmação	Alto
WebSearch	Automático	Baixo

Configurando permissões no settings.json

          {

            "permissions": {

              // Permite Bash sem confirmar (use com cuidado):

              "allow": ["Bash"],

              // Ou apenas comandos específicos:

              "allow": ["Bash(npm test)", "Bash(git *)"],

              // Bloqueia completamente:

              "deny": ["Bash(rm *)"]

            }

          }

🔌 ANTHROPIC_BASE_URL

ANTHROPIC_BASE_URL é a variável que determina para onde Claude Code envia as chamadas de API. Por padrão, aponta para https://api.anthropic.com. Troque para Ollama ou OpenRouter e use de graça.

Para Ollama (local)

            # No settings.json:

            {

              "env": {

                "ANTHROPIC_BASE_URL": "http://localhost:11434",

                "ANTHROPIC_API_KEY": "ollama"

              }

            }

Para OpenRouter (nuvem)

            # No settings.json:

            {

              "env": {

                "ANTHROPIC_BASE_URL": "https://openrouter.ai/api/v1",

                "ANTHROPIC_API_KEY": "sk-or-v1-sua-chave-aqui"

              }

            }

Ou via variável de ambiente (sessão)

            # Linux / Mac (apenas sessão atual):

            export ANTHROPIC_BASE_URL="http://localhost:11434"

            export ANTHROPIC_API_KEY="ollama"

            # Depois abra o Claude Code normalmente:

            claude

💡 settings.json > export

Prefira configurar no settings.json em vez de export. O settings persiste entre sessões e não precisa ser repetido toda vez que você abre o terminal. As Trilhas 2, 3 e 4 ensinam a configuração passo a passo para cada opção.

✅ Resumo do Módulo 1.2

✓

Loop agente — CC itera entre modelo e ferramentas até completar a tarefa

✓

5 ferramentas nativas — Read, Edit, Write, Bash, WebSearch

✓

Janela de contexto — memória limitada, gerenciar com /compact ou autoCompactThreshold

✓

CLAUDE.md — instruções persistentes lidas automaticamente em cada sessão

✓

ANTHROPIC_BASE_URL — o "interruptor" para trocar o motor de modelo

Próximo Módulo:

1.3 — 📋 Conceitos Essenciais: tokens, compactação, API Key, settings.json e variáveis de ambiente

← Módulo Anterior Próximo Módulo →