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: true/false による素早い有効化／無効化が可能です

ralph-loop プラグイン

.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 行目：アクティブでなければすぐに終了）
• iteration count と max_iterations を読み込みます
• ループ終了のために completion_promise を抽出します
• 本文を、再び渡すプロンプトとして読み込みます
• ループごとに iteration count を更新します

クイックリファレンス

ファイルの場所

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-loop の実装に関する詳細な解説

サンプルファイル

examples/ に動作するサンプルがあります。

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

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

script/ に開発ツールがあります。

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

実装ワークフロー

プラグインに設定を追加するには、次の手順に従います。

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

設定をシンプルに保ち、設定ファイルが存在しない場合に適切なデフォルト値が使用されるようにしてください。