Claude CodeフックをnpmパッケージOpenWolfで自動管理：ファイル解析・学習メモリ・トークン追跡の仕組み

この記事ではClaude Codeに特化して解説します。Claude Code全般は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

OpenWolfとは

OpenWolf（cytostack/openwolf）は、Claude Codeのフック機構に統合するnpmパッケージです。6本のNode.jsフックスクリプトをClaude Codeの操作ライフサイクルに挿入し、ファイルインデックス・学習メモリ・バグログ・トークン台帳を.wolf/ディレクトリで一元管理します。

Claude Codeは会話のたびにコンテキストをゼロから構築します。プロジェクト規模が大きくなるにつれて「どのファイルに何があるか」「以前試みた変更」「過去に踏んだバグ」「トークン予算の状況」をClaudeが把握していないまま操作が進み、重複した質問や不必要なファイル読み込みが発生します。

OpenWolfはこれらをClaude Codeフックを通じて自動的に補完します。npmパッケージとして配布されており、グローバルインストールから初期化まで2コマンドで完了します。公式READMEによると、20プロジェクト・132セッション以上の実測値で平均65.8%のトークン削減、大規模プロジェクトでは最大80%削減が報告されています。

Claude Codeフックとは：OpenWolfが使う仕組み

OpenWolfが活用するClaude Codeフックは、Claude Codeが各ツール操作（ファイル読み込み・編集・検索など）を実行する前後に任意のスクリプトを実行できる仕組みです。

フックの種類

Claude Codeが提供するフックには主に次の種類があります。

settings.jsonによるフック登録

フックはプロジェクトの.claude/settings.jsonに登録します。OpenWolfはopenwolf init実行時にこのファイルを自動更新し、6本のフックスクリプトを登録します。手動での設定は不要です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "node .wolf/hooks/pre-read.js"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node .wolf/hooks/post-edit.js"
          }
        ]
      }
    ]
  }
}

ハーネスエンジニアリング入門で解説しているように、Claude Codeのフック設計はエージェントの信頼性を高める主要な手段の一つです。OpenWolfはそのフック機構を活用したツールの典型例です。

.wolf/ディレクトリの7つのコンポーネント

openwolf initを実行すると.wolf/ディレクトリが作成され、7つのファイルとフックスクリプト群が配置されます。

anatomy.md — ファイルマップ

プロジェクト全体のファイル構造を記述したマップです。各ファイルの説明とトークン推定値が記録されます。Claude Codeがファイルにアクセスする前に、このマップを参照して「どのファイルに何があるか」を把握できます。

重複したファイル読み込みを防止するため、OpenWolfの実測では71%の繰り返しファイル読み込みをブロックしたと報告されています。

# Project Anatomy

## src/components/
- Button.tsx [~2.1k tokens] — Primary UI button, variants: primary/secondary/ghost
- Modal.tsx [~3.4k tokens] — Dialog overlay, supports controlled/uncontrolled
- Form.tsx [~5.2k tokens] — Form wrapper with validation hooks

## src/hooks/
- useAuth.ts [~1.8k tokens] — Authentication state management
- useQuery.ts [~2.3k tokens] — Data fetching with cache invalidation

cerebrum.md — 学習メモリ

ユーザーの修正履歴・好み・プロジェクト固有の禁則事項を蓄積します。セッションをまたいでも「この変更は以前失敗した」「このファイルはAではなくBから呼び出す」という知識が保持されます。

公式READMEはDo-Not-Repeatリストについて「Claudeのアップデートで約85〜90%のコンプライアンス率」と報告しています。

# Cerebrum — Learning Memory

## Do Not Repeat
- DO NOT use `useEffect` for data fetching → use React Query instead
- DO NOT modify auth.ts directly → all auth changes go through AuthProvider
- DO NOT import from @/utils/legacy → deprecated, use @/lib/helpers

## Preferences
- Prefer functional components over class components
- Use TypeScript strict mode, never `any`
- CSS: Tailwind utility classes, no inline styles

memory.md — セッションログ

各セッションで実施した操作を時系列で記録します。「前回のセッションで何をしたか」をClaudeが参照できるため、作業の継続性が向上します。

buglog.json — バグ修正履歴

過去に発生したバグとその解決策を記録します。同じバグを再発見するコストを排除します。openwolf bug search <キーワード>でクエリ可能です。

