ultrapilot

Ultrapilot スキル

ファイルの所有権を分割し、複数のワーカーを起動する並列自動操縦機能です。最大限の速度を実現します。

概要

Ultrapilot は、自動操縦機能を並列化したものです。タスクを並列実行可能な独立したサブタスクに分解し、重複しないファイルセットを各ワーカーに割り当てて、同時に実行します。

主な機能：

1. タスクを並列実行が安全なコンポーネントに分解します
2. ファイルを排他的な所有権で分割します（競合なし）
3. 最大 20 個の並列ワーカーを起動します
4. TaskOutput を介して進捗を調整します
5. 共有ファイルを順次処理しながら変更を統合します
6. システム全体の整合性を検証します

速度倍率： 適したタスクでは、順次実行の自動操縦より最大 5 倍高速です。

使用方法

/oh-my-claudecode:ultrapilot <your task>
/oh-my-claudecode:up "Build a full-stack todo app"
/oh-my-claudecode:ultrapilot Refactor the entire backend

マジックキーワード

次のフレーズを使うと、Ultrapilot が自動的に有効になります。

• 「ultrapilot」、「ultra pilot」
• 「parallel build」、「parallel autopilot」
• 「swarm build」、「swarm mode」
• 「fast parallel」、「ultra fast」

使用するタイミング

Ultrapilot が得意なタスク：

• 複数コンポーネントのシステム（フロントエンド + バックエンド + データベース）
• 異なるモジュールにまたがる独立した機能の追加
• モジュールの境界が明確な大規模リファクタリング
• テストファイルの並列生成
• 複数サービスのアーキテクチャ

Autopilot が適しているタスク：

• シングルスレッドで順次実行するタスク
• コンポーネント間の相互依存が強いタスク
• 継続的な統合チェックが必要なタスク
• 単一モジュール内の、小規模で範囲が明確な機能

アーキテクチャ

User Input: "Build a full-stack todo app"
           |
           v
  [ULTRAPILOT COORDINATOR]
           |
   Decomposition + File Partitioning
           |
   +-------+-------+-------+-------+
   |       |       |       |       |
   v       v       v       v       v
[W-1]   [W-2]   [W-3]   [W-4]   [W-5]
backend frontend database api-docs tests
(src/  (src/   (src/    (docs/)  (tests/)
 api/)  ui/)    db/)
   |       |       |       |       |
   +---+---+---+---+---+---+---+---+
       |
       v
  [INTEGRATION PHASE]
  (shared files: package.json, tsconfig.json, etc.)
       |
       v
  [VALIDATION PHASE]
  (full system test)

フェーズ

フェーズ 0：タスク分析

目標： タスクが並列化可能かどうかを判断します

チェック項目：

• タスクを 2 つ以上の独立したサブタスクに分割できますか？
• ファイルの境界は明確ですか？
• 依存関係は最小限ですか？

出力： 実行可否の判定（適さない場合は Autopilot に切り替えます）

フェーズ 1：分解

目標： タスクを並列実行が安全なサブタスクに分割します

エージェント： Architect（Opus）

方法： AI によるタスク分解

Ultrapilot は decomposer モジュールを使って、タスクをインテリジェントに分解します。

import {
  generateDecompositionPrompt,
  parseDecompositionResult,
  validateFileOwnership,
  extractSharedFiles
} from 'src/hooks/ultrapilot/decomposer';

// 1. Generate prompt for Architect
const prompt = generateDecompositionPrompt(task, codebaseContext, {
  maxSubtasks: 5,
  preferredModel: 'sonnet'
});

// 2. Call Architect agent
const response = await Task({
  subagent_type: 'oh-my-claudecode:architect',
  model: 'opus',
  prompt
});

// 3. Parse structured result
const result = parseDecompositionResult(response);

// 4. Validate no file conflicts
const { isValid, conflicts } = validateFileOwnership(result.subtasks);

// 5. Extract shared files from subtasks
const finalResult = extractSharedFiles(result);

プロセス：

1. Architect エージェントを介してタスクの要件を分析します
2. ファイルの境界に基づいて、独立したコンポーネントを特定します
3. 複雑さに応じてエージェントの種類（executor-low／executor／executor-high）を割り当てます
4. サブタスク間の依存関係（blockedBy）をマッピングします
5. 並列実行グループを生成します
6. 共有ファイルを特定します（コーディネーターが処理します）

出力： 構造化された DecompositionResult：

