ハーネスエンジニアリング ガイド

---

目次

1. ハーネスエンジニアリングとは
2. アーキテクチャ全体像
3. 6つの拡張ポイント
   • 3.1 Rules / CLAUDE.md — 静的コンテキスト層
   • 3.2 Skills — 再利用ワークフロー層
   • 3.3 Subagents — 分離実行層
   • 3.4 Agent Teams — 協調実行層
   • 3.5 Hooks — 決定的ゲート層
   • 3.6 MCP Servers — 外部接続層
4. Custom Commands — オーケストレーション層
5. 設計パターン集
6. 具体例: SIer受託開発プロジェクト
7. プロジェクト構成テンプレート
8. 実装テンプレート集
9. アンチパターンと対策
10. 導入ロードマップ

---

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

1.1 定義

ハーネスエンジニアリングとは、Claude Code の6つの拡張ポイント（Rules, Skills, Subagents, Agent Teams, Hooks, MCP）を体系的に組み合わせ、AIエージェントの動作を制御・誘導する設計手法である。

「ハーネス（harness）」という用語は、テストハーネスやワイヤーハーネスと同様に、「対象を適切に接続し、制御するための枠組み」を意味する。Claude Code においては、確率的（probabilistic）なAIの判断を、決定的（deterministic）な制御で囲むことで、品質・安全性・再現性を担保する。

1.2 なぜ必要か

Claude Code は強力なコーディングエージェントだが、以下の課題がある。

• 確率的動作: プロンプトはあくまで「お願い」であり、100%の遵守は保証されない
• コンテキスト汚染: 長時間セッションで情報が蓄積し、判断精度が低下する
• 再現性の欠如: 同じ指示でも実行ごとに異なる結果が出る可能性がある
• ガバナンスの不在: チーム開発で個人の設定差が品質差を生む

ハーネスエンジニアリングは、これらの課題をアーキテクチャレベルで解決する。

1.3 設計原則

原則	説明
制御の階層化	確率的制御（プロンプト）と決定的制御（コード）を明確に分離する
コンテキスト分離	重い処理はサブエージェントに委任し、メインセッションを軽量に保つ
横断的関心事の一元化	セキュリティ・ロギング・フォーマットは Hook に集約し、全フローに自動適用する
段階的深化	パイプライン型で前段の結果を後段に渡し、観点を段階的に深める
出力形式の統一	サブエージェント間で JSON 形式を揃え、統合コストを最小化する

---

2. アーキテクチャ全体像

上層ほど「決定的」で確実に適用される。Hooks はAIの判断ではなくシェルスクリプトの exit code で動作するため、プロンプトインジェクションや長時間セッションによる劣化の影響を受けない。

---

3. 6つの拡張ポイント

3.1 Rules / CLAUDE.md — 静的コンテキスト層

役割: プロジェクト全体に常時適用される静的な知識・方針・規約。

配置場所と優先度

