continuous-learning-v2

継続学習（Continuous Learning）v2.1 - 本能（Instinct）ベースのアーキテクチャ

高度な学習システムです。原子的な「本能（Instincts）」——確信度スコア付きの小さな学習行動——を通じて、Claude Code のセッションを再利用可能な知識に変換します。

v2.1 では プロジェクトスコープの本能（project-scoped instincts） が追加されました。React のパターンは React プロジェクト内に、Python の規約は Python プロジェクト内に保持され、（「常に入力を検証する」のような）汎用的なパターンはグローバルに共有されます。

有効にするタイミング

• Claude Code のセッションから自動的に学習するよう設定するとき
• フック（hooks）を介して、本能ベースの行動を抽出するよう設定するとき
• 学習行動の確信度しきい値を調整するとき
• 本能ライブラリを表示、エクスポート、またはインポートするとき
• 本能を完全なスキル（Skills）、コマンド（Commands）、またはエージェント（Agents）へと発展させるとき
• プロジェクトスコープとグローバルな本能を管理するとき
• 本能をプロジェクトスコープからグローバルスコープへ昇格（Promote）させるとき

v2.1 の新機能

特性	v2.0	v2.1
ストレージ	グローバル (~/.claude/homunculus/)	プロジェクトスコープ (projects//)
スコープ	すべての本能があらゆる場所に適用される	プロジェクトスコープ + グローバル
検出	なし	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 の重み付け
発展	直接スキルへ	本能 -> クラスタリング -> スキル/コマンド/エージェント
共有	なし	本能のエクスポート/インポート

本能モデル（The Instinct Model）

本能とは、小さな学習行動です。

---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# 偏好函数式风格

## 动作（Action）
在适当时使用函数式模式而非类（classes）。

## 证据（Evidence）
- 观察到 5 次偏好函数式模式的实例
- 用户在 2025-01-15 将基于类的方案纠正为函数式

属性：

• 原子的（Atomic） —— 1 つのトリガー、1 つのアクション
• 確信度による重み付け（Confidence-weighted） —— 0.3 = 暫定的、0.9 = ほぼ確実
• ドメインタグ付き（Domain-tagged） —— code-style、testing、git、debugging、workflow など
• 証拠に裏付けられている（Evidence-backed） —— どの観察結果によって作成されたかを追跡
• スコープを認識（Scope-aware） —— project（デフォルト）または global

仕組み

会话活动 (在 git 仓库中)
      |
      | 钩子（Hooks）捕获提示词 + 工具使用 (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/  (全局 GLOBAL)          |
|   * 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            |
+---------------------------------------------+

プロジェクト検出（Project Detection）

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

1. CLAUDE_PROJECT_DIR 環境変数 (最優先)
2. git remote get-url origin —— ハッシュから移植可能なプロジェクト ID を作成します (異なるマシン上でも同じリポジトリには同じ ID が割り当てられます)
3. git rev-parse --show-toplevel —— フォールバックとしてリポジトリパスを使用します (マシン固有)
4. グローバルフォールバック —— プロジェクトが検出されない場合、本能はグローバルスコープに保存されます

各プロジェクトには 12 桁のハッシュ ID が割り当てられます (例：a1b2c3d4e5f6)。~/.claude/homunculus/projects.json にあるレジストリファイルで、ID と人間が読める名前を対応付けます。

クイックスタート

1. 観察フック（Observation Hooks）を有効にする

~/.claude/settings.json に追加します。

プラグインとしてインストールする場合 (推奨)：

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

~/.claude/skills に手動でインストールする場合：

{
  "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 ~/.claude/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 のコード内のデフォルト値で設定します。

ファイル構造

~/.claude/homunculus/
+-- identity.json           # 你的个人资料，技术水平
+-- projects.json           # 注册表：项目哈希 -> 名称/路径/远程地址
+-- observations.jsonl      # 全局观察结果 (回退方案)
+-- instincts/
|   +-- personal/           # 全局自动学习的本能
|   +-- inherited/          # 全局导入的本能
+-- evolved/
|   +-- agents/             # 全局生成的智能体
|   +-- skills/             # 全局生成的技能
|   +-- commands/           # 全局生成的命令
+-- projects/
    +-- a1b2c3d4e5f6/       # 项目哈希 (来自 git remote URL)
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # 项目特定的自动学习
    |   |   +-- inherited/  # 项目特定的导入
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # 另一个项目
        +-- ...

スコープの判断ガイド

パターンの種類	スコープ	例
言語/フレームワークの規約	プロジェクト (project)	「React hooks を使用する」、「Django REST のパターンに従う」
ファイル構造の設定	プロジェクト (project)	「テストファイルは __tests__/ に配置する」、「コンポーネントは src/components/ に配置する」
コードスタイル	プロジェクト (project)	「関数型スタイルを使用する」、「データクラス (dataclasses) を優先する」
エラー処理方針	プロジェクト (project)	「エラー処理には Result 型を使用する」
セキュリティ対策	グローバル (global)	「ユーザー入力を検証する」、「SQL をサニタイズする (Sanitize SQL)」
汎用的なベストプラクティス	グローバル (global)	「先にテストを書く」、「常にエラーを処理する」
ツールのワークフロー設定	グローバル (global)	「変更前に Grep する」、「書き込む前に読み取る」
Git の実践	グローバル (global)	「コミットメッセージ規約」、「小さく焦点を絞ったコミット」

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

同じ本能が複数のプロジェクトで高い確信度をもって現れた場合、グローバルスコープへの昇格候補となります。

自動昇格の基準：

• 同じ本能 ID が 2 つ以上のプロジェクトに存在する
• 平均確信度 >= 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	ほぼ確実	中核となる動作

確信度が上がる場合：

• パターンが繰り返し観察されたとき
• 提案された動作をユーザーが修正しなかったとき
• 他のソースの類似した本能が一致したとき

確信度が下がる場合：

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

なぜ観察にスキル（Skills）ではなくフック（Hooks）を使用するのですか？

「v1 は観察にスキルを使用していました。スキルは確率的であり、Claude の判断に基づいて、およそ 50-80% の確率でしかトリガーされません。」

フック（Hooks）は決定論的で、100% トリガー されます。つまり：

• すべてのツール呼び出しが観察されます
• パターンを見逃すことがありません
• 学習が包括的になります

下位互換性

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

• ~/.claude/homunculus/instincts/ にある既存のグローバル本能は、引き続きグローバル本能として機能します
• v1 の既存の ~/.claude/skills/learned/ スキルは、引き続き機能します
• Stop フックは引き続き実行されます (ただし、現在は v2 にもデータを提供します)
• スムーズに移行できます：両方を並行して実行します

隐私

• 观察结果保存在你的机器 本地
• 项目作用域本能按项目隔离
• 只有 本能 (模式) 可以被导出 —— 而不是原始观察结果
• 不会分享实际的代码或对话内容
• 你可以控制哪些内容被导出和提升

相关内容

• Skill Creator - 从仓库历史生成本能
• Homunculus - 启发了 v2 基于本能的架构的社区项目 (原子观察、置信度评分、本能演化流水线)
• 长篇指南 (The Longform Guide) - 持续学习章节

---

基于本能的学习：教会 Claude 你的模式，一次一个项目。