{
  "subtasks": [
    {
      "id": "1",
      "description": "Backend API routes",
      "files": ["src/api/routes.ts", "src/api/handlers.ts"],
      "blockedBy": [],
      "agentType": "executor",
      "model": "sonnet"
    },
    {
      "id": "2",
      "description": "Frontend components",
      "files": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
      "blockedBy": [],
      "agentType": "executor",
      "model": "sonnet"
    },
    {
      "id": "3",
      "description": "Wire frontend to backend",
      "files": ["src/client/api.ts"],
      "blockedBy": ["1", "2"],
      "agentType": "executor-low",
      "model": "haiku"
    }
  ],
  "sharedFiles": [
    "package.json",
    "tsconfig.json",
    "README.md"
  ],
  "parallelGroups": [["1", "2"], ["3"]]
}

分解の種類：

種類	説明	用途
DecomposedTask	id、files、blockedBy、agentType、model を含む完全なタスク	インテリジェントなワーカーの起動
DecompositionResult	subtasks、sharedFiles、parallelGroups を含む完全な結果	分解結果全体
toSimpleSubtasks()	レガシー互換性のために string[] に変換します	シンプルなタスクリスト

フェーズ 2：ファイル所有権の分割

目標： 排他的なファイルセットをワーカーに割り当てます

ルール：

1. 排他的な所有権 - 複数のワーカーセットに同じファイルを含めません
2. 共有ファイルは後回し - 統合時に順次処理します
3. 境界ファイルを追跡 - 境界をまたいでインポートするファイルを追跡します

データ構造： .omc/state/ultrapilot-ownership.json

{
  "sessionId": "ultrapilot-20260123-1234",
  "workers": {
    "worker-1": {
      "ownedFiles": ["src/api/routes.ts", "src/api/handlers.ts"],
      "ownedGlobs": ["src/api/**"],
      "boundaryImports": ["src/types.ts"]
    },
    "worker-2": {
      "ownedFiles": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
      "ownedGlobs": ["src/ui/**"],
      "boundaryImports": ["src/types.ts"]
    }
  },
  "sharedFiles": ["package.json", "tsconfig.json", "src/types.ts"],
  "conflictPolicy": "coordinator-handles"
}

フェーズ 3：並列実行

目標： すべてのワーカーを同時に実行します

ワーカーの起動：

// Pseudocode
workers = [];
for (subtask in decomposition.subtasks) {
  workers.push(
    Task(
      subagent_type: "oh-my-claudecode:executor",
      model: "sonnet",
      prompt: `ULTRAPILOT WORKER ${subtask.id}

Your exclusive file ownership: ${subtask.files}

Task: ${subtask.description}

CRITICAL RULES:
1. ONLY modify files in your ownership set
2. If you need to modify a shared file, document the change in your output
3. Do NOT create new files outside your ownership
4. Track all imports from boundary files

Deliver: Code changes + list of boundary dependencies`,
      run_in_background: true
    )
  );
}

モニタリング：

• 各ワーカーの TaskOutput をポーリングします
• 完了ステータスを追跡します
• 競合を早期に検出します
• 境界依存関係を蓄積します

最大ワーカー数： 5（Claude Code の上限）

フェーズ 4：統合

目標： すべてのワーカーの変更をマージし、共有ファイルに対応します

プロセス：

1. 成果物を収集 - すべてのワーカーの成果物を集めます
2. 競合を検出 - 想定外の重複がないか確認します
3. 共有ファイルに対応 - package.json などを順番に更新します
4. 境界ファイルを統合 - 型定義や共有ユーティリティをマージします
5. インポートを解決 - 境界をまたぐインポートが有効であることを確認します

エージェント： Executor（Sonnet）- 順次処理

競合の解決：

• ワーカーが予期せず同じファイルを変更した場合 → 手動でマージします
• 共有ファイルに複数の変更が必要な場合 → 順番に適用します
• 境界ファイルが変更された場合 → 依存するすべてのワーカーを検証します

フェーズ 5：検証

目標： 統合されたシステムが動作することを確認します

チェック（並列）：

1. ビルド - プロジェクトのビルドコマンドを実行します
2. Lint - プロジェクトの lint コマンドを実行します
3. 型チェック - プロジェクトの型チェックコマンドを実行します
4. ユニットテスト - すべてのテストに合格することを確認します
5. 統合テスト - コンポーネント間のテストを実行します

エージェント（並列）：

• Build-fixer（Sonnet）- ビルドエラーを修正します
• Architect（Opus）- 機能が完全であることを確認します
• Security-reviewer（Opus）- コンポーネント間の脆弱性を確認します

再試行ポリシー： 検証は最大 3 ラウンドまでです。失敗が続く場合は、詳細なエラーレポートをユーザーに提示します。

状態管理

セッション状態

場所： .omc/ultrapilot-state.json

