Continuous Learning 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
+---------------------------------------------+
|          패턴 감지                           |
|   * 사용자 수정 -> 본능                      |
|   * 오류 해결 -> 본능                        |
|   * 반복 작업 흐름 -> 본능                    |
|   * 범위 결정: 프로젝트 or 전역?             |
+---------------------------------------------+
      |
      | 생성/업데이트
      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) [전역]  |
|   * 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. 관찰 후크 활성화

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

추가 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 hooks 사용", "Django REST 패턴 따르기"
파일 구조 선호도	project	"__tests__/에 테스트", "src/components/에 컴포넌트"
코드 스타일	project	"함수형 스타일 사용", "데이터클래스 선호"
오류 처리 전략	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에게 패턴을 가르치기.