メインコンテンツまでスキップ

ハーネスエンジニアリング入門: AI エージェントの信頼性は周囲の設計で決まる

· 約30分
rasshii
Software Engineer

「モデルを最新版に上げたのに、結局同じ間違いを繰り返す」「プロンプトを工夫してもどこかで頭打ちになる」。AI エージェントを業務に組み込もうとすると、必ずこの壁に当たります。これは多くの場合モデル本体の問題ではなく、モデルを取り囲む環境 (= harness) の設計品質に起因します。本記事では 2026 年 2 月以降に急速に体系化された ハーネスエンジニアリング (Harness Engineering) という考え方を、自分の ~/.claude/ 配下の構成例とあわせて整理します。

なお、用語の語源について軽く触れておきます。「harness」は『装備・馬具・(動詞で) 力を制御し活用する』意味を持つ英単語で、AI 文脈では Mitchell Hashimoto (HashiCorp 共同創設者) が 2026 年 2 月に「モデルを支える環境一式」の意味で導入しました。中核にある等式はとてもシンプルです。

Agent = Model + Harness

この等式を出発点に、harness とは何か、どう設計するか、どう段階的に育てるかを見ていきます。

本記事の読み方

本記事は 公式 / 業界共通の概念 と 自分の運用例 が混在しています。後者は :::info 自分の運用例 ::: のブロックで囲んで明示しているので、「あなたの Claude Code にもそのまま当てはまるか」「rasshii さん独自の運用か」を判別しながら読み進めてください。コード雛形もすべて自分の運用例ブロック内に置いています。

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

ハーネスエンジニアリングとは、AI エージェント (Claude Code / Codex / Cursor などの coding agent) が動作する 全環境を設計する実践 を指します。Mitchell Hashimoto が 2026 年 2 月に個人ブログで概念を提唱し、数日後に OpenAI の Ryan Lopopolo がフィールドレポートで追従しました。Lopopolo のチームは 5 ヶ月で約 100 万行のコードベースを 手書き 0 行 / 1500 自動 PR で構築したと報告しており、これが業界の注目を集めるきっかけになりました。その後 Anthropic / Augment Code / Birgitta Böckeler (Martin Fowler のサイト掲載) / SIG など複数社がそれぞれの語彙で体系化し、2026 年 5 月現在は業界共通の用語として定着しつつあります。

ハーネスエンジニアリングは、これまでの「プロンプトエンジニアリング」「コンテキストエンジニアリング」と階層的に区別される概念です。

層問いスコープ
Prompt Engineering何を尋ねるか単一インタラクション
Context Engineering何を見せるか1 つの context window 内
Harness Engineering環境全体をどう設計するか複数セッション横断 / 環境設計 / phase gate

プロンプトエンジニアリングが「単発の指示文を磨く」のに対し、ハーネスエンジニアリングは エージェントが今後ずっと動く環境全体 を対象にします。同じモデルでも、harness の設計品質次第でエージェントの信頼性は大きく変わる、というのが主張です。

中核等式: Agent = Model + Harness​

もう一度等式を書きます。

Agent = Model + Harness

ここでいう Model は Claude Opus / Sonnet / Haiku、GPT、Gemini といった LLM 本体です。Harness はそれ以外のすべてを指します。具体的には次のようなものが含まれます。

  • システムプロンプト
  • 常時注入される指示書 (Claude Code でいう CLAUDE.md)
  • ルール / スキル / サブエージェントの定義
  • MCP (Model Context Protocol) サーバー / 各種 tool / permissions
  • フック (PreToolUse / PostToolUse / Stop など、ツール実行前後の特定タイミングで発火する shell 連携。詳細は後述)
  • メモリ (会話を跨いだ永続化)
  • コンテキスト管理 (compaction [会話履歴の圧縮] や reset の戦略)
  • 検証ループ (CI / lint / type-check / 自動レビュー)

つまり「エージェントが世界とやり取りする経路」と「エージェントが自分を律する仕組み」をまとめて harness と呼びます。モデル単体の精度より、これらが噛み合っているかどうかが、業務利用に耐える信頼性を左右します。

