Modulo 1.3 - Flags de Linha de Comando | 6 Pilares do Claude Code Resumido

⚡ -p (Prompt Direto) - Execucao sem Sessao Interativa

A flag -p (ou --print) e a porta de entrada para usar o Claude Code em modo nao-interativo. Em vez de abrir uma sessao de conversa, voce envia um prompt unico, recebe a resposta e volta ao shell. Sem REPL, sem historico, sem sessao persistente. Pensa nela como um curl para inteligencia artificial.

🎯 Conceito Principal

O modo interativo do Claude Code e otimo para sessoes de trabalho longas. Mas quando voce precisa de uma resposta pontual, rodar um script ou integrar com outras ferramentas, o modo interativo atrapalha. A flag -p resolve isso: executa, responde e sai.

• Execucao unica: Envia o prompt, recebe a resposta no stdout e o processo termina. Nao ha sessao para gerenciar
• Compativel com pipes: Voce pode alimentar o Claude com dados via stdin usando pipe, tornando-o parte de qualquer pipeline Unix
• Ideal para automacao: Cron jobs, scripts de CI/CD, git hooks, pre-commit checks, tudo funciona com -p
• Sem estado: Cada execucao e independente. Nao ha memoria entre chamadas. Se precisa de contexto, passe tudo no prompt ou via pipe

💻 Exemplos Praticos

Prompt direto simples:

claude -p "explique o que faz o comando chmod 755"

Combinando com pipe para analisar um arquivo:

cat src/api/auth.py | claude -p "encontre vulnerabilidades de seguranca neste codigo"

Gerando codigo e salvando direto num arquivo:

claude -p "gere um Dockerfile para uma app Node.js com pnpm" > Dockerfile

Pipeline com diff do git para review automatico:

git diff --staged | claude -p "faca code review dessas mudancas. seja direto e aponte problemas"

💡 Dica Pratica

A flag -p nao le o CLAUDE.md do diretorio automaticamente em todas as situacoes. Se voce precisa que instrucoes do projeto sejam respeitadas em chamadas com -p, passe o conteudo via pipe ou inclua no prompt. Para automacoes mais robustas, considere usar --system-prompt junto com -p.

Crie aliases no seu .bashrc ou .zshrc para comandos que voce roda com frequencia. Exemplo: alias cr='git diff --staged | claude -p "code review direto e conciso"'

✓ O que FAZER

✓ Usar -p para tarefas pontuais: explicar, gerar, converter, analisar
✓ Combinar com pipes para alimentar o Claude com dados reais
✓ Integrar em scripts de CI/CD e git hooks para automacoes

✗ O que NAO fazer

✗ Usar -p para tarefas que precisam de multiplas iteracoes (abra sessao interativa)
✗ Esperar que -p lembre de chamadas anteriores (cada execucao e isolada)
✗ Enviar arquivos gigantes via pipe sem limitar o tamanho (consome tokens desnecessarios)

🧩 --model - Escolhendo o Modelo Certo

A flag --model permite selecionar qual modelo de IA vai processar suas instrucoes. Cada modelo tem um perfil distinto de capacidade, velocidade e custo. Escolher o modelo certo para cada tarefa e a diferenca entre gastar centavos e gastar dolares pelo mesmo resultado.

🎯 Conceito Principal

O Claude Code suporta tres familias principais de modelos. A escolha impacta diretamente na qualidade da resposta, velocidade de execucao e custo por token. Nao existe modelo "melhor" em absoluto. Existe o modelo certo para cada situacao.

• Opus (opus): O mais capaz. Ideal para decisoes de arquitetura, debugging complexo, refactoring de sistemas inteiros e tarefas que exigem raciocinio profundo. Mais lento e mais caro
• Sonnet (sonnet): O equilibrado. Cobre 80% dos casos de uso no dia a dia: implementacao de features, debugging padrao, code review, documentacao. Boa velocidade com custo razoavel
• Haiku (haiku): O rapido e barato. Perfeito para tarefas simples: formatacao, perguntas diretas, gerar boilerplate, conversoes triviais. Resposta quase instantanea com custo minimo

💻 Sintaxe e Exemplos

Iniciar sessao interativa com Opus:

claude --model opus

Prompt rapido com Haiku (barato e instantaneo):

claude -p "converta esse JSON para YAML" --model haiku < config.json

Sonnet para desenvolvimento diario:

claude --model sonnet

📊 Quando Usar Cada Modelo

Opus: Redesign de arquitetura, decisoes que afetam todo o projeto, debugging de bugs que ninguem encontra, analise profunda de trade-offs
Sonnet: Implementar endpoints, criar componentes, escrever testes, fazer code review, refatorar funcoes individuais
Haiku: Formatar JSON/YAML, gerar regex, responder perguntas de sintaxe, criar boilerplate, renomear variaveis em massa
Regra geral: Comece com Sonnet. Suba para Opus quando a tarefa exigir raciocinio profundo. Descha para Haiku quando for mecanico

