はじめに
Claude Codeは豊富な拡張機能（Agent、Command、Hooks、Skills、Plugin）を備えており、開発ワークフロー全体を自動化できます。
本記事では、これらの拡張機能の仕組みを解説しつつ、私が開発した「並列開発ワークフロープラグイン」の設計思想と実装上の工夫を紹介します。このプラグインは、Git worktreeとtmuxを組み合わせて、大規模なタスクを複数のサブタスクに分解し並列実行することができます。
今回実装したプラグインは以下で公開しています。
TL;DR
- Claude Codeの5つの拡張機能：Subagent（メイン会話とは別のコンテキストでバックグラウンド実行できるAIアシスタント）、Command（よく使う指示をショートカット化）、Hooks（ツール実行前後に自動でスクリプトを実行）、Skills（Claudeが自動で発見・適用する能力）、Plugin（これらをまとめて配布できるパッケージ）
- 並列開発の実現方法：Git worktreeで独立した作業ディレクトリを作成し、tmuxセッションで各ワーカーを分離実行、これらをCommandとして定義した
- tmuxセッション早期終了問題の解決：CLAUDE.mdテンプレートにワークフロールールを明記し、意図しない並列ワーカーの終了を防止、AgentとCommandを組み合わせて制御できるようにした
- 監視のサブエージェント化：status-monitorエージェントがバックグラウンドで30秒間隔でワーカーを監視し、完了やエラーを自動検出できるようにした
Claude Codeの拡張機能
Claude Codeには5つの主要な拡張メカニズムがあります。それぞれの役割と特徴を見ていきましょう。
Subagent（サブエージェント）
サブエージェントは、メイン会話とは別のコンテキストでバックグラウンド実行できるAIアシスタントです。
特徴
- 独立したコンテキスト：各エージェントが独自のコンテキストウィンドウを持ち、メイン会話を汚染しない
- ツール制限：エージェントごとに使用可能なツールを制限可能
- モデル選択：Haiku（高速・軽量）、Sonnet（バランス）、Opus（高性能）から選択
- 自動委譲：Claudeがタスクに応じて適切なエージェントを自動選択
定義例
---
name: explorer
description: Fast codebase exploration for finding files and patterns
tools: Read, Grep, Glob
model: haiku
---
# Explorer Agent
You are a fast codebase explorer. Your job is to quickly find files,
patterns, and code locations.
## Constraints
- Complete searches within 30 seconds
- Focus on file discovery, not deep analysis
エージェントは.claude/agents/ディレクトリにMarkdownファイルとして配置します。
Command（スラッシュコマンド）
スラッシュコマンドは、よく使う指示をショートカット化したものです。
特徴
-
明示的な呼び出し：
/command-nameで実行 -
引数サポート：
$ARGUMENTSや$1、$2で動的入力を受け取り - Bash実行：コマンド実行結果をコンテキストに組み込み可能
-
ファイル参照：
@filepathで他ファイルの内容を埋め込み
定義例
---
description: Review a pull request for quality and security
allowed-tools: Bash, Read, Grep, Glob
---
# Review PR
Review PR #$1 for:
1. Code quality and readability
2. Security vulnerabilities
3. Test coverage
4. Performance implications
Current branch: !`git branch --show-current`
Hooks（フック）
フックは、イベント駆動型の自動実行スクリプトです。
特徴
- 決定論的実行：LLMに依存せず確実に実行される
- イベントベース：ツール呼び出し前後、セッション開始/終了など様々なタイミングで発火
- ファイル保護：機密ファイルの編集を自動ブロック
主要なイベントタイプ
| イベント | 説明 |
|---|---|
PreToolUse |
ツール実行前（ブロック可能） |
PostToolUse |
ツール実行後（自動フォーマットなど） |
Notification |
通知送信時 |
Stop |
セッション終了時 |
定義例
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "if echo '$FILE' | grep -q '\\.env'; then exit 2; fi"
}
]
}
]
}
}
Skills（スキル）
スキルは、Claudeが自動的に発見・適用する能力の拡張です。
特徴
- 自動検出：ユーザーの要求がスキルの説明にマッチすると自動提案
- 複数ファイル対応：SKILL.md本体と参照資料の組み合わせ
- 段階的情報開示：必要な情報だけを効率的にロード
コマンドとの違い
| 観点 | Command | Skill |
|---|---|---|
| 呼び出し | 明示的（/command） |
自動（Claudeが判断） |
| 構造 | 単一ファイル | ディレクトリ＋複数ファイル |
| 用途 | 頻繁な小さいタスク | 大規模な専門知識 |
Plugin（プラグイン）
プラグインは、上記すべてをパッケージ化した配布単位です。
my-plugin/
├── .claude-plugin/
│ └── plugin.json # プラグイン定義
├── commands/ # スラッシュコマンド
├── agents/ # サブエージェント
├── skills/ # スキル
└── hooks/
└── hooks.json # フック定義
Marketplaceを通じてチーム間で共有・配布が可能です。共有するにはmarketplace.jsonファイルを作成し、プラグインのメタデータを定義する必要があります。
Output Stylesについて（今回不使用）
Output Stylesは、Claude Codeのシステムプロンプト全体を変更する機能です。今回のプラグインでは、既存のClaude Codeの能力を活かしつつ拡張するアプローチを採用したため、使用しませんでした。
今回の実装方針：tmuxとGit worktreeを使った並列開発
設計思想
大規模な開発タスクを効率的に処理するため、以下のアプローチを採用しました。（/pw:hogehogeは今回実装したCommandです）
┌─────────────────────────────────────────────────────────┐
│ Orchestrator │
│ (/pw:decompose → /pw:orchestrate) │
└─────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Worker 1 │ │ Worker 2 │ │ Worker 3 │
│ (tmux) │ │ (tmux) │ │ (tmux) │
│ worktree-1 │ │ worktree-2 │ │ worktree-3 │
└─────────────┘ └─────────────┘ └─────────────┘
Git worktreeとtmuxによるセッション分離
Git worktreeで独立した作業ディレクトリを作成し、各worktreeに対応するtmuxセッションを起動して、独立したClaude Codeインスタンスを実行します。
# ワーカー並列化用スクリプトのの主要ロジック
for BRANCH in "$@"; do
BRANCH_SAFE="${BRANCH//\//-}"
SESSION_NAME="${PROJECT_NAME}__${BRANCH_SAFE}"
WORKTREE_PATH="../wt-${BRANCH_SAFE}"
# worktree作成
git worktree add "$WORKTREE_PATH" -b "$BRANCH" "$BASE_BRANCH"
# tmuxセッション起動
tmux new-session -d -s "$SESSION_NAME" -c "$WORKTREE_PATH"
done
ワークフロー全体
以下のCommandによってワークフローを制御します。
1. /pw:design → 仕様から実装設計を作成
2. /pw:decompose → 独立したサブタスクに分解
3. /pw:orchestrate → worktree + tmux セッション起動
4. /pw:worker → 各セッションでタスク実行
5. /pw:status → 進捗確認
6. /pw:review → PRレビュー
7. /pw:merge → マージ（人間の承認必須）
8. /pw:cleanup → 並列ワーカー環境のクリーンアップ
並列タスク使用時の注意点と工夫
問題1：tmuxセッションが早期終了してしまう
発生した問題
並列ワーカーが自分のタスクを完了すると、PRを作成する前にtmuxセッションを終了してしまうことがありました。これは、Claudeが「タスク完了」と判断してセッションを閉じてしまうためです。
解決策：CLAUDE.mdテンプレートの作成
プロジェクトごとに配置するCLAUDE.md用のテンプレートを作成し、ワークフロールールを明記しました。
## Git Workflow
**CRITICAL**: Follow these rules strictly.
### Branch Protection
- **NEVER** push directly to `main` or `release` branches
- Always create a feature branch from the default branch
- Submit all changes via Pull Request
- Wait for CI checks to pass before merging
### Default Behavior for Implementation Tasks
When implementing features or fixing bugs:
1. **First**: Use `explorer` subagent to find relevant code
2. **Then**: Plan minimal changes based on existing patterns
3. **Implement**: Follow this project's code style
4. **Verify**: Run `make check` before committing
5. **For large tasks**: Consider `/pw:design` for parallel execution
これにより、ワーカーがPR作成まで確実に実行するようになりました。
問題2：ワーカーの進捗監視
発生した問題
複数のワーカーが並列で動作している間、オーケストレーターは各ワーカーの状態を把握できませんでした。オーケストレーター進捗を監視する際に、オーケストレーターのJobは停止してしまうのでやや非効率でした。
解決策：status-monitorサブエージェントの作成
バックグラウンドで動作する監視エージェントを作成することで、オーケストレーターで監視Jobを実行する必要がなくなりました。
---
name: status-monitor
description: Background status monitoring agent
tools: Bash
model: haiku
---
# Status Monitor Agent
- **Check interval**: 30 seconds
- **Max checks**: 60 (30 minutes total)
- **Report on**: PR creation, errors, completion
このエージェントは以下を自動検出します：
| パターン | 状態 |
|---|---|
error, failed, exception
|
⚠️ ERROR |
pull request, pr created
|
✅ COMPLETED |
committed, git commit
|
🔄 COMMITTED |
| その他 | ⏳ WORKING |
# 監視スクリプトのロジックの一部
for session in $(tmux list-sessions -F '#{session_name}' | grep "^${PROJECT_NAME}__"); do
OUTPUT=$(tmux capture-pane -t "$session" -p | tail -30)
if echo "$OUTPUT" | grep -qi "error\|failed"; then
echo "⚠️ $session: ERROR DETECTED"
elif echo "$OUTPUT" | grep -qi "pull request\|pr created"; then
echo "✅ $session: PR CREATED"
fi
done
サブエージェント化のメリット
- 独立したコンテキスト：メインの会話を汚染しない
- 軽量モデル使用：Haikuで十分なため、コスト効率が良い
- バックグラウンド実行：オーケストレーターは他の作業を続行可能
- 自動通知：全ワーカー完了時に自動で報告
その他の工夫
モデルの使い分け
タスクの複雑さに応じてモデルを選択しています。
| エージェント | モデル | 用途 |
|---|---|---|
| explorer | Haiku | 高速なファイル検索 |
| status-monitor | Haiku | 軽量な監視処理 |
| analyzer | Sonnet | 深いコード分析 |
| worker | Opus | 実装タスク |
ガードレール
PRマージには必ず人間の承認を要求するようにして、勝手にデプロイが走らないにようにしています。
# マージ前の検証
REVIEW=$(gh pr view $PR --json reviewDecision --jq '.reviewDecision')
if [ "$REVIEW" != "APPROVED" ]; then
echo "❌ Human approval required"
exit 1
fi
プラグインの全体像
今回実装したプラグインは以下で公開しています。
本記事で紹介しきれなかったコンポーネントの一覧です。
Commands（スラッシュコマンド）
| コマンド | 説明 |
|---|---|
/pw:design |
GitHub IssueやSpecから実装設計を作成 |
/pw:decompose |
大規模タスクを並列実行可能なサブタスクに分解 |
/pw:orchestrate |
worktree + tmuxセッションを起動しワーカーを開始 |
/pw:worker |
割り当てられたタスクを実行 |
/pw:status |
全ワーカーとPRの進捗を確認 |
/pw:review |
PRの品質・セキュリティレビュー |
/pw:fix |
レビュー指摘への対応 |
/pw:merge |
PRをマージ（人間の承認必須） |
/pw:cleanup |
ワーカー環境のクリーンアップ |
/pw:resolve-conflicts |
マージコンフリクトの解消 |
Skills（スキル）
| スキル | 説明 |
|---|---|
code-quality |
コード品質チェックリスト（可読性、保守性、型安全性） |
security-review |
セキュリティレビューチェックリスト（OWASP Top 10対応） |
Agents（サブエージェント）
| エージェント | モデル | 説明 |
|---|---|---|
explorer |
Haiku | 高速なファイル検索・パターン探索 |
analyzer |
Sonnet | 深いアーキテクチャ分析 |
status-monitor |
Haiku | バックグラウンドでワーカー進捗を監視 |
Hooks
| イベント | 説明 |
|---|---|
PreToolUse |
.envなどの機密ファイル編集をブロック |
Notification |
セッション完了時のデスクトップ通知 |
Stop |
セッション終了時のログ記録 |
まとめ
Claude Codeの拡張機能を活用することで、大規模な開発タスクを効率的に並列処理できるプラグインを実装しました。
学んだこと
- 拡張機能の使い分け：Agent、Command、Skills、Hooksはそれぞれ異なる目的を持ち、適切に組み合わせることで強力なワークフローを構築できる
- Git worktree + tmuxの相性の良さ：完全に独立した作業環境を構築でき、並列開発に最適
- サブエージェントの活用：監視や探索など、特定の役割を分離することで効率とコスト最適化を両立
ぜひ試してみてください！
Discussion