Claude Code ハーネス作成の重要ポイント — 制御可能なAIエージェントを作る

ハーネスとは何か

Claude Code における ハーネス（harness） とは、AI の振る舞いを制御するためのレイヤーのことです。具体的には以下の要素を組み合わせて構成します。

CLAUDE.md — プロジェクトのルールと文脈
settings.json — グローバル設定と Hooks
Memory — 会話を超えた記憶
MCP サーバー — 外部ツール連携
Plugins / Skills — 拡張機能

これらを適切に設計することで、Claude Code は「ただのチャットボット」から「チームのルールを理解した開発パートナー」に変わります。

なぜハーネスが重要なのか

AI にコードを書かせること自体は簡単です。難しいのは 「プロジェクトの文脈を理解した上で、一貫性のあるコードを書かせること」 です。

ハーネスなしの場合：

毎回同じ説明を繰り返す必要がある
コーディング規約を守らないことがある
テストを書かずにコードだけ生成する
危険な操作（force push、本番DBへの接続）を平気で提案する

ハーネスありの場合：

プロジェクトのルールを常に参照する
過去のフィードバックを記憶して同じミスを繰り返さない
自動的にテストを実行してから提案する
危険な操作の前に確認を入れる

ハーネスの品質 = AI の出力品質 と言っても過言ではありません。

1. CLAUDE.md の設計

基本構造

CLAUDE.md は「プロジェクトの取扱説明書」です。以下の構造が実用的です。

# プロジェクト名

## ビルドとテスト
（ビルド・テスト・デプロイのコマンド）

## フォルダ構成
（ディレクトリの役割）

## コーディング規約
（命名規則、スタイル、パターン）

## やってはいけないこと
（禁止事項を明確に）

## よくある作業フロー
（日常的なタスクの進め方）

良い CLAUDE.md の例

# my-api

## ビルドとテスト