二分法フレームワーク: Guides × Sensors​

harness の設計を整理する上で最も実用的なフレームが、Birgitta Böckeler（Thoughtworks Distinguished Engineer、Martin Fowler のサイトで公開）による Guides + Sensors の二分法です。

  • Guides (feedforward): 行動「前」のステアリング。失敗が起きる前に方向付けする
  • Sensors (feedback): 行動「後」の自己修正。間違いを検出して直す

さらにそれぞれを、Computational か Inferential かで十字に分類します。Computational は deterministic、つまり機械的に毎回同じ結果が返る検証 (lint / 型チェック / テストなど) です。Inferential は LLM-based、すなわち LLM の推論に依存する確率的な検証 (レビュー agent / 提案 skill など) です。すると 4 象限になります。

このフレームの重要な含意は、どちらか片方だけでは harness は機能しない ことです。

  • Feedback だけ (Sensors のみ): エージェントは同じミスを何度も繰り返した後でしか修正できない
  • Feedforward だけ (Guides のみ): ルールを書いても LLM は確率的に違反するため、効果を検証する手段がない
  • Computational だけ: 機械的な lint や型は通っても、設計の妥当性や仕様適合は見抜けない
  • Inferential だけ: LLM のレビューは確率的で、// eslint-disable のような明確な違反すら見落とすことがある

良い harness は 4 象限すべてで何か手を打ってある 状態を目指します。

CLAUDE.md / MCP / memory: harness の入口​

~/.claude/ 配下の細かいディレクトリに入る前に、Claude Code 標準で用意されている harness の入口 にあたる 3 要素を押さえておきます。これらは Anthropic が公式に提供している機能で、誰の Claude Code でも同じように使えます。

  • CLAUDE.md: プロジェクトルートや ~/.claude/ 直下に置く Markdown 指示書。起動時に常時 context に注入されます。@path/to/file 構文で他ファイルを auto-load (自動読み込み) できるため、ハブ的な位置づけになります
  • MCP (Model Context Protocol): 外部ツール / データソースへのアクセス手段。Claude Code に対するプラグインのようなものです。例: context7 (ライブラリの最新 docs)、aws-knowledge (AWS 公式 docs)、terraform、sequential-thinking (構造化推論)、serena (LSP ベースのコード検索) など
  • auto-memory: 会話を跨いで ~/.claude/projects/<project>/memory/ に永続化される情報 (<project> は git リポジトリから派生)。ビルドコマンド、デバッグ知見、アーキテクチャメモ、コーディング規約の好み、ワークフロー習慣などが蓄積されます

これら 3 つは harness の「外周の入口」にあたります。CLAUDE.md がエージェントに「今回も守ってほしいこと」を毎回伝え、MCP が「最新の一次情報にアクセスする手段」を提供し、memory が「前回までに学んだことを思い出させる」役割を担います。

自分の運用例

僕は CLAUDE.md の Quality & Accuracy Policy セクションに「MCP 第一選択 → WebSearch fallback」と明記しています。これは、WebSearch だけに頼ると古い情報を引きやすいためで、ライブラリ仕様は context7 / AWS は aws-knowledge / Terraform は terraform MCP / 複雑判断は sequential-thinking、と用途別に MCP を割り当てています。さらに、特定キーワード (例: 「ultrathink」「アーキテクチャ設計」) が発話に含まれたら sequential-thinking を自動起動するように CLAUDE.md でトリガーを定義しています。

~/.claude/ 配下の構成 (全体マップ)​

ここから先は具体的なディレクトリ構成の例として、自分の ~/.claude/ 配下を題材に紹介します。Claude Code 標準の機能と自分の独自運用を 2 列で対比した表が以下です。

