크라우니코드 상호보완 구조 v1

개요

크라우니코드의 두 경로 — 로컬 에이전트(규칙엔진+LLM 윤활유)와 /크라우니코드 슬래시(Claude 풀맥락) — 를 항상 보완하도록 단일 인터페이스로 묶는다. 성능·비용·학습환류 세 축을 동시 개선.

배경

• 로컬 에이전트: HIT=0원, MISS시 Haiku 호출 — 캐싱 미적용 (90% 할인 미사용)
• 슬래시: 매번 풀맥락, 학습DB 환류 끊김 — 만든 코드가 다음 세션에 안 남음
• 결과: 둘 다 영양실조. 한선씨 비율 70% 유지에 위협.

목표 KPI

지표	현재	목표
로컬 HIT률	58%	80%+
캐시 히트율 (MISS 경로)	0%	70%+
슬래시→DB 환류율	<10% (수동)	95%+ (자동)
컴파일 성공률	~60% (함정 미회피)	90%+
한선씨 패턴 누적	54,139	65,000+

아키텍처

                  ┌──────────────────────┐
                  │   사용자 요청          │
                  └──────────┬───────────┘
                             ▼
                  ┌──────────────────────┐
                  │ router.sh (공통 입구) │
                  │ intent + 복잡도 판정   │
                  └──┬────────────────┬──┘
              단순/정형              복합/신규/디버그
                  ▼                  ▼
        ┌─────────────────┐  ┌────────────────────┐
        │ 로컬 에이전트    │  │ /크라우니코드 슬래시 │
        │ pattern DB HIT  │  │ Claude (메모리·맥락)│
        │ → 0 cost        │  │ → 풀 캐시(이미)     │
        │ MISS → LLM      │  │                    │
        │ (★캐시 적용)     │  │                    │
        └────────┬────────┘  └─────────┬──────────┘
                 │                     │
                 ▼                     ▼
        ┌────────────────────────────────────────┐
        │ verify.sh — crowny run 컴파일 검증     │
        └────────────────┬───────────────────────┘
                         ▼
        ┌────────────────────────────────────────┐
        │ auto-learn.sh (공통 출구)             │
        │ 학습DB 양방향 등록 + intent 인덱스 갱신│
        │ 함정 사전(traps.dat) 보강             │
        └────────────────┬───────────────────────┘
                         ▼
        ┌────────────────────────────────────────┐
        │ stats.sh — 통합 대시보드               │
        │ HIT률·캐시히트율·로컬/슬래시 비율·환류수│
        └────────────────────────────────────────┘

컴포넌트 명세

1. prompts/hanseon_system.txt (신규)

3,000~5,000 토큰 분량의 정적 시스템 프롬프트. Haiku 캐시 최소(2048)를 안정 상회.

구성:

• 역할/출력규칙 — 코드만 출력, 마크다운 금지
• 한선씨 키워드 60개 — 변수/함수/만약/아니면/혹시/동안/반환/가져오기/...
• 예약어 함정 — 전이/확정/결정/변환/파일명/입력/출력/상태/설정/길이/추가/포함/부분/범위/배열 (변수명 금지)
• 배열·맵 의미론 — 재대입 필수, 설정=쓰기전용/꺼내=읽기
• 내장함수 카탈로그 60개 — 출력/입력/글자수/부분/거듭제곱/...
• 컴파일러 함정 5건 — 배열 플랫화, 파일존재 -1, 인라인주석 다중단어, 시도/오류 무한루프, 함수명에 예약어
• Few-shot 5건 — 가장 빈도 높은 패턴
• 라이브러리 가져오기 — 셀코어/문자열/JSON/네트워크/...

자산 출처: HANSEON_REFERENCE.md, HANSEON_IDIOMS.md, CrownyTVM/CLAUDE.md, crownyc/CLAUDE.md, 메모리 함정 메모 11+건.

2. llm-bridge.sh (개선)

기존: messages: [{role: user, content: prompt}] 변경: system: [{type: text, text: <hanseon_system>, cache_control: {type: ephemeral}}] + messages: [{role: user, content: <intent+desc+dynamic_examples>}]

추가:

• usage 응답 파싱 → logs/cache_stats.log 적재 (input_tokens / cache_read_input_tokens / cache_creation_input_tokens / output_tokens)
• claude-cli 모드 호환 유지 (캐시는 API 모드 한정)

