【実録】ハーネスエンジニアリング — 25体AIエージェントを本番運用して「モデルより設計が22倍重要」だと気づいた話

3/31、Claude Codeのソースコード512,000行がnpmのsource mapバグでリークした。GitHub上で84,000スター。 みんなモデルの中身に注目したが、本当にヤバかったのはそこじゃない。 「ハーネス」と呼ばれるAIの制御層の設計が丸見えになったことだ。

SWE-benchのデータが全てを物語る：

モデル性能は誤差。ハーネス設計が22倍重要。 僕はこれを、25体のAIエージェントで法人を運営して体で覚えた。

ハーネスとは何か

公式: Coding Agent = AI Model + Harness

ハーネスはモデルの外側にある制御層。具体的には：

CLAUDE.md（行動規範）
  + skills/（専門知識モジュール 19種）
    + hooks（ガードレール）
      + subagents（タスク分離）
        + memory（セッション横断記憶）

TomorrowProofでは、このハーネスでClaude Sonnet 4を25体のAIエージェントとして運用している。 Dev, Marketing, Sales, CFO, Legal, Security... 全部AIだ。人間は僕1人。

うちの実装構造（全公開）

TomorrowProofagent/
├── CLAUDE.md              # 全エージェント共通ルール（50行に圧縮）
├── .claude/
│   ├── rules/
│   │   ├── business-os.md    # 事業ロジック（3層モデル+技術横断マップ）
│   │   ├── pipelines.md      # 5本の実行パイプライン
│   │   ├── team-structure.md  # 4チーム制（Revenue/Product/Strategy/Brand）
│   │   ├── branding.md       # ダーク×ミニマル×テック
│   │   └── projects/         # 10プロジェクトカード
│   ├── skills/               # 19エージェントのスキル定義
│   │   ├── dev/SKILL.md
│   │   ├── marketing/SKILL.md
│   │   ├── sales/SKILL.md
│   │   ├── sns/SKILL.md      # v8.0 AI実装実況者ペルソナ
│   │   └── ...
│   └── settings.json         # hooks設定
├── discord-bot/
│   └── src/engine/
│       ├── taskExecutor.js    # 30秒ポーリング→Claude API実行
│       ├── taskDecomposer.js  # CEO指示→タスクチェーン自動分解
│       └── taskStore.js       # 依存管理+propagateContext
└── cockpit/                   # ローカル管制塔（PWA+音声入力）

ハーネス5層と実際のファイル

Layer 1: Rules（CLAUDE.md + rules/）

CLAUDE.mdは50行。「ここを読め」のリンク集だけ。 本体はrules/に分散。business-os.mdだけで200行、10プロジェクトの事業構造が書いてある。

教訓: CLAUDE.mdを500行書くと、モデルが従わなくなる。150行が限界。分散配置が正解。

Layer 2: Skills（.claude/skills/）

19個のSKILL.md。各エージェントの「取扱説明書」。 例: SNS Agent（sns/SKILL.md）はv8.0で以下を含む：

教訓: スキルは「知識モジュール」であって「命令書」ではない。必要な時だけロードされるのが鍵。常に全部読み込むとコンテキスト汚染する。

Layer 3: Hooks（settings.json）

確定的なガードレール。CLAUDE.mdの指示は「お願い」だが、hooksは「強制」。

例: commit前にセキュリティチェック、push前に品質ゲート。 違反したらブロック。AIが「申し訳ありません」と言っても通らない。

Layer 4: Subagents（タスク分離）

25体が全部同じコンテキストで動いたら破綻する。 各タスクは独立したコンテキストウィンドウで実行。必要な情報だけpropagateContextで引き継ぐ。

marketing(KW選定)
  → writer(記事執筆) ← marketingの出力がcontextに注入
    → visualizer(画像生成) ← writerの出力が注入
      → dev(HP公開)

教訓: サブエージェントは「コンテキストのファイアウォール」。これがないと、Dev AgentがMarketing Agentの思考過程に引きずられて変なコードを書く。

Layer 5: Memory（MEMORY.md）

セッション横断の記憶。200行以内のインデックスファイル。 CEOからのフィードバック28件が蓄積されている。

例: 「架空の売上を投稿するな」「Vercelはgit pushのみ、CLIデプロイ禁止」「事業ポートフォリオは絞るな」

教訓: メモリは「AIが同じ失敗を繰り返さないための仕組み」。コードに書けないビジネス判断の蓄積。

3ヶ月で遭遇した5つの地獄

地獄1: 白飛び事件（二重AIパイプライン）

VTON画像をGeminiに食わせて再生成 → 白飛び。AI出力を別AIに食わせると品質が劣化する。 → 単一パス原則をrules/dev-quality-gate.mdに明文化。

地獄2: コミット忘れ地獄

Dev Agentが6ファイル修正して「完了しました」→ git statusは全部uncommitted。 → 「コミットするまで未完了」をルール化。

地獄3: ライセンス地雷（2連踏み）

IDM-VTON統合完了 → CC BY-NC-SA = 商用不可。代替FitDiT → 同じライセンス。 → OSS採用前にライセンス確認をhooksで強制。

地獄4: APIキー露出

VITE_GEMINI_API_KEYがブラウザバンドルに丸見え。 → セキュリティチェックをpre-commit hookに追加。

地獄5: 本番デプロイ2連続破壊

間違ったVercelプロジェクトにデプロイ → 本番真っ白 → 翌日も同じ。 → .vercel/project.json確認をデプロイ手順に組み込み。

実運用コスト（freee実データ）

項目 月額
Claude Max ¥26,000
Claude API従量 ¥75〜5,000
Railway ¥0（無料枠）
Vercel Pro ¥3,000
合計 ¥29,000〜34,000

25体のAIエージェントで法人を回して月3万円。 人件費換算なら1人月100万円×25 = 2,500万円分の仕事を3万円で。

なぜ今「ハーネスエンジニアリング」なのか

3/31のリーク以降、コミュニティが爆発的に成長：

しかし、ほとんどの記事はデモプロジェクトでの検証。 本番環境で25体を3ヶ月回した実績を持っているのは、僕が知る限りうちだけだ。

まとめ

ハーネスエンジニアリングの本質は「AIに手綱をつけること」ではない。 AIが最大限の能力を発揮できる環境を設計することだ。

モデルは道具。ハーネスは職場環境。 優秀な人材でも、劣悪な環境では力を発揮できない。AIも同じ。

参考文献