ディレクトリClaude Code 標準機能自分の運用
rules/✅ Memory システムの一部 (auto-load 対象)29 ファイルに分割、frontmatter paths: で path-scoped 化
skills/✅ Skill システム (発話 trigger で起動)23 個、Step 0 で MCP 起動を強制
agents/✅ Subagent システム (隔離 context で起動)7 個、Generator (implementer) と Evaluator (code-reviewer / architect / test-strategist) を意図的に分離
hooks/✅ PreToolUse / PostToolUse / Stop などの hook システム2 個、suppression 検出 / 保護ファイル防御
teams/⚠️ 公式機能ではなく自分で定義した meta orchestration パターンmulti-perspective-review 等、複数 agent を main agent から spawn (起動)
references/❌ 公式機能ではなく自分の命名progressive disclosure 用、on-demand Read で context 節約
scripts/❌ 公式機能ではなく自分の運用月次 cron で consistency check / self-test
commands/✅ Custom slash command システム軽量な汎用コマンド (init / review / security-review など)
output-styles/✅ Output style システムレスポンス調整用、最小限のみ

「✅」が付いているディレクトリは Claude Code 公式機能の格納先で、誰でも同じ位置に置けば同じように動きます。「⚠️ / ❌」は個人的に切り出した運用上の慣習で、別に notes/ でも meta/ でも構わない名前です。読者の Claude Code でこれをそのまま真似する必要はありませんが、なぜそういうディレクトリを切ったのか の理由を以降の章で紹介します。

全体のレイヤ構造は、入口 (CLAUDE.md / MCP / memory) から Inferential Guides (rules / skills)、Generator/Evaluator (agents) へと進みます。その先に Computational Sensors (hooks)、Orchestration (teams)、補助 (references / scripts) が続く構成です。

rules/: Inferential Guides の中核​

Claude Code には Memory システムという仕組みがあり、~/.claude/rules/*.md (および各リポジトリの CLAUDE.md) を起動時に context に取り込みます。常時ロードされる rule と、frontmatter (Markdown 冒頭の --- 区切りメタデータ部) に paths: を持つ path-scoped rule (特定パスのファイルを読んだときだけロード) の 2 種類が公式にサポートされています。

rule は「LLM に向けた規範指示」なので、二分法フレームでいう Inferential Guide に分類されます。コンパイラや lint と違って違反を機械的に止められるわけではありませんが、エージェントに「こうあってほしい」を伝える最も基本的な手段です。

自分の運用例

僕は ~/.claude/rules/ を 29 ファイルに分割して運用しています。1 ファイルに詰め込みすぎると context window (LLM が一度に扱える情報量) を圧迫し、かつ「いつでも全部読まれる」状態になるためです。

  • 常時ロード: コーディング規約 (code-style.md)、Git ワークフロー (git-workflow.md)、harness 概念 (harness-engineering.md) など、どのタスクでも参照したいもの
  • path-scoped: Terraform 規約 (terraform.md、paths: ["**/*.tf"])、Ratchet ワークフロー (ratchet-workflow.md、関連 path Read 時のみ) など、特定ドメインに入ったときだけ必要なもの

各 rule の構造はだいたい次のような Markdown です。

---
name: code-style
description: コード可読性 / 命名規則 / コメント / シークレット管理
---

# Code Style

- Priority: readability > maintainability > performance > brevity
- 変数・関数・クラス名: English / コメント: Japanese ("why" を説明)
- Documentation format: JSDoc
- Credentials via environment variables only, never hardcoded

## Example (Good)

```ts
const MAX_RETRY_COUNT = 3;
function groupUsersByRole(users: User[]): Map<Role, User[]> { /* ... */ }
const apiKey = process.env.MY_SERVICE_API_KEY;
```

## Example (Bad)

```ts
function f(u: any[]) { /* ... */ }                // 命名違反
const apiKey = "hardcoded-value-here";            // ハードコード禁止
```
一般的な TypeScript コード品質の話題 (上記 code-style.md の harness 版ではなく、コードそのものをどう書くか) は本サイトの Docs に Clean Code (TypeScript) として体系化しています。命名・関数設計・SOLID 等は そちらを参照してください。

一方、特定の拡張子やパスでのみ参照したい規約は、frontmatter に paths: (minimatch グロブ) を追加するだけで path-scoped rule になります。Terraform 規約ならこんな感じです:

---
name: terraform
description: Terraform のコーディング規約 (provider バージョン / リソース命名 / シークレット管理)
paths:
  - "**/*.tf"
  - "**/*.tfvars"
