Continuous Learning v2.1 - 本能ベースアーキテクチャは何をしますか？

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

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

有効化するタイミング

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

v2.1の新機能

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

v2の新機能 (v1との比較)

機能	v1	v2
観測	Stopフック（セッション終了）	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/<project-hash>/observations.jsonl  |
|   (プロンプト、ツール呼び出し、結果、プロジェクト) |
+---------------------------------------------+
      |
      | オブザーバーエージェントが読み取り（バックグラウンド、Haiku）
      v
+---------------------------------------------+
|          パターン検出                       |
|   * ユーザーの修正 → 本能                  |
|   * エラー解決 → 本能                    |
|   * 繰り返しワークフロー → 本能          |
|   * スコープ判断: プロジェクトかグローバルか? |
+---------------------------------------------+
      |
      | 作成/更新
      v
+---------------------------------------------+
|  projects/<project-hash>/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/<hash>/evolved/ (プロジェクトスコープ)|
|  evolved/ (グローバル)                       |
|   * commands/new-feature.md                  |
|   * skills/testing-workflow.md               |
|   * agents/refactor-specialist.md            |
+---------------------------------------------+

プロジェクト検出

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

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

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

データディレクトリ

Continuous-learning-v2 は ~/.claude の外にオブザーバーデータを保存するため、Claude Codeの機密パスガードがバックグラウンドの本能書き込みをブロックしません:

CLV2_HOMUNCULUS_DIR が絶対パスに設定されている場合
$XDG_DATA_HOME/ecc-homunculus
$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 <file>`	スコープ制御付きで本能をインポート
`/promote [id]`	プロジェクト本能をグローバルスコープに昇格
`/projects`	既知のすべてのプロジェクトとその本能数を一覧表示

設定

config.json を編集してバックグラウンドオブザーバーを制御します:

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

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

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

オブザーバープラットフォームサポート

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

observe.sh は次のフック呼び出しでこれを検出し、オブザーバーが数回連続して存続に失敗した後、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/       # 別のプロジェクト
        +-- ...

スコープ判断ガイド

パターンタイプ	スコープ	例
言語/フレームワークの規則	project	"Reactフックを使用する"、"Django RESTパターンに従う"
ファイル構造の好み	project	"`__tests__`/ にテストを配置"、"コンポーネントを src/components/ に"
コードスタイル	project	"関数型スタイルを使用"、"dataclassを優先"
エラーハンドリング戦略	project	"エラーにResult型を使用"
セキュリティプラクティス	global	"ユーザー入力を検証"、"SQLをサニタイズ"
一般的なベストプラクティス	global	"最初にテストを書く"、"常にエラーを処理する"
ツールワークフローの好み	global	"編集前にGrep"、"書き込み前に読み取り"
Gitプラクティス	global	"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/ スキルは引き続き動作します
Stopフックは引き続き実行されます（ただし、現在はv2にもフィードされます）
段階的な移行: 両方を並行して実行

プライバシー

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

お気に入りのAIに質問する

ドキュメント

Continuous Learning v2.1 - 本能ベースアーキテクチャ は何をしますか？

有効化するタイミング

v2.1の新機能

v2の新機能 (v1との比較)

本能モデル

仕組み

プロジェクト検出

データディレクトリ

クイックスタート

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

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

3. 本能コマンドを使用する

コマンド

設定

オブザーバープラットフォームサポート

ファイル構造

スコープ判断ガイド

本能の昇格（プロジェクト -> グローバル）

信頼度スコアリング

観測にスキルではなくフックを使用する理由

後方互換性

プライバシー

関連情報

Individual skills in this repo

accessibility

affaan-m/content-engine

affaan-m/ECC

affaan-m/fal-ai-media

affaan-m/manim-video

affaan-m/remotion-video-creation

affaan-m/video-editing

agent-architecture-audit

agent-eval

agent-harness-construction

agentic-engineering

agentic-os

agent-introspection-debugging

agent-payment-x402

agent-self-evaluation

agent-sort

ai-first-engineering

ai-regression-testing

android-clean-architecture

angular-developer

関連スキル

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

Continuous Learning v2.1 - 本能ベースアーキテクチャは何をしますか？