ハーネスエンジニアリング実践知 — 「AIを使う人」と「AIを設計する人」の決定的な差

まさお(@AI_masaou) 氏が、Claude Code のハーネス（開発基盤）をテーマにした約 80 分の対談形式勉強会のまとめ記事を公開しました。

新しい note を公開しました！ハーネスエンジニアリングに向き合う上で、実践的にはどうしているのか？の勉強会を行いましたのでそのまとめを記事にしました — @AI_masaou

元記事（ハーネスエンジニアリングの実践知を共有！【質問/勉強会のまとめ】）は有料コンテンツのため、本記事ではテーマであるハーネスエンジニアリングの実践知について、公開情報をもとに技術的な背景と具体的な手法を解説します。

ハーネスエンジニアリングとは

「ハーネス」とは馬具のことです。馬の力をそのまま放置すれば暴走しますが、ハーネスで制御すれば有用な仕事に変わります。AI エージェントも同じです。LLM の推論能力をそのまま使うのではなく、適切な制御基盤（ハーネス）で囲むことで信頼性の高い成果に変換するのがハーネスエンジニアリングです。

コンピュータの構成に対応させると、位置づけがわかりやすくなります。

コンピュータ	AI エージェント
CPU	LLM（推論エンジン）
OS	エージェントハーネス（制御・管理基盤）
アプリケーション	AI エージェント（実行層）

CPU がどれだけ高速でも、OS が適切に管理しなければアプリケーションは動きません。同様に、LLM がどれだけ賢くても、ハーネスの設計が悪ければエージェントの出力品質は上がりません。

コンテキストエンジニアリングとの関係

Andrej Karpathy が X で提唱した「コンテキストエンジニアリング」は、ハーネスエンジニアリングの中核概念です。

Context engineering is the delicate art and science of filling the context window with just the right information for the next step. — Andrej Karpathy

LLM のコンテキストウィンドウを「RAM」と捉え、次のステップに必要な最適な情報だけを入れる技術です。ハーネスエンジニアリングはこのコンテキスト管理の仕組み全体を包む上位概念にあたります。

ハーネスエンジニアリング（全体設計）
  ├── コンテキストエンジニアリング（何を LLM に渡すか）
  ├── 権限制御（何を許可・禁止するか）
  ├── ライフサイクル自動化（いつ何を実行するか）
  └── 並列実行・隔離（どう安全に並列化するか）

「環境設計 > モデル能力」— OpenAI Codex チームの実証

ハーネスエンジニアリングの重要性を最も説得力をもって示したのが、OpenAI のエンジニアリングチームによる 5 ヶ月間の実験です。

実験条件: 3〜7 名のチームで、人間はコードを 1 行も書かない縛り

結果:

指標	数値
生成コード量	100 万行
PR 件数	1,500 件
1 人あたり PR/日	平均 3.5 件
手作業比の開発時間	1/10

この実験から導出された 5 つの教訓が、ハーネスエンジニアリングの実践原則として広く引用されています。

教訓 1: 環境設計がモデル能力に勝る

進捗が遅い原因は AI ではなく、環境の未整備です。同じ Claude Code を使っても成果に数倍の差が出る理由はここにあります。モデルを GPT-4 から Claude に切り替えるよりも、CLAUDE.md を整備するほうが効果が大きいケースが多いのです。

教訓 2: 地図を渡す（Progressive Disclosure）

1,000 ページの仕様書をコンテキストに詰め込むのではなく、約 100 行の目次（AGENTS.md） を起点に、必要に応じて詳細フォルダに誘導する「段階的開示」が有効です。

AGENTS.md（約 100 行の目次）
 ↓ 必要に応じて参照
docs/
 ├── design-docs/     設計文書（索引付き）
 ├── exec-plans/      実行計画（アクティブ/完了/技術負債）
 ├── product-specs/   仕様書
 └── references/      LLM 向けライブラリ資料

教訓 3: アーキテクチャ規律の自動強制

不変条件（「テーブル名は snake_case」「API レスポンスは必ず envelope で返す」等）を機械的に強制し、実装の細部は自由にさせます。リンターや CI で自動チェックし、人間がレビューで指摘する必要をなくす設計です。

教訓 4: 観測性の統合

エージェントが自分の出力をセルフレビューできる仕組みを組み込みます。ブラウザの DevTools Protocol 連携、ログクエリ（LogQL/PromQL）による自動検証などが具体例です。「検証手段を与えるのが最重要」と Claude Code 開発者自身も述べています。

教訓 5: ドキュメント = コード

ドキュメントの陳腐化を防ぐため、CI にドキュメント検証を組み込み、doc-gardening エージェントが自動修正 PR を作成する仕組みを導入します。

Claude Code におけるハーネスの 6 層構成

Claude Code のハーネスは、具体的には以下の 6 層で構成されています。

┌─────────────────────────────────────────────┐
│ CLAUDE.md          知識管理層                 │
├─────────────────────────────────────────────┤
│ settings.json      権限制御層                 │
├─────────────────────────────────────────────┤
│ Hooks              ライフサイクル自動化層      │
├─────────────────────────────────────────────┤
│ Skills             動的コンテキスト注入層      │
├─────────────────────────────────────────────┤
│ MCP                外部統合層                 │
├─────────────────────────────────────────────┤
│ Worktree           並列開発層                 │
└─────────────────────────────────────────────┘

1. CLAUDE.md（知識管理層）

「プレミアム広告枠」として扱い、500 行以内に収めるのが推奨です。書くべきは「人間だけが知っていること」、すなわち意思決定の理由・禁止事項・ビジネス制約です。

4 レベルの階層構造があり、コンテキストの肥大化を防ぎます。

レベル	ファイル	読み込みタイミング
グローバル	`~/.claude/CLAUDE.md`	常に
プロジェクト	`PROJECT_ROOT/CLAUDE.md`	プロジェクト内で常に
ユーザープロジェクト	`.claude/CLAUDE.md`（gitignore 対象）	プロジェクト内で常に
サブディレクトリ	`src/api/CLAUDE.md` 等	そのパスにアクセスした時のみ

サブディレクトリレベルの CLAUDE.md はアクセス時のみ読み込まれるため、API 層の規約を UI 層のコンテキストに混入させずに済みます。

良い CLAUDE.md の例:

1
2
3
4
5
6
7
## 禁止事項
- 本番 DB への直接クエリ禁止（必ず read replica を使う）
- .env ファイルをコミットしない

## アーキテクチャ判断
- 認証: JWT + httpOnly cookie（セッション方式は採用しない）
- 理由: マイクロサービス間の認証伝播が容易

悪い CLAUDE.md の例:

1
2
3
4
## ビルドコマンド
npm run build
npm run test
npm run lint

ビルドコマンドは package.json を読めばわかるため、コンテキストの無駄遣いです。

2. settings.json（権限制御層）

deny-first（最小権限の原則） で設計します。明示的に許可したコマンドだけを実行可能にし、それ以外はブロックします。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(DROP TABLE)"
    ],
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Read",
      "Glob",
      "Grep"
    ]
  }
}

3. Hooks（ライフサイクル自動化層）

ライフサイクルイベント（ツール実行前後、コミット時等）でスクリプトを起動します。3 種類の Hook があります。

種類	処理内容	例
Command Hook	シェルスクリプト（決定論的処理）	lint、フォーマッタ
Prompt Hook	Haiku LLM による二値判断	コミットメッセージの品質チェック
Agent Hook	サブエージェントで複数ステップ検証	セキュリティレビュー

重要な設計原則は「Block-at-Submit, not Block-at-Write」です。開発中の書き込みをいちいちブロックするとフローが止まります。代わりに、コミット時点でゲートする設計が推奨されます。

4. Skills（動的コンテキスト注入層）

よく使うワークフローをスラッシュコマンドとして定義します。

1
2
3
4
5
---
description: コードレビューを実行
context: fork
---
`!git diff HEAD~1` の差分をレビューしてください。

context: fork パラメータがポイントです。これにより別のサブエージェントインスタンスに隔離され、メインセッションのコンテキスト容量を温存できます。

!command 構文を使うとリアルタイムデータ（git diff の出力等）をプロンプトに注入してから LLM に送信できます。

5. MCP（外部統合層）

外部ツール（Slack、DB、API 等）との接続を管理します。チーム共有は .mcp.json で管理し、認証情報は環境変数経由で渡します。

6. Worktree（並列開発層）

git worktree で複数の独立したディレクトリを作成し、並列実行を実現します。典型的なパターンは Writer/Reviewer 並列化です。

worktree-1（Writer）: 実装を進める
worktree-2（Reviewer）: Writer の出力をリアルタイムレビュー
→ 両方が同じ .git オブジェクトを共有しつつ独立したコンテキストで動作

コンテキスト管理の 3 原則

ハーネスエンジニアリングの実践で最も重要なのがコンテキスト管理です。LLM のコンテキストウィンドウは有限であり、不要な情報で埋まると推論精度が低下します。

Reduce（圧縮）

古い情報や冗長な記述を圧縮・要約して削除します。CLAUDE.md の定期的な棚卸しがこれにあたります。

Offload（退避）

長いログや大量のデータは外部ストレージに退避し、必要な時だけ参照します。RAG やファイル参照がこの手法です。

Isolate（隔離）

重い処理やコンテキストを消費する作業をサブエージェントに隔離します。Skills の context: fork や Worktree がこの実装です。

メインセッション（コンテキスト温存）
  ├── fork: コードレビュー → 結果だけ返す
  ├── fork: テスト実行 → pass/fail だけ返す
  └── fork: セキュリティチェック → 指摘事項だけ返す

Claude Code が 12 個のツールに絞っている理由

Claude Code は Read、Write、Edit、Bash、Glob、Grep 等、わずか 12 個のツールしか持っていません。これは設計上の意図的な制約です。

ツール数	効果
少ない（12 個）	各ツールの利用判断精度が高い。コンテキスト消費が少ない
多い（50 個以上）	どのツールを使うか迷い、誤選択が増える。ツール定義だけでコンテキストを圧迫

