Claude Code: Modo Interativo e Guia de Operação

Q: P: O modo headless é seguro?

R: --headless apenas remove a UI; operações ainda requerem controle de permissão. Mas --allow-full-auto aprova todas as operações automaticamente — alto risco, apenas recomendado em ambientes de CI.

Última atualização: 2026-08-31

O Claude Code oferece múltiplos modos de interação, desde conversas no terminal até automação via pipeline, cada um adequado para diferentes cenários.

💡 Dica: Modo interativo é para conversar com o Claude Code; modo pipeline é para scripts chamarem o Claude Code; modo headless é para automação sem UI.

📋 Pré-requisitos: Capítulo 6 - Inicialização de Projeto e Estrutura

1. O Que Você Vai Aprender

Três modos de interação e casos de uso
Dicas de operação em sessão interativa
Input/output do modo pipeline
Cenários de automação do modo headless
Interrupção, retomada e gerenciamento multi-sessão

2. Três Modos de Interação

(1) Visão Geral dos Modos

Modo	Método de Lançamento	Caso de Uso	Interação Humana
Interativo	`claude`	Desenvolvimento diário, programação exploratória	Interação completa
Pipeline	`echo "..." \| claude`	Tarefas únicas rápidas	Semi-interativo
Headless	`claude --headless`	CI/CD, scripts de automação	Sem interação

(2) Decisão de Seleção de Modo

graph TD
    A[Precisa do Claude Code] --> B{Precisa de interação?}
    B -->|Sim| C{Única ou múltiplas rodadas?}
    B -->|Não| D[Modo Headless]
    C -->|Múltiplas| E[Interativo]
    C -->|Única| F[Modo Pipeline]
    D --> D1[CI/CD]
    D --> D2[Scripts em lote]
    E --> E1[Desenvolvimento diário]
    E --> E2[Refatoração complexa]
    F --> F1[Consulta rápida]
    F --> F2[Modificação de arquivo único]

3. Modo Interativo

(1) Lançamento e Operações

BASH

# Lançamento padrão
claude

# Lançamento com instrução inicial
claude "Analyze project structure"

# Retomar última sessão
claude --resume

# Especificar modelo
claude --model claude-opus-4-20250514

(2) Controle de Operações na Sessão

Operação	Tecla/Comando	Descrição
Enviar instrução	Enter	Enviar input atual
Nova linha	Shift+Enter	Input de múltiplas linhas
Interromper	Ctrl+C	Parar operação atual
Sair	Ctrl+D ou `/exit`	Sair do Claude Code
Limpar contexto	`/clear`	Limpar histórico de conversa
Ver ajuda	`/help`	Mostrar comandos disponíveis

▶ Exemplo 1: Fluxo de Sessão Interativa

TEXT 📖 Somente leitura

$ claude

> Show me the utility functions under src/utils/

Claude: Reading src/utils/...
  - date.ts      formatDate(), relativeTime()
  - string.ts    capitalize(), truncate()
  - validation.ts isValidEmail(), isValidPhone()

> Add a slugify function to string.ts

Claude: Adding slugify() to src/utils/string.ts...
  → Reading src/utils/string.ts
  → Adding slugify function with tests
  → Running: npm test -- string.test.ts
  ✅ All tests passed

> Also add a camelToSnake conversion function

Claude: Adding camelToSnake() to src/utils/string.ts...
  → Reading src/utils/string.ts
  → Adding camelToSnake with tests
  → Running: npm test -- string.test.ts
  ✅ All tests passed

4. Modo Pipeline

(1) Uso Básico

BASH

# Passar instrução via stdin
echo "Explain this function's purpose" | claude

# Passar conteúdo de arquivo para o Claude Code
cat src/auth.ts | claude "Review this code's security"

# Uso combinado
git diff | claude "Review these changes, identify potential issues"

(2) Controle de Saída

BASH

# Saída em texto simples (sem confirmação interativa)
claude -p "List all TODO comments" --output text

# Saída em formato JSON
claude -p "Analyze project dependencies" --output json

# Modo silencioso (apenas resultados)
echo "Run tests" | claude --quiet

▶ Exemplo 2: Aplicações Práticas do Modo Pipeline

BASH

# Automação de code review
git diff main..feature | claude "Review changes:
1. Security vulnerabilities
2. Code style compliance
3. Missing tests"