{
  "sessionId": "ultrapilot-20260123-1234",
  "taskDescription": "Build a full-stack todo app",
  "phase": "execution",
  "startTime": "2026-01-23T10:30:00Z",
  "decomposition": { /* from Phase 1 */ },
  "workers": {
    "worker-1": {
      "status": "running",
      "taskId": "task-abc123",
      "startTime": "2026-01-23T10:31:00Z",
      "estimatedDuration": "5m"
    }
  },
  "conflicts": [],
  "validationAttempts": 0
}

ファイル所有権マップ

場所： .omc/state/ultrapilot-ownership.json

どのワーカーがどのファイルを所有しているかを追跡します（上記のフェーズ 2 の例を参照）。

進捗状況の追跡

場所： .omc/ultrapilot/progress.json

{
  "totalWorkers": 5,
  "completedWorkers": 3,
  "activeWorkers": 2,
  "failedWorkers": 0,
  "estimatedTimeRemaining": "2m30s"
}

設定

.claude/settings.json で設定できるオプション項目：

{
  "omc": {
    "ultrapilot": {
      "maxWorkers": 5,
      "maxValidationRounds": 3,
      "conflictPolicy": "coordinator-handles",
      "fallbackToAutopilot": true,
      "parallelThreshold": 2,
      "pauseAfterDecomposition": false,
      "verboseProgress": true
    }
  }
}

設定の説明：

• maxWorkers - 並列ワーカーの最大数（Claude Code の上限は 5 です）
• maxValidationRounds - 検証の再試行回数
• conflictPolicy - 「coordinator-handles」または「abort-on-conflict」
• fallbackToAutopilot - タスクを並列化できない場合に自動で切り替えます
• parallelThreshold - ultrapilot を使用する最小サブタスク数（それ未満の場合はフォールバックします）
• pauseAfterDecomposition - 実行前にユーザーに確認します
• verboseProgress - ワーカーの進捗状況を詳細に表示します

キャンセル

/oh-my-claudecode:cancel

または、「stop」、「cancel ultrapilot」、「abort」と言います。

動作：

• すべての実行中ワーカーを正常に終了します
• 途中までの進捗状況を状態ファイルに保存します
• セッションを再開できます

再開

ultrapilot がキャンセルされた場合、またはワーカーが失敗した場合：

/oh-my-claudecode:ultrapilot resume

再開のロジック：

• 失敗したワーカーのみ再起動します
• 完了したワーカーの成果物を再利用します
• 最後のフェーズから続行します

例

例 1：フルスタックアプリ

/oh-my-claudecode:ultrapilot Build a todo app with React frontend, Express backend, and PostgreSQL database

ワーカー：

1. フロントエンド（src/client/）
2. バックエンド（src/server/）
3. データベース（src/db/）
4. テスト（tests/）
5. ドキュメント（docs/）

共有ファイル： package.json、docker-compose.yml、README.md

所要時間： 約 15 分（順次実行の場合は約 75 分）

例 2：複数サービスのリファクタリング

/oh-my-claudecode:up Refactor all services to use dependency injection

ワーカー：

1. 認証サービス
2. ユーザーサービス
3. 決済サービス
4. 通知サービス

共有ファイル： src/types/services.ts、tsconfig.json

所要時間： 約 8 分（順次実行の場合は約 32 分）

例 3：テストカバレッジ

/oh-my-claudecode:ultrapilot Generate tests for all untested modules

ワーカー：

1. API テスト
2. UI コンポーネントテスト
3. データベーステスト
4. ユーティリティテスト
5. 統合テスト

共有ファイル： jest.config.js、test-utils.ts

所要時間： 約 10 分（順次実行の場合は約 50 分）

ベストプラクティス

1. 明確なモジュール境界 - コードが適切に分離されている場合に最も効果を発揮します
2. 共有状態を最小限にする - 統合の複雑さを軽減します
3. 分割を信頼する - Architect は並列処理が安全な範囲を把握しています
4. 進捗状況を確認する - .omc/ultrapilot/progress.json を確認します
5. 競合を早期に確認する - 統合の段階まで待たないでください

ファイル所有権の戦略

所有権の種類

排他的所有権：

• ワーカーが単独で書き込みアクセスできます
• 他のワーカーはこれらのファイルに触れられません
• ワーカーは所有するディレクトリ内に新しいファイルを作成できます

共有ファイル：

• どのワーカーも排他的なアクセス権を持ちません
• 統合フェーズで順次処理されます
• 対象：package.json、tsconfig.json、設定ファイル、ルートの README

境界ファイル：

• すべてのワーカーが読み取り可能です
• 書き込みアクセス権は使用状況の分析によって決まります
• 一般的な例：型定義、共有ユーティリティ、インターフェース

所有権検出アルゴリズム

