--bare（ベア）

CIスクリプトやGitHub Actionsで claude -p を呼んでいて、毎回 hooks や CLAUDE.md が読み込まれて挙動が揺れて困っている人向け

Claude Codeを自動化スクリプトやCIから呼ぶ時、毎回毎回CLAUDE.mdが読まれて、誰かが入れたhookが裏で走って、プロジェクトの.mcp.jsonに書いてあるMCPサーバーが起動して、結果が日によって違う。これを止めるための起動時の指定が --bare です。Anthropic公式が「scripted and SDK calls」つまりスクリプトやSDK経由の呼び出しに推奨している起動方法でもあります。

同じコマンドを誰のパソコンで叩いても、同じCIマシンで毎日走らせても、結果がブレない状態を作るための仕組みです。読み込まれる「余計なもの」を最初から全部スキップする、そういう発想。

噛み砕くと

普段のClaude Codeの起動を「新しい職場の初日に、机の引き出しを片っ端から開けて中身を確認していくスタッフ」だとします。同僚が残したメモ、過去のマニュアル、共有フォルダの常駐ツール、全部目を通してから仕事を始める。賢いやり方ですが、毎日この儀式をやられるとCIスクリプトには邪魔です。

--bare はその新人に「今日は引き出し開けなくていい。机に置いてある今日の指示書だけ見て動いて」と伝える指定です。引き出しの中身が同僚ごとに違っても、結果は同じになる。

大事な前提：これは-pとセットで使う指定

--bare は自動化用途で意味を持ちます。具体的には -p を使った非対話モードと組み合わせる前提。claude --bare だけ叩いても、CLAUDE.mdが読まれないインタラクティブ画面が立ち上がるだけで使いどころが見えにくい。

公式ドキュメントの基本例も claude --bare -p "Summarize this file" --allowedTools "Read" の形です。-p とセットで覚えるのが正解。

「CIで毎日走らせるリンター」を例に、実際の手順を見る

題材は「PRごとに git diff main の中身を Claude にチェックさせて、誤字や typo を報告させるリンター」。 GitHub Actionsで毎晩自動実行する想定です。

ステップ1: 普通に -p で動かしてみる

まず--bareなしで動かしてみると、CIマシン上でも自分のローカル環境と同じものが読まれます。

$ git diff main | claude -p "find typos and report file:line"

このコマンドは、自分のローカルでは ~/.claude/CLAUDE.md も、プロジェクト直下の CLAUDE.md も、設定してあるhookも全部読み込む。賢いふるまいですが、CIマシンには ~/.claude がそもそも存在しないし、同僚のhookも入っていない。結果、ローカルとCIで答えが微妙にズレる原因になります。

ステップ2: --bare を足して再現性を確保する

$ git diff main | claude --bare -p "find typos and report file:line" --allowedTools "Read"

--bare を1つ足すだけで、次の6種類の自動読み込みが全部止まります。

• hook: SessionStart等で自動実行される処理
• skill: ~/.claude/skills や .claude/skills 配下にあるもの
• plugin: 導入済みのplugin全部
• MCPサーバー: .mcp.json に記載されているもの全部
• auto memory: 自動で蓄積されている記憶
• CLAUDE.md: プロジェクト直下のものと ~/.claude のもの両方

この6つを止めれば、誰のマシンで叩いても同じ動作になる。これがCIで欲しい性質です。

ステップ3: 残るのは3つの道具だけ

bareモードで動いている時、Claudeが使える道具は3つに絞られます。

• Bash（コマンド実行）
• file read（ファイル読み込み）
• file edit（ファイル書き換え）

逆に言うと、自前のskillやpluginで足していた機能は全部消えます。「いつもこのpluginが提供する関数を呼んでた」みたいな場合、CIで動かないのはこれが原因。

ステップ4: 必要なものは個別に明示的に渡す

「でもMCPサーバーは絶対必要」「CLAUDE.mdの一部だけは読ませたい」という時は、必要なものだけを個別に指定します。公式ドキュメントが整理している対応表が次のとおり。

渡したいもの                       使う指定
─────────────────────────────────────────────────
追加のシステムプロンプト           --append-system-prompt
                                 --append-system-prompt-file
設定                              --settings <file-or-json>
MCPサーバー                       --mcp-config <file-or-json>
カスタムエージェント              --agents <json>
plugin                            --plugin-dir <path>
                                 --plugin-url <url>

たとえばCIで「PostgreSQLを読むMCPサーバーは必要だが、その他は全部切りたい」なら、 claude --bare -p "..." --mcp-config ./ci-mcp.json --allowedTools "Read" のように、必要なMCPサーバーの設定書類だけ食わせる形になります。

ステップ5: 認証は API キーを直接渡す

ここで初心者がやりがちな勘違いがあります。普段 claude login でブラウザログインしている人は、ローカルだとそれで動いている。でも --bare は OAuth とキーチェーン読み込みをスキップします。CIで動かしたら認証エラーで止まる。

解決策は2つ。GitHub Actions の Secrets に ANTHROPIC_API_KEY を登録して環境側から渡すか、 --settings にapiKeyHelperを仕込んだJSONを渡す。Bedrock/Vertex/Foundry経由なら、各クラウドプロバイダの認証方法が普通に効きます。

ステップ6: スクリプト側で「bareで動いている」を判定したい時