3. router.sh (신규)

입력: 사용자 요청 한 줄 출력: LOCAL_HIT|LOCAL_MISS|SLASH + intent

복잡도 점수:

• 키워드 매칭 점수 (keywords.dat 적중 수)
• 동사 개수 (1개=단순, 2+=복합)
• 라이브러리 의존 (가져오기/셀코어 등 키워드)
• 학습DB lookup HIT? → LOCAL_HIT 즉시 반환

라우팅 규칙:

점수≥0.8 + HIT → LOCAL_HIT (즉시 반환)
점수≥0.5 + MISS → LOCAL_MISS (LLM 윤활유, 캐시활용)
점수<0.5 또는 동사≥3 또는 디버그요청 → SLASH 큐

4. 슬래시 환류 훅 (강화)

기존 PostToolUse 훅이 .한선 Write/Edit 시 자동 학습한다고 CLAUDE.md에 명시 — 실제 동작 점검 + 누락 케이스 보강:

• 슬래시 모드 마커 (env: CROWNYCODE_VIA=slash) 식별
• 컴파일 성공 시 자동 learn.sh add <intent> "<코드>"
• intent 추출 로직 (파일명 기반 + 첫 주석 기반)

5. traps.dat (신규)

컴파일 실패 케이스를 패턴으로 누적:

패턴: 변수 전이 = ...
에러: 예약어 사용
회피: '전이' → '상태이동'으로 치환

다음 LLM 호출 시 시스템 프롬프트에 최근 함정 3건 자동 주입.

6. stats.sh (개선)

agent.sh stats 확장:

=== 크라우니코드 통합 대시보드 ===
[로컬]
  HIT률:        82% (123 / 150)
  MISS→LLM:     27건
  캐시 히트율:   71% (19 / 27)
  토큰 절감:    ~84% 비용 감소

[슬래시]
  세션 호출:    18건
  자동 환류:    17건 (94%)
  intent 신규:  +12

[전체]
  한선씨 패턴:  54,139 → 54,168 (+29)
  함정 사전:    5건 신규 등록
  비율:         로컬 89% / 슬래시 11%

인터페이스

bash# 단일 진입점
./router.sh "한글 명령"

# 강제 경로
./router.sh --local "..."
./router.sh --slash "..."   # 슬래시 큐에만 적재

# 통계
./router.sh stats

검증 기준 (Phase [9])

시나리오	기대
포트 7777 TCP 서버	LOCAL_HIT, ms단위 응답
JSON 파싱 후 셀에 저장하고 룰엔진 실행	LOCAL_MISS → 캐시 히트 → 학습
이 코드 디버그해줘 [에러로그]	SLASH로 라우팅
tcp_listen (영어)	기가팩토리 변환 → LOCAL_HIT
회귀 27건	모두 통과

관련 파일

• 작업: /Users/ef/Downloads/CrownyTVM/crownycode-working/
• 오리지널: /Users/ef/Downloads/CrownyTVM/crownycode-agent/
• 학습DB: ~/.crownycode/학습.dat (8.4M), ~/Downloads/CrownyTVM/crownycode/data/all_patterns.dat (96M)
• 통계: ~/.crownycode/통계.dat
• KPS 4계층: /Users/ef/kpscode/

잔여 이슈

• Haiku 캐시 최소 토큰이 정확히 2048인지 응답 헤더로 검증 필요 (Phase [4] 첫 호출 시 로깅)
• traps.dat 자동 보강이 본 시스템 프롬프트를 무한히 키울 가능성 → 최대 5건/3K 토큰 제한
• 슬래시 환류 훅에서 intent 자동 추출이 부정확하면 noise 패턴 누적 → 검토 큐 필요

다음 단계

1. [완료] Phase [1] 클론 → working
2. [완료] Phase [2] 설계 문서 (본 문서)
3. [진행] Phase [3] hanseon_system.txt 구축
4. Phase [4] llm-bridge.sh 캐시 적용
5. Phase [5] router.sh 신규
6. Phase [6] 슬래시 환류 훅 강화
7. Phase [7] traps.dat
8. Phase [8] stats.sh
9. Phase [9] 검증 + promote