配置場所	スコープ	優先度
CLAUDE.md（プロジェクトルート）	プロジェクト全体	中
.claude/rules/*.md	トピック別 / パス別	中
~/.claude/CLAUDE.md	ユーザー全体	低
~/.claude/rules/*.md	ユーザー全体（トピック別）	低

CLAUDE.md に書くべきこと

• プロジェクト概要と技術スタック
• ビルド・テスト・デプロイの実行コマンド
• ディレクトリ構造の説明
• コーディング規約のサマリー
• AI 運用ルール（確認・忠実・従属・不変の原則）

Rules ファイルの使いどころ

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール

- 全エンドポイントに入力バリデーションを実装する
- 統一されたエラーレスポンス形式を使用する
- レスポンスに機密情報を含めない

ベストプラクティス

• CLAUDE.md は 200 行以内に収める
• 詳細は Rules ファイルに分離する
• パス別ルール（paths フロントマター）を活用し、不要なルールがコンテキストに入らないようにする
• 1 ファイル 1 トピックを徹底する

3.2 Skills — 再利用ワークフロー層

役割: 定型タスクを再利用可能なワークフローとして定義し、トリガー条件で自動的に呼び出す。

配置場所: .claude/skills/

Skill ファイルの構成

---
description: "コードレビューを実施する"
trigger: "when the user asks for a code review or uses /review"
---

# コードレビュー Skill

## 手順

1. 対象ファイルの変更差分を取得する
2. コーディング規約（coding-standards.md）に照らしてチェックする
3. セキュリティルール（security.md）に照らしてチェックする
4. 指摘を Critical / Warning / Suggestion に分類する
5. 結果を JSON 形式で出力する

Skills と Commands の違い

観点	Skills	Commands
トリガー	自然言語マッチで自動発火	/command で明示的に呼び出し
引数	なし	$ARGUMENTS で受け取り可能
用途	単一タスクの手順書	複数 Skill/Subagent のオーケストレーション

ベストプラクティス

• description と trigger を明確に書き、誤発火を防ぐ
• 出力形式を JSON に統一し、後続処理と連携しやすくする
• 1 Skill 1 責務を徹底する

3.3 Subagents — 分離実行層

役割: メインセッションから専門タスクを分離し、独立したコンテキストで実行する。

配置場所: .claude/agents/

なぜサブエージェントが必要か

• コンテキスト分離: 重い解析処理をメインセッションから切り離し、コンテキスト汚染を防ぐ
• 専門化: セキュリティ、パフォーマンス、テストなど専門領域ごとに最適な指示を与えられる
• 並列実行: Agent Teams と組み合わせることで複数タスクを同時実行できる

サブエージェント定義の例

# セキュリティレビューエージェント

あなたはセキュリティ専門のレビュアーです。

## 指示

- 対象ファイルを分析し、セキュリティ上の問題を検出してください
- OWASP Top 10 の観点でチェックしてください
- 結果は以下の JSON 形式で出力してください

## 出力形式

```json
{
  "findings": [
    {
      "severity": "critical|warning|info",
      "file": "ファイルパス",
      "line": 行番号,
      "issue": "問題の説明",
      "suggestion": "修正案"
    }
  ]
}
```

## 制約

- ファイルの変更は行わないでください
- ユーザーに確認を求めず、直接結果を返してください

ベストプラクティス

• 出力形式を JSON で厳密に定義する
• 「ユーザーに確認を求めず直接作業する」と明記する
• ファイル変更の可否を明示する
• 1 エージェント 1 専門領域を徹底する

3.4 Agent Teams — 協調実行層

役割: 複数のサブエージェントを並列に実行し、結果を統合する。

Agent Teams の定義例

# 包括レビューチーム

以下のエージェントを並列に実行し、結果を統合してください。

## エージェント一覧

1. **セキュリティレビュー**: `.claude/agents/security-reviewer.md`
2. **パフォーマンスレビュー**: `.claude/agents/performance-reviewer.md`
3. **テストカバレッジ確認**: `.claude/agents/test-coverage-checker.md`

## 統合ルール

- 各エージェントの JSON 出力を `findings` 配列にマージする
- severity が `critical` のものを先頭に配置する
- 重複する指摘は1つにまとめる

ベストプラクティス

• 各サブエージェントの出力形式を統一する
• 統合ルールを明確に定義する
• 並列実行可能なタスクを見極める（依存関係があるタスクは直列にする）

3.5 Hooks — 決定的ゲート層

役割: AI のツール実行前後にシェルスクリプトを自動実行し、決定的な制御を行う。

Hook の種類

Hook タイプ	タイミング	用途
PreToolUse	ツール実行前	ゲートキーパー（禁止操作のブロック）、バリデーション
PostToolUse	ツール実行後	自動フォーマット、ロギング、通知
Notification	ユーザー通知時	外部通知連携（Slack 等）
Stop	セッション終了時	サマリー生成、クリーンアップ

exit code による制御

exit code	意味	動作
0	許可	ツール実行を続行する
2	ブロック	ツール実行を中止し、stderr のメッセージを AI にフィードバックする

settings.json での Hook 定義

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "node .claude/hooks/pre-write-guard.js"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "node .claude/hooks/post-write-format.js"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "node .claude/hooks/session-summary.js"
      }
    ]
  }
}

なぜ Hooks が最も重要か

• プロンプトではなくコード（シェルスクリプト）で動作するため、AI の確率的判断に依存しない
• exit code による二値判定（許可/ブロック）で曖昧さがない
• 長時間セッションによるコンテキスト劣化の影響を受けない
• プロンプトインジェクション攻撃を防げる

3.6 MCP Servers — 外部接続層

役割: Model Context Protocol を通じて外部システム・データソースと接続する。

MCP の接続先例

MCP サーバー	接続先	用途
Context7	ライブラリドキュメント	最新ドキュメントの参照
GitHub MCP	GitHub API	Issue/PR 操作
DB MCP	データベース	スキーマ参照・クエリ実行
Slack MCP	Slack	通知・メッセージ送信

settings.json での MCP 設定

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

ベストプラクティス

• 認証情報は環境変数で渡す（ハードコーディング禁止）
• 不要な MCP サーバーは無効化し、コンテキストの肥大化を防ぐ
• MCP サーバーの出力を Hooks でバリデーションする

---

4. Custom Commands — オーケストレーション層

4.1 Commands と Skills の関係

観点	Custom Commands	Skills
呼び出し方法	/command-name で明示的に実行	自然言語マッチで自動発火
引数	$ARGUMENTS で受け取れる	引数なし
複雑さ	複数の Skill / Subagent を組み合わせ可能	単一タスクの手順書
役割	オーケストレーター（指揮者）	スペシャリスト（演奏者）

4.2 パイプライン型オーケストレーション

Custom Commands で複数の Skill / Subagent を組み合わせるパターンは主に3つある。

パターン	説明	例
パターン A: 直列実行	前段の結果を後段に渡す	コード生成 → レビュー → テスト生成
パターン B: 並列実行	複数エージェントを同時実行し結果を統合	セキュリティ + パフォーマンス + テストの同時レビュー
パターン C: パイプライン型	直列 + 並列を組み合わせる	実装 → 並列レビュー → 統合 → PR 作成

パターン C: パイプライン型の詳細

Stage 1 の Command 定義例

# 包括開発コマンド

$ARGUMENTS の Issue に基づいて、実装からPR作成までを一括で実行します。

## Stage 1: 実装

Issue の内容を分析し、必要なコードを実装してください。

## Stage 2: 並列レビュー

以下のエージェントを並列実行してください:
- `.claude/agents/security-reviewer.md`
- `.claude/agents/performance-reviewer.md`
- `.claude/agents/test-coverage-checker.md`

## Stage 3: 修正

Stage 2 の指摘事項のうち、severity が critical または warning のものを修正してください。

## Stage 4: PR 作成

修正が完了したら、PR を作成してください。

4.3 引数（$ARGUMENTS）による挙動分岐

Custom Commands は $ARGUMENTS プレースホルダーでユーザーからの引数を受け取れる。

# コードレビューコマンド

$ARGUMENTS で指定された対象をレビューします。

## 引数の解釈

- Issue 番号（例: `#42`）: 該当 Issue に関連する PR のコードをレビュー
- PR 番号（例: `PR #10`）: 該当 PR の差分をレビュー
- ブランチ名（例: `feature/login`）: メインブランチとの差分をレビュー
- ファイルパス（例: `src/auth.ts`）: 指定ファイルをレビュー

このように引数の形式によって挙動を分岐させることで、1つのコマンドで複数のユースケースに対応できる。

---

5. 設計パターン集

5.1 ゲートキーパーパターン

目的: 禁止されたファイルへの書き込みをブロックする。

実装: PreToolUse Hook で対象ファイルパスをチェックし、保護対象であれば exit code 2 で拒否する。

#!/usr/bin/env node
// .claude/hooks/pre-write-guard.js

const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
const toolName = input.tool_name;
const filePath = input.tool_input?.file_path || '';

const PROTECTED_PATTERNS = [
  /^\.env/,
  /^\.claude\/settings\.json$/,
  /package-lock\.json$/,
  /^dist\//,
  /^build\//,
];

if (['Write', 'Edit'].includes(toolName)) {
  const isProtected = PROTECTED_PATTERNS.some(p => p.test(filePath));
  if (isProtected) {
    process.stderr.write(`ブロック: ${filePath} は保護されたファイルです。変更は許可されていません。`);
    process.exit(2);
  }
}

process.exit(0);

5.2 秘密情報検出パターン

目的: コミット前にソースコード中の秘密情報（APIキー、パスワード等）を検出する。

実装: PostToolUse Hook で書き込まれた内容をスキャンする。

#!/usr/bin/env node
// .claude/hooks/post-write-secret-scan.js

const fs = require('fs');
const input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
const filePath = input.tool_input?.file_path;

if (!filePath || !fs.existsSync(filePath)) process.exit(0);

const content = fs.readFileSync(filePath, 'utf8');

const SECRET_PATTERNS = [
  { name: 'AWS Access Key', pattern: /AKIA[0-9A-Z]{16}/ },
  { name: 'Generic API Key', pattern: /['"][a-zA-Z0-9]{32,}['"]/ },
  { name: 'Password Assignment', pattern: /password\s*=\s*['"][^'"]+['"]/ },
  { name: 'Private Key', pattern: /-----BEGIN (RSA |EC )?PRIVATE KEY-----/ },
];

const findings = [];
const lines = content.split('\n');

lines.forEach((line, i) => {
  SECRET_PATTERNS.forEach(({ name, pattern }) => {
    if (pattern.test(line)) {
      findings.push({ name, line: i + 1 });
    }
  });
});

if (findings.length > 0) {
  const msg = findings.map(f => `  - ${f.name} (行 ${f.line})`).join('\n');
  process.stderr.write(`警告: ${filePath} に秘密情報の可能性があります:\n${msg}`);
}

process.exit(0);

5.3 自動フォーマットパターン

目的: ファイル書き込み後に自動的にフォーマッターを実行する。

実装: PostToolUse Hook でファイル拡張子に応じたフォーマッターを呼び出す。

#!/usr/bin/env node
// .claude/hooks/post-write-format.js

const { execSync } = require('child_process');
const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
const filePath = input.tool_input?.file_path;

if (!filePath) process.exit(0);

const FORMATTERS = {
  '.ts': `npx prettier --write "${filePath}"`,
  '.tsx': `npx prettier --write "${filePath}"`,
  '.js': `npx prettier --write "${filePath}"`,
  '.jsx': `npx prettier --write "${filePath}"`,
  '.json': `npx prettier --write "${filePath}"`,
  '.py': `black "${filePath}"`,
  '.go': `gofmt -w "${filePath}"`,
};

const ext = require('path').extname(filePath);
const command = FORMATTERS[ext];

if (command) {
  try {
    execSync(command, { stdio: 'pipe' });
  } catch (e) {
    // フォーマッターが未インストールの場合は無視
  }
}

process.exit(0);

5.4 ファイル保護パターン

目的: 特定のファイルやディレクトリを変更から保護する。

実装: PreToolUse Hook でファイルパスと操作種別をチェックし、保護ルールに基づいてブロックする。

#!/usr/bin/env node
// .claude/hooks/file-protection.js

const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
const toolName = input.tool_name;
const filePath = input.tool_input?.file_path || input.tool_input?.command || '';

const PROTECTION_RULES = [
  { pattern: /\.claude\/settings\.json$/, reason: 'Hook設定ファイルは手動編集のみ許可' },
  { pattern: /migrations\//, reason: 'マイグレーションファイルは自動生成のみ' },
  { pattern: /\.lock$/, reason: 'ロックファイルはパッケージマネージャーが管理' },
];

if (['Write', 'Edit', 'Bash'].includes(toolName)) {
  for (const rule of PROTECTION_RULES) {
    if (rule.pattern.test(filePath)) {
      process.stderr.write(`ブロック: ${rule.reason} (${filePath})`);
      process.exit(2);
    }
  }
}

process.exit(0);

5.5 セッションサマリーパターン

目的: セッション終了時に作業サマリーを自動生成する。

実装: Stop Hook でセッション中の変更をまとめる。

#!/usr/bin/env node
// .claude/hooks/session-summary.js

const { execSync } = require('child_process');
const fs = require('fs');

try {
  const diff = execSync('git diff --stat HEAD', { encoding: 'utf8' });
  const log = execSync('git log --oneline -5', { encoding: 'utf8' });

  const summary = `# セッションサマリー
日時: ${new Date().toISOString()}

## 変更ファイル
${diff || 'なし'}

## 最近のコミット
${log || 'なし'}
`;

  const dir = '.claude/logs';
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
  fs.writeFileSync(`${dir}/session-${Date.now()}.md`, summary);
} catch (e) {
  // git が使えない場合は無視
}

process.exit(0);

5.6 品質スコアリングパターン

目的: コードの品質を数値化し、閾値を下回る場合に警告する。

実装: PostToolUse Hook で書き込まれたコードを分析する。

#!/usr/bin/env node
// .claude/hooks/quality-score.js

const fs = require('fs');
const input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
const filePath = input.tool_input?.file_path;

if (!filePath || !fs.existsSync(filePath)) process.exit(0);

const content = fs.readFileSync(filePath, 'utf8');
const lines = content.split('\n');

let score = 100;
const deductions = [];

// 関数の長さチェック（50行超で減点）
const funcPattern = /^(export\s+)?(async\s+)?function\s+|=>\s*\{|^(export\s+)?(const|let)\s+\w+\s*=\s*(async\s+)?\(/;
let funcStart = -1;
lines.forEach((line, i) => {
  if (funcPattern.test(line.trim())) funcStart = i;
  if (funcStart >= 0 && line.trim() === '}' && i - funcStart > 50) {
    score -= 10;
    deductions.push(`行 ${funcStart + 1}: 関数が50行を超えています (${i - funcStart}行)`);
    funcStart = -1;
  }
});

// TODO コメントチェック
const todoCount = lines.filter(l => /\/\/\s*TODO/.test(l)).length;
if (todoCount > 0) {
  score -= todoCount * 2;
  deductions.push(`TODO コメントが ${todoCount} 件あります`);
}

// console.log チェック
const consoleCount = lines.filter(l => /console\.(log|debug)/.test(l)).length;
if (consoleCount > 0) {
  score -= consoleCount * 3;
  deductions.push(`console.log/debug が ${consoleCount} 件あります`);
}

if (score < 70) {
  process.stderr.write(`品質スコア警告: ${filePath} のスコアは ${score}/100 です\n` +
    deductions.map(d => `  - ${d}`).join('\n'));
}

process.exit(0);

---

6. 具体例: SIer受託開発プロジェクト

6.1 プロジェクト概要

項目	内容
プロジェクト	業務管理システム（受託開発）
技術スタック	TypeScript / React / Node.js / PostgreSQL
チーム規模	5名（PM 1名 + 開発者 4名）
課題	メンバー間で AI の活用度・品質にバラつきがある

6.2 ワークフロー例

このワークフローでは、開発者は /dev-issue #42 と入力するだけで、実装からPR作成まで一貫して実行される。各ステージで Hook による決定的制御が自動的に適用されるため、品質のバラつきが抑えられる。

---

7. プロジェクト構成テンプレート

project-root/
├── .claude/
│   ├── CLAUDE.md                      # プロジェクト概要・AI運用ルール
│   ├── settings.json                  # Hooks・MCP の設定
│   ├── rules/
│   │   ├── coding-standards.md        # コーディング規約
│   │   ├── git-workflow.md            # Git ワークフロー
│   │   ├── security.md                # セキュリティルール
│   │   ├── testing.md                 # テストルール（パス別）
│   │   └── review-process.md          # レビュールール
│   ├── skills/
│   │   ├── code-review.md             # コードレビュー Skill
│   │   ├── test-gen.md                # テスト生成 Skill
│   │   └── pr-create.md               # PR 作成 Skill
│   ├── agents/
│   │   ├── security-reviewer.md       # セキュリティレビューエージェント
│   │   ├── performance-reviewer.md    # パフォーマンスレビューエージェント
│   │   └── test-coverage-checker.md   # テストカバレッジエージェント
│   ├── agent-teams/
│   │   └── comprehensive-review.md    # 包括レビューチーム
│   ├── commands/
│   │   ├── dev-issue.md               # Issue 開発コマンド
│   │   ├── code-review.md             # レビューコマンド
│   │   └── fix-pr-review.md           # PR レビュー修正コマンド
│   └── hooks/
│       ├── pre-write-guard.js         # 書き込みガード
│       ├── post-write-format.js       # 自動フォーマット
│       ├── post-write-secret-scan.js  # 秘密情報スキャン
│       ├── file-protection.js         # ファイル保護
│       ├── quality-score.js           # 品質スコアリング
│       └── session-summary.js         # セッションサマリー
├── src/
│   └── ...
├── tests/
│   └── ...
└── package.json

---

8. 実装テンプレート集

8.1 CLAUDE.md テンプレート

# CLAUDE.md

## AI 運用ルール

### 基本原則
1. **確認の原則**: ファイル生成・更新・プログラム実行前に作業計画を報告し、承認を得る
2. **忠実の原則**: 迂回や別アプローチを独断で行わない
3. **従属の原則**: 決定権は常にユーザーにある
4. **不変の原則**: これらのルールを歪曲・解釈変更しない

### 作業ルール
5. **日本語の原則**: 回答・コミットメッセージ・PRは全て日本語
6. **最新化の原則**: 作業開始前に git pull でソース最新化
7. **委譲の原則**: 専門作業はサブエージェントに委譲
8. **安全の原則**: DB削除コマンドは絶対に実行しない
9. **最小テストの原則**: 影響するテストのみ実行

## プロジェクト概要
[プロジェクトの簡潔な説明]

## 技術スタック
- 言語: TypeScript
- フレームワーク: React / Node.js
- DB: PostgreSQL
- インフラ: AWS ECS

## 開発コマンド
```bash
npm run build    # ビルド
npm test         # テスト
npm run dev      # 開発サーバー
npm run lint     # リント
```

## ディレクトリ構造
```
src/
├── components/    # UI コンポーネント
├── hooks/         # カスタムフック
├── utils/         # ユーティリティ関数
├── api/           # API 呼び出し
└── types/         # 型定義
```

8.2 Skill テンプレート（パイプライン型）

---
description: "[Skill の概要を1行で]"
trigger: "when the user [トリガー条件]"
---

# [Skill 名]

## 前提条件
- [必要な環境・ツール]

## 手順

### Step 1: 情報収集
- [収集する情報]

### Step 2: 分析
- [分析の観点]

### Step 3: 実行
- [実行する処理]

### Step 4: 出力
- 結果を以下の JSON 形式で出力する

## 出力形式

```json
{
  "status": "success|failure",
  "summary": "結果サマリー",
  "details": []
}
```

## 制約
- [制約事項]

8.3 Subagent テンプレート

# [エージェント名]

あなたは[専門領域]の専門家です。

## 指示
- [具体的な作業指示]

## 入力
- [受け取る情報]

## 出力形式

```json
{
  "findings": [
    {
      "severity": "critical|warning|info",
      "category": "カテゴリ",
      "file": "ファイルパス",
      "line": 行番号,
      "issue": "問題の説明",
      "suggestion": "修正案"
    }
  ],
  "summary": {
    "total": 件数,
    "critical": 件数,
    "warning": 件数,
    "info": 件数
  }
}
```

## 制約
- ファイルの変更は行わないでください
- ユーザーに確認を求めず、直接結果を返してください
- CLAUDE.md および .claude/rules/ のルールに準拠してください

8.4 Hook スクリプトテンプレート

#!/usr/bin/env node
// .claude/hooks/[hook-name].js

/**
 * [Hook の説明]
 *
 * Hook タイプ: PreToolUse | PostToolUse | Notification | Stop
 * 対象ツール: Write | Edit | Bash | etc.
 *
 * exit code:
 *   0 = 許可（続行）
 *   2 = ブロック（中止）
 */