{
  "bugs": [
    {
      "id": "bug_001",
      "description": "Hydration error in SSR when using localStorage directly",
      "solution": "Wrap localStorage access in useEffect or check typeof window",
      "files_affected": ["src/hooks/useLocalStorage.ts"],
      "date": "2026-03-15"
    }
  ]
}

token-ledger.json — トークン台帳

Claude Codeとのすべてのやり取りのトークン使用量を追跡します。読み込み・書き込み・繰り返しアクセスの試行回数が記録されます。

identity.md — エージェントペルソナ

プロジェクト固有のエージェントペルソナを定義します。Claudeがプロジェクトに関する役割・制約・優先事項を把握するための指示書として機能します。

OPENWOLF.md — セッション指示

各セッション開始時にClaudeが参照するセッション指示書です。プロジェクト固有のルール・作業方針・コンテキストが集約されます。

OpenWolfのアーキテクチャ

フックが起動からClaudeの応答・記録までどのように動くかを示します。

フックはClaudeの各アクションの前後で起動し、ファイルマップ・学習メモリをコンテキストに注入しながら、操作結果をメモリとトークン台帳に記録します。このサイクルが繰り返されることで、セッションをまたいだ知識蓄積が実現されます。

6本のフックスクリプト

.wolf/hooks/に配置される6本のフックスクリプトは、Claude Codeの操作ライフサイクルに沿って配置されています。

これらはすべてNode.jsスクリプトとして実装されており、プロジェクトの.wolf/hooks/ディレクトリに格納されます。フックの中身は直接編集してカスタマイズすることもできます。

npmインストールと初期化

Claude Codeフック環境へのOpenWolf導入は2コマンドで完了します。

1. グローバルインストール

npm install -g openwolf

npmパッケージとして配布されているため、Node.js 20以上の環境があれば即座にインストールできます。

2. プロジェクト初期化

cd your-project
openwolf init

openwolf initにより以下が作成されます：

your-project/
├── .wolf/
│   ├── anatomy.md          # ファイルマップ + トークン推定
│   ├── cerebrum.md         # 学習メモリ（Do-Not-Repeat）
│   ├── memory.md           # セッションログ
│   ├── buglog.json         # バグ修正履歴
│   ├── token-ledger.json   # トークン台帳
│   ├── config.json         # 設定ファイル
│   ├── identity.md         # エージェントペルソナ
│   ├── OPENWOLF.md         # セッション指示
│   └── hooks/              # 6本のフックスクリプト
│       ├── pre-read.js
│       ├── post-read.js
│       ├── pre-edit.js
│       ├── post-edit.js
│       ├── pre-session.js
│       └── post-session.js
└── .claude/
    └── settings.json       # フック設定（OpenWolfが自動追加）

3. Claude Codeから自動利用開始

openwolf init完了後、Claude Codeを起動するとフックスクリプトが自動で有効になります。追加設定は不要です。

CLIコマンド一覧

OpenWolfが提供するCLIコマンドはファイルインデックスの管理からリアルタイムダッシュボードまで多岐にわたります。

# ヘルスチェックと統計の表示
openwolf status

# プロジェクト構造をスキャンしてanatomy.mdを更新
openwolf scan

# anatomy.mdの精度を検証（古い場合はexit 1）
openwolf scan --check

# リアルタイムWebダッシュボードにアクセス
openwolf dashboard

# バックグラウンドデーモンの管理
openwolf daemon start
openwolf daemon stop

# スケジュールタスクの管理
openwolf cron list
openwolf cron run <task>
openwolf cron retry <task>

# バグ履歴の検索
openwolf bug search <キーワード>

# デザインQC（Puppeteerスクリーンショット）
openwolf designqc

# 登録プロジェクトの一括更新
openwolf update

# バックアップから復元
openwolf restore
openwolf restore <backup-timestamp>

openwolf statusの出力例

OpenWolf v1.0.4 — Project Status
─────────────────────────────────────────
Project: my-saas-app
Wolf Store: .wolf/ (7 files)

File Intelligence
  anatomy.md         : 847 files indexed
  Last scan          : 2 hours ago
  Stale files        : 12 (run openwolf scan to refresh)

