04. プラグインシステム詳解

プラグインの3つの構成要素

1. コマンド（Commands）

基本構造

---
description: コマンドの説明（1行）
allowed-tools: ツールの制限（任意）
argument-hint: 引数のヒント（任意）
---

# コマンドの本文（マークダウン形式）

これがプロンプトとしてClaude APIに送信されます。

YAMLフロントマターのフィールド

フィールド	必須	説明	例
description	✅	コマンドの説明	"Create a git commit"
allowed-tools	❌	使用可能なツールの制限	"Bash(git add:*), Bash(git commit:*)"
argument-hint	❌	引数のヒント	"Optional feature description"

allowed-toolsの構文

形式: ツール名(パターン1:*), ツール名(パターン2:*)

例:

allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

これは以下を許可します：

• ✅ git add .
• ✅ git status
• ✅ git commit -m "message"
• ❌ git push（許可されていない）
• ❌ npm install（許可されていない）

ワイルドカード:

• *: 任意の文字列にマッチ
• :*: コロン以降の任意の引数にマッチ

動的コマンド実行

構文: !command“

例:

- Current git status: !`git status`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`

動作:

1. コマンド実行時に!`command`部分が検出される
2. CLIがシェルコマンドを実行
3. 実行結果がマークダウンに埋め込まれる
4. 完成したプロンプトがClaude APIに送信される

実行結果の例:

- Current git status:
  modified: src/main.ts
  modified: README.md
- Current branch: feature/new-api
- Recent commits:
  abc1234 Add new API endpoint
  def5678 Update documentation

引数の使用

コマンドに引数を渡す場合：

コマンド定義:

---
description: Guided feature development
argument-hint: Optional feature description
---

Initial request: $ARGUMENTS

使用例:

# ユーザーの入力
/feature-dev Add dark mode toggle to settings

# $ARGUMENTSに展開
Initial request: Add dark mode toggle to settings

2. エージェント（Agents）

基本構造

---
name: エージェント名
description: エージェントの説明
tools: 使用可能なツールのリスト
model: sonnet|opus|haiku
color: yellow|blue|green|red（任意）
---

# システムプロンプト

このマークダウン本文がエージェントのシステムプロンプトになります。
エージェントの役割、振る舞い、指示を記述します。

YAMLフロントマターのフィールド

フィールド	必須	説明	例
name	✅	エージェント名（一意）	"code-explorer"
description	✅	エージェントの説明	"Analyzes codebase features"
tools	✅	使用可能なツール	"Glob, Grep, Read, TodoWrite"
model	✅	使用するモデル	"sonnet", "opus", "haiku"
color	❌	表示色	"yellow", "blue", "green"

toolsフィールド

エージェントが使用できるツールを制限します。

利用可能なツール:

• Glob - ファイルパターン検索
• Grep - コンテンツ検索
• Read - ファイル読み込み
• Write - ファイル書き込み
• Edit - ファイル編集
• Bash - シェルコマンド実行
• TodoWrite - TODO管理
• WebFetch - Web取得
• WebSearch - Web検索
• NotebookRead - Jupyter Notebook読み込み
• その他…

例:

# 読み取り専用エージェント
tools: Glob, Grep, Read, TodoWrite

# ファイル編集可能なエージェント
tools: Glob, Grep, Read, Edit, Write, Bash, TodoWrite

# 最小限のツールセット
tools: Read

modelフィールド

モデル	用途	特徴
haiku	高速・シンプルなタスク	コスト最小、レイテンシ最小
sonnet	バランス型	品質とスピードのバランス（推奨）
opus	複雑なタスク	最高品質、コスト最大

エージェントの起動方法

コマンドから起動:

Launch 2-3 code-explorer agents in parallel to analyze the codebase.

Task tool経由:

メインプロセスがTaskツールを使ってエージェントを起動

マルチエージェントパターン

並列実行の例（feature-devより）:

Launch 2-3 code-explorer agents in parallel. Each agent should:
- Target a different aspect of the codebase
- Trace through code comprehensively
- Return a list of 5-10 key files to read

Example agent prompts:
- "Find features similar to [feature] and trace implementation"
- "Map architecture and abstractions for [area]"
- "Analyze current implementation of [feature]"

逐次実行の例:

1. Launch code-explorer to understand existing code
2. Wait for results
3. Launch code-architect to design solution
4. Wait for results
5. Implement based on design
6. Launch code-reviewer to review implementation

3. フック（Hooks）

基本構造

hooks.json:

{
  "description": "フックの説明",
  "hooks": {
    "フックタイプ": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "実行するコマンド"
          }
        ],
        "matcher": "ツール名のパターン（任意）"
      }
    ]
  }
}

フックタイプ

タイプ	実行タイミング	用途
SessionStart	セッション開始時	初期設定、スタイル変更
PreToolUse	ツール実行前	バリデーション、警告表示
PostToolUse	ツール実行後	（将来の機能）

SessionStartフックの例

{
  "description": "Learning mode output style",
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat ${CLAUDE_PLUGIN_ROOT}/prompts/learning-mode.md"
          }
        ]
      }
    ]
  }
}

用途: セッション開始時にプロンプトを追加して動作を変更

PreToolUseフックの例

{
  "description": "Security reminder hook",
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py"
          }
        ],
        "matcher": "Edit|Write|MultiEdit"
      }
    ]
  }
}

用途: 特定のツール実行前にチェック・警告を表示

matcherパターン

構文: 正規表現パターン（パイプ|で区切る）

例:

• "Edit" - Editツールのみ
• "Edit|Write" - EditまたはWriteツール
• "Edit|Write|MultiEdit" - 複数のファイル編集ツール
• "Bash" - Bashツールのみ

フックスクリプトの入出力

stdin（標準入力）: ツールのパラメータがJSON形式で渡される

例（Editツールの場合）:

{
  "file_path": "/path/to/file.yml",
  "old_string": "...",
  "new_string": "..."
}

stdout（標準出力）: スクリプトの出力がプロンプトに追加される

例:

⚠️ Warning: You are editing a GitHub Actions workflow file.
Be careful of command injection vulnerabilities.

stderr（標準エラー出力）: デバッグログ用（プロンプトには含まれない）

フックスクリプトの実装例（Python）

#!/usr/bin/env python3
import json
import sys

# stdinからツールパラメータを読み込み
input_data = json.load(sys.stdin)
file_path = input_data.get("file_path", "")

# パターンチェック
if ".github/workflows/" in file_path:
    # stdoutに警告を出力（プロンプトに追加される）
    print("⚠️ Warning: GitHub Actions workflow detected")
    print("Be careful of command injection vulnerabilities")
    sys.exit(0)

# 問題なければ何も出力しない
sys.exit(0)

環境変数

フック内で使用可能な環境変数：

変数	説明	例
${CLAUDE_PLUGIN_ROOT}	プラグインのルートディレクトリ	/path/to/plugin
${CLAUDE_SESSION_ID}	セッションID	abc123...

設定ファイルの仕様

plugin.json

各プラグインの.claude-plugin/plugin.json:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  }
}

marketplace.json

プラグインマーケットプレイスの中央レジストリ（.claude-plugin/marketplace.json）:

{
  "plugins": [
    {
      "id": "commit-commands",
      "name": "Git Workflow Automation",
      "description": "Simplifies git operations",
      "version": "1.0.0",
      "author": "Anthropic",
      "path": "./plugins/commit-commands"
    }
  ]
}

settings.local.json

プロジェクト固有の設定（.claude/settings.local.json）:

{
  "plugins": {
    "enabled": ["commit-commands", "feature-dev"]
  },
  "model": "sonnet",
  "temperature": 0.7
}

ベストプラクティス

コマンド設計

1. 単一責任: 1つのコマンドは1つのタスクに集中
2. ツール制限: allowed-toolsで最小限のツールのみ許可
3. 動的コンテキスト: !command“で最新情報を取得
4. 明確な指示: やるべきことを具体的に記述

エージェント設計

1. 専門化: 各エージェントは特定の領域に特化
2. ツール最小化: 必要最小限のツールのみ付与
3. 適切なモデル選択: タスクの複雑さに応じてモデルを選択
4. 明確な役割: システムプロンプトで役割を明確に定義

フック設計

1. 軽量: フックは高速に実行されるべき
2. エラーハンドリング: エラーでもセッションを壊さない
3. 適切なマッチング: 必要なツールにのみフックを適用
4. 情報的: ユーザーに有用な情報を提供

次のステップ

• 学習パスガイド - 実践的な学習方法
• 実例集 - 具体的な実装例を見る