🔴 ハーネス設計法

⚠️ 推奨前提: 先にハーネスエンジニアリングとは？をお読みください。

ハーネスを設計するとは、AIモデルが実際にタスクを完遂できる全体システムを作ることです。このドキュメントでは、ハーネスを構成する5つのレイヤーとそれぞれの設計原則を解説します。

ハーネスの5つのコアレイヤー

┌──────────────────────────────────────────┐
│  Layer 5: 実行ループ (Execution Loop)     │
├──────────────────────────────────────────┤
│  Layer 4: 権限制御 (Permission)           │
├──────────────────────────────────────────┤
│  Layer 3: メモリ (Memory)                 │
├──────────────────────────────────────────┤
│  Layer 2: コンテキスト (Context)          │
├──────────────────────────────────────────┤
│  Layer 1: ツール (Tools)                  │
├──────────────────────────────────────────┤
│          [ AIモデル ]                     │
└──────────────────────────────────────────┘

Layer 1: ツール (Tools)

概念

ツールは、モデルが外部世界と相互作用する唯一の手段です。ツールがなければ、モデルはファイルを読むことも、コードを実行することもできません。

Claude Codeでの実装

Claude Codeには組み込みツールが内蔵されています:

ツール	役割
`Read`	ファイルの読み込み
`Write`	ファイルの作成
`Edit`	ファイルの修正
`Bash`	シェルコマンドの実行
`Grep`	コンテンツ検索
`Glob`	ファイルパターン検索
`WebSearch`	Web検索

MCP（Model Context Protocol）を通じて外部ツールを追加することもできます。

コア原則: 「安いツール優先」

ツールにはコストがあります。処理時間、API費用、エラーの可能性、すべてがコストです。

ツールタイプ	相対コスト	用途
`Grep`、`Glob`、`Read`	非常に低い	検索、探索
`Bash`（ローカルスクリプト）	低い	単純な変換・計算
`Edit`、`Write`	普通	ファイル修正
追加LLM呼び出し	高い	複雑な判断・生成
外部API呼び出し	高い + レイテンシ	外部データが必要な場合

✅ 良い例: ファイルから関数リストを抽出するとき
   → Grepで"def "パターンを検索（0.01秒）

❌ 悪い例: ファイルから関数リストを抽出するとき
   → ファイル全体をLLMに渡して関数名の抽出を依頼（2〜5秒 + コスト）

💡 設計のヒント: ツール選択の順序 = Grep/Glob → Read → Bash → Edit → LLM

Layer 2: コンテキスト (Context)

概念

モデルが正確な判断を下すには、正しい背景情報が必要です。コンテキストレイヤーは「モデルに何を伝えるか」を設計します。

Claude Codeでの実装

CLAUDE.md — プロジェクト全体のコンテキスト

markdown

# CLAUDE.md

## プロジェクト概要
このプロジェクトはNext.js 14 + Supabaseで作ったSaaSです。

## コーディングルール
- TypeScript strictモードを使用
- コンポーネントはsrc/components/配下に配置
- APIルートはapp/api/配下に配置

## やってはいけないこと
- console.logをコミットに残さない
- anyタイプの使用禁止

.claude/rules/ — 状況別ルールファイル

.claude/rules/
  docs.md        ← ドキュメント作成ルール
  testing.md     ← テスト作成ルール
  database.md    ← DB関連の注意事項

コンテキスト設計原則

❌ 悪いコンテキスト: 存在しないか、長すぎる
   → モデルがプロジェクトのルールを推測して記述

✅ 良いコンテキスト: 核心のみ、構造的に
   → プロジェクト概要 + ルール + 禁止事項を簡潔に

⚠️ 注意: コンテキストはすべてのリクエストに含まれます。長すぎると実際の作業スペースが減ります。

Layer 3: メモリ (Memory)

概念

AIモデルは基本的にセッションが終わるとすべてを忘れます。メモリレイヤーは、セッション間で状態を維持する方法を設計します。

Claude Codeでの実装

短期メモリ — セッション内

markdown

# TODO.md（タスク追跡）
- [x] ログインAPI実装
- [ ] メール認証の追加
- [ ] テストの作成

# 現在の作業コンテキストをファイルで維持

長期メモリ — セッション間

.claude/memory/
  user.md          ← ユーザーの好み・作業スタイル
  project.md       ← 進行中の作業、決定事項
  feedback.md      ← 以前のフィードバック、学習内容
  MEMORY.md        ← メモリファイルインデックス

中期メモリ — 複雑なタスク向け

markdown

# Plans.md（実装計画）
## 目標
認証システムの実装

## 完了
- [x] DBスキーマ設計
- [x] 会員登録API

## 進行中
- [ ] JWTトークン発行

## 次
- [ ] メール認証

セッション間の状態維持設計

作業開始 → Plans.md / TODO.md を確認
    ↓
作業中   → 完了項目をチェック、新しい決定事項を記録
    ↓
作業終了 → 次のセッションのためのコンテキストを保存
    ↓
次のセッション → ファイルを読んで続きから作業

💡 設計のヒント: /compactコマンドで長い会話を圧縮し、要点をPlans.mdに保存してください。

