AI エージェントハーネスの設計原則 — 責任分担・スキル委譲・フォールバック

本記事に登場する HUMAN_INPUT マーカーとは、AI 執筆 skill が記事本文に残す「ここは人間が後で確定値を埋めるべき」を示すプレースホルダー（形式例: ）。

本記事はアーキテクト / シニアエンジニア / テックリード向けに、Claude Code を前提としたエージェントハーネス設計の原則を整理する。業務効率化・ROI・経営判断の観点は経営判断側の記事「AI エージェントを事業の中心に据える」に委ねる。ここでは設計の構造そのものを扱う。

用語の整理: 本記事で「3 層」はハーネスの構造（責任者エージェント / スキル / フォールバック）を指し、「3 フェーズ」はフォールバック内部の段階（リトライ / 代替パス / 人間エスカレーション）を指す。

エージェントに業務を委ねた直後、最初に壁にぶつかるのは「失敗したとき、誰が責任を取るか」という問いだ。エージェントがハルシネーションを起こしたとき、タイムアウトしたとき、外部 API が落ちていたとき——その先の処理をどう続けるか、設計の段階で決まっていない組織が多い。

エージェントハーネス（agent harness）とは、この「業務委譲の安全網」を構造として実装したものだ。本記事では、ハーネスを支える 3 つの設計原則——責任者エージェントによる責任分担、スキル委譲による決定論タスクの分離、フォールバックによる安全網——を順に解説する。Claude Code の .claude/agents/ 構造を前提に、実装可能なパターンとして整理する。

Key takeaway 3 点:

ハーネスの核は「責任者エージェント」「スキル」「フォールバック」の役割分担。この 3 層が揃って初めて業務委譲が安全になる
スキルは決定論タスク（入力 → 出力が確定するタスク）を切り出す単位。エージェントの判断領域を絞る設計道具だ
フォールバックは後付けにできない。業務フローを設計するタイミングで、失敗の 3 分類（ハルシネーション / タイムアウト / 外部依存）と対応する 3 フェーズ（リトライ / 代替パス / 人間エスカレーション）をセットで定義する

ハーネスとは何か — AI エージェントアーキテクチャハーネス設計の核心

ハーネスのメタファー — 制御と委譲の同時成立

「ハーネス」という語は馬具に由来する。手綱・胴締め・牽引具を組み合わせることで、馬の力を制御しながら目的の方向に引き出す仕組みだ。AI エージェントに当てはめると、ハーネスは「エージェントの能力を安全に引き出しながら、業務の方向を維持する構造」を意味する。

重要なのは、ハーネスが「エージェントを縛る」ためではなく「委譲を安全にする」ために存在するという点だ。エージェントに何も制約を与えなければ、確かに柔軟に動く。しかし業務の文脈では、「柔軟すぎるエージェント」は問題を起こす。予算ゼロで外部サービスを申し込む、承認なしでメール送信する、ファイルを誤って削除する——これらはいずれも「自由すぎる委譲」が引き起こす失敗だ。

ハーネスの設計とは、この「自由と安全のトレードオフ」を構造として解決する行為だ。責任者エージェントが業務範囲を宣言し、スキルが決定論タスクを封じ込め、フォールバックが失敗時の経路を保証する——3 層が揃ったとき、委譲は安全になる。

ハーネスなしでエージェントに委ねたときの典型的な失敗

ハーネスなしでエージェントに業務を委ねたとき、失敗パターンは共通している。

失敗パターン 1: 責任の所在が不明確

「エージェントにやらせた」という指示はあるが、何の権限範囲で動いていたかが定義されていない。失敗したとき、どこに問題があったかの追跡が難しくなる。複数のエージェントが同じタスクを奪い合ったり、逆に誰も引き受けなかったりする「責任の空白」が生まれる。

失敗パターン 2: スキルとエージェントの混在

「文書を要約して」「スプレッドシートに書き込んで」「メール送信して」を一つのエージェントに全部委ねる。これは表面上はシンプルに見えるが、各ステップの失敗が混在して追跡できなくなる。「要約は正しかったが書き込みで失敗した」「送信は成功したが本文が誤っていた」——失敗箇所の特定に時間がかかる。