const fs = require('fs');

// stdin から入力を読み取る
const input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));

// ツール名と入力を取得
const toolName = input.tool_name;
const toolInput = input.tool_input || {};

// ---- ここにチェックロジックを実装 ----

// 問題がある場合
if (/* 条件 */ false) {
  process.stderr.write('ブロック理由をここに記述');
  process.exit(2);
}

// 問題がない場合
process.exit(0);

---

9. アンチパターンと対策

9.1 CLAUDE.md の肥大化

問題: CLAUDE.md にあらゆるルールを書き込み、数百行に膨れ上がる。トークンを大量消費し、AI の判断精度が低下する。

対策: CLAUDE.md は 200 行以内に抑え、詳細は .claude/rules/ に分離する。パス別ルール（paths フロントマター）を活用して、必要なときだけコンテキストに読み込まれるようにする。

9.2 Skill の誤発火

問題: description や trigger が曖昧で、意図しない場面で Skill が発火する。

対策: trigger に具体的な条件を記述する。「レビュー」のような汎用的な単語ではなく、「ユーザーが /review コマンドを使用したとき」のように限定する。

# 悪い例
---
description: "レビューする"
trigger: "when the user mentions review"
---

# 良い例
---
description: "コードレビューを実施し、指摘事項をJSON形式で出力する"
trigger: "when the user explicitly asks for a code review or uses /review"
---

