MoAI-ADK は ハーネスエンジニアリング (Harness Engineering) パラダイムを実装しています。開発者が直接コードを書く代わりに、AI エージェントが最適なコードを生産できる環境 (ハーネス) を設計する アプローチです。

“Human steers, agents execute.” — エンジニアの役割はコード作成からハーネス設計へと転換します: SPEC、品質ゲート、フィードバックループ。

従来のバイブコーディングは、AI に自由にコードを生成させた後、結果を手動でレビューします。ハーネスエンジニアリングはその逆です — 規格 (SPEC)、自動検証、継続的フィードバックループ で AI エージェントをガイドし、一貫した品質のコードを生産します。

ハーネスとは何でしょうか? 基盤モデルを取り囲み、実行をオーケストレーションするシステム全体 — モデルがどう考え計画するか、ツールをどう呼び出すか、コンテキストをどう認識し管理するか、成果物をどこに保存するか、結果をどう評価するかを決定する層です。MoAI-ADK は Claude Code の上に載る、まさにこのハーネスです。

ハーネスエンジニアリングは、v3.0 の3つの核心が交わる地点です。

特に2番目の核心が鍵となるイノベーションです。AI の再帰的自己改善 (RSI) の現実的な短期経路は、モデルの重みを直接修正することではなく モデルを取り囲むハーネスを改善すること です。MoAI-ADK はまさにこの経路を取ります — モデルではなくハーネス (スキル・エージェント指針) を再帰的に改善します。

graph TD
    subgraph Harness["ハーネスエンジニアリング"]
        direction TB
        SF["Scaffolding First
空ファイルのスタブ生成"] --> FC["Failing Checklist
受け入れ基準のタスク登録"]
        FC --> SV["Self-Verify Loop
コード→テスト→修正→合格"]
        SV --> GC["Garbage Collection
デッドコード除去"]
        GC --> CM["Context Map
アーキテクチャ文書の維持"]
        CM --> SP["Session Persistence
セッション間の進捗追跡"]
        SP --> LA["Language-Agnostic
16言語の自動検出"]
        LA --> SF
    end

    style Harness fill:#f0f7ff,stroke:#1565C0

各コンポーネントは MoAI の特定のコマンドにマッピングされます:

/moai run が始まると、エージェントはコードを書く前にまず必要なファイル構造を生成します:

src/
├── auth/
│   ├── handler.go      ← 空のスタブ
│   ├── handler_test.go  ← 空のテスト
│   ├── service.go       ← 空のスタブ
│   └── service_test.go  ← 空のテスト
└── middleware/
    └── jwt.go           ← 空のスタブ

この方式は、エージェントが無秩序にファイルを生成するのを防ぎ、一貫したプロジェクト構造を維持します。

SPEC の受け入れ基準が自動的にタスクリストに登録されます:

- [ ] JWT トークン生成エンドポイント
- [ ] トークン検証ミドルウェア
- [ ] リフレッシュトークンのロジック
- [ ] 期限切れトークンの処理
- [ ] 85%+ テストカバレッジ

各項目が実装されテストに合格するとチェックされます。すべての項目がチェックされて初めて作業が完了します。

エージェントが自律的に実行するコアサイクル:

graph TD
    A["コード作成"] --> B["テスト実行"]
    B --> C{"合格?"}
    C -->|"失敗"| D["エラー分析"]
    D --> A
    C -->|"合格"| E["次の項目"]

このループは /moai loop で最大100回まで反復され、収束検知 (同じエラーの繰り返し時に代替戦略を適用) を含みます。完了条件を自ら宣言したい場合は goal エンジン (/moai goal "<条件>") を使います — 条件が満たされるかターン上限に達するまで、セッションが自ら働き続けます。

/moai codemaps が生成するアーキテクチャ文書は、エージェントにコードベースの全体構造を提供します。これによりエージェントは:

• 既存コードと衝突しない実装方法を選択
• 適切なパターンとルールに従う
• 依存関係を理解し、影響範囲を把握

Claude Code のセッションが中断されても、progress.md が完了したステップを記録します:

## Progress
- [x] Phase 1: 分析完了
- [x] Phase 2: ハンドラー実装
- [ ] Phase 3: テスト作成 ← ここから再開
- [ ] Phase 4: リファクタリング

/moai run --resume SPEC-XXX で中断した地点から自動的に再開されます。

ハーネスは固定された環境ではありません。ループが回るほど観察が蓄積され、ハーネスがその観察から学習して自ら指針を改善します。

ループ実行 → 観察の蓄積 → パターン学習 → 指針の進化 (承認ゲート)

自動進化が人間の監視なしに閉じたループを回ることはありません。評価者と権限統制は進化ループの 外 に置きます:

• 5層の安全パイプライン — スナップショットとロールバック (moai harness rollback) でいつでも復元できます
• ユーザー承認ゲート — Tier-4 自動アップデートは必ずユーザー承認を経ます
• Constitution システム — 不変ルール (FROZEN) は進化対象から除外されます (Constitution システム 参照)

moai harness status      # 学習状態の確認 (観察数、パターン、提案)
moai harness apply       # 提案の適用 (ユーザー承認ゲートの通過が必要)
moai harness rollback    # 直前の適用をロールバック
moai harness disable     # 学習の無効化

指針を直すこと自体も一つの実験です。ルール・エージェント・フックといったハーネス構成要素を編集する際は 決定の可観測性 が適用されます: 編集ごとに反証可能な予測 (どの失敗クラスが再発しなくなるか) を記録し、採用前に二重チェックを通過しなければなりません — held-in (元の失敗を実際に捕捉するか) と held-out (既存のガード・テストが引き続き通過するか)。却下された編集も記録に残り、同じ失敗した試みを繰り返しません。

自分でカスタムスキルやエージェントを作るとき、moai update がどの資産を上書き (overwrite) し、どの資産を保存 (preserve) するかを知っておく必要があります。MoAI-ADK は名前空間を 「汎用配布 (template-managed)」 と 「ユーザー作成 (user-owned)」 に明確に分離します。

moai-* prefix のスキルと moai-harness-* は MoAI-ADK パッケージが提供する汎用資産 です。すべてのユーザープロジェクトに配布され、moai update 実行時に最新の template で 上書き されます。そのため、これらの資産を直接修正すると、次のアップデートで変更内容が失われます。

hns-* prefix のスキル (Harness v4 Builder が生成する正式な名前空間) と .claude/agents/harness/ ディレクトリは ユーザープロジェクトが所有 します。前世代の prefix である harness-* / my-harness-* も同様に認識されます。moai update はこれらを 絶対に削除・修正せず、アップデート前にバックアップしてそのまま保存します。

自分で作ったドメイン特化スキルやエージェントが moai update 後も生き残るようにするには、必ず hns-* prefix を使ってください (エージェントは .claude/agents/harness/ に配置)。moai-* または moai-harness-* prefix で作ると template-managed と見なされ、次のアップデートで上書きされます。/moai harness "自然言語のリクエスト" でハーネスを生成すると、Builder がこのルールに合った名前を自動的に割り当てます。

• SPEC ベース開発 — ハーネスの入力となる SPEC 文書の書き方
• TRUST 5 品質 — ハーネスが検証する5つの品質基準
• Constitution システム — ハーネスの進化を統制する不変ルール