For each file in codebase:
  If file in shared_patterns (package.json, *.config.js):
    → sharedFiles

  Else if file imported by 2+ subtask modules:
    → boundaryFiles
    → Assign to most relevant worker OR defer to shared

  Else if file in subtask directory:
    → Assign to subtask worker

  Else:
    → sharedFiles (safe default)

共有ファイルのパターン

以下は自動的に共有ファイルとして分類されます：

• package.json、package-lock.json
• tsconfig.json、*.config.js、*.config.ts
• .eslintrc.*、.prettierrc.*
• README.md、CONTRIBUTING.md、LICENSE
• Docker ファイル：Dockerfile、docker-compose.yml
• CI ファイル：.github/**、.gitlab-ci.yml

競合の処理

競合の種類

予期しない重複：

• 2 つのワーカーが同じファイルを変更しました
• 解決方法： コーディネーターがユーザーの確認を得てマージします

共有ファイルの競合：

• 複数のワーカーが package.json の更新を必要としています
• 解決方法： 統合フェーズで順次適用します

境界ファイルの競合：

• 複数のワーカーが型定義を必要としています
• 解決方法： 最初のワーカーが作成し、他のワーカーはインポートします

競合ポリシー

coordinator-handles（デフォルト）：

• コーディネーターが自動マージを試みます
• 複雑な場合はユーザーに引き継ぎます

abort-on-conflict：

• 競合が発生すると、ultrapilot は直ちにキャンセルされます
• ユーザーが競合レポートを確認します
• 手動で修正した後に再開できます

トラブルシューティング

分解に失敗しますか？

• タスクの結合度が高すぎる可能性があります
• フォールバックとして autopilot が自動的に起動します
• 詳細は .omc/ultrapilot/decomposition.json を確認してください

ワーカーが応答しなくなりますか？

• .omc/logs/ultrapilot-worker-N.log でワーカーログを確認してください
• そのワーカーをキャンセルして再起動してください
• ファイルの所有権に問題がある可能性があります

統合時に競合が発生しますか？

• .omc/ultrapilot-state.json の conflicts 配列を確認してください
• 共有ファイルが予期せず変更されていないか確認してください
• 必要に応じて所有権ルールを調整してください

検証がループしますか？

• コンポーネント間の統合に問題があります
• 境界ファイルのインポートを確認してください
• 完全なコンテキストを使って順次再試行する必要があるかもしれません

処理が遅すぎますか？

• ワーカーが本当に独立しているか確認してください
• 分解の品質を確認してください
• autopilot のほうが速いかどうか検討してください（相互依存性が高い場合）

Autopilot との違い

機能	Autopilot	Ultrapilot
実行方式	順次	並列（最大 5 倍）
最適な用途	シングルスレッドのタスク	複数コンポーネントのシステム
複雑さ	低い	高い
速度	標準	3～5 倍高速（適したタスクの場合）
ファイルの競合	該当なし	所有権の分割
フォールバック	該当なし	autopilot にフォールバック可能
セットアップ	即時	分解フェーズ（約 1～2 分）

目安： タスクに独立したコンポーネントが 3 つ以上ある場合は ultrapilot を使ってください。それ以外の場合は autopilot を使ってください。

応用：カスタム分解

カスタム分解ファイルを指定して、フェーズ 1 を省略できます：

場所： .omc/ultrapilot/custom-decomposition.json

{
  "subtasks": [
    {
      "id": "worker-auth",
      "description": "Add OAuth2 authentication",
      "files": ["src/auth/**", "src/middleware/auth.ts"],
      "dependencies": ["src/types/user.ts"]
    },
    {
      "id": "worker-db",
      "description": "Add user table and migrations",
      "files": ["src/db/migrations/**", "src/db/models/user.ts"],
      "dependencies": []
    }
  ],
  "sharedFiles": ["package.json", "src/types/user.ts"]
}

その後、次を実行します：

/oh-my-claudecode:ultrapilot --custom-decomposition

完了時の状態のクリーンアップ

重要：完了時には状態ファイルを削除してください。active: false に設定するだけでは不十分です

すべてのワーカーが正常に完了したら：

# Delete ultrapilot state files
rm -f .omc/state/ultrapilot-state.json
rm -f .omc/state/ultrapilot-ownership.json

今後の機能強化

v4.1 で予定：

• ワーカーの動的スケーリング（2 つから開始し、必要に応じて追加）
• 競合の予測検出（統合前の分析）
• ワーカー間の通信（まれな依存関係に対応）
• 投機的実行（楽観的な並列処理）
• 統合フェーズからの再開（検証に失敗した場合）

v4.2 で予定：

• 複数マシンへの分散（Claude Code がサポートする場合）
• リアルタイムの進捗ダッシュボード
• ワーカーのパフォーマンス分析
• 分解戦略の自動調整