---

# Terraform

- Provider バージョンは `~> X.Y` 形式で固定する
- リソース命名: `<service>_<purpose>` のスネークケース
- シークレットは AWS Secrets Manager / SSM Parameter Store 経由 (ハードコード禁止)
- module は input/output を明示し、可能な限り公式 Verified module を優先する

## Example (Good)

```hcl
provider "aws" {
  region  = "ap-northeast-1"
  version = "~> 5.0"
}

resource "aws_s3_bucket" "app_logs" {
  bucket = "${var.project_name}-app-logs"
}
```

この rule は .tf / .tfvars ファイルを Read したときだけ context に追加されます。フロントエンドだけ触っている日はロードされず context window が空くので、ドメイン別に分割しておくと効きます。

どちらの形式でも、Good / Bad の Example を必ず添えるようにしています。LLM は説明文だけより、具体例から「型」を学ぶほうが安定するためです。

:::

skills/: 発話駆動スキル​

Skill は Claude Code が公式に提供する仕組みで、特定の発話 (たとえば「レビューして」「提案して」「デバッグして」) で起動するワークフローを ~/.claude/skills/<name>/SKILL.md に記述します。SKILL.md の frontmatter で発話トリガー / 利用可能ツール / effort などを宣言し、本文で実行手順を記述する形です。

二分法フレームでいうと、/review や /debug のように出力後に検査・修正するものは Inferential Sensor、/propose のように事前ステアリングするものは Inferential Guide として機能します。

自分の運用例

僕は 23 個の skill を運用しており、主なものは /propose / /review / /debug / /learn / /explain / /compare / /tec-doc / /grill-me / /next / /checkpoint などです。共通の運用ポイントとして:

  • Step 0 で MCP 起動を強制: 複雑判断は sequential-thinking、ライブラリ仕様は context7、AWS は aws-knowledge を必ずロードするよう SKILL.md に書く
  • 反復プロトコル: /review は最大 3 反復で Critical / Major を 0 に収束、/propose は敵対的自己批判で最大 2 反復、/debug は Investigate → Fix → Verify を最大 3 反復、というように skill ごとに反復回数を決める

SKILL.md の雛形例:

---
name: review
description: コード変更を 7 観点 (正確性 / 可読性 / パフォーマンス / セキュリティ / 保守性 / 規約 / デグレ) で重要度付きレビュー
when_to_use: 「レビュー」「review」「見て」「チェック」発話で起動
allowed-tools: Read, Grep, Glob, Bash, WebSearch
effort: max
---

## Step 0: MCP 起動

- sequential-thinking (複雑判断時に強制)
- context7 (FW 用法検証時)

## Step 1: 変更範囲の把握

git status / git diff で対象ファイルを取得。

## Step 2-3: 7 観点レビュー → 重要度付け

Critical / Major / Minor / Nit の 4 段階で指摘。

## 終了条件

Critical / Major が 0 になるか、最大 3 反復に到達したら終了。

agents/: Subagent (Generator-Evaluator 分離)​

Claude Code には Subagent (サブエージェント) という公式機能があり、隔離された context で独立した役割を持つエージェントを起動できます。~/.claude/agents/<name>.md に定義し、main agent から Agent ツール (subagent を起動するための main agent 側の tool) 経由で呼び出します。

ここで harness engineering の重要原則のひとつ、Generator-Evaluator 分離 が登場します。Anthropic や業界共通の知見として「実装した agent が自分で評価すると self-evaluation bias が働き、品質を過大評価する」ことが分かっています。実装役 (Generator) と評価役 (Evaluator) は別の agent にする、というのが要点です。

自分の運用例

自分の ~/.claude/agents/ には 7 個の subagent を定義しています。

  • Generator 系: implementer (TDD [テスト駆動開発] + 型安全)、refactorer (振る舞い保存のリファクタ)、debugger (バグ自律解決)
  • Evaluator 系: code-reviewer (7 観点レビュー、read-only [読み取り専用])、architect (設計レビュー + 敵対的検証)、test-strategist (テスト戦略)、infra-reviewer (TF / IaC レビュー)

