ハーネスエンジニアリング実践ガイド — Claude Code を「育てる」ための 5 つの型とテンプレ【2026年版】

前回の記事で、ハーネス＝モデルを「働けるエージェント」に変える外側の実行環境一式、という整理をしました。この記事はその続編で、手を動かす人向けです。

テーマは一つ。エージェントが失敗したとき、チャットで「次から気をつけて」と言うのをやめて、環境側（ルール・hooks・権限・スキル）を恒久修正するへの切り替え方です。この営みには「ハーネスエンジニアリング」という名前がついており、Claude Code はそのための拡張点を最初から開いています。5 つの型に分けて、コピペで使えるテンプレートと一緒に紹介します。

順番に注意してください。CLAUDE.md やルールを先に「書き溜める」のは悪手です。実際に起きた失敗から逆算せずに書いたルールは当たらず、コンテキストを圧迫するだけに終わりがちです。だから型 1（失敗ログ）が最初に来ます。

ハーネスエンジニアリングの心臓部です。国内でも、失敗を記録 → 再発防止ルールに変換 → 危険な操作は hook で物理ブロック、という改善ループで Claude Code をドメイン特化させる方法論が公開されており（Stanby Tech Blog — 失敗から育てる AI ハーネス設計・取得 2026-08）、実務感覚としてもこれが本丸です。

やることは 3 ステップだけです。

1. 記録 — エージェントの失敗・手戻り・ヒヤリとした操作を、その場で 1 行でもいいのでログに残す
2. 変換 — 週次で 15 分、ログを見返して「どの部品の恒久修正に変換するか」を決める
3. 削除 — 修正が済んだログは消すか、済スタンプを押す（ログは積み上げる場所ではなく処理待ち行列）

# Lessons Learned（処理待ち行列 — 週次で恒久修正に変換して消す）

## 2026-08-13: マイグレーションファイルを直接編集した
- 起きたこと: 既存マイグレーションを書き換え、レビューで発覚
- なぜ困るか: 適用済み環境と定義がズレる
- 変換先の候補: CLAUDE.md に理由つき禁止 → 再発したら hooks で物理ブロック
- 状態: [ ] 未変換 / [x] 変換済（2026-08-15 CLAUDE.md へ）

## 2026-08-12: テスト全件実行で 20 分待った
- 起きたこと: 1 ファイルの修正確認に全テストを回した
- 変換先の候補: CLAUDE.md に「変更ファイルに対応するテストのみ実行」の指針
- 状態: [ ] 未変換

変換先の判断基準はシンプルです。

CLAUDE.md（プロジェクト直下に置く指示ファイル）は常時コンテキストに載るため、1 行ごとに家賃がかかると考えてください。書いていいのは「その現場でしか分からないこと」だけです。

書く: プロジェクト固有の前提（このリポジトリのビルド・テストの回し方）、守るべき制約とその理由（なぜ直接編集禁止か）、してはいけないことのうち文章で足りるもの。

書かない: 一般的なプログラミング知識、モデルが既にできること（「丁寧にコードを書いて」）、長い手順書（→ スキルへ）、二度と起きない一回性の失敗の記録（→ ログで処理して捨てる）。

# <プロジェクト名> — エージェント運用ルール

## このリポジトリの前提
- ビルド: `npm run build` / テスト: `npm run test -- <path>`（全件実行はしない）
- デプロイは CI 経由のみ。ローカルからのデプロイコマンド実行は禁止

## 守るべき制約（理由つき）
- マイグレーションファイルは編集せず新規追加する
  （適用済み環境と定義がズレるため。過去に手戻りが発生）
- 環境変数の実値をコード・ログ・コミットに含めない

## 完了の定義
- 変更に対応するテストが通っていること
- lint が通っていること
- 「できました」ではなく、テスト・lint の実行結果を添えて報告すること

最後の「完了の定義」がいちばん効きます。ハーネス解説記事のチェックリストで見たとおり、申告ベースの完了判定をやめて検証結果ベースに変えることが、体感品質を最も大きく変える一手だからです。

CLAUDE.md のルールは高確率で従われますが、保証はありません。破られたら困る操作は、hooks で物理的に止めます。

Claude Code の hooks は、セッション開始・プロンプト送信・ツール実行前後といったライフサイクルの各時点で自作の処理を差し込める拡張点です。ツール実行前に発火する PreToolUse は実行のブロックが可能で、フックが終了コード 2 を返すとその操作は実行されません。設定は .claude/settings.json（プロジェクト共有）などに書きます。 ※ 出典: Claude Code Docs — Hooks reference（取得 2026-08）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/guard.sh — stdin の JSON からコマンドを取り出して検査。
# 終了コード 2 で当該ツール実行をブロックする（公式仕様）。
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