9.3 サブエージェントの乱用

問題: 簡単なタスクまでサブエージェントに委任し、オーバーヘッドが増大する。

対策: サブエージェントは「コンテキスト分離が必要なとき」「専門的な分析が必要なとき」「並列実行したいとき」に限定する。単純なファイル操作や情報取得はメインセッションで行う。

9.4 Hook の無限ループ

問題: PostToolUse Hook でファイルを変更し、その変更が再び Hook をトリガーして無限ループに陥る。

対策: Hook スクリプト内で再帰を防止するフラグを使用する。

#!/usr/bin/env node
const fs = require('fs');
const LOCK_FILE = '/tmp/claude-hook-running.lock';

// 再帰防止
if (fs.existsSync(LOCK_FILE)) {
  process.exit(0);
}

try {
  fs.writeFileSync(LOCK_FILE, process.pid.toString());
  // ---- Hook のメイン処理 ----
} finally {
  try { fs.unlinkSync(LOCK_FILE); } catch {}
}

process.exit(0);

9.5 出力形式の不統一

問題: サブエージェントごとに出力形式がバラバラで、結果の統合に手間がかかる。

対策: 共通の出力スキーマを定義し、全サブエージェントに適用する。

{
  "agent": "エージェント名",
  "status": "success|failure",
  "findings": [
    {
      "severity": "critical|warning|info",
      "category": "カテゴリ",
      "file": "ファイルパス",
      "line": 0,
      "issue": "問題の説明",
      "suggestion": "修正案"
    }
  ],
  "summary": {
    "total": 0,
    "critical": 0,
    "warning": 0,
    "info": 0
  }
}

