継続的学習 v2.1 - インスティンクトベースアーキテクチャ

継続的学習 v2.1 - インスティンクトベースアーキテクチャ は何をしますか？

Claude Codeセッションを、アトミックな「インスティンクト」（信頼度スコア付きの小さな学習行動）を通じて再利用可能な知識に変える高度な学習システムです。

v2.1 ではプロジェクトスコープのインスティンクトが追加されました。ReactパターンはReactプロジェクトに、Python規約はPythonプロジェクトに留め、普遍的なパターン（「常に入力を検証する」）はグローバルに共有されます。

アクティベートすべきタイミング

• Claude Codeセッションからの自動学習を設定する場合
• フックを介したインスティンクトベースの行動抽出を構成する場合
• 学習行動の信頼度しきい値を調整する場合
• インスティンクトライブラリをレビュー、エクスポート、インポートする場合
• インスティンクトをフルスキル、コマンド、エージェントに進化させる場合
• プロジェクトスコープとグローバルインスティンクトを管理する場合
• インスティンクトをプロジェクトスコープからグローバルスコープに昇格させる場合

v2.1の新機能

機能	v2.0	v2.1
ストレージ	グローバル (~/.claude/homunculus/)	プロジェクトスコープ (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<ハッシュ>/)
スコープ	すべてのインスティンクトがどこにでも適用	プロジェクトスコープ + グローバル
検出	なし	git remote URL / リポジトリパス
昇格	N/A	2つ以上のプロジェクトで確認された場合、プロジェクト→グローバル
コマンド	4 (status/evolve/export/import)	6 (+promote/projects)
プロジェクト間	汚染リスクあり	デフォルトで分離

v2（v1と比較）の新機能

機能	v1	v2
観測	停止フック（セッション終了）	PreToolUse/PostToolUse（100%信頼性）
分析	メインコンテキスト	バックグラウンドエージェント（Haiku）
粒度	フルスキル	アトミックな「インスティンクト」
信頼度	なし	0.3-0.9の重み付け
進化	スキルに直接	インスティンクト -> クラスタ -> スキル/コマンド/エージェント
共有	なし	インスティンクトのエクスポート/インポート

インスティンクトモデル

インスティンクトは小さな学習行動です：

---
id: prefer-functional-style
trigger: "新しい関数を書くとき"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# 関数型スタイルを優先

## アクション

適切な場合、クラスベースのパターンよりも関数型パターンを使用する。

## 証拠
- 関数型パターン優先の5つのインスタンスを観測
- 2025-01-15にユーザーがクラスベースのアプローチを関数型に修正

プロパティ：

• アトミック -- 1つのトリガー、1つのアクション
• 信頼度重み付け -- 0.3 = 暫定的、0.9 = ほぼ確実
• ドメインタグ付き -- code-style、testing、git、debugging、workflowなど
• 証拠ベース -- どの観測が作成したかを追跡
• スコープ認識 -- project（デフォルト）または global

動作の仕組み

セッションアクティビティ（gitリポジトリ内）
      |
      | フックがプロンプト + ツール使用をキャプチャ（100%信頼性）
      | + プロジェクトコンテキストを検出（git remote / リポジトリパス）
      v
+---------------------------------------------+
|  projects/<プロジェクトハッシュ>/observations.jsonl  |
|   （プロンプト、ツール呼び出し、結果、プロジェクト）  |
+---------------------------------------------+
      |
      | Observerエージェントが読み取り（バックグラウンド、Haiku）
      v
+---------------------------------------------+
|          パターン検出                        |
|   * ユーザーの修正 -> インスティンクト        |
|   * エラー解決 -> インスティンクト            |
|   * 繰り返しワークフロー -> インスティンクト   |
|   * スコープ判断: プロジェクトまたはグローバル？ |
+---------------------------------------------+
      |
      | 作成/更新
      v
+---------------------------------------------+
|  projects/<プロジェクトハッシュ>/instincts/personal/ |
|   * prefer-functional.yaml (0.7) [project]   |
|   * use-react-hooks.yaml (0.9) [project]     |
+---------------------------------------------+
|  instincts/personal/  (グローバル)            |
|   * always-validate-input.yaml (0.85) [global]|
|   * grep-before-edit.yaml (0.6) [global]     |
+---------------------------------------------+
      |
      | /evolve クラスタリング + /promote
      v
+---------------------------------------------+
|  projects/<ハッシュ>/evolved/ (プロジェクトスコープ) |
|  evolved/ (グローバル)                        |
|   * commands/new-feature.md                  |
|   * skills/testing-workflow.md               |
|   * agents/refactor-specialist.md            |
+---------------------------------------------+

プロジェクト検出

