Plugin Settings

Claude Code プラグインの設定パターン

概要

プラグインでは、プロジェクトディレクトリ内の .claude/plugin-name.local.md ファイルに、ユーザーが設定できる設定や状態を保存できます。このパターンでは、構造化された設定に YAML フロントマターを、プロンプトや追加のコンテキストに Markdown の本文を使用します。

主な特徴：

• ファイルの場所：プロジェクトのルートにある .claude/plugin-name.local.md
• 構造：YAML フロントマター + Markdown の本文
• 目的：プロジェクトごとのプラグイン設定と状態
• 用途：フック、コマンド、エージェントから読み込み
• ライフサイクル：ユーザーが管理（Git に含めず、.gitignore に追加する必要があります）

ファイル構造

基本テンプレート

---
enabled: true
setting1: value1
setting2: value2
numeric_setting: 42
list_setting: ["item1", "item2"]
---

# Additional Context

This markdown body can contain:
- Task descriptions
- Additional instructions
- Prompts to feed back to Claude
- Documentation or notes

例：プラグインの状態ファイル

.claude/my-plugin.local.md：

---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

# Plugin Configuration

This plugin is configured for standard validation mode.
Contact @team-lead with questions.

設定ファイルの読み込み

フックから読み込む（Bash スクリプト）

パターン：存在を確認してフロントマターを解析する

#!/bin/bash
set -euo pipefail

# Define state file path
STATE_FILE=".claude/my-plugin.local.md"

# Quick exit if file doesn't exist
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0  # Plugin not configured, skip
fi

# Parse YAML frontmatter (between --- markers)
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# Extract individual fields
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')
STRICT_MODE=$(echo "$FRONTMATTER" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^"\(.*\)"$/\1/')

# Check if enabled
if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Disabled
fi

# Use configuration in hook logic
if [[ "$STRICT_MODE" == "true" ]]; then
  # Apply strict validation
  # ...
fi

完全に動作する例については、examples/read-settings-hook.sh を参照してください。

コマンドから読み込む

コマンドでは、動作をカスタマイズするために設定ファイルを読み込めます。

---
description: Process data with plugin
allowed-tools: ["Read", "Bash"]
---

# Process Command

Steps:
1. Check if settings exist at `.claude/my-plugin.local.md`
2. Read configuration using Read tool
3. Parse YAML frontmatter to extract settings
4. Apply settings to processing logic
5. Execute with configured behavior

エージェントから読み込む

エージェントは、指示の中で設定を参照できます。

---
name: configured-agent
description: Agent that adapts to project settings
---

Check for plugin settings at `.claude/my-plugin.local.md`.
If present, parse YAML frontmatter and adapt behavior according to:
- enabled: Whether plugin is active
- mode: Processing mode (strict, standard, lenient)
- Additional configuration fields

解析方法

フロントマターの抽出

# Extract everything between --- markers
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

個々のフィールドの読み込み

文字列フィールド：

VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')

ブール値フィールド：

ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
# Compare: if [[ "$ENABLED" == "true" ]]; then

数値フィールド：

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')
# Use: if [[ $MAX -gt 100 ]]; then

Markdown 本文の読み込み

2 つ目の --- 以降の内容を抽出します。

# Get everything after closing ---
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

よくあるパターン

パターン 1：フックの一時的な有効化

設定ファイルを使用して、フックの有効化を制御します。

#!/bin/bash
STATE_FILE=".claude/security-scan.local.md"

# Quick exit if not configured
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0
fi

# Read enabled flag
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Disabled
fi

# Run hook logic
# ...

用途： hooks.json を編集せずにフックを有効化／無効化できます（再起動が必要です）。

パターン 2：エージェントの状態管理

エージェント固有の状態と設定を保存します。

.claude/multi-agent-swarm.local.md：

---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
---

# Task Assignment

Implement JWT authentication for the API.

**Success Criteria:**
- Authentication endpoints created
- Tests passing
- PR created and CI green

フックから読み込み、エージェント間の連携を行います。

AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')
COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')

# Send notification to coordinator
tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

パターン 3：設定に基づく動作

.claude/my-plugin.local.md：

---
validation_level: strict
max_file_size: 1000000
allowed_extensions: [".js", ".ts", ".tsx"]
enable_logging: true
---

# Validation Configuration

Strict mode enabled for this project.
All writes validated against security policies.

フックやコマンドで使用します。

LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')

case "$LEVEL" in
  strict)
    # Apply strict validation
    ;;
  standard)
    # Apply standard validation
    ;;
  lenient)
    # Apply lenient validation
    ;;
esac

設定ファイルの作成

コマンドから作成する

コマンドで設定ファイルを作成できます。

# Setup Command

Steps:
1. Ask user for configuration preferences
2. Create `.claude/my-plugin.local.md` with YAML frontmatter
3. Set appropriate values based on user input
4. Inform user that settings are saved
5. Remind user to restart Claude Code for hooks to recognize changes

テンプレートの生成

プラグインの README にテンプレートを記載します。

## Configuration

Create `.claude/my-plugin.local.md` in your project:

\`\`\`markdown
---
enabled: true
mode: standard
max_retries: 3
---

# Plugin Configuration

Your settings are active.
\`\`\`

After creating or editing, restart Claude Code for changes to take effect.

ベストプラクティス

ファイル名

✅ 推奨：

• .claude/plugin-name.local.md の形式を使用する
• プラグイン名と完全に一致させる
• ユーザー固有のファイルには .local.md の接尾辞を使用する

❌ 非推奨：

• 別のディレクトリを使用する（.claude/ 以外）
• 一貫性のない命名にする
• .local を付けずに .md を使用する（コミットされる可能性があります）

Gitignore

必ず .gitignore に追加してください。

.claude/*.local.md
.claude/*.local.json

この点をプラグインの README に記載してください。

デフォルト値

設定ファイルが存在しない場合に備え、適切なデフォルト値を用意してください。

if [[ ! -f "$STATE_FILE" ]]; then
  # Use defaults
  ENABLED=true
  MODE=standard
else
  # Read from file
  # ...
fi

検証

設定値を検証してください。

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')

# Validate numeric range
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
  echo "⚠️  Invalid max_value in settings (must be 1-100)" >&2
  MAX=10  # Use default
fi

再起動の要件

重要： 設定を変更した場合、Claude Code の再起動が必要です。

README に記載してください。

## Changing Settings

After editing `.claude/my-plugin.local.md`:
1. Save the file
2. Exit Claude Code
3. Restart: `claude` or `cc`
4. New settings will be loaded

セッション中にフックをホットスワップすることはできません。

セキュリティに関する考慮事項

ユーザー入力のサニタイズ

ユーザー入力から設定ファイルを書き込む場合：

# Escape quotes in user input
SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')

# Write to file
cat > "$STATE_FILE" <<EOF
---
user_setting: "$SAFE_VALUE"
---
EOF

ファイルパスの検証

設定にファイルパスが含まれる場合：

FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')

# Check for path traversal
if [[ "$FILE_PATH" == *".."* ]]; then
  echo "⚠️  Invalid path in settings (path traversal)" >&2
  exit 2
fi

権限

設定ファイルは次の条件を満たす必要があります。

• ユーザーのみが読み取れる（chmod 600）
• Git にコミットしない
• ユーザー間で共有しない

実際の使用例

multi-agent-swarm プラグイン

.claude/multi-agent-swarm.local.md：

---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: Use JWT tokens, not sessions
---

# Task: Implement Authentication

Build JWT-based authentication for the REST API.
Coordinate with auth-agent on shared types.

フックでの使用（agent-stop-notification.sh）：

• ファイルが存在するか確認する（15～18 行目：存在しない場合はすぐに終了）
• フロントマターを解析し、coordinator_session、agent_name、enabled を取得する
• enabled が有効な場合、コーディネーターに通知を送信する
• enabled: true/false で素早く有効化／無効化できる

ralph-wiggum プラグイン

.claude/ralph-loop.local.md：

---
iteration: 1
max_iterations: 10
completion_promise: "All tests passing and build successful"
---

Fix all the linting errors in the project.
Make sure tests pass after each fix.

フックでの使用（stop-hook.sh）：

• ファイルが存在するか確認する（15～18 行目：アクティブでない場合はすぐに終了）
• 反復回数と max_iterations を読み込む
• ループ終了に使用する completion_promise を抽出する
• 本文を、フィードバックするプロンプトとして読み込む
• ループのたびに反復回数を更新する

クイックリファレンス

ファイルの場所

project-root/
└── .claude/
    └── plugin-name.local.md

フロントマターの解析

# Extract frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

# Read field
VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: *//' | sed 's/^"\(.*\)"$/\1/')

本文の解析

# Extract body (after second ---)
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

すぐに終了するパターン

if [[ ! -f ".claude/my-plugin.local.md" ]]; then
  exit 0  # Not configured
fi

参考資料

参考ファイル

実装パターンの詳細については、以下を参照してください。

• references/parsing-techniques.md - YAML のフロントマターと Markdown 本文を解析するための完全なガイド
• references/real-world-examples.md - multi-agent-swarm と ralph-wiggum の実装の詳細な解説

サンプルファイル

examples/ にある動作するサンプル：

• read-settings-hook.sh - 設定を読み込んで使用するフック
• create-settings-command.md - 設定ファイルを作成するコマンド
• example-settings.md - 設定ファイルのテンプレート

ユーティリティスクリプト

scripts/ にある開発ツール：

• validate-settings.sh - 設定ファイルの構造を検証
• parse-frontmatter.sh - フロントマターのフィールドを抽出

実装ワークフロー

プラグインに設定を追加するには：

1. 設定スキーマを設計します（フィールド、型、デフォルト値）
2. プラグインのドキュメントにテンプレートファイルを作成します
3. .claude/*.local.md の gitignore エントリを追加します
4. フック／コマンドで設定の解析を実装します
5. 早期終了パターンを使用します（ファイルの存在を確認し、有効化フィールドを確認します）
6. テンプレートを含め、プラグインの README に設定について記載します
7. 変更を反映するには Claude Code の再起動が必要であることをユーザーに伝えます

設定をシンプルに保ち、設定ファイルが存在しない場合に適切なデフォルト値を提供することを重視してください。