05. 学習パスガイド

推奨学習順序

🟢 初級編：シンプルなプラグインから（2-3時間）

ステップ1: commit-commandsプラグイン

ファイルパス: plugins/commit-commands/

構造:

commit-commands/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── commit.md
│   ├── commit-push-pr.md
│   └── clean_gone.md
└── README.md

学ぶポイント:

1. コマンドファイルの基本構造
2. YAMLフロントマター + マークダウン形式
3. allowed-toolsでツールを制限する方法
4. !git status“のような動的コマンド実行
5. シンプルなワークフローの定義

読む順序:

1. plugins/commit-commands/README.md
   → プラグインの概要を理解

2. plugins/commit-commands/commands/commit.md
   → 最もシンプルなコマンド
   → allowed-toolsの使い方
   → 動的コマンド実行

3. plugins/commit-commands/commands/commit-push-pr.md
   → より複雑なワークフロー
   → 複数ステップの処理

4. plugins/commit-commands/.claude-plugin/plugin.json
   → プラグインメタデータ

実際に試す:

cd /path/to/claude-code
claude

# プロンプトで実行
/commit

---

🟡 中級編：フックシステムを理解（3-4時間）

ステップ2: security-guidanceプラグイン

ファイルパス: plugins/security-guidance/

構造:

security-guidance/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── security_reminder_hook.py
└── README.md

学ぶポイント:

1. PreToolUseフックの仕組み
2. matcherでツールをフィルタする方法
3. Pythonスクリプトの入出力（stdin/stdout）
4. セキュリティパターンの検出ロジック
5. 状態管理とセッション追跡

読む順序:

1. plugins/security-guidance/README.md
   → フックの目的を理解

2. plugins/security-guidance/hooks/hooks.json
   → フック定義の構造
   → PreToolUseフック
   → matcherパターン

3. plugins/security-guidance/hooks/security_reminder_hook.py
   → Pythonスクリプトの実装
   → stdinからのJSON読み込み
   → パターンマッチング
   → stdoutへの出力

4. 実行フローを追跡する
   → ユーザーが Edit ツールを使う
   → フックが発動
   → Pythonスクリプトがチェック
   → 警告がプロンプトに追加

重要なコード部分:

hooks.json:

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

security_reminder_hook.py（抜粋）:

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

# パターンチェック
if ".github/workflows/" in file_path:
    print("⚠️ Warning: GitHub Actions workflow")
    print("Be careful of command injection")

---

🔴 上級編：複雑なエージェントシステム（5-8時間）

ステップ3: feature-devプラグイン

ファイルパス: plugins/feature-dev/

構造:

feature-dev/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── feature-dev.md
├── agents/
│   ├── code-explorer.md
│   ├── code-architect.md
│   └── code-reviewer.md
└── README.md

学ぶポイント:

1. マルチエージェントワークフロー
2. 7フェーズの構造化プロセス
3. エージェント間の連携方法
4. toolsパラメータで権限を制限
5. 並列エージェント実行
6. TodoWriteツールの活用

読む順序:

1. plugins/feature-dev/README.md
   → 全体のワークフローを理解

2. plugins/feature-dev/commands/feature-dev.md
   → 7フェーズの詳細
   → 各フェーズの目的と手順
   → エージェント起動のパターン

3. plugins/feature-dev/agents/code-explorer.md
   → コードベース探索エージェント
   → 使用可能なツール
   → システムプロンプトの内容

4. plugins/feature-dev/agents/code-architect.md
   → アーキテクチャ設計エージェント
   → 設計アプローチの提案

5. plugins/feature-dev/agents/code-reviewer.md
   → コードレビューエージェント
   → 品質チェックの観点

7フェーズワークフローの理解:

Phase 1: Discovery（発見）
  ↓ 要件を理解
Phase 2: Codebase Exploration（探索）
  ↓ 2-3個のcode-explorerエージェントを並列起動
  ↓ 各エージェントが異なる観点で調査
  ↓ 重要ファイルのリストを返却
Phase 3: Clarifying Questions（質問）
  ↓ 不明点をユーザーに確認
Phase 4: Architecture Design（設計）
  ↓ 2-3個のcode-architectエージェントを並列起動
  ↓ 異なるアプローチを提案
Phase 5: Implementation（実装）
  ↓ 選択されたアプローチで実装
Phase 6: Testing（テスト）
  ↓ テストを実行
Phase 7: Review（レビュー）
  ↓ code-reviewerエージェントで品質チェック

エージェント定義の例:

code-explorer.md:

---
name: code-explorer
description: Deeply analyzes existing codebase features
tools: Glob, Grep, Read, TodoWrite, WebFetch, WebSearch
model: sonnet
color: yellow
---

You are an expert code analyst...

## Core Mission
Provide complete understanding of how a feature works...

## Analysis Approach
1. Feature Discovery
2. Code Flow Tracing
3. Architecture Analysis
4. Implementation Details

---

📚 補足：他のプラグインも学ぶ

code-reviewプラグイン

特徴: 信頼度スコアリングシステム

学ぶポイント:

• 複数の専門レビューエージェント
• 信頼度ベースのフィルタリング（≥80%）
• false positiveの削減

読むファイル:

plugins/code-review/commands/code-review.md
plugins/code-review/README.md

pr-review-toolkitプラグイン

特徴: 6つの専門分析エージェント

学ぶポイント:

• comment-analyzer: コメント分析
• test-analyzer: テストカバレッジ分析
• type-design-analyzer: 型設計分析
• code-reviewer: コードレビュー
• code-simplifier: 簡素化提案
• silent-failure-hunter: サイレント失敗検出

読むファイル:

plugins/pr-review-toolkit/agents/*.md

---

実践的な学習方法

1. 既存プラグインを試す

cd /path/to/claude-code
claude

# 試してみるコマンド
/commit              # シンプルなコマンド
/commit-push-pr      # 複雑なワークフロー
/feature-dev         # マルチエージェント
/code-review         # PR レビュー

2. コードリーディング

ファイルの読み方:

1. README.mdを先に読む

   • プラグインの目的を理解
   • 使い方を把握

2. plugin.jsonでメタデータを確認

   • 名前、バージョン、作者

3. コマンド/エージェント定義を読む

   • YAMLフロントマターの構造
   • マークダウン本文の内容
   • 動的コマンド実行の箇所

4. フロー図を描く

   • 処理の流れを視覚化
   • エージェント間の連携を理解

3. 自分でプラグインを作成

最小構成のプラグイン

目標: /hello コマンドを作る

手順:

1. ディレクトリ作成

mkdir -p .claude/commands

2. コマンド定義作成

cat > .claude/commands/hello.md << 'EOF'
---
description: Say hello to the user
---

Please greet the user in a friendly way and ask how you can help them today.
EOF

3. 試す

claude
# プロンプトで
/hello

中級プラグイン

目標: 動的コマンド実行を含むプラグイン

例: /status コマンド（Gitとnpmの状態を表示）

---
description: Show project status
allowed-tools: Bash(git status:*), Bash(npm:*)
---

# Project Status Report

## Git Status
!`git status`

## Current Branch
!`git branch --show-current`

## Package Info
!`npm list --depth=0`

## Your Task
Based on the above information, provide a concise summary of the project's current state.

上級プラグイン

目標: フックを含むプラグイン

例: ファイル保存前のlintチェック

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/hooks

hooks.json:

{
  "description": "Lint check before file edits",
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lint_check.py"
      }]
    }]
  }
}

lint_check.py:

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

input_data = json.load(sys.stdin)
file_path = input_data.get("file_path", "")

# TypeScriptファイルのみチェック
if file_path.endswith(".ts"):
    print("💡 Reminder: Run linter after editing TypeScript files")
    print("Command: npm run lint")

sys.exit(0)

---

デバッグとトラブルシューティング

フックのデバッグ

ログファイルを使う:

DEBUG_LOG_FILE = "/tmp/my-hook-debug.log"

def debug_log(message):
    with open(DEBUG_LOG_FILE, "a") as f:
        f.write(f"{message}\n")

debug_log(f"File path: {file_path}")
debug_log(f"Input data: {input_data}")

ログを確認:

tail -f /tmp/my-hook-debug.log

コマンドのデバッグ

1. 動的コマンドの確認:

   Debug info: !`echo "Current dir: $(pwd)"`

2. allowed-toolsの検証:

   • 制限が厳しすぎないか確認
   • 必要なツールが含まれているか確認

エージェントのデバッグ

1. toolsリストの確認:

   • 必要なツールが含まれているか
   • 不要なツールが含まれていないか

2. モデルの選択:

   • タスクに適したモデルか
   • コストとパフォーマンスのバランス

---

学習チェックリスト

初級

• コマンドファイルの構造を理解
• YAMLフロントマターの書き方を理解
• 動的コマンド実行を試した
• allowed-toolsの仕組みを理解
• 簡単なコマンドを自作した

中級

• フックの仕組みを理解
• hooks.jsonの構造を理解
• matcherパターンを理解
• Pythonスクリプトで入出力を処理できる
• PreToolUseフックを自作した

上級

• エージェントの仕組みを理解
• マルチエージェントワークフローを理解
• toolsパラメータの使い方を理解
• 並列エージェント実行を理解
• 複雑なプラグインを自作した

---

次のステップ

さらに深く学ぶ

1. 公式ドキュメントを読む:

   • https://docs.claude.com/en/docs/claude-code/overview
   • https://docs.claude.com/en/docs/claude-code/plugins

2. コミュニティプラグインを探す:

   • GitHub で検索
   • 他の開発者の実装を学ぶ

3. 自分のワークフローに合わせたプラグインを作る:

   • 日常のタスクを自動化
   • チーム固有の規約をフックで強制

プラグインを公開する

1. GitHubリポジトリを作成
2. README.mdを充実させる
3. plugin.jsonを適切に設定
4. コミュニティと共有

---

リソース

参考リンク

• Claude Code 公式ドキュメント
• プラグインシステム公式ドキュメント
• Agent SDK ドキュメント

実例

• シンプルなコマンドの例
• フックシステムの例
• マルチエージェントの例