持續學習 v2.1 - 直覺型架構

持續學習 v2.1 - 直覺型架構 是做什麼的？

一個進階的學習系統，能將你的 Claude Code 工作階段轉化為可重複使用的知識，透過原子化的「直覺」（instincts）——帶有信心指數的小型學習行為來實現。

v2.1 新增了專案範圍直覺——React 模式留在你的 React 專案中，Python 慣例留在你的 Python 專案中，而通用模式（例如「永遠驗證輸入」）則在全域範圍共用。

何時啟用

• 設定從 Claude Code 工作階段自動學習
• 透過 Hook 設定基於直覺的行為提取
• 調整學習行為的信心門檻
• 檢視、匯出或匯入直覺庫
• 將直覺演化為完整的技能、指令或代理
• 管理專案範圍與全域直覺
• 將直覺從專案範圍提升至全域範圍

v2.1 的新功能

功能	v2.0	v2.1
儲存位置	全域 (~/.claude/homunculus/)	專案範圍 (${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<雜湊值>/)
範圍	所有直覺全域適用	專案範圍 + 全域
偵測	無	git 遠端 URL / 儲存庫路徑
提升	不適用	專案 → 全域（在 2 個以上專案中出現時）
指令	4 個（status/evolve/export/import）	6 個（+promote/projects）
跨專案	有污染風險	預設隔離

v2（相較於 v1）的新功能

功能	v1	v2
觀察方式	停止 Hook（工作階段結束）	PreToolUse/PostToolUse（100% 可靠）
分析者	主要上下文	背景代理 (Haiku)
粒度	完整技能	原子化「直覺」
信心指數	無	0.3-0.9 加權
演化流程	直接轉為技能	直覺 -> 聚類 -> 技能/指令/代理
分享功能	無	匯出/匯入直覺

直覺模型

直覺是一個小型學習行為：

---
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"
---

# 偏好函數式風格

## 行為

在適當情況下使用函數式模式而非類別。

## 證據

- 觀察到 5 次函數式模式偏好
- 使用者在 2025-01-15 將類別導向方法修正為函數式

屬性：

• 原子化 —— 一個觸發條件，一個行為
• 信心加權 —— 0.3 = 暫定，0.9 = 近乎確定
• 領域標籤 —— code-style, testing, git, debugging, workflow 等
• 有據可查 —— 追蹤哪些觀察結果建立了它
• 範圍感知 —— project（預設）或 global

運作方式

工作階段活動（在 git 儲存庫中）
      |
      | Hook 擷取提示 + 工具使用（100% 可靠）
      | + 偵測專案上下文（git 遠端 / 儲存庫路徑）
      v
+---------------------------------------------+
|  projects/<project-hash>/observations.jsonl  |
|   (提示、工具呼叫、結果、專案)               |
+---------------------------------------------+
      |
      | 觀察者代理讀取（背景，Haiku）
      v
+---------------------------------------------+
|          模式偵測                            |
|   * 使用者修正 -> 直覺                      |
|   * 錯誤解決 -> 直覺                        |
|   * 重複工作流程 -> 直覺                    |
|   * 範圍決策：專案或全域？                   |
+---------------------------------------------+
      |
      | 建立/更新
      v
+---------------------------------------------+
|  projects/<project-hash>/instincts/personal/ |
|   * prefer-functional.yaml (0.7) [專案]      |
|   * use-react-hooks.yaml (0.9) [專案]        |
+---------------------------------------------+
|  instincts/personal/  (全域)                  |
|   * always-validate-input.yaml (0.85) [全域] |
|   * grep-before-edit.yaml (0.6) [全域]       |
+---------------------------------------------+
      |
      | /evolve 聚類 + /promote
      v
+---------------------------------------------+
|  projects/<hash>/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 之外，以避免 Claude Code 的敏感路徑防護機制阻擋背景直覺寫入：

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. 啟用觀察 Hook

如果以插件形式安裝（建議）：

不需要在 settings.json 中額外加入 Hook 區塊。Claude Code v2.1+ 會自動載入插件 hooks/hooks.json，且 observe.sh 已註冊在其中。

如果你之前曾將 observe.sh 複製到 ~/.claude/settings.json，請移除該重複的 PreToolUse / PostToolUse 區塊。重複的插件 Hook 會導致雙重執行以及 ${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}

# 專案目錄會在 Hook 首次於 git 儲存庫中執行時自動建立

3. 使用直覺指令

/instinct-status     # 顯示已學習的直覺（專案 + 全域）
/evolve              # 將相關直覺聚類為技能/指令
/instinct-export     # 將直覺匯出到檔案
/instinct-import     # 從他人處匯入直覺
/promote             # 將專案直覺提升至全域範圍
/projects            # 列出所有已知專案及其直覺數量

指令

指令	說明
/instinct-status	顯示所有直覺（專案範圍 + 全域）及其信心指數
/evolve	將相關直覺聚類為技能/指令，並建議提升
/instinct-export	匯出直覺（可按範圍/領域篩選）
/instinct-import <檔案>	匯入直覺，並可控制範圍
/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）上，它會啟動並報告成功，但當生成它的 Hook 退出且其 Job Object 關閉時，該程序會被終止，因此不會執行任何分析——在那裡設定 observer.enabled: true 實際上無效（請參閱 issue #2489）。

observe.sh 會在後續的 Hook 呼叫中偵測到此情況，並在觀察者連續多次無法持續執行時，將解釋性警告寫入 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 遠端 URL）
    |   +-- project.json    # 每個專案的元資料鏡像（id/name/root/remote）
    |   +-- observations.jsonl
    |   +-- observations.archive/
    |   +-- instincts/
    |   |   +-- personal/   # 專案特定自動學習
    |   |   +-- inherited/  # 專案特定匯入
    |   +-- evolved/
    |       +-- skills/
    |       +-- commands/
    |       +-- agents/
    +-- f6e5d4c3b2a1/       # 另一個專案
        +-- ...

範圍決策指南

模式類型	範圍	範例
語言/框架慣例	專案	"使用 React hooks"，"遵循 Django REST 模式"
檔案結構偏好	專案	"測試放在 __tests__/"，"元件放在 src/components/"
程式碼風格	專案	"使用函數式風格"，"偏好 dataclasses"
錯誤處理策略	專案	"對錯誤使用 Result 類型"
安全實踐	全域	"驗證使用者輸入"，"清理 SQL"
一般最佳實踐	全域	"先寫測試"，"始終處理錯誤"
工具工作流程偏好	全域	"編輯前先 Grep"，"寫入前先讀取"
Git 實踐	全域	"慣用提交訊息"，"小型聚焦提交"

直覺提升（專案 -> 全域）

當相同的直覺在多個專案中以高信心出現時，它便成為提升至全域範圍的候選對象。

自動提升標準：

• 在 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	近乎確定	核心行為

信心指數提升當：

• 模式被重複觀察到
• 使用者未修正建議的行為
• 來自其他來源的類似直覺相符

信心指數降低當：

• 使用者明確修正該行為
• 模式長時間未被觀察到
• 出現矛盾的證據

為何觀察使用 Hook 而非技能？

「v1 依賴技能進行觀察。技能是機率性的——它們依據 Claude 的判斷，約有 50-80% 的機率觸發。」

Hook 100% 會觸發，確定性高。這表示：

• 每個工具呼叫都被觀察到
• 不會遺漏任何模式
• 學習是全面的

向後相容性

v2.1 完全相容於 v2.0 和 v1：

• 可使用 scripts/migrate-homunculus.sh 將現有的全域直覺從 ~/.claude/homunculus/instincts/ 遷移
• v1 產生的現有 ~/.claude/skills/learned/ 技能仍可運作
• 停止 Hook 仍會執行（但現在也會饋入 v2）
• 逐步遷移：兩者可並行執行

隱私

• 觀察結果保留在本機
• 專案範圍直覺按專案隔離
• 只有直覺（模式）可以匯出——而非原始觀察結果
• 不分享任何實際程式碼或對話內容
• 你掌控要匯出和提升的內容

相關資源

• ECC-Tools GitHub 應用程式 - 從儲存庫歷史記錄產生直覺
• Homunculus - 啟發 v2 直覺型架構的社群專案（原子化觀察、信心評分、直覺演化管線）
• 長篇指南 - 持續學習章節

---

直覺型學習：教導 Claude 你的模式，一次一個專案。