Token Performance
  Sessions tracked   : 23
  Total tokens saved : 1,284,500 (est.)
  Reduction rate     : 71.3%
  Repeated reads blocked: 892

Learning Memory
  Do-Not-Repeat rules: 18
  Compliance rate    : 88%

─────────────────────────────────────────

トークン台帳で消費量を可視化する

openwolf statusを定期的に確認することで、どの操作がトークンを多く消費しているかを把握できます。

Token Ledger — Lifetime
─────────────────────────────────
Sessions tracked    : 42
Total tokens used   : 1,284,500
  Input tokens      : 980,200
  Output tokens     : 304,300

Top token-consuming operations:
  1. file-read (large files) : 412,000 tokens
  2. multi-file-edit         : 285,000 tokens
  3. search-and-replace      : 198,000 tokens
─────────────────────────────────

このデータをもとにコンテキスト注入の戦略を改善するPDCAサイクルを回せます。大きなファイルへの繰り返しアクセスがボトルネックになっている場合、anatomy.mdの要約品質を上げることで効果が得られます。

Design QC：UIレビューの自動化

OpenWolfにはUI変更後のスクリーンショットを自動キャプチャするDesign QC機能が含まれています。

# Puppeteerのインストール（Design QC使用時のみ必要）
npm install puppeteer-core

# デザインQCの実行
openwolf designqc

Puppeteerを使用してフルページのスクリーンショットを取得し、デザイン評価をClaudeが行えるようにします。UIコンポーネントの変更後に目視確認が必要な場合でも、スクリーンショットが自動生成されるため手作業が不要になります。

Reframe：フレームワーク移行支援

OpenWolfには12のUIフレームワークに対応したReframeフィーチャーが組み込まれています。実績のある移行プロンプト（バトルテスト済み）のキュレーションナレッジベースを活用して、フレームワーク間の移行作業を支援します。

対応フレームワークの例：

• React → Next.js
• Vue 2 → Vue 3
• Angular → React
• CSS Modules → Tailwind CSS
• Redux → Zustand / Jotai

移行時に陥りやすいパターンをcebrum.mdのDo-Not-Repeatリストとして事前登録しておくことで、同じ落とし穴に繰り返しはまるリスクを低減できます。

コンテキスト管理の変化

OpenWolf導入前後のコンテキスト管理の違いを比較します。

Claude Code Auto Modeの自律実行と組み合わせることで、長時間の作業セッションでもコンテキストの精度を維持しやすくなります。

他のClaude Code補完ツールとの位置づけ

Claude Codeのコンテキスト管理・フック活用を目的としたツールはいくつか存在します。用途によって使い分けるか組み合わせることが可能です。

Claude Codeベストプラクティスガイドでは、こうした補完ツールも含めたClaude Code全体の活用方針が解説されています。

ユースケース

大規模モノレポのナビゲーション

数百〜数千ファイルが存在するモノレポでは、Claudeが「どのパッケージに何があるか」を把握するだけでも多くのトークンを消費します。anatomy.mdによるファイルマップにより、この探索コストを事前インデックス化に置き換えられます。

openwolf scanでインデックスを更新し、openwolf scan --checkでCIパイプラインに組み込んでインデックスの鮮度を保証する運用が有効です。

# CIでのインデックス鮮度チェック
openwolf scan --check || (echo "anatomy.md is stale, run openwolf scan" && exit 1)

チームでのClaude Code共有

.wolf/ディレクトリをGitリポジトリに含めることで、チームメンバー間でファイルインデックスと学習メモリを共有できます。

cerebrum.mdに「このリポジトリのDo-Not-Repeatルール」を蓄積することで、チーム全体でClaude Codeの精度を高める仕組みを構築できます。

# .gitignoreでtoken-ledgerのみ除外（個人データ）
echo ".wolf/token-ledger.json" >> .gitignore

# その他は共有
git add .wolf/anatomy.md .wolf/cerebrum.md .wolf/memory.md .wolf/buglog.json

バグの再発防止サイクル

バグを修正したらbuglog.jsonに記録し、次回Claudeが同じファイルを編集する際にpre-editフックが過去の修正履歴を自動注入します。

# バグ履歴の検索
openwolf bug search "hydration error"
# → 過去の修正履歴、影響ファイル、解決策を表示

openwolf bug search "csrf"
# → 関連するセキュリティバグとその対処法を表示