--bare で起動すると CLAUDE_CODE_SIMPLE という名前の設定値が自動でオンになります。スクリプト側からこの設定値の中身を見れば、自分が今bareで動いているか普通の状態で動いているかが分かる。hookの中で「bareの時はこの処理スキップ」みたいな分岐を入れたい時に使います。

つまり --bare は何をしてくれるのか

• やってくれる: 起動時の自動読み込み6種類をスキップして、起動時間を縮め、誰の環境でも同じ結果を出す
• やってくれない: Claudeの応答性能を上げたり、内容を変えたりはしない。あくまで「読み込まれる前提情報を消す」だけ
• 意味が薄い場面: インタラクティブ画面で人間が会話しながら使う時。CLAUDE.mdを読んでくれた方が便利なので、 -p なしで --bare 単独で叩く意味はあまりない

使いどころ3シナリオ

シナリオ1: package.jsonに自前リンターを仕込む

料理ブログのソースコードをチームで触っている。レシピのMarkdown誤字をPRを送る前に潰したい。package.jsonのscripts欄にこんなのを書いておきます。

"lint:claude": "git diff main | claude --bare -p \"typo report. file:line + issue.\" --allowedTools \"Read\""

同僚のローカルマシンにあるhookや、誰かの~/.claude/CLAUDE.mdの趣味設定が混ざらないので、npm run lint:claude の結果が全員の手元で揃います。Aさんのマシンでだけ余計な提案が増える、みたいな揉め事が起きない。

シナリオ2: GitHub Actionsで毎晩PRレビュー

家計簿アプリのソースコード一式に対して、夜中の3時にその日入ったPRを全部レビューさせる仕組みを組む。GitHub ActionsのSecretsにANTHROPIC_API_KEYを入れて、ワークフローのstepで gh pr diff $PR_NUMBER | claude --bare -p "review for security issues" --output-format json を叩くだけ。 --bare がなければ、CIマシンの~/.claudeに何も入っていない件で勝手に挙動が変わったり、別プロジェクトのために書いたhookが暴発したりするリスクがある。bareなら最初からゼロベース。安心して回せます。

シナリオ3: 「いつもと違う動きをしてる」のデバッグ

自分のローカルで claude -p がなぜか妙な答えを返してくる。同僚の同じプロジェクトでは普通に動くのに自分のだけおかしい。こういう時、 --bare を一旦付けて叩き直してみると、結果が変わるかどうかで「自動読み込みのどれかが悪さしている」が一発で切り分けられます。bareで正常に戻ったなら、CLAUDE.md・hook・plugin・MCPのどれかが原因。1個ずつ --mcp-config や --append-system-prompt-file で戻していって犯人を特定できる。最小再現の道具として優秀。

初心者が踏みやすい落とし穴

• -pを付け忘れる。--bareは自動化前提の指定。claude --bareだけで起動しても、CLAUDE.mdが読まれないインタラクティブ画面が出てくるだけで、ありがたみが薄い。必ず-p "..."とセットで覚える
• 普段のclaude loginが効かないことを忘れる。bareはブラウザログインとキーチェーンを読まないので、 ANTHROPIC_API_KEY を export するか、 --settings でapiKeyHelperを渡さないと認証エラーで止まる。GitHub ActionsでSecrets未設定のまま流すと毎回ここで詰まる
• 「いつものMCPが動かない」と混乱する。.mcp.jsonが読まれないので、PostgresのMCPサーバーやGitHub MCPなど、普段当たり前に使っているものがゼロから消える。必要なら --mcp-config ./ci-mcp.json で明示的に渡す
• CLAUDE.mdの指示が効かない。「いつも守ってもらってる文体ルール」「禁止語リスト」が全部スキップされる。CIで効かせたいなら、本文の質問テキストに直接書くか、--append-system-prompt-file ./ci-prompt.txtで渡す
• hookが全部スキップされる。SessionStartでログ収集していた、PostToolUseで監査記録を取っていた、そういう仕掛けは --bare 起動時には1つも走らない。CIで監査ログが必要なら、Claude Codeのhookに頼らず、ワークフロー側のstepで取る設計に切り替える
• インタラクティブで叩いて困惑する。--bare はあくまで「起動を速く、再現性を高く」する自動化向け。会話しながら使う場面ではCLAUDE.mdが読まれた方が便利なので、普段使いに --bare を癖でつける必要はない
• 将来 -p のデフォルトになる予定を知らない。Anthropicの公式ドキュメントは「--bare is the recommended mode for scripted and SDK calls, and will become the default for -p in a future release.」と明記している。今は手動で付ける指定だが、いずれ -p 単独で同じ動きになる。逆に「今後も -p だけで CLAUDE.md を読んでほしい」運用なら、その時の移行アナウンスを追う必要がある

書き方

claude --bare -p "<質問テキスト>" [--allowedTools "..."] [--mcp-config <file>] [--append-system-prompt-file <file>] [--settings <file>]

やってみるとこうなる

入力

git diff main | claude --bare -p "find typos and report file:line" --allowedTools "Read"

出力例

src/recipes/curry.md:42 「ニンジン」が「ニンジソ」になっている
src/recipes/curry.md:88 「煮込む」が「似込む」になっている
src/recipes/ramen.md:15 全角スペースが混入している

関連項目

• /print（準備中）
• /allowed-tools（準備中）
• --mcp-config（エムシーピー・コンフィグ）
• --append-system-prompt（アペンドシステムプロンプト）
• --settings（セッティングス）

公式ドキュメント

https://code.claude.com/docs/en/headless#start-faster-with-bare-mode