💡 Dica Pratica

Voce pode configurar o modelo padrao no arquivo de configuracao do Claude Code para nao precisar passar --model toda vez. Mas mantenha o habito de trocar de modelo conscientemente conforme a tarefa. Usar Opus para formatar um JSON e como usar um caminhao para ir na padaria.

Dentro de uma sessao interativa, voce pode trocar o modelo usando /model. Isso permite comecar uma tarefa com Sonnet e, quando encontrar um problema complexo, mudar para Opus sem sair da sessao.

✓ O que FAZER

✓ Escolher o modelo com base na complexidade da tarefa, nao no habito
✓ Usar Haiku em automacoes repetitivas para economizar
✓ Reservar Opus para momentos onde qualidade maxima e necessaria

✗ O que NAO fazer

✗ Usar sempre Opus para tudo (caro e desnecessario na maioria dos casos)
✗ Usar Haiku para tarefas que exigem raciocinio profundo (vai errar e custar mais no refazer)
✗ Ignorar a existencia de --model e usar sempre o padrao sem pensar

🔄 --resume - Retomando Sessoes Anteriores

A flag --resume permite retomar uma sessao anterior exatamente de onde parou. Todo o contexto, decisoes tomadas, arquivos discutidos e estado da tarefa sao preservados. E como fechar o laptop na sexta e reabrir na segunda com tudo no lugar.

🎯 Conceito Principal

Cada sessao do Claude Code recebe um ID unico. Quando voce encerra uma sessao (Ctrl+C ou /exit), ela nao e destruida. O historico fica armazenado localmente e pode ser retomado a qualquer momento. O --resume recarrega esse historico completo.

• Sem argumento: claude --resume retoma a sessao mais recente automaticamente
• Com ID especifico: claude --resume SESSION_ID retoma uma sessao especifica, mesmo que nao seja a mais recente
• Contexto preservado: Todas as mensagens, decisoes, arquivos lidos e modificados ficam no historico. O Claude retoma com conhecimento completo do que foi feito
• Limite de contexto: Sessoes muito longas podem precisar de /compact apos resume, ja que todo o historico e recarregado na janela de contexto

💻 Exemplos Praticos

Retomar a sessao mais recente:

claude --resume

Retomar uma sessao especifica pelo ID:

claude --resume abc123-def456-ghi789

Listar sessoes anteriores para escolher qual retomar:

claude --resume  # sem ID, mostra lista de sessoes recentes para selecionar

Retomar e continuar com prompt direto:

claude --resume -p "continue implementando os testes que faltaram"

🔍 Cenarios de Uso

Projetos multi-dia: Comecou uma feature na segunda, retoma na terca sem perder contexto de arquitetura e decisoes
Interrupcoes: Almoco, reuniao, fim do dia. O --resume garante que voce volta exatamente de onde parou
Debugging longo: Quando um bug leva horas para rastrear, poder fechar e reabrir sem recomecar do zero e essencial
Revisao: Retomar uma sessao antiga para revisar decisoes que foram tomadas e entender o raciocinio

💡 Dica Pratica

Antes de fechar uma sessao que voce pretende retomar, diga ao Claude algo como "vou pausar aqui. quando eu voltar, continue a partir dos testes de integracao do modulo de pagamentos". Isso cria um marco claro no historico que facilita a retomada.

Se a sessao retomada estiver com contexto muito cheio, rode /compact foco no estado atual da tarefa e proximos passos logo apos o resume. Isso limpa o historico antigo mas preserva o que importa para continuar.

✓ O que FAZER

✓ Usar --resume para projetos que duram mais de uma sessao
✓ Deixar um "marco" antes de fechar a sessao para facilitar a retomada
✓ Rodar /compact apos resume se a sessao era longa

✗ O que NAO fazer

✗ Comecar sessao nova para cada tarefa pequena de um mesmo projeto
✗ Retomar sessoes muito antigas sem verificar se o contexto ainda e relevante
✗ Assumir que --resume funciona entre maquinas diferentes (o historico e local)

🔒 --allowedTools - Controle de Ferramentas

A flag --allowedTools restringe quais ferramentas o Claude pode usar durante a sessao. Em vez de ter acesso total a Bash, Read, Write, Edit e todas as ferramentas dos MCPs, voce define um subconjunto especifico. E o princípio do menor privilegio aplicado a IA.

🎯 Conceito Principal

Por padrao, o Claude Code tem acesso a um conjunto amplo de ferramentas: executar comandos no terminal (Bash), ler arquivos (Read), escrever arquivos (Write), editar arquivos (Edit), buscar na web e todas as ferramentas de MCPs configurados. Em muitos cenarios, voce quer limitar esse acesso.