この「ツール数を制限して判断精度を上げる」という設計は、自作ハーネスにも応用できます。MCP で大量のツールを接続するとかえって性能が下がる場合があるのは、この原理によるものです。

実践的なハーネス構成例

GitHub で公開されている claude-code-harness は、以下の規模のハーネスを構築しています。

構成要素	数
Skills 定義	41 個
サブエージェント	11 個
Hooks	セーフティ + オートメーション用
ガードスクリプト	複数

ただし、これは大規模な例です。まさお氏も「汎用エージェントハーネスをどう作っているか」という記事で、OpenClaw のような既成品よりも自分の業務に合わせた自作ハーネスを推奨しています。

最小構成で始める

最初から 41 個の Skills を作る必要はありません。以下の 3 ファイルから始められます。

プロジェクトルート/
  ├── CLAUDE.md          ← 禁止事項とアーキテクチャ判断を書く
  ├── .claude/
  │   └── settings.json  ← deny-first の権限設定
  └── .claude/
      └── commands/
          └── review.md  ← 最初の 1 個の Skill

ここから業務に応じて Hooks → MCP → Worktree と段階的に追加していくのが実践的です。

「Plan → Work → Review」の基本サイクル

ハーネスエンジニアリングにおけるエージェント設計の基本パターンは 3 段階サイクルです。

1. Plan   — Plan mode で計画立案（コードを書かない）
     ↓
2. Work   — 実装（複数 Worktree で並列化可能）
     ↓
3. Review — セルフレビュー（エージェント自身が検証手段を実行）
     ↓
   （次の Plan へ）

このサイクルを回す際の実践的なポイントは以下の通りです。

Plan フェーズでは Glob/Grep/Read だけ許可: 編集権限を与えないことで、調査に集中させる
Work フェーズでは検証手段を明示: 「テストを実行して全て pass したら完了」等の終了条件を与える
Review フェーズは別コンテキストで実行: 実装者と同じコンテキストでレビューすると確証バイアスが生じるため、context: fork で隔離する

コミュニティの動向

ハーネスエンジニアリングは 2026 年初頭の日本語 AI コミュニティで急速に広まっています。

梶谷健人(@kajikent) 氏が OpenAI の事例を紹介し、広く認知されました。Masahiro Nishimi(@mah_lab) 氏はさらに踏み込み、以下のように述べています。

ハーネスエンジニアリングを業務領域に拡張して、更に事業領域に拡張して、更に経営領域に拡張することが AI ネイティブ戦略であると言える

2026 年 3 月 12 日には Claude Code Meetup Japan #3 が開催予定で、「自律型エージェントが切り拓く AI 駆動開発の新境地」をテーマにハーネスエンジニアリングが中心的な話題になる見込みです。

まとめ

ハーネスエンジニアリングは「AI の OS」を設計する技術: LLM の推論能力を制御基盤で囲み、信頼性の高い成果に変換する
「環境設計 > モデル能力 > プロンプト工夫」の優先順位: OpenAI Codex チームの 5 ヶ月間実験で、人間がコードを書かずに 100 万行・1,500 PR を達成
Claude Code のハーネスは 6 層構成: CLAUDE.md（知識管理）、settings.json（権限制御）、Hooks（自動化）、Skills（コンテキスト注入）、MCP（外部統合）、Worktree（並列開発）
コンテキスト管理の 3 原則: Reduce（圧縮）、Offload（退避）、Isolate（隔離）で有限なコンテキストウィンドウを最適化
ツール数は少ないほど精度が上がる: Claude Code が 12 個に絞っている設計意図を自作ハーネスにも応用する
最小構成（CLAUDE.md + settings.json + 1 Skill）から始められる: 業務に応じて段階的に Hooks → MCP → Worktree を追加
エンジニアの仕事が変わる: 「コードを書く」から「エージェントが動ける環境を設計する」への移行が進んでいる

ハーネスエンジニアリング実践知 — 「AIを使う人」と「AIを設計する人」の決定的な差#

ハーネスエンジニアリングとは#

コンテキストエンジニアリングとの関係#

「環境設計 > モデル能力」— OpenAI Codex チームの実証#

教訓 1: 環境設計がモデル能力に勝る#

教訓 2: 地図を渡す（Progressive Disclosure）#

教訓 3: アーキテクチャ規律の自動強制#

教訓 4: 観測性の統合#

教訓 5: ドキュメント = コード#

Claude Code におけるハーネスの 6 層構成#

1. CLAUDE.md（知識管理層）#

2. settings.json（権限制御層）#

3. Hooks（ライフサイクル自動化層）#

4. Skills（動的コンテキスト注入層）#

5. MCP（外部統合層）#

6. Worktree（並列開発層）#

コンテキスト管理の 3 原則#

Reduce（圧縮）#

Offload（退避）#

Isolate（隔離）#

Claude Code が 12 個のツールに絞っている理由#

実践的なハーネス構成例#

最小構成で始める#

「Plan → Work → Review」の基本サイクル#

コミュニティの動向#

まとめ#

参考#