自動化パイプラインを本番運用していると、「なぜかREADME生成が失敗した」「今月のAPI費用が予想より高い」「あのとき何が実行されたのか確認したい」といった場面に必ず遭遇します。Claude Codeの --debug、--settings、--setting-sources を活用すれば、パイプラインの動作を完全に可視化し、障害調査・コスト分析・セキュリティ監査を効率的に行えます。
前提知識
Claude Code CLI の printモード（claude -p）、セッション管理、--effort によるコスト最適化、--disallowed-tools による権限設計の基本を理解していることを前提とします。
前提知識について詳しく知りたい人は、以下の記事を参考にしてください。
- 【Claude Code】printモード入門｜パイプ連携とスクリプト活用の基本
- Claude Codeの–json-schemaで構造化出力する方法――スキーマ定義から実践まで
- Claude Codeの–max-budget-usdでAPI費用を管理する方法――コスト超過を防ぐ実践テクニック
- Claude Code –effort完全ガイド｜low・medium・highの使い分けでコストを半減させる方法
- Claude Code権限設計入門｜–allowed-tools・–disallowed-toolsで安全な自動化を実現する
設定の階層構造を理解する
Claude Codeは複数の設定ソースを持ち、優先度の高い順に適用されます。
コマンドラインオプション（最高優先度）
↑
--settings で注入した設定
↑
プロジェクトレベルの設定ファイル
↑
ユーザーレベルの設定ファイル
↑
デフォルト設定（最低優先度）この階層を把握しておくことで、「意図しない設定が混入している」といったトラブルを防げます。
–settings で設定を外部から注入する
--settings オプションを使うと、設定をJSON文字列またはファイルパスで渡せます。
# 設定ファイルを作成
cat << 'EOF' > pipeline_settings.json
{
"systemPrompt": "README生成の専門家として応答してください。",
"model": "claude-sonnet-4-20250514"
}
EOF
# 設定ファイルを使って実行
claude -p "解析してREADME概要を生成" --settings pipeline_settings.json --output-format json | jq -r '.result'
JSON文字列で直接渡すこともできます。
claude -p "解析してREADME概要を生成" --settings '{"systemPrompt": "技術文書の専門家として応答"}' --output-format json | jq -r '.result'設定ファイルが不正なJSONだとエラーになるため、事前にバリデーションしておきましょう。
–setting-sources で設定ソースを限定する
本番パイプラインでは、ビルドランナー上のユーザー設定が意図せず適用されることがあります。--setting-sources で明示的に制限しましょう。
claude -p "概要を教えてください" --setting-sources "project" --output-format json | jq -r '.result'この設定ではプロジェクトレベルの設定のみが有効になり、ユーザーレベルの個人設定は無視されます。CI/CD環境での再現性を確保するために重要です。
–debug でデバッグログを有効化する
パイプラインの問題調査に不可欠なのがデバッグログです。
-d（--debug）はデバッグモードを有効化するオプションです。有効にすると、ツール呼び出しのペイロード、パーミッション判定、ファイル操作の詳細、コンテキストウィンドウの使用率変化などが出力されます。
# 対話モードでデバッグ情報を確認
claude -dカテゴリフィルタリングにも対応しており、必要な情報だけに絞れます。
# APIとMCP関連のみ表示
claude -d "api,mcp"
# 特定カテゴリを除外
claude -d "!statsig,!file"注意点: -d のデバッグ出力は標準出力（stdout）に出力されます。そのため、printモード（-p）で使うとJSON出力と混ざってしまい、jq でのパースに支障が出ます。
パイプラインのデバッグには、次のセクションで紹介する --debug-file を使ってください。
–debug-file でファイルに直接保存する
--debug-file を使えば、stderrのリダイレクトよりもクリーンにログを保存できます。
claude -p "README情報を生成してください"
--debug-file ~/debug.log
--output-format json | jq -r '.result'タイムスタンプ付きのログファイル名にすれば、ログローテーションも簡単です。
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
claude -p "解析してください"
--debug-file "logs/debug_${TIMESTAMP}.log"
--output-format json | jq -r '.result'--debug-file のパスにログディレクトリが存在しないと書き込みに失敗します。スクリプトの冒頭で mkdir -p しておきましょう。
–verbose で軽量な詳細表示
--verbose は --debug よりも軽量な詳細表示モードです。ツール使用状況や主要な処理ステップが表示されますが、APIリクエストの詳細など低レベルの情報は省略されます。日常的な動作確認に適しています。
次に試してみよう
開発・ステージング・本番の3環境用に設定ファイルを作成し、環境変数で切り替えられる仕組みを試してみましょう。--debug-file で保存したログから jq でAPIリクエスト回数やトークン数を抽出するコマンドを作るのも良い練習になります。
まとめ
--settingsで設定をファイルパスまたはJSON文字列で注入でき、環境ごとの切り替えが容易--setting-sourcesで設定ソースを限定し、予期しない設定の混入を防ぐ-d（--debug）と--debug-fileでデバッグログを有効化・保存し、問題調査に活用--verboseは日常的な動作確認に適した軽量な詳細表示モード- 監査ログを設計して残すことで、パイプラインの透明性と追跡可能性を確保できる
--mcp-debugは非推奨。代わりに--debugを使用する
さらに深く学びたい方へ
Claude Codeの Skills・MCP・Agent・Hooks・Plugin を体系的に学べる有料教材を Zenn で公開しています。
Claude Code 実践ガイド（Zenn Book）