失敗パターン 3: フォールバックが人間頼みのみ

エージェントが失敗したとき、唯一の対応が「人間が気づいて再試行する」だけの設計。夜間バッチが止まっても翌朝まで誰も気づかない、エラーがサイレントに飲み込まれる——人間が常時監視することを前提としたシステムは、スケールしない。

これらの失敗は「エージェントを使うのをやめれば解決する」問題ではない。設計の問題だ。ハーネスの 3 層——責任者エージェント / スキル / フォールバック——を組むことで、同じエージェント能力を維持しながらこれらの失敗を構造的に防げる。

設計原則 1: 責任者エージェントによる責任分担

責任者エージェントとは何か（{domain}-director パターン）

{domain}-director パターン とは、業務ドメインごとに「その領域 (area) の責任者エージェント」を {domain}-director.md として立てる設計だ。実装例: blog-director.md / sales-director.md / dev-director.md / seo-director.md / editor-in-chief.md。

{domain}-director パターンで立てる責任者エージェントは以下の 3 つを宣言する:

担当業務範囲: このエージェントが引き受けるタスクの種類
委譲先: タスクの実行をどのスキル / サブエージェントに委ねるか
権限の限界: このエージェントが自律的に判断できる範囲と、人間確認が必要なライン

「責任者エージェント」という呼び方は八雲での内部命名だが、パターン自体は汎用だ。「チームリーダーエージェント」「ドメインエージェント」「コーディネーターエージェント」と呼ぶ組織もある。本質は「業務ドメインと責任範囲を一対一で対応させること」にある。

責任者エージェントは、すべての作業を自分でやらない。判断（何をするか）を担い、実行（どうやるか）はスキルかサブエージェントに渡す。この「判断と実行の分離」が、後述する「スキル委譲」の前提になる。

業務ドメインごとに責任者を立てる設計思想

エージェント設計の初期段階でよくある判断ミスは、「一つの万能エージェントに全部委ねる」ことだ。一見シンプルだが、業務の規模が大きくなると保守が難しくなる。

業務ドメインごとに責任者を立てる設計には、3 つのメリットがある。

メリット 1: 障害の局所化

営業エージェントが失敗しても、採用エージェントや経理エージェントは影響を受けない。ドメイン境界が障害伝播のバリアになる。

メリット 2: 権限設計の明確化

「このエージェントは外部 API 呼び出し可」「このエージェントはファイル削除不可」——権限ポリシーをエージェント単位で設定できる。万能エージェントに同じことをしようとすると、すべての業務文脈を把握したポリシー定義が必要になり、複雑度が跳ね上がる。

メリット 3: system prompt の焦点化

一つのエージェントが担うコンテキストが限定されるため、system prompt を短くシャープに書ける。万能エージェントの system prompt は長くなりがちで、モデルが重要な制約を読み飛ばすリスクが高まる。

責任者エージェントの定義ファイル（`.claude/agents/`）の構造

Claude Code では、責任者エージェントは .claude/agents/ ディレクトリ以下のマークダウンファイルとして定義する。

.claude/agents/
├── sales-director.md      # 営業領域の責任者
├── dev-director.md        # 開発領域の責任者
├── blog-director.md       # コンテンツ領域の責任者
└── seo-director.md        # SEO 領域の責任者

各ファイルには以下の宣言を含める:

---
name: sales-director
description: 営業業務の責任者エージェント。提案書作成・見積・請求書発行を担当する。
tools:
  - read_file
  - write_file
  - bash  # スクリプト実行のみ許可
---

# sales-director

## 担当業務
- 提案書のドラフト作成
- 見積書・請求書の生成
- 営業パイプラインの管理

## 委譲先スキル
- /propose: 提案書ドラフトの生成
- /estimate: 見積金額の計算
- /invoice: 請求書の発行

## 権限の限界
- 最終的な提案書の送信には人間の承認が必要
- 100 万円以上の見積は自動生成しない（人間確認を要求する）

このファイル 1 枚が「責任者エージェントの定義」として機能する。ファイルの存在が、そのエージェントの権限範囲と委譲先を文書化し、チームメンバー（人間とエージェント双方）に対して「このエージェントが何を担うか」を宣言する。