• Seguranca: Em ambientes de producao, voce pode querer que o Claude so leia arquivos, sem executar comandos ou modificar nada
• Previsibilidade: Em automacoes, restringir ferramentas garante que o Claude faca apenas o esperado, sem surpresas
• Auditoria: Quando voce precisa provar que uma IA so leu dados e nao modificou nada, o --allowedTools e a evidencia

💻 Exemplos Praticos

Somente leitura (Read e Grep, sem execucao ou escrita):

claude --allowedTools Read,Grep -p "analise a estrutura deste projeto"

Leitura e escrita, mas sem Bash (nao executa comandos):

claude --allowedTools Read,Write,Edit,Grep,Glob

Somente Bash para operacoes de infra:

claude --allowedTools Bash -p "verifique o status dos containers docker"

Incluir ferramentas de MCP especificos:

claude --allowedTools Read,Grep,mcp_github

⚠️ Atencao

Se voce restringir demais, o Claude pode nao conseguir completar a tarefa. Por exemplo, se pedir para ele "corrigir um bug" mas so permitir Read, ele vai identificar o problema mas nao vai conseguir editar o arquivo. Pense nas ferramentas como permissoes: de acesso suficiente para a tarefa, nem mais, nem menos.

💡 Dica Pratica

Para automacoes em CI/CD, use a combinacao --allowedTools Read,Grep -p para tarefas de analise (code review, verificacao de padroes, auditoria). Isso garante que o Claude nunca modifica nada no pipeline, apenas analisa e reporta.

Voce pode usar /status dentro da sessao para verificar quais tools estao disponiveis. Se uma tool nao aparece, e porque foi restrita pelo --allowedTools.

✓ O que FAZER

✓ Restringir ferramentas em automacoes e pipelines de CI/CD
✓ Usar modo somente leitura para auditorias e analises
✓ Documentar quais tools cada script de automacao usa

✗ O que NAO fazer

✗ Restringir ferramentas em sessoes interativas de desenvolvimento (atrapalha o fluxo)
✗ Pedir tarefas que exigem tools que voce bloqueou
✗ Ignorar --allowedTools em ambientes de producao por "praticidade"

📤 --output-format - Formato de Saida Estruturado

A flag --output-format define como o Claude Code formata sua resposta. Em vez de texto livre para humanos lerem, voce pode pedir saida em JSON estruturado ou JSON em streaming. Isso transforma o Claude Code de um assistente conversacional em um componente programatico de qualquer pipeline.

🎯 Conceito Principal

Existem tres formatos de saida disponiveis. Cada um atende um caso de uso diferente:

• text (padrao): Texto livre formatado para leitura humana. Inclui markdown, blocos de codigo, listas. E o que voce ve normalmente no terminal
• json: Saida estruturada em JSON. Ideal para automacoes que precisam parsear a resposta programaticamente. O resultado inteiro vem como um objeto JSON valido
• stream-json: JSON em streaming, onde cada evento (texto gerado, tool call, resultado) vem como uma linha JSON separada. Perfeito para UIs em tempo real que mostram o progresso da geracao

💻 Exemplos Praticos

Saida JSON para processamento automatico:

claude -p "liste os 5 maiores arquivos deste projeto" --output-format json

JSON + jq para extrair campos especificos:

claude -p "analise este codigo" --output-format json | jq '.result'

Stream JSON para interfaces em tempo real:

claude -p "implemente a funcao de login" --output-format stream-json

Pipeline completo: analise + parse + acao:

cat src/*.ts | claude -p "encontre funcoes sem tipagem" \
  --output-format json --model haiku | jq '.result' > report.txt

📊 Comparacao de Formatos

text: Legivel por humanos, nao parseavel de forma confiavel. Use quando voce vai ler o resultado no terminal
json: Parseavel, estruturado, chega completo. Use em scripts que processam a resposta inteira de uma vez
stream-json: Parseavel, em tempo real, chega incrementalmente. Use em dashboards, UIs web ou apps que mostram progresso
Regra: Se um humano vai ler, use text. Se uma maquina vai processar, use json. Se uma UI vai exibir em tempo real, use stream-json

💡 Dica Pratica

Combine --output-format json com jq para criar pipelines poderosos. O jq e um processador de JSON na linha de comando que permite filtrar, transformar e extrair dados da saida do Claude de forma precisa.

Para integracoes com Node.js ou Python, o formato json permite que voce faca JSON.parse() ou json.loads() diretamente na saida, sem precisar de regex ou parsing manual de texto.

✓ O que FAZER

✓ Usar json em toda automacao que precisa processar a resposta
✓ Combinar com jq para extrair exatamente o campo que precisa
✓ Usar stream-json quando precisa mostrar progresso ao usuario

✗ O que NAO fazer

✗ Tentar parsear saida text com regex (fragil e imprevisivel)
✗ Usar json na sessao interativa (a saida fica ilegivel para humanos)
✗ Ignorar --output-format e fazer parsing manual de texto em automacoes

🧬 Combinando Flags - Receitas Avancadas de CLI

Cada flag individual tem seu valor. Mas o poder real aparece quando voce combina multiplas flags em um unico comando. Essas combinacoes criam receitas reutilizaveis para tarefas especificas: review automatico, documentacao sob demanda, auditoria de seguranca, e mais.

🎯 Receitas Prontas

Estas sao combinacoes testadas que resolvem problemas reais do dia a dia. Copie, adapte e crie aliases para as que voce mais usa.

• Review rapido e barato: Combina -p + --model haiku + pipe do git diff para code review instantaneo e economico
• Analise profunda: Combina -p + --model opus + --output-format json para analise estruturada de alta qualidade
• Auditoria segura: Combina --allowedTools Read,Grep + -p + --output-format json para auditorias somente leitura com saida parseavel
• Retomada com modelo especifico: Combina --resume + --model opus para retomar uma sessao com o modelo mais potente

💻 Receitas Completas

Code review automatico (rapido e barato):

git diff --staged | claude -p "code review direto. aponte bugs, \
  problemas de performance e sugestoes" --model haiku

Gerar documentacao estruturada em JSON:

cat src/api/*.ts | claude -p "documente todas as funcoes exportadas \
  com parametros, retorno e descricao" \
  --model sonnet --output-format json > docs/api.json

Auditoria de seguranca somente leitura:

claude -p "audite este projeto por vulnerabilidades de seguranca" \
  --allowedTools Read,Grep --model opus --output-format json \
  > security-audit.json

Retomar sessao com modelo diferente:

claude --resume --model opus

Alias no .zshrc para uso diario:

# Code review rapido
alias cr='git diff --staged | claude -p "code review conciso" --model haiku'

# Explicar arquivo
alias explain='claude -p "explique o que este arquivo faz" --model sonnet'

# Gerar testes
alias gentest='claude -p "gere testes unitarios para este arquivo" --model sonnet'

Para Scripts de CI/CD

Automacao de pipeline

Use -p + --output-format json + --allowedTools Read,Grep + --model haiku. Garante execucao rapida, saida parseavel, sem modificacoes no repo e custo minimo. O JSON pode ser processado pelo proximo step do pipeline.

Para Desenvolvimento Diario

Fluxo de trabalho interativo

Use --model sonnet para a sessao interativa padrao. Quando encontrar algo complexo, troque para --model opus via /model ou reinicie com --resume --model opus.

Para Documentacao e Reports

Geracao de conteudo estruturado

Use -p + --model sonnet + --output-format json com pipe de arquivos fonte. Processe o JSON com jq ou seu script favorito para gerar markdown, HTML ou qualquer formato de saida desejado.

💡 Dica Pratica

Crie um diretorio ~/scripts/claude/ com scripts shell para suas receitas favoritas. Cada script encapsula uma combinacao de flags para um caso de uso especifico. Isso e mais flexivel que aliases porque permite logica condicional, variaveis e composicao.

Exemplo de script reutilizavel: um review.sh que aceita o branch como argumento, faz diff, envia para o Claude com --model haiku, formata a saida com --output-format json e salva o report num arquivo datado.

✓ O que FAZER

✓ Criar aliases e scripts para combinacoes que voce usa com frequencia
✓ Documentar suas receitas para o time reutilizar
✓ Testar receitas novas em repos de teste antes de usar em producao

✗ O que NAO fazer

✗ Memorizar combinacoes de flags sem criar aliases (vai esquecer a sintaxe)
✗ Usar combinacoes complexas sem testar antes (debug e dificil com multiplas flags)
✗ Hardcodar session IDs em scripts (eles mudam a cada sessao)

📋 Resumo do Modulo

✓

-p transforma o Claude em ferramenta de linha de comando - Execucao unica, compativel com pipes, ideal para scripts e automacoes

✓

--model seleciona a ferramenta certa para o trabalho - Opus para complexidade, Sonnet para o dia a dia, Haiku para rapidez e economia

✓

--resume preserva contexto entre sessoes - Essencial para projetos multi-dia e interrupcoes no fluxo de trabalho

✓

--allowedTools garante seguranca e previsibilidade - Principio do menor privilegio para automacoes e ambientes sensiveis

✓

--output-format integra o Claude em pipelines - JSON para automacoes, stream-json para UIs em tempo real, text para humanos

✓

Combinar flags cria receitas reutilizaveis - Aliases, scripts e pipelines que automatizam tarefas repetitivas do dia a dia

Modulo Anterior:

Proximo Modulo:

1.2 - Slash Commands Nativos

1.4 - Pipe de Dados

← Modulo Anterior Voltar para Trilha Proximo Modulo →