← Voltar ao curso
Nível 3 — Automação e escala · Módulo 3.5 — Automação: routines, headless e CI

3.5.2 · Headless com `-p`

4 min de vídeo TEC BASIS

Objetivo: ao final, o consultor roda o Claude Code como um comando de shell dentro de um pipeline, e sabe exatamente qual flag garante que o resultado não dependa da máquina onde rodou.

O que você precisa levar desta aula

  1. -p (ou --print) roda o Claude uma vez, sem interface: lê a entrada padrão, escreve na saída padrão e encerra — é um comando de shell como qualquer outro, com teto de 10 MB no stdin.
  2. -p não pula a descoberta do ambiente local. Sem flag adicional, ele carrega o mesmo contexto de uma sessão interativa: hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. A flag que pula tudo isso é --bare.
  3. Para execução desassistida, combine --bare com --permission-mode dontAsk (módulo 2.5.3) ou --allowedTools, e autentique por ANTHROPIC_API_KEY — porque bare também pula OAuth e keychain.

O que -p faz

git diff main...release/qas-0730 | claude -p "resuma as mudanças deste diff como nota de transporte: um bullet por objeto, com o impacto funcional"
Comportamento Detalhe
Roda uma vez, sem interface Faz o trabalho e encerra; nenhuma tela interativa
Lê a entrada padrão Aceita pipe de qualquer comando; limite de 10 MB — acima disso, encerra com erro e status diferente de zero
Escreve na saída padrão Redireciona para arquivo, encadeia em pipe, alimenta outro programa
Aceita todas as flags do CLI Inclusive --allowedTools, --continue, --output-format, --permission-mode
Aceita skill e comando no prompt /nome-da-skill dentro da string do prompt é expandido antes de rodar. Comandos que só existem no terminal, como /login, não funcionam

A correção que importa: -p não roda limpo

Esta é a afirmação que mais circula errada sobre headless, e vale ler duas vezes:

Sem --bare, claude -p carrega o mesmo contexto que uma sessão interativa carregaria, incluindo qualquer coisa configurada na pasta de trabalho e no ~/.claude da máquina.

Na prática, isso significa que um claude -p dentro de um pipeline pode se comportar de forma diferente em duas máquinas:

O que existe na máquina Com -p sozinho Com --bare -p
Hook no ~/.claude de quem rodou Roda Não roda
Servidor MCP no .mcp.json do projeto Sobe Não sobe
Skills e plugins instalados Carregam Não carregam
Memória automática e CLAUDE.md Entram no contexto Não entram
Ferramentas disponíveis As do ambiente + o que você autorizar Bash, leitura e edição de arquivo + o que você passar por flag

Para CI e script, é --bare que dá o mesmo resultado em toda máquina, porque ele simplesmente nunca lê essas fontes. A documentação recomenda --bare como o modo padrão para chamada de script e SDK, e avisa que ele deve se tornar o comportamento padrão de -p numa versão futura — mais uma razão para escrever o script já com a flag explícita, em vez de depender do padrão de hoje.

Como carregar contexto em modo bare

Para carregar Use
Instrução de sistema adicional --append-system-prompt, --append-system-prompt-file
Settings --settings <arquivo-ou-json>
Servidor MCP --mcp-config <arquivo-ou-json>
Agentes customizados --agents <json>
Plugin --plugin-dir <caminho>, --plugin-url <url>

Autenticação em modo bare: como ele pula OAuth e leitura de keychain, defina ANTHROPIC_API_KEY no ambiente ou configure um apiKeyHelper no JSON de --settings. Amazon Bedrock, Google Cloud e Microsoft Foundry usam as credenciais habituais do provedor.

Permissão em execução desassistida — a ligação com 2.5.3

O módulo 2.5.3 já resolveu o "qual modo". Aqui é só como passar por linha de comando:

Forma Quando
--allowedTools "Read,Edit,Bash(git diff *)" Caso simples, com poucas ferramentas nomeadas. Segue a sintaxe de regra de permissão: o espaço antes do * importa
--permission-mode dontAsk Execução travada, de CI: nega tudo que não estiver nas suas regras de allow ou no conjunto de comandos somente-leitura, sem parar para perguntar
--permission-mode acceptEdits Deixa escrever arquivo e rodar comandos comuns de arquivo sem perguntar; outro comando de shell ainda precisa de allow explícito

Onde isso se aplica de verdade num projeto SAP

Vale um reconhecimento honesto: a maior parte do trabalho ABAP não vive em git. Objeto ABAP mora no repositório do próprio sistema, e ordem de transporte não é commit. Headless não muda isso. Onde ele se aplica de fato no Meridiano:

Onde funciona Exemplo
Stack aberta — CAP, Fiori, extensões BTP Changelog de release, revisão de diff, geração de nota de transporte a partir do diff
Scripts operacionais de BASIS Resumir log de job, classificar dump, gerar relatório de execução em lote
Documentação versionada Verificar se a especificação funcional acompanhou a mudança de objeto
Artefatos exportados Diff de export de customizing ou de definição de objeto salvo em arquivo, versionado à parte

