はじめに
Claude Codeは強力なAIコーディングアシスタントですが、大規模なプロジェクトでは単一インスタンスの処理能力に限界があります。そこで私は、複数のClaude Codeインスタンスを「管理者」と「ワーカー」として協調動作させるシステムを構築しました。 この記事では、実際にLlama 3.1 70BモデルのQLoRA訓練分析で使用したワーカー協調システムの仕組み、実装、そして成果を詳しく紹介します。なぜ必要だったのか
課題:- 17個の並列GPU訓練ジョブの結果を分析
- 各ジョブのログファイル（SFT、DPO、検証）を詳細に解析
- 成功例と失敗例の分類、エラー原因の特定
- 技術レポートとブログ記事の作成
- 長時間の連続作業で文脈が肥大化
- 複数のサブタスクを並列実行できない
- 一つのタスクに集中すると他が停滞
システムアーキテクチャ
全体構成
┌─────────────────────────────────────────────────────────┐
│ 管理者インスタンス │
│ (/Users/masaka/dpo-rlhf-demo/) │
│ │
│ - マスターチケット作成 │
│ - サブチケット分割・割り当て │
│ - 進捗監視 │
│ - 最終統合 │
└──────────────┬───────────────────────┬──────────────────┘
│ │
┌───────┴───────┐ ┌──────┴────────┐
│ │ │ │
┌──────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐
│ Worker-1 │ │ Worker-2 │ │ Worker-3 │
│ (専用dir) │ │ (専用dir) │ │ (専用dir) │
│ │ │ │ │ │
│ チケットA │ │ チケットB │ │ チケットC │
│ 実行 │ │ 実行 │ │ 実行 │
└─────────────┘ └────────────┘ └────────────┘
│ │ │
└───────┬───────┴───────┬───────┘
│ │
┌──────▼───────────────▼──────┐
│ Discord通知システム │
│ (iPhone即座に受信可能) │
└─────────────────────────────┘ディレクトリ分離
各ワーカーは独立したディレクトリで作業し、Git衝突を回避：/Users/masaka/
├── dpo-rlhf-demo/ # 管理者用（メインリポジトリ）
├── dpo-rlhf-demo-worker-1/ # worker-1専用（クローン）
├── dpo-rlhf-demo-worker-2/ # worker-2専用（クローン）
└── dpo-rlhf-demo-worker-3/ # worker-3専用（クローン）- ✅ 各ワーカーが独立してGit操作可能
- ✅ ブランチ・コミットの衝突なし
- ✅ 同時編集による競合を回避
チケット駆動開発
すべての作業はチケット（Markdownファイル）で管理：---
priority: 1
description: "Trial 21 QLoRA成功例の詳細分析（ワーカータスクB）"
assignee: "worker-1"
role: "worker"
status: "assigned"
parent_ticket: "251101-045352-trial21-70b-analysis-master.md"
---主要コンポーネント
1. ワーカー識別システム
各ワーカーに一意の名前を付与し、~/.worker-nameに保存：
使い方:#!/bin/bash/Users/masaka/Documents/worker_identity_setup.sh
WORKER_NAME=$1ワーカー名を保存
echo "$WORKER_NAME" > ~/.worker-nameワーカー専用ディレクトリを作成
PROJECT_NAME="dpo-rlhf-demo" WORKER_DIR="/Users/masaka/${PROJECT_NAME}-${WORKER_NAME}"if [ ! -d "$WORKER_DIR" ]; then git clone "/Users/masaka/${PROJECT_NAME}" "$WORKER_DIR" fi
cd "$WORKER_DIR"
echo "✅ ワーカー: $WORKER_NAME" echo "✅ ディレクトリ: $WORKER_DIR"
bash /Users/masaka/Documents/worker_identity_setup.sh worker-12. チケット検索システム
ワーカーにアサインされた次のチケットを自動検索：使い方:#!/bin/bash/Users/masaka/Documents/next_ticket.sh
WORKER_NAME=$(cat ~/.worker-name 2>/dev/null)チケットを検索（優先度順、assignee=WORKER_NAME, status=assigned）
find tickets/ -name "*.md" -type f | while read ticket; do assignee=$(grep "^assignee:" "$ticket" | sed 's/assignee: "\(.\)"/\1/') status=$(grep "^status:" "$ticket" | sed 's/status: "\(.\)"/\1/') priority=$(grep "^priority:" "$ticket" | sed 's/priority: \(.\)/\1/')
if [ "$assignee" = "$WORKER_NAME" ] && [ "$status" = "assigned" ]; then echo "$priority|$ticket" fi done | sort -t'|' -k1 -n | head -1 | cut -d'|' -f2
bash /Users/masaka/Documents/next_ticket.sh✅ 次のチケット見つかりました！
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📌 チケット: 251101-165000-trial21-qlora-success-analysis.md 🎯 優先度: 2 📝 説明: Trial 21 QLoRA成功例の詳細分析（ワーカータスクB） ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3. Discord通知システム
作業完了時に管理者へ自動通知を送信：使い方:/Users/masaka/Documents/worker_ticket_notification.py
import os import yaml import requests from datetime import datetime
def send_notification(ticket_name): # ワーカー名を取得 with open(os.path.expanduser("~/.worker-name")) as f: worker_name = f.read().strip()
# チケット情報を読み込み with open(f"tickets/{ticket_name}") as f: content = f.read() metadata = yaml.safe_load(content.split("---")[1])
# Discord Webhook URLを取得 webhook_url = os.getenv("DISCORD_WEBHOOK_URL")
# 通知メッセージを構築 message = f""" ✅ チケット完了: {ticket_name}
ワーカー: {worker_name} 完了時刻: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
📝 説明 {metadata.get('description', 'なし')}
🎯 優先度 {metadata.get('priority', 'なし')} """
# Discord送信 requests.post(webhook_url, json={"content": message})
python3 /Users/masaka/Documents/worker_ticket_notification.py 251101-165000-trial21-qlora-success-analysis.md---✅ チケット完了: 251101-165000-trial21-qlora-success-analysis.mdワーカー: worker-1 完了時刻: 2025-11-01 17:30:00
📝 説明 Trial 21 QLoRA成功例の詳細分析（ワーカータスクB）
🎯 優先度 2
🔗 親チケット 251101-045352-trial21-70b-analysis-master
実際の使用例: Trial 21分析
背景
Llama 3.1 70BモデルのQLoRA訓練を17個の並列ジョブで実行。成功率22.2%（2/9）という結果を詳細分析する必要がありました。マスターチケット作成
管理者が親チケットを作成：---
priority: 1
description: "Trial 21: Llama 70BモデルQLoRA訓練の総合分析（管理者チケット）"
assignee: "manager"
role: "coordinator"
status: "assigned"
---
Trial 21: Llama 70BモデルQLoRA訓練の総合分析（マスター）
サブチケット一覧
チケットA: 結果ファイルの収集・整理
- 割り当て: worker-1
- 優先度: 1（最優先）
- タスク: 17個のジョブ結果を収集し、成功/失敗を分類
チケットB: QLoRA成功例の詳細分析
- 割り当て: worker-1
- 優先度: 2
- タスク: H100 SXM5とPCIeの成功ログを詳細分析
- 依存: チケットA完了後
チケットC: 失敗例のエラー分類
- 割り当て: manager（予備）
- 優先度: 3
チケットD: ブログ記事ドラフト作成
- 割り当て: manager（予備）
優先度: 4
Worker-1の作業フロー
#### Step 1: セットアップ新しいClaude Codeインスタンスを起動
bash /Users/masaka/Documents/worker_identity_setup.sh worker-1
出力:
✅ ワーカー名を設定: worker-1
✅ ワーカーディレクトリ作成: /Users/masaka/dpo-rlhf-demo-worker-1/
✅ リポジトリクローン完了
bash /Users/masaka/Documents/next_ticket.sh
出力:
✅ 次のチケット見つかりました！
📌 チケット: 251101-045500-trial21-results-collection.md
🎯 優先度: 1
成果物:cd /Users/masaka/dpo-rlhf-demo-worker-1 bash ~/ticket.sh start 251101-045500-trial21-results-collection.md作業実行（17個のジョブ結果を収集）
ls trial21_*_results/→ 9個のディレクトリ確認
→ 成功2個、失敗7個を分類
→ results_summary.md作成
bash ~/ticket.sh close
trial21_analysis/results_summary.md（136行）
#### Step 4: チケットB実行（QLoRA分析）
成果物:bash /Users/masaka/Documents/next_ticket.sh出力:
✅ 次のチケット見つかりました！
📌 チケット: 251101-165000-trial21-qlora-success-analysis.md
🎯 優先度: 2
bash ~/ticket.sh start 251101-165000-trial21-qlora-success-analysis.md作業実行（QLoRA成功例の詳細分析）
→ SFT訓練メトリクス抽出
→ H100 SXM5 vs PCIe比較
→ DPO/検証エラー原因特定
→ 詳細レポート作成
bash ~/ticket.sh close
trial21_analysis/qlora_success_detailed.md（387行、11.4KB）
#### Step 5: 完了通知
python3 /Users/masaka/Documents/worker_ticket_notification.py 251101-165000-trial21-qlora-success-analysis.md
Discord通知が管理者のiPhoneに即座に届く
成果
Worker-1が生成した成果物:1. 結果サマリー: - 9ジョブ分類（成功2、失敗7） - エラー種別の整理（HF認証、メモリ不足） - タイムスタンプ分析
2. QLoRA詳細分析レポート: - H100 SXM5: 4.1分、$0.29 - H100 PCIe: 5.7分、$0.24 - 性能比較表（SXM5は40%高速、PCIeは17%安い） - DPOメモリ不足の原因特定 - Reference model 8-bit量子化による解決策提案
作業時間: 約2時間（2つのチケット完了） 並列処理の効果: Worker-2、Worker-3を追加すれば3倍のスピードで処理可能。 ---技術的な工夫
1. Git衝突の回避
問題: 複数のClaude CodeがGitリポジトリを同時編集するとコンフリクト発生 解決策: ワーカーごとに独立したディレクトリ（クローン）を作成/Users/masaka/dpo-rlhf-demo/ # 管理者用（メイン）
/Users/masaka/dpo-rlhf-demo-worker-1/ # worker-1専用クローン
/Users/masaka/dpo-rlhf-demo-worker-2/ # worker-2専用クローン- 各ワーカーが独立してコミット可能
- ブランチ衝突なし
- プッシュ・プルのタイミングを自由に制御
2. YAMLメタデータの活用
チケットファイルのYAMLフロントマターで構造化データを管理：---
priority: 2 # 優先度（1-5）
assignee: "worker-1" # 担当者
role: "worker" # ロール（worker/coordinator）
status: "assigned" # ステータス（assigned/doing/done）
parent_ticket: "251101-045352..." # 親チケット
created_at: "2025-11-01T16:50:00Z" # 作成日時
started_at: null # 開始日時（自動更新）
closed_at: null # 完了日時（自動更新）
---- 機械可読（スクリプトで自動処理）
- 人間可読（Claude Codeが直接理解）
- Git差分で変更履歴を追跡
3. ステータス遷移の自動化
チケット開始
bash ~/ticket.sh start
→ status: "assigned" → "doing"
→ started_at: タイムスタンプ自動記録
→ 専用ブランチ作成
チケット完了
bash ~/ticket.sh close
→ status: "doing" → "done"
→ closed_at: タイムスタンプ自動記録
→ mainブランチへマージ
4. 優先度ベースの自動ソート
複数のチケットがアサインされている場合、優先度順に自動ソート：next_ticket.sh内の処理
find tickets/ -name "*.md" | while read ticket; do
# ... (チケット解析)
echo "$priority|$ticket"
done | sort -t'|' -k1 -n | head -1 # 優先度1が最優先5. Discord Webhook統合
環境変数からWebhook URLを取得し、iPhoneへリアルタイム通知：webhook_url = os.getenv("DISCORD_WEBHOOK_URL")
requests.post(webhook_url, json={"content": message})- 管理者がポーリング不要
- モバイルで即座に確認
- 複数ワーカーの進捗を一元管理
導入方法
前提条件
- Claude Code（複数インスタンス起動可能）
- Git（バージョン管理）
- Python 3.x（通知スクリプト用）
- Discord（オプション、通知用）
セットアップ手順
#### 1. ticket.shのインストールticket.shをダウンロード
curl -O https://raw.githubusercontent.com/masuidrive/ticket.sh/main/ticket.sh
実行権限を付与
chmod +x ticket.sh
プロジェクトディレクトリで初期化
./ticket.sh initworker_identity_setup.sh
next_ticket.sh
worker_ticket_notification.py
を /Users/masaka/Documents/ に配置
.env_keysファイルに追加
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_WEBHOOK_URL"~/.zshrc または ~/.bashrc
alias 次="bash /Users/masaka/Documents/next_ticket.sh"
alias チケット="bash ~/ticket.sh"
alias 開始="bash ~/ticket.sh start"
alias 完了="bash ~/ticket.sh close"
alias 通知="python3 /Users/masaka/Documents/worker_ticket_notification.py"使い方
#### 管理者（Coordinator）1. マスターチケット作成
2. サブチケット分割・割り当て
3. 進捗監視（bash ~/ticket.sh list）
4. 最終統合
1. セットアップ: bash worker_identity_setup.sh worker-1
2. 次のチケット確認: 次
3. チケット開始: 開始
4. 作業実行
5. チケット完了: 完了
6. 通知送信: 通知
7. 繰り返し
メリット・デメリット
メリット
#### 1. 並列処理による高速化
- 単一インスタンスの3-5倍のスループット
- 依存関係のないタスクを同時実行
#### 2. 文脈の分離
- 各ワーカーが専門タスクに集中
- 文脈肥大化を回避
#### 3. スケーラビリティ
- ワーカー数を動的に増減
- 大規模プロジェクトに対応
#### 4. 透明性
- チケットで進捗を可視化
- Git履歴で作業内容を追跡
#### 5. 柔軟性
- チケットの再割り当てが容易
- 優先度の動的変更
デメリット
#### 1. 初期セットアップのコスト
- スクリプト配置
- ディレクトリ構成
- 学習曲線
#### 2. 管理のオーバーヘッド
- チケット分割の判断
- 進捗監視
- 統合作業
#### 3. 通信コスト
- チケット確認
- 通知の送受信
#### 4. ツール依存
- ticket.sh
- Discord（オプション）
- カスタムスクリプト
適用シーン
向いているケース:- ✅ 大規模な分析・調査タスク
- ✅ 複数の独立したサブタスク
- ✅ 長時間の連続作業
- ✅ データ収集・整理・レポート作成
- ❌ 単純な1ファイル編集
- ❌ 高度に依存し合うタスク
- ❌ リアルタイムな共同編集
- ❌ セットアップコスト > 作業時間
実証済みの成功事例
Trial 21分析プロジェクト
規模:- 17個のGPU訓練ジョブ
- 数百MBのログファイル
- 9種類のエラーパターン
- 2つの成功例の詳細分析
- ✅ Worker-1が2つのチケット完了（2時間）
- ✅ 523行の技術レポート生成
- ✅ H100 GPUの性能比較表
- ✅ DPO訓練のメモリ課題と解決策を特定
- ✅ コストパフォーマンス分析（PCIeが17%安い）
- 単一インスタンスなら4-6時間かかる作業を2時間で完了
- 並列処理の余地あり（Worker-2、Worker-3追加可能）
ワーカー協調システム自体の開発
皮肉なことに、このブログ記事も Worker-1 によって作成されています！ メタ的な成功:- システムを使ってシステム自身を説明
- 387行の技術レポート + このブログ記事
- 実用性の自己証明
まとめ
ワーカー協調システムは、Claude Codeの制約を超えて大規模タスクを効率的に処理する実証済みのソリューションです。 キーポイント:1. ディレクトリ分離でGit衝突を回避 2. チケット駆動開発で作業を構造化 3. Discord通知でリアルタイム進捗共有 4. 優先度ベース自動ソートで効率的な作業順 5. 実証済みの成功（Trial 21で523行のレポート生成）
次のステップ: このシステムは以下のような拡張が可能です：- Webhookベースの自動チケット割り当て
- ワーカープール管理（動的スケーリング）
- 進捗ダッシュボード（Web UI）
- チケット依存関係の自動解決
- 他のAIエージェントへの応用
参考リンク
- ticket.sh: https://github.com/masuidrive/ticket.sh
- 詳細ドキュメント:
.claude/worker-coordination.md - 実装例: Trial 21分析プロジェクト
