/moai harness

プロジェクト固有の動的な専門家チーム (ハーネス) を生成し、ハーネス学習ライフサイクルを管理します。

情報

スラッシュコマンド: Claude Code で /moai:harness <自然言語リクエスト> と入力すると、このコマンドをすぐに実行できます。

/moai:harness は MoAI-ADK の Harness v4 Builder を実行して、プロジェクト要件に合わせた動的な専門家チームを自動生成します。

v3 の 3 つ目の核心である エージェンティックハーネス をそのまま体感できるコマンドです — ハーネスがハーネスを作る再帰構造です。汎用エージェントカタログでは足りないプロジェクト固有の領域 (例: 特定の DB マイグレーション手順、社内 API 規約) があれば、自然言語一文でその領域の専門家チームをスキャフォールドできます。生成されたハーネスは 再帰的な自己学習 サブシステムにつながります — 使用の観察が蓄積されるとハーネスが自ら改善提案を作り、ユーザー承認ゲートを経て指針が進化します。

Harness v4 Builder は Socratic インタビューベースの 4-phase ワークフロー (ANALYZE → PLAN → GENERATE → ACTIVATE) でチームを構成します。

moai harness は単一の Cobra サブコマンドツリーで、最初の引数 ($ARGUMENTS の最初のトークン) に応じて 3 つの経路のいずれかに分岐します — 別のコマンドを導入しない argument-branching ルーティング です。