Evaluator 系は disallowedTools: Write, Edit を設定して、編集権限を持たない read-only な役割に固定しています。これで「レビュアーが勝手にコードを書き換える」事故を構造的に防げます。

subagent 定義の雛形:

---
name: code-reviewer
description: ペアプログラミング用コードレビュアー。コード変更後のレビューとガイダンスを提供
tools: Read, Grep, Glob, Bash, WebSearch
disallowedTools: Write, Edit
---

## Step 0: MCP 起動 (必須)

- sequential-thinking (複数仮説の検証で強制)
- context7 (FW 用法検証時)

## レビュー観点

正確性 / 可読性 / パフォーマンス / セキュリティ / 保守性 / 規約 / デグレ

## 出力フォーマット

- Critical / Major / Minor / Nit で重要度付け
- ファイル名 + 行番号で指摘箇所を明示
- 修正案を提示 (具体的な diff か命令で)

hooks/: Computational Sensors​

Claude Code の Hook システムは、特定のイベント (PreToolUse: ツール実行前、PostToolUse: ツール実行後、Stop: 応答終了時、UserPromptSubmit: ユーザー入力受信時 など) で shell コマンドを実行できる公式機能です。~/.claude/settings.json で hooks フィールドに登録します。

二分法フレームでいうと、hook は典型的な Computational 層: deterministic な仕組みで、入力と出力が毎回同じ shell スクリプトに従います。Guide 用途 (実行前ブロック) と Sensor 用途 (実行後検出) の両方に使えます。

自分の運用例

僕は 2 個の hook を運用しています。

  • check-suppression.sh (PostToolUse): // eslint-disable / @ts-ignore / # type: ignore / # noqa などの lint 抑制コメントの新規追加を検出 します。検出時は exit 2 で Claude にフィードバックを返し、根本原因の修正を強制します (編集そのものを未然に止めたいなら PreToolUse を使います)
  • check-protected-files.sh (PreToolUse): .env / 秘密鍵 / 認証情報ファイルへの書き込みを未然にブロック

check-suppression.sh の最小実装例:

#!/bin/bash
# ~/.claude/hooks/check-suppression.sh
# PostToolUse hook: lint suppression コメントの新規追加をブロック

set -eu

# 緊急時の override (環境変数で skip 可能)
if [ "${CLAUDE_HOOK_SKIP_SUPPRESSION:-0}" = "1" ]; then
  exit 0
fi

# hook 入力 (JSON) から新規追加コンテンツを取り出す
INPUT=$(cat)
NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')

# 抑制パターンの検出
if echo "$NEW_CONTENT" | grep -qE '(eslint-disable|@ts-ignore|# type: ignore|# noqa)'; then
  echo "ERROR: Suppression comment is not allowed. Fix the root cause instead." >&2
  exit 2   # PostToolUse の exit 2 は Claude に feedback として返る
fi

exit 0

settings.json への登録例 (matcher フィールドで発火対象のツール名を正規表現で絞れます):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/check-suppression.sh" }
        ]
      }
    ]
  }
}

ポイントは 「rules で『any 禁止』と書くだけでは LLM は確率的に違反する」 という前提です。重要規範ほど deterministic な hook で機械的に止める、というのが harness engineering の中核哲学のひとつになります。

補助ディレクトリ (teams / references / scripts)​

ここからは Claude Code 標準機能ではない、自分の運用上の慣習として切り出したディレクトリです。読者がそのまま真似する必要はありませんが、なぜこういう箱が欲しくなるのかを共有しておきます。

teams/: Multi-agent Orchestration​

複数の subagent を協調動作させたいケースがあります。たとえば「10 ファイル以上の変更を、code-reviewer (品質) + architect (設計) + test-strategist (テスト) の 3 視点で並列レビューしたい」など。

自分の運用例

~/.claude/teams/multi-perspective-review/team.md に、main agent が 3 subagent を並列 spawn して結果を統合する手順を Markdown で記述しています。発話に「複数視点」「総合レビュー」「3 視点」が含まれたら main agent が team.md を Read して実行する、という運用です。