Layer 4: 権限制御 (Permission)

概念

モデルが何をできて何をできないかを明確に定義します。権限制御がなければ、誤って重要なファイルを削除したり、意図しないAPIを呼び出すリスクがあります。

Claude Codeでの実装

settings.json — ツールの許可/ブロック

json

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm test)",
      "Read(**)",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  }
}

Hooks — ツール実行前後の制御

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo '[BASH] 実行: $TOOL_INPUT' >> .claude/audit.log"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{
          "type": "command",
          "command": "npm run lint --fix"
        }]
      }
    ]
  }
}

権限設計原則

最小権限の原則: 必要なものだけを許可
監査ログ: 重要な操作は記録
自動化: 繰り返しの検証はHookで自動化

状況	権限設計
読み取り専用の分析	Bashをブロック、Readのみ許可
安全な開発環境	git push --forceをブロック
自動化パイプライン	特定ディレクトリのみWriteを許可

Layer 5: 実行ループ (Execution Loop)

概念

モデルが一度答えて終わりではなく、タスクが完了するまで繰り返し作業するループを設計します。

Claude Codeでの実装

Claude Codeには「会話 → ツール実行 → 結果反映 → 繰り返し」ループが内蔵されています。

ユーザーのリクエスト
    ↓
分析（Read, Grepでコードベースを探索）
    ↓
計画立案（Plans.mdを記述）
    ↓
実行（Edit, Bashなど）
    ↓
検証（テスト実行、lint確認）
    ↓
完了 or 次のステップ

カスタムコマンドでループを制御

.claude/commands/ディレクトリにカスタムループを定義できます:

markdown

# .claude/commands/review.md
---
description: PRコードレビューループ
---

以下の順序でPRをレビューしてください:
1. 変更されたファイル一覧の確認（git diff --name-only）
2. 各ファイルの変更内容を読む
3. コード品質、セキュリティ、パフォーマンスの観点でフィードバックを記述
4. REVIEW.mdにまとめて保存

実践: 5レイヤー設計例

目標: 「ドキュメント自動更新エージェント」の作成

Layer 1（ツール）
  → Read, Grep（コードの読み込み）
  → Write（ドキュメント生成）
  → Bash("git diff")（変更の検出）

Layer 2（コンテキスト）
  → CLAUDE.md: 「このプロジェクトのドキュメントスタイルとルール」
  → .claude/rules/docs.md: 「ドキュメントフォーマットガイド」

Layer 3（メモリ）
  → TODO.md: 「どのファイルのドキュメントがまだ更新されていないか」
  → last-updated.json: 「各ファイルの最終ドキュメント更新日時」

Layer 4（権限）
  → Edit(docs/**)を許可
  → Bash(git push)をブロック（人間が確認してからプッシュ）
  → PostToolUse Hook: ドキュメント更新後にspellcheckを自動実行

Layer 5（実行ループ）
  → /update-docsカスタムコマンドでループ開始
  → コード変更を検出 → 関連ドキュメントを更新 → レビュー依頼 → 繰り返し

レイヤー別 Claude Code実装まとめ

レイヤー	Claude Code実装
ツール	組み込みツール（Read/Write/Bashなど）+ MCPサーバー
コンテキスト	`CLAUDE.md` + `.claude/rules/*.md`
メモリ	`TODO.md` + `Plans.md` + `.claude/memory/`
権限	`settings.json` + Hooks
実行ループ	組み込み会話ループ + `.claude/commands/*.md`

💡 次のステップ: 自分のワークフローに合ったハーネスを設計してみましょう。最も手軽な出発点は、CLAUDE.mdを丁寧に記述することです。

🔴 ハーネス設計法 ​

ハーネスの5つのコアレイヤー ​

Layer 1: ツール (Tools) ​

概念 ​

Claude Codeでの実装 ​

コア原則: 「安いツール優先」 ​

Layer 2: コンテキスト (Context) ​

概念 ​

Claude Codeでの実装 ​

コンテキスト設計原則 ​

Layer 3: メモリ (Memory) ​

概念 ​

Claude Codeでの実装 ​

セッション間の状態維持設計 ​

Layer 4: 権限制御 (Permission) ​

概念 ​

Claude Codeでの実装 ​

権限設計原則 ​

Layer 5: 実行ループ (Execution Loop) ​

概念 ​

Claude Codeでの実装 ​

実践: 5レイヤー設計例 ​

レイヤー別 Claude Code実装まとめ ​

🔴 ハーネス設計法

ハーネスの5つのコアレイヤー

Layer 1: ツール (Tools)

概念

Claude Codeでの実装

コア原則: 「安いツール優先」

Layer 2: コンテキスト (Context)

概念

Claude Codeでの実装

コンテキスト設計原則

Layer 3: メモリ (Memory)

概念

Claude Codeでの実装

セッション間の状態維持設計

Layer 4: 権限制御 (Permission)

概念

Claude Codeでの実装

権限設計原則

Layer 5: 実行ループ (Execution Loop)

概念

Claude Codeでの実装

実践: 5レイヤー設計例

レイヤー別 Claude Code実装まとめ