設計原則 2: スキル委譲 — Claude Code エージェント設計における決定論タスクの分離

エージェントとスキルの役割分担

エージェントとスキルの違いを一言で言うと、「判断するか / 実行するか」だ。

特性	エージェント	スキル
動作	状況を解釈して次の行動を判断する	決まった入力から決まった出力を返す
失敗のリスク	判断ミス / ハルシネーション / 過剰行動	仕様外の入力 / 外部依存の失敗
再利用	コンテキスト依存で再利用しにくい	I/O contract があれば複数エージェントから呼べる
テスト	期待動作の定義が難しい	入力 → 期待出力でテスト可能

スキルが担うべきは「決定論タスク」だ。ここで「決定論」とは「同じ入力を与えれば、同じ出力が返ってくることが期待できる」という意味で使う。LLM を使っていても、プロンプトと構造が固まっていれば実質的に決定論タスクとして扱える。

決定論スキルの抽出基準

どのタスクをスキルに切り出すべきか。判断軸は 3 つある。

軸 1: 入力と出力が定義できるか

「提案書の素材（会社名・課題・予算）を受け取り、提案書 markdown を返す」——入力と出力の型が定義できるタスクはスキル化の候補だ。逆に「状況を見て何をするか判断する」はエージェントの仕事で、スキルには向かない。

軸 2: 複数の文脈から呼ばれるか

同じタスクを複数のエージェントから呼びたい場合、スキルとして抽象化する価値が高い。「請求書発行」を営業エージェントからも経理エージェントからも呼べる形にするなら、スキル化が正しい。

軸 3: 人間が仕様をレビューできるか

スキルの定義（入力 / 処理 / 出力）は、エンジニアでなくても読めるレベルで文書化できる。文書化できれば、仕様の誤りを早期に発見できる。「エージェントが勝手にやった」ではなく「スキルの仕様通りに動いた」という説明責任も果たせる。

典型的に決定論スキルに向くタスクは以下だ:

✅ スキル向き（決定論タスク）
- /propose: 入力フォーム → 提案書 markdown の生成
- /estimate: 要件リスト → 見積金額の計算
- /invoice: 請求情報 → 請求書 PDF の生成
- /publish: 記事 frontmatter → 公開判定とスケジュール登録
- /translate: 日本語テキスト → 英語テキストの変換

❌ エージェント向き（文脈依存タスク）
- 「この案件を進めるべきか判断する」
- 「クライアントの状況を見て次のステップを提案する」
- 「複数の候補から最適な選択肢を選ぶ」

スキルの I/O contract と再利用性

スキルを定義するとき、I/O contract（入出力の約束）を明示することが再利用性を決める。

Claude Code のスキルは .claude/skills/ 以下のマークダウンファイルで定義する:

.claude/skills/
├── propose/
│   └── SKILL.md    # I/O contract と処理フローを定義
├── estimate/
│   └── SKILL.md
└── publish/
    └── SKILL.md

SKILL.md に含めるべき最低限の要素:

# /propose — 提案書ドラフト生成スキル

## Input
- `company_name`: 提案先の名称（string）
- `pain_points`: 課題の箇条書き（string[]）
- `budget_range`: 予算感（string、例: "50〜100 万円"）

## Process
1. BRAND.md の voice ガイドラインに従って文体を設定する
2. `pain_points` を課題として整理し、解決策を生成する
3. `budget_range` の範囲内で実現可能な提案内容を設定する

## Output
- `draft.md`: 提案書の Markdown ドラフト
- `estimated_hours`: 見積工数の概算（数値）

## Error handling
- `pain_points` が空の場合: エラーを返し、入力を再確認するよう促す
- `budget_range` が解析できない場合: デフォルト値（"〜50 万円"）で続行し、warning を出す

I/O contract が明示されていると、スキルを呼ぶエージェントは「何を渡せばいいか / 何が返ってくるか」を確認できる。フォールバック設計（次の設計原則）でも、この contract を基準に「どんな失敗が起きうるか」をリストアップできる。

現在 .claude/skills/ には 15 個のスキル（うちブログ運用系 14 個 + 汎用 1 個）が定義されている。

設計原則 3: フォールバック設計 — エージェント失敗時のフォールバック設計をどのように実装するか

エージェント失敗の分類（3 種類）

フォールバックを設計する前に、エージェントの失敗を分類する必要がある。失敗の種類が違えば、適切な対応も変わる。

失敗分類 1: ハルシネーション（出力品質の失敗）

LLM が誤った情報を生成する、指定した形式に従わない、仕様外の行動をとる——これらは「出力品質の失敗」だ。この種の失敗は「スキルの仕様に対する違反」として検出できる場合がある（構造検証 / バリデーション）。

対応の方針: 構造的な検証で検出できるものは自動で検出する。検出できないものは人間レビューを経路として設ける。

失敗分類 2: タイムアウト（実行時間の失敗）

LLM の応答が遅延する、処理が規定時間内に終わらない——これは「実行時間の失敗」だ。原因は LLM の混雑、入力量の過大、あるいは処理ロジックの非効率にある。

対応の方針: タイムアウト閾値を明示し、超過時のリトライ回数と待機時間を設計する。リトライ上限に達したら代替パスか人間エスカレーションへ移行する。

失敗分類 3: 外部依存の失敗

Google Drive API が落ちている、メール送信サービスが 5xx を返す、データベース接続が切れる——これは「外部システムへの依存失敗」だ。エージェントやスキルの設計には関係なく、外部の問題で失敗する。

対応の方針: 外部依存ごとに「利用できない場合の代替動作」を定義する。キャッシュ / キューイング / 劣化モードでの継続 / エラー通知のいずれかを選択する。

フォールバックの 3 フェーズ（リトライ / 代替パス / 人間エスカレーション）

フォールバックは「失敗したらどうするか」の 3 フェーズで構造化する。

Layer 1: リトライ

最も単純な対応。エラーが一時的なものであれば、同じ処理を時間をおいて再試行する。外部 API の一時的な失敗、ネットワーク遅延、LLM の混雑——これらはリトライで解決できることが多い。

設計するべきこと:

リトライ回数の上限（例: 3 回）
リトライ間隔のバックオフ（指数バックオフ推奨: 1 秒 → 2 秒 → 4 秒）
リトライ上限到達時の次の動作（Layer 2 への移行）

async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxAttempts: number; backoffMs: number }
): Promise<T> {
  let lastError: Error | undefined;
  for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err as Error;
      if (attempt < options.maxAttempts) {
        await sleep(options.backoffMs * Math.pow(2, attempt - 1));
      }
    }
  }
  throw lastError;
}

Layer 2: 代替パス

リトライで解決しない場合、別の経路で同じ目的を達成する。外部 API が使えない場合はローカルキャッシュで代替する、メール送信が失敗した場合は Slack 通知に切り替える、リアルタイム処理が失敗した場合はキューに積んで非同期処理に切り替える——これが代替パスだ。

設計するべきこと:

各外部依存に対して「使えない場合の代替動作」を定義する
代替動作が「本来の動作との差分」を明示する（例: メール代替で Slack に切り替えた場合、添付ファイルが送れない等）
代替パスへの切り替えをログに記録し、後から確認できるようにする

Layer 3: 人間エスカレーション

Layer 1 と Layer 2 で解決できない場合、人間に判断を委ねる。エスカレーション先、通知方法、期待する対応時間——これらを設計段階で定義する。

重要なのは「エスカレーションを設計の最後の手段」として位置づけることだ。「とりあえず人間に聞く」設計は、エスカレーション頻度が高くなると運用負荷が跳ね上がる。Layer 1 / Layer 2 で処理できる範囲を広げ、Layer 3 は「本当に人間の判断が必要なもの」に絞る。

// エスカレーション通知の最小実装例
async function escalate(context: {
  taskName: string;
  error: Error;
  attemptedLayers: ('retry' | 'fallback')[];
  requiredAction: string;
}): Promise<void> {
  await notifySlack({
    channel: '#agent-escalations',
    message: [
      `[エスカレーション] ${context.taskName}`,
      `エラー: ${context.error.message}`,
      `試行済み: ${context.attemptedLayers.join(', ')}`,
      `必要なアクション: ${context.requiredAction}`,
    ].join('\n'),
  });
}

フォールバックを後付けにしないための設計タイミング

フォールバック設計の最大の落とし穴は「後付け」だ。「まず動くものを作ってから、フォールバックを追加する」——この順序で開発すると、フォールバックは実装されないまま本番に出ることが多い。

AI エージェントの責任者パターンとスキル委譲の設計原則として、フォールバックは業務フローの設計段階で定義する。具体的には:

業務フローを定義するとき、各ステップで「この処理が失敗したら」を同時に記述する
スキルの I/O contract に Error handling セクションを必ず含める（前述の SKILL.md の例を参照）
責任者エージェントの定義ファイルに、そのエージェントが扱うエラー分類と対応方針を記述する

実装の優先順位は「ハッピーパス → Layer 1 → Layer 2 → Layer 3」の順で進めるとしても、各 Layer が何であるかは設計段階で全部定義しておく。定義のない Layer は後から追加されない。

2026-05 にフォールバック 3 フェーズを業務フローに組み込んだ。きっかけは、執筆スキルが HUMAN_INPUT マーカーを規定数下回って生成しても気付かないまま draft が後段の review / publish へ流れ、品質ゲートで差し戻されてからリカバリーするという手戻りが繰り返されたことだった。対処として、(1) 執筆スキルに marker validation loop（最大 2 回リトライ）、(2) _state.json への blockers 記録、(3) pipeline DAG の human-review step（blocking）を同時に組み込み、失敗が後段ではなく発生源で止まる構造に変えた。

実装パターン — Claude Code でのハーネスの組み方

`.claude/agents/` ディレクトリの構造と命名規約

Claude Code でハーネスを実装するとき、以下のディレクトリ構造が基本形になる:

.claude/
├── agents/
│   ├── {domain}-director.md     # 責任者エージェント（{domain}-director パターン）
│   └── ...
├── skills/
│   ├── {verb}/
│   │   └── SKILL.md             # 決定論スキルの I/O contract
│   └── ...
└── README.md                    # ハーネス全体の設計概要

命名規約の原則:

ファイルタイプ	命名パターン	例
責任者エージェント	`{domain}-director.md`	`sales-director.md`, `dev-director.md`
汎用エージェント	`{role}.md`	`reviewer.md`, `planner.md`
スキル	`{動詞}/SKILL.md`	`propose/SKILL.md`, `translate/SKILL.md`

「director」という接尾辞は「この領域の責任者である」を示す命名規約だ。命名が一貫していると、.claude/agents/ を見たときにどのエージェントがどの領域を担当するかが一目でわかる。

CLAUDE.md によるハーネス設計の宣言

ハーネスの設計意図を CLAUDE.md に記述する。CLAUDE.md は Claude Code がプロジェクトのコンテキストを把握するために最初に読むファイルだ。ここにハーネスの全体像を書くことで、Claude Code（人間と AI エージェントの両方）が設計の意図を参照できる。

CLAUDE.md のハーネス宣言に含めるべき要素:

## エージェント組織（ハーネス設計）

このプロジェクトでは以下の区分でエージェントを使い分ける:

### 責任者エージェント（.claude/agents/{domain}-director.md）
業務ドメインごとに責任者を置く。責任者エージェントは「判断」を担い、実行はスキルに委ねる。

| エージェント | 担当領域 |
|---|---|
| sales-director | 提案書・見積・請求書の生成 |
| dev-director | 実装計画・コードレビュー・テスト設計 |

### スキル（.claude/skills/{verb}/SKILL.md）
決定論タスク（入力 → 出力が確定するタスク）を切り出した再利用可能な処理単位。

### 実装ルール
- CLAUDE.md を実装の起点とする
- エージェントに委ねる前に、そのタスクがスキル化できないかを検討する
- フォールバックは業務フロー定義と同時に記述する

この宣言があることで、新しいメンバー（人間 / エージェント）がプロジェクトに入ったとき、ハーネスの設計方針を最初に把握できる。

Synapse を例に見るハーネスの全体像

責任者エージェント 3 個（blog-director / editor-in-chief / seo-director） / スキル 15 個 / 2026 年 3 月に initial commit、以降本番運用中。

八雲が Claude Code 上に組んだ業務横断エージェント組織（Synapse）は、この 3 層ハーネスを実際に運用している。.claude/agents/ に定義された複数の責任者エージェントが各業務ドメインを担い、.claude/skills/ の決定論スキル群（提案書生成・見積計算・記事発行など）を呼び出す設計になっている。

具体的には、営業領域の責任者エージェントが「提案書を作ってほしい」という要求を受け取ると、自分で文章を生成するのではなく、提案書生成スキルに素材を渡す。スキルが提案書ドラフトを返し、責任者エージェントがそれをレビューして人間に渡す——この「判断と実行の分離」が Synapse の基本パターンだ。詳細な実装は Synapse の責任者エージェント設計の実装詳細を参照してほしい。

ハーネスとして機能するのは、各責任者エージェントの定義ファイルに「権限の限界」が書かれており、スキルの SKILL.md に I/O contract が書かれており、重要な処理には人間エスカレーションパスが設計されているからだ。3 層のうちどれが欠けても、エージェントの業務委譲は破綻する。

アンチパターン — エージェント責任分担アーキテクチャでやってはいけないこと

このパターンを採用するまでに、middleware パターン（処理を固定順序のパイプラインで通過させる）と event-driven パターン（イベント発火で複数の listener が並列に反応する）も選択肢にあった。どちらも採用しなかった理由はひとつ、トークン消費の予測可能性だ。

middleware は処理が全段を順序通り通過するため、リクエスト 1 件で全エージェントが context を読み込む。判断と無関係な領域の director まで Opus が走ってしまう。event-driven は逆に、イベント発火で複数 listener が同時に反応するため、必要のないエージェントまで起動して context を消費する。どちらも「リクエスト 1 件あたり何トークン使うか」を事前に見積もるのが難しい。

{domain}-director パターンは main thread (Opus) が「これは何の領域の話か」をまず判断し、関係する 1 つの director にだけ振る。さらに判断は Opus、実 work は Sonnet / Haiku に skill 経由で委譲する分離を組み合わせると、トークン消費が「main 1 + 関連 director 1 + 実 work skill 1」の合計に収まり予測可能になる。

この設計判断は、AI 補助金の時代が終わりつつあることへの備えでもある。「AI Subscription Time Bomb」の調査によれば、Anthropic ユーザーは 1 ドルの収益に対して約 8 ドルの計算コストを消費しており、GitHub Copilot は 2026 年 6 月 1 日から使用量ベース課金に移行する。サブスクリプション固定料金で吸収されている時代が終われば、トークンを設計レベルでコントロールできない組織は運用コストで詰む。エージェントアーキテクチャはトークン経済性まで含めて設計する。

アンチパターン 1: 責任者なしのフラット構造

全エージェントが対等に並んでいて、どのエージェントが何を担当するかが定義されていない状態。

症状:

同じタスクに複数のエージェントが手をつけて衝突する
タスクが誰も引き受けず、人間が調整しなければならない
エージェントが失敗したとき、原因を追うのが難しい

対処: {domain}-director パターンで業務ドメインごとに責任者を立てる。ドメインの境界が曖昧な場合は「この案件は sales-director と dev-director のどちらが担当するか」を CLAUDE.md に明示する。

アンチパターン 2: スキルとエージェントを混同した設計

判断が必要なタスクをスキルに入れたり、決定論タスクをエージェントに委ねたりする設計。

症状:

スキルが「状況を判断して最適な方法を選ぶ」という実装になっている
エージェントが単純な変換処理（フォーマット変換・テキスト整形等）を担当している
スキルの I/O contract が「入力によって返す内容が変わる」仕様になっている

対処: スキルとエージェントの判断軸（「決定論かどうか」）を使い、タスクを分類し直す。境界が曖昧な場合は「このスキルを別の文脈から呼んだとき、同じ入力で同じ出力が返ってくるか」を自問する。返ってこない場合はエージェントの仕事だ。

アンチパターン 3: フォールバックが人間頼みのみ

「エージェントが失敗したら、担当者が手動で対応する」だけの設計。

症状:

夜間や休日のバッチ処理が失敗しても、翌営業日まで誰も気づかない
「エージェントが変な動作をした」という報告が事後にしか来ない
エスカレーション先が設計されておらず、誰に連絡すればいいか不明確

対処: フォールバックの 3 フェーズ（リトライ / 代替パス / 人間エスカレーション）を設計段階で定義する。特にエスカレーション先（チャンネル / 担当者 / 期待応答時間）を明文化する。「人間が判断する」はフォールバックの最後の手段であり、最初の手段ではない。

2026-05 に Opus が判断系工程を超えて mechanical edit に手を出し、scope creep が発生した。原因: 責任者エージェント / 作業スキル / main thread Opus の役割分担が明文化されておらず、Opus が「自分でやった方が早い」と判断して直接実行した（retro: blog-ops/retros/2026-05-18-opus-mechanical-edit-overreach.md）。対処として CLAUDE.md と .claude/README.md に「Opus = judgment 専用、量産執筆 / mechanical edit は skill 経由」を明示する利用軸を追加した。

まとめ — ハーネス設計のチェックリスト

エージェントハーネスの 3 設計原則を再掲する。

原則 1: 責任者エージェントによる責任分担

業務ドメインごとに .claude/agents/{domain}-director.md を定義したか
各責任者エージェントの担当範囲・委譲先・権限の限界を宣言したか
CLAUDE.md にハーネス設計の全体像を記述したか

原則 2: スキル委譲

「決定論タスク」（入力 → 出力が確定）はスキルに切り出したか
各スキルに I/O contract（Input / Process / Output / Error handling）を定義したか
スキルを複数の責任者エージェントから呼べる設計になっているか

原則 3: フォールバック設計

エージェント失敗を 3 分類（ハルシネーション / タイムアウト / 外部依存）で整理したか
フォールバックの 3 フェーズ（リトライ / 代替パス / 人間エスカレーション）を業務フローと同時に定義したか
エスカレーション先・通知方法・期待応答時間を明文化したか

八雲内の追加規約

新しいエージェント / スキルを追加する前に .claude/README.md の「委譲ポリシー」を確認し、そのエージェント/スキルが「別プロジェクトでもそのまま呼べるか」を自問する（NO ならプロジェクト側 .claude/ に配置する）
各ディレクトリ配下のコード・設定を編集する前に _README.md（存在すれば）を読む。目的・規約・更新ポリシー・他ファイルとの関係が記述されている
新規記事執筆 pipeline を起動する前に blog-ops/config/pipelines/new-article-{pillar,spoke}.json の DAG を Read して全 step を確認する。review skip 禁止、HUMAN_INPUT 残り は human-review（blocking step）で処理する

ハーネスの 3 層が揃っている状態と、一つでも欠けている状態では、エージェントへの業務委譲の安全性が根本的に違う。「まず動かして、後からフォールバックを追加する」設計は機能しない。設計段階で 3 層を定義し、実装はその順序で進める——これがエージェントハーネス設計の核心だ。

ROI・コスト比較・業務変革の business 観点は business 観点の記事「AI エージェントを事業の中心に据える」に詳しい。本記事で整理した設計原則を、事業側の意思決定コンテキストと組み合わせて読んでほしい。

スキルが SSOT を参照しない設計: 執筆スキルが SSOT（brand.ts / members.ts / .claude/skills/）を context に持っていなかったため、SSOT から確定取得できる情報（agent 数 / skill 数 / 失敗事例）までが HUMAN_INPUT マーカーになった。skill 定義時に「参照すべき SSOT のマッピング表」を SKILL.md に明示することで再発を防いだ（retro: blog-ops/retros/2026-05-19-ssot-driven-human-input-fill.md）。

2026-05 に blog-gate G1（HUMAN_INPUT マーカー検出）が「失敗事例を本文で説明する記事」を誤検出し、自分の失敗を語る記事が gate を fail させる矛盾が発生した。原因: 単純 grep で context-aware stripping が無く、code block 内の説明テキストも検査対象だった（retro: blog-ops/retros/2026-05-18-gate-false-positive.md）。対処として code block / inline code を除外する stripCodeContexts を実装し、Gate を文脈認識型に進化させた。