# プラグインシステム

Claude Code プラグインシステムを使用すると、カスタムスラッシュコマンド、専門エージェント、再利用可能なスキル、自動化フックを作成して Claude の機能を拡張できます。プラグインを使用することで、チームのベストプラクティスとワークフローをコード化できます。

## プラグインとは？

### 基本概念

Claude Code プラグインは、以下のコンポーネントを追加できる特定のファイル構造を持つディレクトリです：

| コンポーネント | 説明 | ファイル形式 |
|---------------|------|-------------|
| **Commands（コマンド）** | カスタムスラッシュコマンド | `.md` ファイル |
| **Agents（エージェント）** | 専門タスクのサブエージェント | `.md` ファイル |
| **Skills（スキル）** | 再利用可能な知識と能力 | ディレクトリ + `SKILL.md` |
| **Hooks（フック）** | イベントトリガーの自動化 | `hooks.json` |

### なぜプラグインが必要？

- **チームの標準化**：コーディング規約やレビュー基準を実行可能なコマンドとしてエンコード

- **ワークフロー自動化**：コミット、デプロイ、レビューなどの繰り返しタスクを自動化

- **知識共有**：チームメンバー間でベストプラクティスと専門知識を共有

- **カスタム体験**：プロジェクトのニーズに合わせて Claude の動作をカスタマイズ

## プラグインディレクトリ構造

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 必須：プラグインマニフェスト
├── commands/                 # スラッシュコマンド（.md ファイル）
│   ├── review.md
│   └── deploy.md
├── agents/                   # サブエージェント定義（.md ファイル）
│   └── code-reviewer.md
├── skills/                   # エージェントスキル（サブディレクトリ）
│   └── coding-standards/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # イベントハンドラー設定
├── .mcp.json                # MCP サーバー定義（オプション）
└── scripts/                 # ヘルパースクリプト（オプション）
```

## クイックスタート

### プラグインのインストール

```bash
# マーケットプレイスからインストール
/plugin install plugin-name@claude-code-marketplace

# ローカルディレクトリからインストール
claude --plugin-dir /path/to/my-plugin
```

### プラグイン作成ウィザードを使用

```bash
/plugin-dev:create-plugin
```

このコマンドは 8 つのフェーズを通じて完全なプラグインの作成をガイドします。

## カスタムコマンドの作成

### 基本コマンド形式

`commands/` ディレクトリに `.md` ファイルを作成：

```markdown
---
description: コードレビューを実行
argument-hint: [file-path]
allowed-tools: Read, Bash(git:*)
---

以下のファイルのコード品質をレビューしてください：@$1

フォーカスポイント：
1. コードの可読性
2. 潜在的なバグ
3. パフォーマンスの問題
4. セキュリティの脆弱性
```

### YAML フロントマター設定

| フィールド | 説明 | 例 |
|-----------|------|-----|
| `description` | コマンドの説明（/help に表示） | `コードレビューを実行` |
| `argument-hint` | パラメータヒント | `[file-path] [options]` |
| `allowed-tools` | 許可されるツール | `Read, Bash(git:*)` |
| `model` | 使用モデルを指定 | `opus` または `sonnet` |

### 動的引数の使用

- `$1`, `$2`, `$3`... - 位置引数

- `$ARGUMENTS` - すべての引数

- `@path/to/file` - ファイル参照

- `!`command`` - Bash コマンドを実行

### コマンド例

**コードレビューコマンド** (`commands/review.md`)：

```markdown
---
description: 包括的なコードレビュー
argument-hint: [file-or-directory]
allowed-tools: Read, Grep, Glob
model: opus
---

@$1 の包括的なコードレビューを実行してください。

チェックリスト：
- [ ] コードスタイルがプロジェクト規約に従っている
- [ ] 潜在的なセキュリティ問題がない
- [ ] エラーハンドリングが完全
- [ ] テストが必要

ディレクトリの場合、まず Glob ツールで関連ファイルをすべて見つけてください。
```

**スマートコミットコマンド** (`commands/commit.md`)：

```markdown
---
description: メッセージを生成してスマートコミット
allowed-tools: Bash(git:*)
---

1. `git status` を実行して変更を確認
2. `git diff --staged` を実行してステージされた変更を分析
3. 変更内容に基づいて規約に沿ったコミットメッセージを生成
4. `git commit` を実行

コミットメッセージ形式：
- feat: 新機能
- fix: バグ修正
- docs: ドキュメント更新
- refactor: リファクタリング
- test: テスト関連
```

## カスタムエージェントの作成

### エージェント定義形式

`agents/` ディレクトリに `.md` ファイルを作成：

```markdown
---
description: 専門のコードレビューエージェント
model: opus
tools: Read, Grep, Glob
---