システムは現在のプロジェクトを自動的に検出します：

1. CLAUDE_PROJECT_DIR 環境変数（最優先） -- ディレクトリがgitリポジトリでない場合でも明示的なオーバーライドとして尊重されます（絶対パスでハッシュ化）
2. git remote get-url origin -- ハッシュ化してポータブルなプロジェクトIDを作成（同じリポジトリは異なるマシンでも同じIDになります）
3. git rev-parse --show-toplevel -- フォールバックとしてリポジトリパスを使用（マシン固有）
4. グローバルフォールバック -- プロジェクトが検出されない場合、インスティンクトはグローバルスコープに送られます

各プロジェクトは12文字のハッシュID（例：a1b2c3d4e5f6）を取得します。${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json のレジストリファイルがIDを人間が読める名前にマッピングします。

データディレクトリ

Continuous-learning-v2は、Claude Codeの機密パスガードがバックグラウンドのインスティンクト書き込みをブロックしないように、~/.claude の外部にObserverデータを保存します：

1. CLV2_HOMUNCULUS_DIR が絶対パスに設定されている場合
2. $XDG_DATA_HOME/ecc-homunculus
3. $HOME/.local/share/ecc-homunculus

~/.claude/homunculus にデータを持つ既存ユーザーは、一度だけ移行できます：

bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh

クイックスタート

1. 観測フックを有効にする

プラグインとしてインストールされた場合（推奨）：

余分な settings.json フックブロックは不要です。Claude Code v2.1+ はプラグイン hooks/hooks.json を自動的にロードし、observe.sh は既にそこに登録されています。

以前に observe.sh を ~/.claude/settings.json にコピーした場合は、その重複した PreToolUse / PostToolUse ブロックを削除してください。プラグインフックが重複すると二重実行が発生し、${CLAUDE_PLUGIN_ROOT} 変数はプラグイン管理下の hooks/hooks.json エントリ内でのみ利用可能なため、解決エラーが発生します。

手動で ~/.claude/skills にインストールした場合、~/.claude/settings.json に以下を追加します：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }]
  }
}

2. ディレクトリ構造を初期化する

システムは初回使用時に自動的にディレクトリを作成しますが、手動で作成することもできます：

# グローバルディレクトリ
mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/ecc-homunculus"/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}

# プロジェクトディレクトリは、フックがgitリポジトリ内で初めて実行されると自動的に作成されます

3. インスティンクトコマンドを使用する

/instinct-status     # 学習したインスティンクトを表示（プロジェクト + グローバル）
/evolve              # 関連するインスティンクトをスキル/コマンドにクラスタリング
/instinct-export     # インスティンクトをファイルにエクスポート
/instinct-import     # 他の人からインスティンクトをインポート
/promote             # プロジェクトインスティンクトをグローバルスコープに昇格
/projects            # すべての既知のプロジェクトとそのインスティンクト数を一覧表示

コマンド

コマンド	説明
/instinct-status	すべてのインスティンクト（プロジェクトスコープ + グローバル）を信頼度とともに表示
/evolve	関連するインスティンクトをスキル/コマンドにクラスタリングし、昇格候補を提案
/instinct-export	インスティンクトをエクスポート（スコープ/ドメインでフィルタリング可能）
/instinct-import <ファイル>	インスティンクトをスコープ制御付きでインポート
/promote [ID]	プロジェクトインスティンクトをグローバルスコープに昇格
/projects	すべての既知のプロジェクトとそのインスティンクト数を一覧表示

設定

config.json を編集してバックグラウンドObserverを制御します：

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}

キー	デフォルト	説明
observer.enabled	false	バックグラウンドObserverエージェントを有効にする
observer.run_interval_minutes	5	Observerが観測を分析する頻度
observer.min_observations_to_analyze	20	分析を実行する前に最低限必要な観測数

その他の動作（観測キャプチャ、インスティンクトしきい値、プロジェクトスコープ設定、昇格基準）は、instinct-cli.py および observe.sh のコードデフォルトで設定されています。

Observerプラットフォームサポート

バックグラウンドObserverにはWSL2、Linux、またはmacOSが必要です。ネイティブWindows（Git Bash / MSYS2）では起動して成功を報告しますが、プロセスはスポーンフックが終了しジョブオブジェクトが閉じられると強制終了されるため、分析は実行されません。そのため、observer.enabled: true の設定は事実上何も行いません（issue #2489を参照）。

observe.sh は次のフック呼び出しでこれを検出し、Observerが連続して数回生存に失敗した後、observer-start.log に説明の警告を書き込みます。

| 環境変数 | デフォルト | 説明 | |---------|-------------| | ECC_OBSERVER_NOSURVIVE_WARN_AFTER | 3 | 警告がログに記録されるまでの連続非生存回数 |