これは Claude Code 公式機能ではなく、subagent 機能の上に乗せた meta orchestration (複数 agent を束ねる統制) パターンです。

references/: 詳細プロトコル (progressive disclosure)​

rules/ に詳細な手順 / テンプレート / 適用例まで書き込むと、auto-load されるたびに context を圧迫します。そこで rules には 規範ルール (要約) だけ書き、詳細プロトコルは別の場所に置いて、必要時のみ Read する、という形で分離します (これを progressive disclosure [段階的開示] と呼びます)。

自分の運用例

~/.claude/references/ に 25 ファイルの詳細プロトコルを置いています。rules 側から「詳細プロトコル: ~/.claude/references/xxx.md (必要時 Read)」と参照する形です。これで context window を節約しつつ、深掘りしたいときは詳細にアクセスできます。

これも公式機能ではなく、命名も任意です。docs/ でも manuals/ でも構いません。

scripts/: 計測・検証​

harness 自体の整合性を機械的にチェックする shell スクリプト置き場です。

自分の運用例

~/.claude/scripts/ に内部整合性チェック (check-internal-consistency.sh) と self-test (self-test.sh) を置き、月次 cron (定期実行ジョブ) で実行しています。「rules 内のクロスリンクが壊れていないか」「skill の発話トリガーが衝突していないか」など、harness そのものの drift を検出する Computational Sensor です。

Phase 0-6 段階的導入パス​

ここまで個別のディレクトリを紹介してきましたが、これらを どういう順番で導入していくか が次の論点になります。「29 個の rules / 23 個の skills / 7 個の agents / 2 個の hooks」を一気に書こうとすると、context window が溢れ、規範が形骸化し、違反が量産されて基準そのものが崩壊します。

Phase 番号は自分で付けた整理軸です

以下の Phase 0-6 という段階分けは僕が自分の harness を整理するために便宜的に付けたラベルで、公式・業界標準の区分ではありません。ただし、各 Phase で扱う 個別の概念 (Computational Guards / Architecture Fitness / Generator-Evaluator 分離 / Spec-First / Ratchet / Metrics) は僕のオリジナルではありません。Hashimoto / Anthropic / Neal Ford / Birgitta Böckeler などの公式・業界由来です。

Phase名称主な成果物概念の由来
0概念整理harness 規範 rule の文書化Hashimoto / Lopopolo / Böckeler
1Computational Guardshook (suppression 検出 / protected files) + pre-commitAnthropic / 業界共通
2Architecture Fitnessdependency-cruiser / Conftest / tflint で構造制約検証Neal Ford (Building Evolutionary Architectures)
3Generator-Evaluator 分離subagent (implementer / code-reviewer / architect ...)Anthropic
4Spec-First PipelineCONTEXT.md (用語) / docs/adr/ (決定) / docs/specs/ (仕様)Hashimoto
5Ratchet Workflow失敗 → 永続修正への昇格手順Hashimoto の原則 + 自分の運用整理
6Metrics & Health Check4 Quality metrics の月次集計スクリプトHashimoto / Lopopolo

進化の流れを図にすると以下です。

各 Phase の狙いは次のとおりです。

  • Phase 0: まず harness とは何かを文書化する。rules/harness-engineering.md のような規範文書を書き、その後の Phase で何を強制したいかの 語彙 を揃える
  • Phase 1: rule (Inferential Guide) で書いた規範のうち、機械化できるものを hook / lint / type-check で deterministic に止める。LLM の probabilistic compliance を補完する最初の砦
  • Phase 2: 単一ファイルではなくファイル間関係 (循環依存 / レイヤ違反 / cross-feature 依存 [feature 間の不要な依存関係]) を CI で検出する。具体的には dependency-cruiser (JS/TS の依存方向検証) / Conftest (OPA Rego ベースの policy 検証) / tflint (Terraform linter) などのツールを使う。Neal Ford の Architecture Fitness Functions が出典
  • Phase 3: 実装役と評価役を別 subagent に分ける。Generator (implementer) と Evaluator (code-reviewer / architect / test-strategist) を意図的に分離し、self-evaluation bias を排除する
  • Phase 4: 用語定義 (CONTEXT.md) / 重要設計決定 (ADR) / 機能仕様 (docs/specs) を harness の必須入力にする。Spec を読まずに実装させない
  • Phase 5: 失敗パターンを rule / hook / fitness function に永続化して再発を構造的に不可能にする (Hashimoto の原則がベース。詳細は後述)。僕は中間置き場として learnings/ を使い、繰り返した失敗だけを昇格させる運用
  • Phase 6: harness 自体の信頼性を 4 Quality metrics (後述) で計測し、月次 cron で health check する

