結論：CIではbareを起点に必要物だけを足す

Claude Codeを無人実行する時は、claude --bare -pを起点に、credential、読込context、tool、出力schema、timeout、成功条件をjob側で明示します。-pだけではinteractive dialogがないままproject hooksやMCPを読み得ます。bare modeはauto-discoveryを止めますが、Bash・Read・Editという能力そのものを消す設定ではないため、taskとpermissionも狭くします。

読者の困りごとは、開発者端末では成功したscriptがCIで別のhookやpluginを読み、credentialを使い、stdoutの自然文だけを成功として後工程へ渡すことです。この記事を読むと、通常-pとbare modeを比較し、read-onlyから段階導入できます。

次の行動：一つのrepositoryで「READMEを読みJSONで要約する」だけのjobを選び、write・network・MCPなしで試してください。

公式仕様：bareが省くものと残すもの

公式headless文書では、-pまたは--printで非対話実行し、成功時はexit code 0、失敗時はnon-zeroを返します。invalid flagは開始前にstderrへ、authenticationなど実行中の失敗はresultとしてstdoutへ出る場合があります。したがってchannelだけでなくexit codeとpayloadの両方を検査します。

--bareはhooks、skills、plugins、MCP servers、auto memory、CLAUDE.mdの自動探索を省き、machineごとの差を減らします。未trust folderでも-pはdialogを出せないため、bareなしではproject settingsのhookや.mcp.jsonが動く可能性があります。bareはscriptとSDK callで公式推奨とされ、将来-pのdefaultになる予定です。

bare modeはClaude subscriptionのOAuth credentialやsystem keychainを読みません。Anthropic APIならCI secretとしてANTHROPIC_API_KEYを渡すか、--settings内のapiKeyHelperを明示します。Bedrock、Google Cloud、Microsoft Foundryは各provider credentialを使います。secretをprompt、log、artifactへ書かず、job identityと短い有効期間を優先します。

必要contextは--append-system-prompt、--settings、--mcp-config、--agents、--plugin-dirなどで個別指定します。stdinは10MB上限で、超える入力はfileへ置いてpathを示します。structured outputはtext、json、stream-jsonを選べ、JSON Schemaも指定できます。

通常-pとbare modeを7軸で比較する

  1. context：端末とprojectの設定を再利用するなら通常、同一入力を再現するならbareです。
  2. trust：interactive確認を前提にできないCIでは、repository由来の自動実行をbareで止めます。
  3. credential：通常はlogin状態に依存し得ますが、bareはAPI keyなどを明示します。
  4. tool：どちらでも能力を持ち得るため、--allowedToolsとpermission modeを別途固定します。
  5. 出力：人が読むtextではなく、schema、exit code、test結果をmachine gateにします。
  6. 依存：MCPやpluginが必要ならpath、version、checksum、load errorを確認します。
  7. 費用：jobごとのtotal_cost_usd、model内訳、再試行、上限を記録します。

bareは「安全mode」ではなく「implicit contextを省くmode」です。Bash、file read、file editは利用できるため、untrusted pull requestへwrite tokenを渡したり、--dangerously-skip-permissionsを常用したりすれば境界は失われます。checkout、network、secret、tool、artifactをCI platform側でも制限してください。

無人実行を安全にする8手順

  1. read-onlyで失敗影響の小さいtaskを選び、期待JSONと不合格条件を先に書きます。
  2. runnerをfresh checkoutまたはcontainerへ隔離し、fork由来codeをtrustしない前提にします。
  3. claude --version、model、provider、install channelをjob logへ残します。
  4. --bare -pを使い、必要なsettings、system prompt、MCPだけを明示します。
  5. API keyをCI secret storeから最小scopeで渡し、stdout、debug、artifactのmaskをtestします。
  6. --allowedToolsをReadなど必要最小限にし、Bash、Edit、networkは業務理由がある時だけ足します。
  7. --output-format jsonとJSON Schemaを使い、exit code、error field、load error、testを検査します。
  8. 時間、費用、入力size、background waitへ上限を置き、失敗時は後工程を止めて人へ証拠を渡します。

チェックリストとHOLD条件

  • bareを選ぶ理由がある
  • fresh runnerを使う
  • untrusted codeを分離した
  • versionを固定した
  • credentialをsecret storeから渡す
  • log maskをtestした
  • allowedToolsを限定した
  • MCPとpluginを明示した
  • stdinが10MB以内
  • schemaを固定した
  • exit codeを検査する
  • 費用上限がある
  • timeoutがある
  • artifact保持期間を決めた

HOLDするのは、外部contributorのcodeへwrite credentialを渡す、bareなしの暗黙hookを把握していない、permission skipを前提にする、自然文に「成功」とあれば通す、MCP load errorを無視する、費用・時間上限がない場合です。

よくある質問と次の行動

bareならMCPは使えませんか？

自動探索しないだけです。必要なserverは--mcp-configで明示し、system/initのstatusとerrorを検査できます。

background processは残りますか？

background Bash taskはfinal result後、stdin closeから約5秒で終了します。background subagentは結果待ちの対象で、既定上限があります。job timeoutも別に置きます。

jsonなら必ず正しい結果ですか？

形式が正しいだけでは業務内容の正しさを保証しません。schema validationに加え、deterministic test、人のreview、差分上限を組み合わせます。

非対話仕様は公式headless guide、flagはCLI reference、trust境界はpermissionsで公開前に確認してください。

workspace trustはtrust判断、secretはcredential masking、費用はcost管理へつなげます。Miraigentの無料診断では、CIの入力、権限、secret、出力、停止条件を整理します。