ファイル構造

${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/
+-- identity.json           # プロフィール、技術レベル
+-- projects.json           # レジストリ: プロジェクトハッシュ -> 名前/パス/リモート
+-- observations.jsonl      # グローバル観測（フォールバック）
+-- instincts/
|   +-- personal/           # グローバル自動学習インスティンクト
|   +-- inherited/          # グローバルインポートインスティンクト
+-- evolved/
|   +-- agents/             # グローバル生成エージェント
|   +-- skills/             # グローバル生成スキル
|   +-- commands/           # グローバル生成コマンド
+-- projects/
    +-- a1b2c3d4e5f6/       # プロジェクトハッシュ（git remote URLから）
    |   +-- project.json    # プロジェクトごとのメタデータミラー（id/name/root/remote）
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # プロジェクト固有の自動学習
    |   |   +-- inherited/  # プロジェクト固有のインポート
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # 別のプロジェクト
        +-- ...

スコープ判断ガイド

パターンタイプ	スコープ	例
言語/フレームワークの規約	プロジェクト	「Reactフックを使用する」、「Django RESTパターンに従う」
ファイル構造の設定	プロジェクト	「__tests__/にテスト」、「コンポーネントはsrc/components/に」
コードスタイル	プロジェクト	「関数型スタイルを使用する」、「dataclassesを優先する」
エラーハンドリング戦略	プロジェクト	「エラーにResult型を使用する」
セキュリティプラクティス	グローバル	「ユーザー入力を検証する」、「SQLをサニタイズする」
一般的なベストプラクティス	グローバル	「最初にテストを書く」、「常にエラーを処理する」
ツールワークフローの設定	グローバル	「編集前にGrep」、「書き込み前に読み取り」
Gitプラクティス	グローバル	「Conventional Commits」、「小規模で焦点を絞ったコミット」

インスティンクトの昇格（プロジェクト -> グローバル）

同じインスティンクトが高い信頼度で複数のプロジェクトに現れる場合、グローバルスコープへの昇格候補となります。

自動昇格基準：

• 2つ以上のプロジェクトで同じインスティンクトID
• 平均信頼度 >= 0.8

昇格方法：

# 特定のインスティンクトを昇格
python3 instinct-cli.py promote prefer-explicit-errors

# 条件を満たすすべてのインスティンクトを自動昇格
python3 instinct-cli.py promote

# 変更せずにプレビュー
python3 instinct-cli.py promote --dry-run

/evolve コマンドも昇格候補を提案します。

信頼度スコアリング

信頼度は時間とともに変化します：

スコア	意味	動作
0.3	暫定的	提案されるが強制されない
0.5	中程度	関連する場合に適用される
0.7	強い	適用が自動承認される
0.9	ほぼ確実	中核的な動作

信頼度が上がる場合：

• パターンが繰り返し観測される
• ユーザーが提案された動作を修正しない
• 他のソースからの類似インスティンクトが一致する

信頼度が下がる場合：

• ユーザーが明示的に動作を修正する
• パターンが長期間観測されない
• 矛盾する証拠が現れる

なぜスキルではなくフックで観測するのか？

「v1は観測にスキルに依存していました。スキルは確率的です -- Claudeの判断に基づいて約50-80%の確率で発動します。」

フックは100%の確率で、決定論的に発動します。つまり：

• すべてのツール呼び出しが観測される
• パターンが見逃されることはない
• 学習は包括的である

後方互換性

v2.1はv2.0およびv1と完全に互換性があります：

• 既存のグローバルインスティンクトは scripts/migrate-homunculus.sh を使用して ~/.claude/homunculus/instincts/ から移行可能です
• v1の既存の ~/.claude/skills/learned/ スキルは引き続き動作します
• 停止フックは引き続き実行されます（ただし現在はv2にもフィードされます）
• 段階的移行：並行して両方を実行できます

プライバシー

• 観測はマシン上のローカルに留まります
• プロジェクトスコープのインスティンクトはプロジェクトごとに分離されています
• エクスポートできるのはインスティンクト（パターン）のみ -- 生の観測はエクスポートされません
• 実際のコードや会話の内容は共有されません
• エクスポートおよび昇格するものをユーザーが制御します

関連情報

• ECC-Tools GitHub App - リポジトリ履歴からインスティンクトを生成
• Homunculus - v2のインスティンクトベースアーキテクチャ（アトミック観測、信頼度スコアリング、インスティンクト進化パイプライン）に影響を与えたコミュニティプロジェクト
• The Longform Guide - 継続的学習セクション

---

インスティンクトベースの学習: あなたのパターンをClaudeに教え、プロジェクトごとに。