if echo "$cmd" | grep -qE 'drop table|rm -rf /|--force'; then
  echo "ブロック: 破壊的コマンドは手動実行のみ許可しています" >&2
  exit 2
fi
exit 0

hooks の使いどころは 3 つに絞るのがコツです。①破壊的操作のブロック（上の例）、②整形・検査の自動実行（編集後に lint を走らせる）、③記録（何が実行されたかのログ取り）。条件分岐だらけの複雑な hooks はそれ自体がバグの温床になるので、複雑になりそうなら permissions の deny（次の型）で表現できないかを先に考えてください。

hooks がスクリプトによる関所だとすると、permissions は宣言だけで書ける関所です。allow に入れた操作は確認なしで通り、deny に入れた操作は禁止されます。deny は allow より優先され、設定はユーザー共通（~/.claude/settings.json）・プロジェクト共有（.claude/settings.json）・個人ローカル（.claude/settings.local.json）の各スコープでマージされます。 ※ 出典: Claude Code Docs — Settings（取得 2026-08）

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ]
  }
}

設計の考え方は「確認疲れを起こさない範囲で、確認を残す」です。全部に確認を求めると人間が読まずに許可を連打し始め、関所の意味がなくなります。読み取り系・検査系は allow で自動化し、機密・破壊・外部送信だけを deny と確認に残す配分が実務的です。

CLAUDE.md が肥大化する典型原因は、事実ではなく手順書が書き込まれていくことです。「リリース手順」「障害調査の型」のような複数ステップの手順は、スキル（.claude/skills/<name>/SKILL.md）に切り出します。スキルの本文は使われるときだけ読み込まれるため、常時コンテキストを圧迫しません。同じ指示を何度もチャットに貼っていたら、それがスキル化のサインです。 ※ 出典: Claude Code Docs — Extend Claude with skills（取得 2026-08）

# .claude/skills/release/SKILL.md（骨格）
---
name: release
description: リリース作業の手順。バージョン更新・タグ・リリースノート作成時に使用
---
1. CHANGELOG を更新（未リリース分を今回バージョンへ）
2. `npm version <type>` でバージョン更新
3. タグを push し、CI のリリースジョブ完了を確認
4. リリースノートの下書きを作成して人間のレビューに回す

最後の「削る」は独立した仕事です。Anthropic はハーネス設計の解説で、モデルの性能向上に応じて不要なコンポーネントを段階的に削除し、最小構成を保つことを推奨しています。前のモデルのために書いた細かすぎる手順は、新しいモデルではむしろ品質を下げる — 足すだけのハーネスは、いずれ檻になります。 ※ 出典: Anthropic — Harness design for long-running application development（取得 2026-08）

この記事の 5 つの型がどこまで整っているかは、ハーネス健全度診断（12 問・無料・登録不要）で採点できます。検証・コンテキスト・権限・運用の 4 領域スコアと、最弱領域の処方箋、チーム共有用のまとめが出ます。

コードレビューと同じ扱いにするのが定石です。.claude/settings.json や CLAUDE.md はリポジトリにコミットされる共有資産なので、変更は PR で回し、「なぜこのルールを足すか（どの失敗由来か）」を説明してマージします。個人の好みは settings.local.json に逃がします。

型 1（失敗ログ）と型 2（CLAUDE.md）だけで十分に元が取れます。hooks・permissions は「破られたら困る操作」が出てきてからで構いません。

使えます。ハーネスエンジニアリングは「失敗を環境側の恒久修正に変換する」という設計思想であって、特定ツールの機能名ではありません。拡張点の名前（hooks・rules 等）が違うだけで、同じ型がそのまま通用します。

自社の業務システムやチーム運用に合わせてハーネスを組みたい — ツール接続・権限設計・検証・運用ルールまで含めて設計してほしい — という段階なら、Tufe が 30 分・オンライン・無料の相談で構成案と期間感をその場でお伝えします。契約前提ではありません。

無料相談を予約する

• 2026-08-13: 初版公開

• Claude の「ハーネス」とは何か — 定義・由来・4つの作り方
• ハーネス健全度診断（12問・無料）
• Claude API・MCP 実装ハンドブック
• Claude Code はソフトウェア開発をどう変えるか
• Claude 導入支援ハブ — 10 の導入商品