flowchart TD
    A["moai harness <最初のトークン>"] --> B{"予約された動詞?"}
    B -->|status / apply / rollback / disable| C["Branch A
学習ライフサイクル"]
    B -->|list / edit / remove / doctor| D["Branch A.1
v4 ライフサイクル"]
    B -->|自然言語リクエスト| E["Branch B
ハーネスビルドエントリ"]
    E --> F["ANALYZE → PLAN → GENERATE → ACTIVATE"]
    C --> G["ファイルシステム操作
(Go バイナリ Cobra サブコマンド)"]
    D --> G

すべての動詞は moai harness <verb> の Go バイナリ Cobra サブコマンドツリーを通じて同じように dispatch されます — 学習動詞と v4 動詞がそれぞれ別の Go バイナリに分離されることはありません。

> /moai:harness <自然言語リクエスト>

例:

私たちの Go バックエンドプロジェクトに合う専門家チームを作って。
DB マイグレーション、REST API エンドポイント、ユニットテストをそれぞれ担当するチームが必要。

Builder が 4-phase を自動実行します:

1. ANALYZE: Go、PostgreSQL、REST API の技術スタックを検出
2. PLAN: DB Engineer、API Developer、Test Engineer の 3 名チーム構成を決定
3. GENERATE:
   • .claude/agents/harness/db-engineer.md
   • .claude/agents/harness/api-developer.md
   • .claude/agents/harness/test-engineer.md
   • .moai/harness/manifest.json を生成
4. ACTIVATE: /harness:backend-team コマンドを登録

生成後、すべての作業でチームを自動活用:

/moai run SPEC-BACKEND-001

MoAI が SPEC の複雑度を分析し、manifest の phase 順にメンバーを自動委任します。

生成されたハーネスは moai harness サブコマンドで管理します。4 つの v4 ライフサイクル動詞が Go バイナリ Cobra サブコマンドとして dispatch されます。

生成されたすべてのハーネス一覧を照会します:

moai harness list

出力情報: ハーネス名、ドメイン、エントリコマンド、manifest に宣言されたスケジュール (宣言時のみ表示)。

manifest.json とエージェント定義ファイルのパスを表示して編集を案内します — manifest が SSOT です:

moai harness edit backend-team

編集対象:

• .claude/commands/harness/<name>/manifest.json (SSOT)
• .claude/agents/harness/hns-<name>*-specialist.md (専門家定義)
• .claude/skills/hns-<name>*/ (コンパニオンスキル)

ハーネスおよびすべての関連ファイルを原子的に削除します:

moai harness remove backend-team

削除される項目:

• .claude/commands/harness/<name>.md (thin-wrapper command)
• .claude/commands/harness/<name>/manifest.json (SSOT)
• .claude/workflows/hns-<name>-run.js (Runner)
• .claude/agents/harness/hns-<name>*-specialist.md (専門家)
• .claude/skills/hns-<name>*/ (コンパニオンスキル)

注意

remove は fail-closed で動作します — 成果物のいずれか 1 つでも欠落していると削除を中断し、欠落ファイルを報告します。orphan 成果物が残らないよう保証します。

すべてのハーネスの参照整合性を検証する smoke gate です:

moai harness doctor

検査項目:

• すべてのハーネスの manifest / specialist / skill ファイルの存在有無
• manifest と成果物間の相互参照の一致
• スケジュール宣言のスキーマ有効性 (無効時は ERROR 深刻度)

ハーネスは生成して終わりの静的な成果物ではありません。moai harness サブコマンドで 学習サブシステム のライフサイクルを管理します。学習動詞 (status / apply / rollback / disable) は Branch A にルーティングされます。

4 階層学習のはしご — 観察が積み重なるほど学習段階が上がります:

成果物: .moai/harness/ ディレクトリ (usage-log.jsonl, learned-rules.yaml, proposals/, learning-history/snapshots/)

Tier-4 (TierAutoUpdate) 提案はファイル修正前に 必ず オーケストレーター発行の AskUserQuestion ラウンドを経る必要があります。ワークフロー本体はオーケストレーターのメインコンテキストで実行され、下位エージェントは AskUserQuestion を直接呼び出せません — 下位エージェントがユーザー入力を必要とする場合は構造化された blocker report を返し、オーケストレーターがゲートを再実行します。

承認時に 5-layer safety pipeline が実行されます:

1. FrozenGuard — path-prefix check (保護されたパスの修正を遮断)
2. Schema validation — 提案フィールドのスキーマ検証
3. Diff inspection — 変更内容の検査
4. Rate-limit window — 週あたり最大 3 回、24 時間クールダウン (harness.yaml rate_limit SSOT)
5. Snapshot creation — 修正前のスナップショットを .moai/harness/learning-history/snapshots/<ISO-DATE>/ に保存

注意

moai harness apply --execute --id <proposal-id> の CLI 経路は 別の ungated trust boundary です — AskUserQuestion 承認ゲートなしで Go execute pipeline で直接適用します。CLI プロセスはユーザーにプロンプトできないので、--execute は呼び出し前に別の手段で承認を取得した呼び出し元のための明示的な opt-in です。デフォルトの apply (no --execute) は payload-only で JSON のみを出力し、ファイルを修正しません。

自動進化は常に ユーザー承認ゲート の下でのみ適用されます。いつでも moai harness rollback <YYYY-MM-DD> で復元できます。

Harness v4 は manifest.json でチーム構成を定義します。

{
  "spec_id": "HARNESS-BACKEND-001",
  "name": "Backend Development Team",
  "version": "1.0.0",
  "created_at": "2026-07-01T10:00:00Z",
  "worktree_isolation": "L1_optional",
  
  "phases": [
    {
      "name": "plan",
      "teammates": [
        {
          "name": "architect",
          "role": "API アーキテクチャ専門家",
          "model": "inherit",
          "skills": ["moai-foundation-core"]
        }
      ]
    },
    {
      "name": "run",
      "teammates": [
        {
          "name": "db-engineer",
          "role": "DB 設計およびマイグレーション",
          "model": "inherit"
        },
        {
          "name": "api-developer",
          "role": "REST API エンドポイント",
          "model": "inherit"
        },
        {
          "name": "test-engineer",
          "role": "ユニットテスト",
          "model": "inherit"
        }
      ]
    }
  ]
}

メンバーごとにモデルを異なって指定できること (model フィールド) はトークノミクス設計の延長です — アーキテクチャ決定のように推論が重い役割と、反復的なテスト作成のように軽い役割に同じモデルを使う理由はありません。

Harness v4 はオプションの worktree 隔離をサポートします。

"worktree_isolation": "L1_optional"

Claude Code が並列メンバー間の衝突を検出したとき自動的に L1 ワークツリーを生成します。

• オプション: 衝突時のみ隔離を適用
• 自動: ランタイムが衝突を検出後に自動生成
• コスト: ワークツリー隔離時にメモリが増加

"worktree_isolation": "none"

すべてのメンバーがプロジェクトルートで作業します (最小限のメモリ使用)。

Harness が有効化されると MoAI はそのチームを自動的に活用します。

> /moai run SPEC-BACKEND-001

MoAI の自動判断:

1. SPEC の複雑度を推定 (ファイル数、コード行数)
2. 適切なハーネスを選択
3. manifest の phase 順にメンバーを順次/並列委任

PLAN Phase:
  → architect メンバーがアーキテクチャ設計を担当

RUN Phase:
  → db-engineer, api-developer を並列委任
  → test-engineer を順次委任 (テスト)

SYNC Phase:
  → ドキュメント生成および PR 作成 (デフォルト manager-docs)

Harness v4 Builder は Socratic インタビュー方式で要件を把握します。

私たちのチームは Python FastAPI バックエンドを開発中です。
API エンドポイント、データ検証、エラーハンドリングが得意なチームが必要です。

Builder が自動的に:

• Python、FastAPI、asyncio の技術スタックを検出
• 3~5 名のチーム規模を決定
• 各メンバーの特化領域を設定
• 必要なスキルを事前ロード

チームが必要です。

→ Builder: プロジェクトの主要な技術は? (言語、フレームワーク)
→ Builder: チームが集中する領域は? (バックエンド、フロントエンド、全体)
→ Builder: 特に必要な専門性は?

• Harness v4 Builder ガイド - Builder 4-phase の詳細
• エージェントガイド - 11 個のエージェントカタログの理解
• SPEC ベース開発 - SPEC ワークフローの概要

情報

ヒント: Harness を一度生成すれば、すべての後続作業でそのチームが自動的に活用されます。/harness:team-name コマンドでいつでも再利用できます。