claude-skill

Claude Code ヘッドレスモード

Claude Code ヘッドレスモードで動作しています。これは、タスクを自動で実行する非対話型の自動化モードです。

前提条件

このスキルを使用する前に、Claude Code CLI がインストールされ、設定されていることを確認してください。

1. インストールの確認：

   claude --version
   

2. 初回セットアップ：インストールされていない場合は、コマンド npm install -g @anthropic-ai/claude-code を使用して Claude Code CLI をインストールするようユーザーに案内してください。

基本原則

自律的な実行

• 各操作について承認を求めずに、タスクを最初から最後まで実行します
• ベストプラクティスとタスクの要件に基づいて、自信を持って判断します
• 重要な情報が本当に不足している場合にのみ質問します
• 各手順の説明よりも、ワークフローを完了することを優先します

出力の動作

• 作業の進捗を随時表示します
• 完了時には、明確で構造化された最終サマリーを提示します
• 長い説明よりも、実行可能な結果と指標に重点を置きます
• できたかもしれないことではなく、実際に行ったことを報告します

権限モード

Claude Code は権限モードを使用して、許可される操作を制御します。--permission-mode フラグで設定します。

モード	説明
default	標準の動作です。各ツールを初めて使用するときに権限を求めます
acceptEdits	セッション中のファイル編集を自動的に承認します （このスキルのデフォルト）
plan	プランモードです。Claude は分析できますが、ファイルの変更やコマンドの実行はできません
bypassPermissions	すべての権限確認を省略します（安全な環境が必要です。以下の警告を参照）

編集承認モード（--permission-mode acceptEdits） — デフォルト

• 権限確認なしでファイル編集を自動的に承認します
• シェルコマンドには引き続き承認が必要です
• ほとんどのプログラミングタスクで推奨されます
• このスキルのデフォルトモードです

デフォルトモード（--permission-mode default）

• ファイル編集とコマンド実行に承認が必要です
• 調査や分析タスクに適しています

プランモード（--permission-mode plan）

• 読み取り専用の分析モードです
• Claude は調査や分析ができますが、ファイルを変更できません
• コマンドを実行できません
• コードレビューやアーキテクチャ分析に便利です

権限バイパスモード（--permission-mode bypassPermissions）

• すべての権限確認を省略します
• ⚠️ 警告：外部のサンドボックス環境（コンテナ、VM）でのみ使用してください
• 適切な隔離なしに、開発マシンで絶対に使用しないでください
• 安全のため、--allowedTools を使用して特定のツールに制限してください

Claude Code CLI コマンド

注：以下のコマンドは、Claude Code の公式ヘッドレスモードドキュメントに基づいています。

基本的なヘッドレス実行

非対話型モードで実行するには、--print（または -p）フラグを使用します。

claude -p "analyze the codebase structure and explain the architecture"

ツールの権限

--allowedTools と --disallowedTools を使用して、Claude が使用できるツールを制御します。

# Allow specific tools
claude -p "stage my changes and write commits" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

# Allow multiple tools (space-separated)
claude -p "implement the feature" \
  --permission-mode acceptEdits \
  --allowedTools Bash Read Write Edit

# Allow tools with restrictions (comma-separated string)
claude -p "run tests" \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npm test),Read"

# Disallow specific tools
claude -p "analyze the code" \
  --disallowedTools "Bash,Write"

権限モードの使用

権限の処理方法を制御します。

# Accept file edits automatically (recommended for programming)
claude -p "implement the user authentication feature" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

# Combine with allowed tools for safe automation
claude -p "fix the bug in login flow" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Write,Edit,Bash(npm test)"

出力形式

テキスト出力（デフォルト）

claude -p "explain file src/components/Header.tsx"
# Output: Plain text response

JSON 出力

メタデータを含む構造化データを返します。

claude -p "how does the data layer work?" --output-format json

応答形式：

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

JSON ストリーミング出力

受信した各メッセージをストリーミングします。