フレームワーク移行プロジェクト

Reframe機能を使ってフレームワーク移行時の知識ベースを活用できます。移行プロジェクトでは、cerebrum.mdに移行済みコンポーネント・未移行コンポーネント・移行時の注意点を記録することで、Claude Codeが一貫した移行判断を下せるようになります。

LangflowなどのワークフロービルダーでAIパイプラインを組む場合も、OpenWolfのようなコンテキスト管理の概念は共通しています。大規模なAIプロジェクトではコンテキストの設計がコスト・品質の両面で重要な要素です。

トークン削減の実際

公式READMEが示す数値

削減効果が大きい条件

• ファイル数が多いプロジェクト：anatomy.mdによるインデックス参照の効果が最大化される
• 繰り返し作業が多いプロジェクト：同一ファイルへのアクセスをブロックする効果が大きい
• 長期継続プロジェクト：cerebrum.mdの学習蓄積により時間とともに効果が向上する

削減効果が小さい条件

• モノリシックな構造のシンプルなプロジェクト
• ファイル数が少なく、毎回フルリードしてもトークンコストが低いケース
• 初回導入直後（cerebrum.mdの学習が蓄積されていない段階）

トークン削減の実際の効果はプロジェクト構成に大きく依存します。公式READMEが報告する65.8%という平均値はあくまで参考値であり、自身のプロジェクト環境でopenwolf statusを使って計測することをお勧めします。

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

ハーネスエンジニアリングは、CLAUDE.md・スキル・フック・エージェントでAIエージェントの動作環境を設計する技法です。OpenWolfはこのフック設計を自動化するツールとして位置づけられます。

ハーネスエンジニアリングの観点では、OpenWolfは以下の役割を担います：

• CLAUDE.md相当の機能：OPENWOLF.md・identity.mdがセッション指示を担う
• フック設定の自動化：settings.jsonへのフック登録を手動で行う必要がなくなる
• 知識の永続化：cerebrum.mdとbuglogがセッションをまたいで知識を保持する

FAQ

OpenWolfとRTKは何が違いますか？ OpenWolfはClaude Codeセッション内のコンテキスト管理（ファイルインデックス・学習メモリ・バグログ）を担うツールです。RTKはClaude Codeとの通信時に不要な出力をフィルタリングしてトークンを削減するプロキシです。アプローチが異なるため、同時使用も可能です。

既存のClaude Code統合をOpenWolfに移行できますか？ できます。OpenWolfはフックスクリプトとして機能するため、既存の.claude/settings.jsonに設定が追加されるだけです。既存のCLAUDE.mdや他のフック設定と共存します。

.wolf/ディレクトリはGit管理すべきですか？ 用途に応じて選択してください。チーム共有を目的とする場合はGit管理が有効です。ただしtoken-ledger.jsonは個人のトークン使用量ログのため、.gitignoreで除外するのが一般的です。

openwolf scanはいつ実行すべきですか？ 大量のファイル追加・削除・リネームが発生したタイミングで実行します。CIにopenwolf scan --checkを組み込んで、古いanatomy.mdでClaudeが動作するリスクを防ぐ運用も有効です。

Design QC機能にはPuppeteerが必要ですか？ はい。openwolf designqcを使用するにはpuppeteer-coreのインストールが必要です。Design QCを使用しない場合はインストール不要です。

OpenWolfのデーモン機能とは何ですか？ openwolf daemon startで起動するバックグラウンドプロセスです。PM2との連携でCronベースのタスク（定期スキャン、ダッシュボードサーバー等）を管理します。PM2は必須ではなく任意のインストールです。

Node.js 20未満の環境でも動きますか？ 公式要件はNode.js 20以上です。20未満での動作は保証されていません。

openwolf restoreはどのような場合に使いますか？ .wolf/ディレクトリの状態を以前のバックアップに戻したい場合に使用します。誤った学習メモリが蓄積された場合や、特定の時点の状態に戻したいときに有効です。引数なしで最新バックアップから復元、タイムスタンプ指定で任意の時点に復元できます。

関連記事: Claude Code完全ガイド2026：インストールから本番運用まで

参照ソース

• cytostack/openwolf - GitHub
• Claude Code フック機構 - Anthropic ドキュメント
• Claude Code Auto Mode 解説
• ハーネスエンジニアリング入門