# Geração de documentação em lote
for file in src/*.ts; do
  echo "Generate JSDoc comments for $file" | claude --quiet >> docs/api.md
done

# Consulta rápida
echo "What outdated dependencies are in package.json?" | claude

5. Modo Headless

(1) Método de Lançamento

BASH

# Sem UI (auto-aprovar operações)
claude --headless "Run full tests and fix all failing cases"

# Especificar formato de saída
claude --headless --output json "Analyze code quality"

# Com CI/CD
claude --headless --allow-full-auto "Code review and auto-fix lint issues"

(2) Considerações de Segurança

Parâmetro	Nível de Risco	Descrição
`--headless`	Médio	Executa automaticamente mas precisa de permissões pré-aprovadas
`--allow-full-auto`	Alto	Totalmente automático, todas as operações sem confirmação
`--allowed-tools`	Baixo	Apenas permite ferramentas especificadas

▶ Exemplo 3: Modo Headless no CI/CD

YAML

# GitHub Actions config
name: AI Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --headless --output json \
            "Review this PR's changes, check:
            1. Security vulnerabilities
            2. Performance issues
            3. Code style
            Output JSON format report"

6. Gerenciamento Multi-Sessão

(1) Retomada de Sessão

BASH

# Listar sessões históricas
claude --list-sessions

# Retomar sessão específica
claude --resume <session-id>

# Retomar sessão mais recente
claude --resume

(2) Alternando Entre Sessões

TEXT 📖 Somente leitura

# Alice lidando com múltiplas tarefas simultaneamente

# Tarefa 1: Refatoração frontend
cd frontend && claude
> Refactor component structure...

# Ctrl+D para sair

# Tarefa 2: API Backend
cd backend && claude
> Add new endpoint...

# Retomar tarefa 1
cd frontend && claude --resume

7. Exemplo Completo: Colaboração Multi-Modo

BASH

# Fluxo de trabalho diário de desenvolvimento da Alice

# Manhã: Exploração em modo interativo
claude "Check yesterday's TODOs, help me handle each one"

# Meio-dia: Correção rápida em modo pipeline
git diff | claude "Fix these lint errors" | git apply

# Tarde: Desenvolvimento profundo em modo interativo
claude "Implement RBAC model for user permission system"

# Noite: Verificação completa em modo headless
claude --headless --allowed-tools Read,Write,Bash \
  "Run full tests, fix all failing cases, don't modify test assertions"

# CI: Review automático em modo headless
claude --headless --output json "Code review"

❓ Perguntas Frequentes

P: Posso alternar entre modos interativo e pipeline? R: Não. O modo é selecionado no lançamento e não pode ser trocado durante a execução. Saia e relance para um modo diferente.

P: O modo headless é seguro? R: --headless apenas remove a UI; operações ainda requerem controle de permissão. Mas --allow-full-auto aprova todas as operações automaticamente — alto risco, apenas recomendado em ambientes de CI.

P: Como interromper a execução do Claude Code? R: Pressione Ctrl+C para interromper a operação atual sem perder modificações existentes. Ctrl+D sai da sessão inteira.

P: Por quanto tempo o histórico de sessões é mantido? R: O histórico de sessões é salvo localmente, retendo os últimos 30 dias por padrão. Visualize com --list-sessions.

P: O modo pipeline suporta conversa de múltiplas rodadas? R: Não. O modo pipeline é input/output único. Use o modo interativo para múltiplas rodadas.

P: Como determinar se o Claude Code executou com sucesso em um script? R: Verifique códigos de saída: 0=sucesso, 1=falha, 2=interrompido.

📖 Resumo

Três modos: Interativo (diário), Pipeline (tarefa única rápida), Headless (automação)
Modo interativo suporta conversa de múltiplas rodadas, Ctrl+C interrompe, Ctrl+D sai
Modo pipeline se adequa a tarefas únicas, combinável com git diff e outros comandos
Modo headless para CI/CD; --allow-full-auto requer cautela
Sessões podem ser retomadas, suportando paralelismo de múltiplas tarefas

📝 Exercícios

Básico (⭐): Complete a mesma tarefa usando modos interativo e pipeline, compare diferenças de operação.
Intermediário (⭐⭐): Implemente fluxo automatizado de code review com git diff | claude "code review".
Avançado (⭐⭐⭐): Configure um workflow do GitHub Actions para executar automaticamente code review do Claude Code em PRs.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós