지속적 학습 v2.1 - 본능 기반 아키텍처

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
관찰	중지 후크 (세션 종료)	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에 클래스 기반 접근 방식을 함수형으로 수정함

속성:

• 원자적 -- 하나의 트리거, 하나의 행동
• 신뢰도 가중치 -- 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            |
+---------------------------------------------+

프로젝트 감지

시스템은 현재 프로젝트를 자동으로 감지합니다:

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. 관찰 후크 활성화

플러그인으로 설치된 경우 (권장):

추가 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)에서는 시작되어 성공을 보고하지만, 생성 후크가 종료되고 Job Object가 닫히면 프로세스가 종료되어 분석이 실행되지 않습니다. 따라서 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	"규칙적 커밋", "작고 집중된 커밋"

본능 승격 (프로젝트 -> 전역)

동일한 본능이 높은 신뢰도로 여러 프로젝트에 나타나면 전역 범위로 승격할 후보가 됩니다.

자동 승격 기준:

• 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에게 당신의 패턴을 가르칩니다.