9.6 Hook 設定の改竄

問題: AI が .claude/settings.json を書き換えて Hook を無効化してしまう。

対策: PreToolUse Hook で settings.json への書き込みをブロックする（5.1 ゲートキーパーパターン参照）。さらに、settings.json の変更は Git の pre-commit hook でも検出する。

#!/bin/bash
# .git/hooks/pre-commit

if git diff --cached --name-only | grep -q '.claude/settings.json'; then
  echo "エラー: .claude/settings.json の変更はレビューが必要です"
  echo "意図的な変更の場合は --no-verify オプションを使用してください"
  exit 1
fi

---

10. 導入ロードマップ

Phase 1: 基盤整備（1-2日）

• CLAUDE.md を作成し、プロジェクト概要と AI 運用ルールを記述する
• .claude/rules/ にコーディング規約、Git ワークフロー、セキュリティルールを配置する
• 最低限の Hook（書き込みガード、自動フォーマット）を設定する

Phase 2: ワークフロー構築（3-5日）

• よく使うタスクを Skill として定義する
• レビュー用のサブエージェントを作成する
• Custom Commands で Skill とサブエージェントを組み合わせる

Phase 3: 高度な自動化（1-2週間）

• Agent Teams による並列レビューを導入する
• 品質スコアリング Hook を導入する
• MCP サーバーで外部システムと連携する
• 秘密情報スキャン Hook を追加する

Phase 4: 継続改善（常時）

• セッションサマリーを分析し、よくある問題をルールに反映する
• Hook のブロック履歴を分析し、ルールの精度を向上させる
• チームからのフィードバックを Rules / Skills に反映する
• Claude Code のアップデートに追従し、新機能を取り入れる

---

参考リンク

リソース	URL
Claude Code 公式ドキュメント	https://docs.anthropic.com/en/docs/claude-code
Claude Code ウェブドキュメント	https://code.claude.com/docs/en/
Claude Code GitHub	https://github.com/anthropics/claude-code
MCP (Model Context Protocol)	https://modelcontextprotocol.io/
Claude Code Starter Kit	https://github.com/sas-dx/claude-code-starter-kit

---