Para o mundo ABAP puro, o caminho não é headless em cima de git — é o Claude lendo artefatos exportados e documentação, que é justamente onde a Wayon versiona material de projeto.

Regra Wayon Todo claude -p que entra em pipeline ou script compartilhado leva --bare obrigatoriamente. Sem ela, o resultado passa a depender do que está instalado na máquina de quem rodou — hook de colega, servidor MCP de projeto, CLAUDE.md de outra pasta — e um pipeline que muda de comportamento por máquina não é um pipeline. Chave de API em pipeline sempre por secret do runner, nunca no arquivo do workflow.

📖 Run Claude Code programmatically · Bare mode · CLI reference

Quiz — 4 questões

1.Um consultor escreveu um passo de pipeline com claude -p e afirma na revisão: "não precisa se preocupar com o CLAUDE.md da pasta nem com os hooks da máquina, porque -p não carrega nada disso". A afirmação está:
  • a)Correta — -p é justamente o modo que roda sem o ambiente local

    É a crença mais comum sobre headless, e é falsa: -p sozinho carrega o mesmo contexto de uma sessão interativa.

  • b)Errada — sem --bare, -p carrega hooks, skills, plugins, MCP e CLAUDE.md como uma sessão normal

    Correto. É --bare que pula a descoberta; -p apenas tira a interface.

  • c)Correta para hooks e MCP, errada para CLAUDE.md

    Não há essa divisão: sem --bare, todas essas fontes são carregadas.

Ver resposta e por quê
❌a) É a crença mais comum sobre headless, e é falsa: -p sozinho carrega o mesmo contexto de uma sessão interativa.
✅b) Correto. É --bare que pula a descoberta; -p apenas tira a interface.
❌c) Não há essa divisão: sem --bare, todas essas fontes são carregadas.
2.O mesmo passo de pipeline produz resultados diferentes quando roda na máquina de dois consultores diferentes. A causa mais provável e a correção:
  • a)Diferença de versão do Claude Code entre as máquinas; fixe a versão no runner

    Pode acontecer, mas há uma causa muito mais comum quando a flag de isolamento está ausente.

  • b)Diferença de modelo; fixe com --model

    Mudaria o estilo da resposta, não explica comportamento divergente de ferramentas e hooks.

  • c)Cada máquina carrega o próprio ambiente (hooks do ~/.claude, MCP do projeto, CLAUDE.md); acrescente --bare

    Correto. --bare nunca lê essas fontes, e é por isso que ele é o modo recomendado para script e CI.

Ver resposta e por quê
❌a) Pode acontecer, mas há uma causa muito mais comum quando a flag de isolamento está ausente.
❌b) Mudaria o estilo da resposta, não explica comportamento divergente de ferramentas e hooks.
✅c) Correto. --bare nunca lê essas fontes, e é por isso que ele é o modo recomendado para script e CI.
3.Você acrescentou --bare ao comando do pipeline e a execução passou a falhar na autenticação, embora a mesma máquina rode claude interativo sem problema.
  • a)Modo bare pula OAuth e leitura de keychain — defina ANTHROPIC_API_KEY no ambiente ou um apiKeyHelper via --settings

    Correto. É a consequência direta de não ler as fontes locais.

  • b)--bare é incompatível com -p e por isso a sessão não autentica

    São combináveis; claude --bare -p é exatamente a forma recomendada.

  • c)É preciso rodar claude login antes de cada execução do pipeline

    Não resolve: bare não lê o resultado do login guardado no keychain.

Ver resposta e por quê
✅a) Correto. É a consequência direta de não ler as fontes locais.
❌b) São combináveis; claude --bare -p é exatamente a forma recomendada.
❌c) Não resolve: bare não lê o resultado do login guardado no keychain.
4.Um job de BASIS roda de madrugada com claude -p. Ele precisa ler arquivos de log e rodar dois comandos de git, e não pode ficar pendurado esperando aprovação que ninguém vai dar às 3h. ---
  • a)--permission-mode bypassPermissions, para garantir que nada bloqueie

    Remove toda checagem de segurança; pela regra Wayon (2.5.3), só dentro de container ou VM isolada, nunca num job com acesso a material de projeto.

  • b)Modo Manual, para que qualquer coisa inesperada fique registrada aguardando revisão

    Em Manual o job para no primeiro pedido de aprovação e fica pendurado a noite inteira — o problema exato que 2.5.3 descreve.

  • c)--allowedTools com as ferramentas exatas, ou --permission-mode dontAsk

    Correto. Don't ask nega o que não está pré-aprovado em vez de travar, e é o modo da execução desassistida.

Ver resposta e por quê
❌a) Remove toda checagem de segurança; pela regra Wayon (2.5.3), só dentro de container ou VM isolada, nunca num job com acesso a material de projeto.
❌b) Em Manual o job para no primeiro pedido de aprovação e fica pendurado a noite inteira — o problema exato que 2.5.3 descreve.
✅c) Correto. Don't ask nega o que não está pré-aprovado em vez de travar, e é o modo da execução desassistida.