要点は「いきなり Phase 6 から始めない」ことです。Phase 0 と Phase 1 だけでも、ほとんどのプロジェクトで効果が出ます。

Ratchet Workflow: 失敗を永続修正に変える​

Phase 5 で登場した Ratchet の考え方は、harness engineering の中でも特に「これだけ覚えて帰っていい」レベルの中核原則なので、独立した節として取り上げます。土台にあるのは Mitchell Hashimoto がブログで示した原則で、原文に沿って要約すると次のとおりです。

agent がミスをしたと気付いたら、その都度、同じミスが二度と起きないような解決を engineering する。

僕はこの原則を Ratchet (ラチェット) と呼び、「同じ失敗が 2 度 観測されたら、必ず rules / hooks / fitness function / learnings のいずれかに 永続的修正 を加え、再発を 構造的に不可能 にする」という形で運用に落とし込んでいます。「ratchet」という呼び名、「2 度」という閾値、修正先の 4 分類は、いずれも Hashimoto の記事そのものにはない僕自身の運用整理です。

ratchet (ラチェット) は工具用語で「一方向にしか回らない歯車」を指します。一度進んだら戻らない、という性質を harness の学習ループに重ねた比喩です。「もう気をつけます」「次から注意します」では同じ失敗を必ず繰り返すので、気をつけなくても発生しない仕組み に組み込む、というのが要点です。

自分の運用例

僕は /learn skill で会話中に得た知見をその場で ~/.claude/learnings/<category>/<topic>.md に追記し、セッション終了時には /record-learnings skill で一括抽出しています。さらに、同じ失敗が複数回観測されたら learnings から rule や hook に昇格させます。たとえば「型違反を見落としがち」という learnings が積み重なれば、rules/typescript-strict.md に項目を足したり、TypeScript 設定を strict 寄りに更新したりします。

8 つの規範ルール​

ハーネスエンジニアリングの実践で守りたい主な規範を 8 つにまとめます。出典は公式 / 業界共通のものと、自分の運用方針が混在しています。

  1. Anything not in context doesn't exist (Hashimoto / Lopopolo): agent に伝えたい情報は repository-local かつ versioned な artifact に置く。Slack や口頭、個人の頭の中は agent から見えない
  2. Probabilistic compliance を信用しない (業界共通): rule で「any 禁止」と書いても LLM は確率的に違反する。重要規範は computational sensor (lint / hook / CI) で deterministic に強制する
  3. Generator と Evaluator は分離する (Anthropic): 実装した agent に自己評価させない。別の subagent でレビューする
  4. Inline-disable suppression を許さない (業界共通): // eslint-disable-next-line / @ts-ignore で sensor を抑制するのは harness を空洞化させる最大の anti-pattern。修正で対応する
  5. Ratchet principle (Hashimoto の原則に基づく自分の運用整理): 同じ失敗を 2 度起こしたら永続的修正を加える。再発を構造的に不可能にする
  6. Volume metrics を主指標にしない (Hashimoto / Lopopolo): 「AI が書いた行数」「採用された提案数」は harness 信頼性を反映しない。後述の Quality metrics を使う
  7. Context Resets > Compaction (Anthropic / Hashimoto): 長期タスクを compaction で延命させず、構造化ハンドオフで完全リセットして新規 agent を起こす
  8. Spec drift を sensor で検出する (Hashimoto): CONTEXT.md / ADR / docs/specs と実装の乖離は下流テストでは捕捉できない。Evaluator agent が仕様準拠で判定する

アンチパターン​