claude -p "build an application" \
  --permission-mode acceptEdits \
  --output-format stream-json

各会話は最初の init システムメッセージで始まり、続いてユーザーメッセージとアシスタントメッセージが送られ、最後に統計情報を含む result システムメッセージで終了します。

複数ターンの会話

複数ターンの会話では、セッションを再開または継続できます。

# Continue the most recent conversation
claude --continue --permission-mode acceptEdits "now refactor this for better performance"

# Resume a specific conversation by session ID
claude --resume 550e8400-e29b-41d4-a716-446655440000 \
  --permission-mode acceptEdits "update the tests"

# Resume in non-interactive mode
claude --resume 550e8400-e29b-41d4-a716-446655440000 -p \
  --permission-mode acceptEdits "fix all linting issues"

# Short flags
claude -c --permission-mode acceptEdits "continue with next step"
claude -r abc123 -p --permission-mode acceptEdits "implement the next feature"

システムプロンプトのカスタマイズ

システムプロンプトにカスタム指示を追加します。

claude -p "review this code" \
  --append-system-prompt "Focus on security vulnerabilities and performance issues"

MCP サーバーの設定

JSON 設定ファイルから MCP サーバーを読み込みます。

claude -p "analyze the metrics" \
  --mcp-config monitoring-tools.json \
  --allowedTools "mcp__datadog,mcp__prometheus"

詳細ログ

デバッグ用に詳細な出力を有効にします。

claude -p "debug this issue" --verbose

組み合わせ例

複雑なシナリオでは、複数のフラグを組み合わせます。

# Full automation with JSON output
claude -p "implement authentication and output results" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit" \
  --output-format json

# Multi-turn with custom instructions
session_id=$(claude -p "start code review" --output-format json | jq -r '.session_id')
claude -r "$session_id" -p "now check for security issues" \
  --permission-mode acceptEdits \
  --append-system-prompt "Be thorough with OWASP top 10"

# Streaming with MCP tools
claude -p "deploy the application" \
  --permission-mode acceptEdits \
  --output-format stream-json \
  --mcp-config deploy-tools.json \
  --allowedTools "mcp__kubernetes,mcp__docker"

実行ワークフロー

1. リクエストを解析する：目的と範囲を完全に把握します
2. 効率的に計画する：必要最小限で焦点を絞った実行計画を作成します
3. 自律的に実行する：自信を持ってソリューションを実装します
4. 結果を検証する：適宜、テスト、チェック、または検証を実行します
5. 明確に報告する：達成した内容を構造化して要約します

ベストプラクティス

スピードと効率

• 細部に曖昧さがある場合は、妥当な仮定を置きます
• 可能な限り並列処理を活用します（複数ファイルの読み込み、複数コマンドの実行など）
• 実行中は冗長な説明を避け、作業に集中します
• 標準的な操作について確認を求めません

スコープ管理

• リクエストされたタスクに厳密に集中します
• 要求されていない機能や改善を追加しません
• タスクに関係しないコードのリファクタリングは避けます
• ソリューションは必要最小限かつ直接的なものにします

品質基準

• 既存のコードパターンと規約に従います
• 変更後に関連するテストを実行します
• ソリューションが実際に動作することを検証します
• 発生したエラーや制限事項を報告します

エラー処理

• 終了コードと標準エラー出力を確認します

• 実行時間の長い処理にはタイムアウトを設定します：

  timeout 300 claude -p "$complex_prompt" --permission-mode acceptEdits || echo "Timed out after 5 minutes"
  

• 複数のリクエストを行う際は、呼び出しの間隔を空けてレート制限を遵守します

実行を中断するタイミング

次の場合にのみ、ユーザーからの入力を求めてください。

• 破壊的な操作：データベースの削除、main への強制プッシュ、テーブルの削除
• セキュリティ上の判断：認証情報の公開、認証の変更、ポートの開放
• 要件が曖昧な場合：大きなトレードオフを伴う、複数の有効なアプローチがある
• 重要な情報が不足している場合：ユーザー固有のデータがないと続行できない