\```bash
npm run build        # TypeScript コンパイル
npm test             # Jest テスト実行
npm run lint         # ESLint チェック
\```

## フォルダ構成

- src/routes/     — Express ルーティング
- src/services/   — ビジネスロジック
- src/models/     — Prisma モデル定義
- src/middleware/  — Express ミドルウェア
- tests/          — テスト（src/ のミラー構成）

## コーディング規約

- 関数は named export を使う（default export 禁止）
- エラーハンドリングは AppError クラスを使う
- DB アクセスは必ず services/ 経由にする
- 型定義は各ファイルの先頭にまとめる

## やってはいけないこと

- main ブランチへの直接コミット
- .env ファイルのコミット
- Prisma の migration を手動実行
- node_modules/ をコミット
- git push --force

アンチパターン

長すぎる CLAUDE.md

❌ 悪い例：
500行の CLAUDE.md にすべての関数のドキュメントを書く
→ トークンを浪費し、重要なルールが埋もれる

CLAUDE.md は ルールと手順だけ を書きます。コードの詳細はコード自体が語るべきです。

曖昧な指示

❌ 悪い例：
- きれいなコードを書いてください
- テストは適宜書いてください

✅ 良い例：
- 関数は 30 行以内に収める
- すべての public 関数に対してユニットテストを書く

「きれい」「適宜」は人によって解釈が異なります。 数字や具体例で示す のがポイントです。

2. Hooks の設計

Hooks で何ができるか

Hooks は Claude Code のライフサイクルイベントに紐づくシェルコマンドです。これにより、AI の動作に「ガードレール」を設けられます。

実用的な Hook パターン

パターン1: ビルドチェック

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "cd /path/to/project && npm run typecheck 2>&1 | tail -5"
          }
        ]
      }
    ]
  }
}

ファイルを編集するたびに TypeScript の型チェックを自動実行。エラーがあれば Claude のコンテキストに入るので、すぐに修正を提案してくれます。

パターン2: 禁止操作の防止

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '$TOOL_INPUT' | grep -qE 'push.*--force|reset.*--hard|rm.*-rf' && echo 'BLOCKED: Dangerous command detected' && exit 1 || exit 0"
          }
        ]
      }
    ]
  }
}

git push --force、git reset --hard、rm -rf などの破壊的コマンドを検出してブロックします。

パターン3: 通知

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"タスク完了\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

長い処理が終わったら macOS 通知で知らせる。

Hook 設計のコツ

matcher は絞る — 空文字（全マッチ）は便利だが、不要な実行が増える
出力は短くする — Hook の stdout は Claude のコンテキストに入るため、tail で絞る
exit code を使い分ける — 0 で通過、非0 でブロック
冪等にする — 何度実行しても同じ結果になるようにする

3. Memory の活用

Memory の種類

Claude Code の Memory は4種類あります。

種類	用途	例
user	ユーザーの属性	「Go 10年、React 初心者」
feedback	フィードバック	「テストは mock 禁止」
project	プロジェクト状況	「3/5 から merge freeze」
reference	外部リソース	「バグは Linear の INGEST で管理」

Memory を効果的に使うコツ

明示的に記憶させる

覚えておいて：このプロジェクトでは ESM ではなく CommonJS を使う。
理由は AWS Lambda のデプロイツールが ESM 未対応だから。

「理由」も一緒に伝えると、edge case での判断が適切になります。

否定形のフィードバックを記憶させる

今後、console.log でデバッグするのではなく、
必ず logger.debug() を使ってください。
本番で console.log が残ったことがあるので。

「やらないでほしいこと」+ 「その理由」のセットで記憶させると効果的です。

記憶の棚卸し

Memory は時間とともに古くなります。定期的に ~/.claude/projects/ 以下のメモリファイルを確認し、もう当てはまらないものは削除しましょう。

4. MCP サーバーとの連携

MCP とは

MCP（Model Context Protocol）は、Claude Code が外部ツールにアクセスするための標準プロトコルです。

実用的な MCP 構成例

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
      }
    }
  }
}

この設定で、Claude Code から直接 GitHub Issues や PR を参照・操作できるようになります。

よく使う MCP サーバー

サーバー	用途
GitHub	Issue/PR の参照・操作
Figma	デザインの読み取り
PostgreSQL	DB スキーマの参照
Filesystem	特定ディレクトリへのアクセス制御

5. 全体設計のベストプラクティス

レイヤー構造で考える

ハーネスは以下のレイヤーで設計すると整理しやすい。

┌─────────────────────────────┐
│  Plugins / Skills           │  ← 機能拡張
├─────────────────────────────┤
│  MCP Servers                │  ← 外部ツール連携
├─────────────────────────────┤
│  Hooks (settings.json)      │  ← 自動化・ガードレール
├─────────────────────────────┤
│  Memory                     │  ← 蓄積される知識
├─────────────────────────────┤
│  CLAUDE.md                  │  ← プロジェクトの基盤ルール
└─────────────────────────────┘

下のレイヤーほど安定的で、上のレイヤーほど動的です。

段階的に導入する

いきなり全部を設定しようとすると挫折します。おすすめの導入順序は以下の通り。

CLAUDE.md を書く（30分）
通知 Hook を設定する（5分）
Memory を有効化して使い始める（1分）
必要に応じて ガードレール Hook を追加
外部連携が必要になったら MCP を導入

チームで共有する

CLAUDE.md はリポジトリにコミットするものなので、チーム全員が同じルールを共有できます。「このプロジェクトでは Claude にこう指示する」という認識を揃えることで、誰が Claude を使っても一貫した品質のコードが出力されます。

まとめ

ハーネスの設計は、AI エージェントを「制御可能」にするための根幹です。

要素	役割	投資時間	効果
CLAUDE.md	ルールの明文化	30分	即効性が高い
Hooks	自動化と安全装置	1時間	事故防止に直結
Memory	知識の蓄積	継続的	使うほど賢くなる
MCP	外部ツール連携	30分〜	ワークフロー拡張

最も重要なのは CLAUDE.md です。ここが粗いと、どれだけ Hooks や Memory を整備しても効果は限定的。まずはプロジェクトの「当たり前」を言語化することから始めましょう。

AI との協業は、指示の質がそのまま成果の質になります。ハーネスは、その指示の質を仕組みで担保するものです。