あなたは専門のコードレビューエージェントです。あなたのタスクは：

1. 提供されたコードを注意深く読む
2. 潜在的な問題を特定する
3. 具体的な改善提案を提供する
4. セキュリティとパフォーマンスに焦点を当てる

常に建設的で具体的であること。
```

### エージェントタイプ

| タイプ | 用途 | 例 |
|--------|------|-----|
| レビューエージェント | コードレビュー、PR レビュー | `code-reviewer` |
| テストエージェント | テストの生成と実行 | `test-generator` |
| ドキュメントエージェント | ドキュメント生成 | `doc-writer` |
| リファクタリングエージェント | コードリファクタリング | `refactorer` |

## スキルの作成

### スキルディレクトリ構造

```
skills/
└── coding-standards/
    ├── SKILL.md              # 必須：スキル定義
    ├── references/           # 参考資料
    │   └── style-guide.md
    └── examples/             # コード例
        └── good-practices.md
```

### SKILL.md 形式

```markdown
# コーディング規約スキル

## 概要
このスキルにはチームのコーディング規約とベストプラクティスが含まれています。

## 知識内容

### 命名規則
- 変数：camelCase
- 定数：UPPER_SNAKE_CASE
- クラス：PascalCase
- ファイル：kebab-case

### コードスタイル
- 2 スペースインデントを使用
- 最大行幅 100 文字
- セミコロンを使用

### エラーハンドリング
- 常に try-catch を使用
- エラーをログに記録
- 意味のあるエラーメッセージを提供
```

## フックの作成

### hooks.json 形式

```json
{
  "hooks": [
    {
      "event": "on_commit",
      "command": "npm run lint",
      "description": "コミット前に lint チェックを実行"
    },
    {
      "event": "on_file_change",
      "pattern": "*.ts",
      "command": "npm run typecheck",
      "description": "TypeScript ファイル変更時に型チェック"
    }
  ]
}
```

### サポートされるイベント

| イベント | トリガータイミング |
|----------|-------------------|
| `on_commit` | コードをコミット時 |
| `on_file_change` | ファイル変更時 |
| `on_session_start` | セッション開始時 |
| `on_command` | コマンド実行時 |

## プラグインマニフェスト

### plugin.json 形式

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "私のカスタムプラグイン",
  "author": "Your Name",
  "components": {
    "commands": ["commands/*.md"],
    "agents": ["agents/*.md"],
    "skills": ["skills/*/SKILL.md"],
    "hooks": "hooks/hooks.json"
  },
  "mcpServers": ".mcp.json"
}
```

## 実践例

### 例 1：チームコードレビュープラグイン

```
team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md          # PR レビューコマンド
│   ├── security-check.md     # セキュリティチェックコマンド
│   └── perf-audit.md         # パフォーマンス監査コマンド
├── agents/
│   ├── security-reviewer.md  # セキュリティレビューエージェント
│   └── perf-analyzer.md      # パフォーマンス分析エージェント
└── skills/
    └── team-standards/
        └── SKILL.md          # チーム規約スキル
```

### 例 2：デプロイ自動化プラグイン

```
deploy-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md     # ステージングへデプロイ
│   ├── deploy-prod.md        # 本番へデプロイ
│   └── rollback.md           # ロールバックコマンド
├── hooks/
│   └── hooks.json            # デプロイ前チェックフック
└── .mcp.json                 # Kubernetes MCP 設定
```

## ベストプラクティス

### コマンド設計

1. **単一責任**：各コマンドは 1 つのことだけを行う

2. **明確な説明**：description を簡潔に保つ

3. **パラメータ文書化**：argument-hint でパラメータを説明

4. **最小権限**：allowed-tools には必要なツールのみを含める

5. **エラーハンドリング**：失敗シナリオを考慮

### プラグイン構成

1. **モジュール化**：関連機能をまとめて整理

2. **再利用可能**：スキルは複数のコマンドで使用可能であるべき

3. **文書化**：README と使用説明を追加

4. **バージョン管理**：セマンティックバージョニングを使用

### セキュリティ考慮事項

1. **シークレットをハードコードしない**：環境変数を使用

2. **ファイルアクセスを制限**：必要なパスのみにアクセス

3. **入力を検証**：パラメータを検証

4. **監査ログ**：機密操作をログに記録

## プラグインのデバッグ

```bash
# プラグインの読み込み状態を表示
/plugin list

# コマンドの詳細を表示
/help my-command

# コマンドをテスト
/my-command test-argument
```

## 次のステップ

- [MCP サーバー](/docs/advanced/mcp) で外部統合を拡張

- [CLI テクニック](/docs/usage/cli-tips) で効率を向上

- [ワークフロー](/docs/usage/workflow-tips) で開発フローを最適化