コアコンセプト

Minionシステムを構成する主要な概念を説明します。

ミニオン

ミニオンは独立したVPS上で動作するClaude Codeエージェントです。各ミニオンは以下を備えています。

コンポーネント	説明
Claude Code CLI	AIエージェントの実行環境
Fastify API	HQとの通信用APIサーバー (port 3001)
Xvfb + noVNC	仮想ディスプレイとブラウザVNC (port 6080)
ttyd	Webターミナル (port 7681)
Cloudflare Tunnel	安全な外部接続
MCP Servers	Playwright, Serena等の拡張ツール

プロジェクト

プロジェクトはワークフローとコンテキストをまとめる単位です。

ミニオンをメンバーとしてアサイン（PM / Engineer ロール）
共有コンテキストをMarkdownで定義
プロジェクト配下のワークフローはメンバー全員が参照可能

スキル

スキルはClaude Codeの再利用可能なプロンプトです。SKILL.mdファイルとして定義され、バージョン管理されます。

---
name: my-skill
display_name: My Skill
description: スキルの説明
---

ここにプロンプトの本文を記述します。

スキルは付随するファイル（テンプレート、設定等）を持つこともできます。

ワークフロー

ワークフローはプロジェクト単位のグラフで、スキルと複数のミニオンを組織的なガバナンスのもとで協調させます。一本道のステップ列ではなく、ノードをエッジでつないだDAG（有向非巡回グラフ）として、HQのビジュアルエディタで構築します。

flowchart LR
    S(("Start")) --> A["Skill: fetch"]
    A --> C{{"Conditional"}}
    C -->|ok| F[["Fan-out"]]
    C -->|error| E(("End"))
    F --> J(("Join"))
    J --> R{"Review"}
    R -->|approved| E

並列実行・fan-out/join・条件分岐 — 単なる直列ではなく実際の依存関係を表現できる
cron式によるスケジュール実行、またはHQからのオンデマンド実行
各ノードに実行ロール（PM / Engineer）を割り当て可能
レビューノードで人間（またはミニオン）の承認ゲートと差し戻しループを挟める
完全なバージョン管理 — 変更のたびにイミュータブルなスナップショットを作成
HQデータベースに完全な監査証跡を記録

利用できるノードの種類はDAGノードを参照してください。

ルーティン

ルーティンはミニオン単位のパイプラインで、自律的に完結するスケジュールタスクです。

flowchart LR
    A["skill-1"] --> B["skill-2"]

プロジェクトではなくミニオン個体が所有
ミニオン上のcronスケジューラでHQを介さず自律実行
ロール割り当てやレビューゲートなし — 所有ミニオンがすべてのステップを実行
常に最新のスキルバージョンを使用（バージョン固定なし）
実行履歴はミニオンのローカルに保存

ルーティンはミニオン個人のcrontabと考えてください。

使い分けの判断基準

複数スキルを扱うかどうかではなく、ガバナンスのレベルとオーケストレーションの複雑さが差別化のポイントです。

**「誰が実行するか」**が1体で決まっている → ルーティン
**「誰が実行するか」**をロールで割り振る → ワークフロー
レビューゲートや監査証跡が必要 → ワークフロー
並列分岐・fan-out・条件分岐が必要 → ワークフロー
ミニオンの自律的な習慣 → ルーティン

同じスキルをルーティンにもワークフローにも使えます。詳細な比較と例はルーティン設計を参照してください。