harness を組むときによく起きる失敗パターンも併せて挙げておきます。

  • One-shot completion: 複雑タスクを一発完了させようとする。途中で hand-off (別 agent / 次セッションへの引き継ぎ) / 反復を入れない
  • Rules files alone: rule だけ書いて computational sensor を併設しない。Inferential Guide のみだと違反は確率的に発生する
  • Over-constraining: 厳しすぎる制約で legitimate な refactoring まで阻害する。「全部禁止」は誰も従わなくなる
  • 完了の早期宣言: verification なしで「完了」と言う。テスト・型・lint の確認なし
  • 部分実装の放置: 途中状態のままハンドオフ。次セッションが拾えない
  • Self-evaluation only: Generator agent に自己評価させる。code-reviewer / architect など別 agent を介さない

4 Quality metrics​

最後に、harness 自体の品質を測る指標を整理します。コードの「行数」「採用率」のような Volume metrics ではなく、信頼性に直結する Quality metrics を主指標にすべき、というのが Hashimoto / Lopopolo の主張です。

指標内容なぜ大事か
Task Resolution Rate自動テストで検証された正解率エージェントが「自称完了」したものの実際の合格率
Code Churn Rate2 週間以内に破棄されたコードの割合短期で書き直された量。harness が安定設計を導けたかの指標
Verification TaxAI 生成コード監査に費やした時間人間のレビュー負荷。これが下がるほど harness が信頼できる
Defect Escape Rate本番に到達した欠陥率最終的なユーザー影響。harness 全体の総合スコア

Volume metrics との対比は次のとおりです。

  • Volume metrics は「使用量」を測る (e.g. AI が書いた行数、受諾された提案数): エージェントがどれだけ働いたか
  • Quality metrics は「信頼性」を測る: エージェントがどれだけ役に立ったか

harness の良し悪しは Quality 側で評価しないと、「たくさん書いたけど 2 週間後に全部書き直し」が高得点になってしまいます。

はじめの一歩 (実践指南)​

ここまで読んで「全部一気にやるのは無理だ」と感じたら、それで正解です。ハーネスエンジニアリングは段階的に育てるものです。読者が今日から始められる最小ステップを 3 つ挙げておきます。

  1. CLAUDE.md を 1 ファイル書く: プロジェクトルートか ~/.claude/CLAUDE.md に「このプロジェクトで守ってほしいこと」を Markdown で 5-10 行。「型は any 禁止」「コメントは日本語」「テストを書いてから実装」など、自分が普段口頭で伝えていることを文字に起こすだけで十分です
  2. 失敗したら learnings に記録: 同じミスが 2 回出たら、CLAUDE.md か別の rule ファイルに永続化する (Ratchet Workflow)。「気をつける」ではなく「次から発生しない仕組み」に倒す
  3. 重要なものは Computational Sensor で deterministic 化: 型安全 (TypeScript strict) や lint (ESLint) は LLM の意思にかかわらず違反を弾けます。一番効くのは pre-commit hook (Git コミット前に走るチェック) と CI

「いきなり 29 個の rules / 23 個の skills を書かない」が最大の落とし穴回避策です。1 ファイルから始めて、必要が出るたびに増やすほうが、長期的には強い harness になります。

出典・参考リンク​

用語提唱・中核概念​

Anthropic 公式 (Long-Running Agents)​

二分法フレームワーク​

Architecture Fitness Functions​

Claude Code 公式 docs​

ツール公式​

語源​

まとめ​

最後にもう一度、中核等式を確認します。

Agent = Model + Harness

モデルを最新版に上げても精度が頭打ちなら、harness を疑う。harness は Guides (feedforward) と Sensors (feedback) の 2 軸、それぞれを Computational / Inferential で十字分類して設計する。一気に全部入れず、Phase 0 (概念整理) と Phase 1 (Computational Guards) から始める。失敗は気をつけるのではなく Ratchet で構造的に不可能にする。

本記事を読み終えたあなたが「自分のプロジェクトでも、まず CLAUDE.md を 1 ファイル書いてみよう」と感じたなら、この記事は十分に役目を果たしたと思います。

記事の感想・フィードバックは X でお気軽にどうぞ

𝕏 で感想をツイート