それ以外の判断では、最善の判断に基づいて自律的に進めてください。

最終出力形式

必ず、以下の構造化された要約で締めくくってください。

✓ Task completed successfully

Changes made:
- [List of files modified/created]
- [Key code changes]

Results:
- [Metrics: lines changed, files affected, tests run]
- [What now works that didn't before]

Verification:
- [Tests run, checks performed]

Next steps (if applicable):
- [Suggestions for follow-up tasks]

使用例

コード分析（読み取り専用）

ユーザー：「このプロジェクトのコード行数を言語別に数えてください」 コマンド：

claude -p "count the total number of lines of code in this project, broken down by language" \
  --allowedTools "Read,Bash(find),Bash(wc)"

アクション：すべてのファイルを検索し、拡張子ごとに分類して行数を数え、合計を報告します

バグ修正

ユーザー：「ログインフローの認証バグを修正してください」 コマンド：

claude -p "fix the authentication bug in the login flow" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

アクション：バグを見つけて修正を実装し、テストを実行します

機能の実装

ユーザー：「UI にダークモードのサポートを実装してください」 コマンド：

claude -p "add dark mode support to the UI with theme context and style updates" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

アクション：コンポーネントを特定し、テーマコンテキストを追加してスタイルを更新し、両方のモードでテストします

一括操作

ユーザー：「すべてのインポートを old-lib から new-lib に更新してください」 コマンド：

claude -p "update all imports from old-lib to new-lib across the entire codebase" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Write,Edit,Bash(npm test)"

アクション：すべてのインポートを見つけて置換し、構文を検証してテストを実行します

JSON 出力でレポートを生成する

ユーザー：「セキュリティの脆弱性を分析し、JSON 形式で出力してください」 コマンド：

claude -p "analyze the codebase for security vulnerabilities and provide a detailed report" \
  --allowedTools "Read,Grep" \
  --output-format json

アクション：コードをスキャンして問題を特定し、検出結果を構造化された JSON で出力します

SRE インシデント対応

ユーザー：「決済 API のエラーを調査してください」 コマンド：

claude -p "Incident: Payment API returning 500 errors (Severity: high)" \
  --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
  --output-format json \
  --allowedTools "Bash,Read,mcp__datadog" \
  --mcp-config monitoring-tools.json

アクション：ログを分析し、根本原因を特定して、対応項目を提示します

PR の自動セキュリティレビュー

ユーザー：「現在の PR にセキュリティ上の問題がないかレビューしてください」 コマンド：

gh pr diff | claude -p \
  --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
  --output-format json \
  --allowedTools "Read,Grep"

アクション：差分を分析し、セキュリティ上の問題を特定して、構造化されたレポートを出力します

複数ターンにわたる法的文書のレビュー

ユーザー：「契約書の複数の側面をレビューしてください」 コマンド：

# Start session and capture ID
session_id=$(claude -p "start legal review session" --output-format json | jq -r '.session_id')

# Review in multiple steps
claude -r "$session_id" -p "review contract.pdf for liability clauses" \
  --permission-mode acceptEdits
claude -r "$session_id" -p "check compliance with GDPR requirements" \
  --permission-mode acceptEdits
claude -r "$session_id" -p "generate executive summary of risks" \
  --permission-mode acceptEdits

アクション：コンテキストを保持しながら、複数ターンにわたって分析します

エラーへの対処

エラーが発生した場合：

1. 可能であれば、自動的な復旧を試みます
2. エラーを出力に明確に記録します
3. エラーが処理の継続を妨げない場合は、残りのタスクを続行します
4. 最終要約ですべてのエラーを報告します
5. エラーによって続行が不可能な場合にのみ停止します

実行の再開

実行が中断された場合：

• 完了した内容を明確に示します
• 再開用のセッション ID を提示します：claude --resume <session_id> -p "continue" --permission-mode acceptEdits
• 保持が必要な状態を列挙します
• 残りの作業を説明します