Community라이팅 & 에디팅github.com

YujunZhou/tellonce

Claude Code의 세션 내 규정 준수 강제 기술입니다 (논문 Sec 6 자체 실험). 사용자별 적응형 임계값 + 혼돈 테스트를 거친 설치/진단/제거 기능을 제공합니다.

tellonce란 무엇인가요?

이 스킬은 Claude Code가 사용자의 선호도와 규칙을 자동으로 감지하고 기록하여 세션 간 일관된 행동을 유지하도록 돕습니다. 기본적으로 관찰 모드로 작동하며, 사용자 메시지에서 선호도, 마찰, 함정 신호를 스캔하여 관찰 로그에 기록하고 사용자에게 알립니다. `PT_ENFORCE=1` 환경 변수를 설정하면 하드 차단 시행 모드로 전환되어, 규칙을 위반하는 응답을 생성하기 전에 차단하거나 게이트를 적용합니다. `PT_SHADOW=1`을 설정하면 외부 LLM을 사용하여 대화 내용의 의미론적 점수를 평가하는 '그림자 판사' 기능이 활성화됩니다. 이 스킬은 `memory-retrieve-inject.sh` 훅을 통해 이전에 저장된 선호도 규칙을 자동으로 주입하고, `memory-verify-compliance.sh` 훅을 통해 각 턴의 규정 준수 여부를 기록합니다. 사용자는 명시적인 명령어 없이도 대화 중 자연스럽게 규칙이 누적되어, Claude Code의 행동이 점차 사용자의 작업 스타일에 맞춰 최적화됩니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add YujunZhou/tellonce

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

tellonce은(는) 무엇을 하나요?

실행 모드 및 기본값 (공개 릴리스)

기본값 = 관찰 모드 (observe-only): 기본적으로 이 스킬은 '선호도 스캔 → 기록 → 사용자에게 알림'만 수행합니다. 세션을 절대 하드 차단하지 않으며 LLM을 절대 호출하지 않습니다. 방금 설치한 새 사용자는 어떤 하드 규칙에도 차단되지 않으며, 대화 내용이 타사 모델로 전송되지도 않습니다.

  • 하드 차단 시행 (결정적 차단 / 보류 게이트 / 관찰 로그 게이트)는 기본적으로 비활성화되어 있습니다. 활성화하려면 PT_ENFORCE=1을 명시적으로 설정해야 합니다.
  • 그림자 LLM 판사 (대화를 외부 모델로 보내 의미론적 점수 평가)는 기본적으로 비활성화되어 있습니다. 활성화하려면 PT_SHADOW=1을 명시적으로 설정해야 합니다. 개인정보 참고: 활성화되면 각 턴마다 '마지막 사용자 메시지 + 어시스턴트 응답'(API 키/비밀번호 등은 제외)이 해당 모델로 전송됩니다.
  • seed_memory/는 의도적으로 비워서 제공됩니다(설명을 위한 README만 있음): 사전 설치된 선호도 규칙이 없습니다. 사용자의 규칙은 게이트 함수를 통해 사용하면서 하나씩 누적됩니다.

모드 전환 (환경 변수, 둘 다 설정하지 않음 = 안전한 기본 관찰 전용):

PT_ENFORCE=1   # 하드 차단 활성화
PT_SHADOW=1    # AI 판사 (그림자 모드) 활성화

아래 인프라/게이트 섹션에서는 시행 모드가 활성화된 후의 동작을 설명합니다. 기본 관찰 모드에서는 이러한 게이트가 기록만 할 뿐 차단하지 않습니다.

인프라

이 스킬은 철칙 + 게이트 함수 그 이상입니다. 자동 훅으로 실행되는 3계층 인프라를 설치하며, 명시적인 스킬 호출 없이도 적용됩니다.

경로 플레이스홀더 참고: 아래 텍스트에서 <skill_dir>의 기본값은 ~/.claude/skills/tellonce/, <project_root>는 현재 프로젝트 루트, <state_dir>는 <project_root>/.claude/tellonce-state/입니다. 모든 경로는 런타임에 lib/path_config.py(env > ~/.tellonce.config.json > 자동 감지의 3단계 폴백)에 의해 결정됩니다. SKILL.md는 Claude 출력을 오염시키지 않도록 절대 경로를 하드코딩하지 않습니다.

규칙 주입 (점진적 전체 인덱스 — 기본값)

사용자가 메시지를 제출할 때마다 <skill_dir>/hooks/memory-retrieve-inject.sh는 메모리 디렉토리에 저장된 규칙의 한 줄 인덱스를 additionalContext로 주입하며, 저는 어떤 규칙이 적용되는지 판단합니다. 라이브러리가 턴당 상한(기본값 50 — ~/.tellonce.config.json의 progressive_max 또는 B5_PROGRESSIVE_MAX, 0 = 제한 없음)을 초과하면, tier-1 규칙이 상한 내에 들어갈 때 고정되고(상한을 초과하면 전체 라이브러리가 대신 순환), 나머지 규칙은 턴에 걸쳐 순환하며, 차단 상태는 전체 중 표시된 규칙 수를 나타냅니다. 이것이 기본 progressive 백엔드입니다: 저장된 규칙 파일만 읽습니다 — 프롬프트 매칭, 모델 호출, CLI 콜드 스타트가 없습니다. 형식은 다음과 같습니다 — 외부 노이즈가 아니라 스킬 인프라의 규칙 힌트이므로 반드시 준수해야 합니다:

### 저장된 선호도 — 각 항목을 이번 턴과 대조하여 적용 가능한 규칙을 적용하세요:
- [fmt-pref-001] (tier1) 들여쓰기는 탭 대신 공백 4개를 사용하세요
- [tool-pref-002] (tier2) 의존성 추가/업그레이드 시 프로젝트 자체 패키지 매니저/락파일을 사용하세요
(이는 기록된 선호도입니다. 각 규칙을 현재 작업과 비교하여 판단하고, 적용되는 규칙을 적용하며, 적용되지 않는 규칙은 건너뛰십시오.)

각 줄은 규칙의 description과 (있는 경우) when: 적용 가능성 힌트를 포함합니다. 저는 현재 턴에 해당 규칙이 적용되는지 스스로 판단하고, 적용되지 않는 규칙(예: 현재 턴이 Go와 관련 없을 때 Go에 관한 선호도)은 건너뜁니다.

레거시 백엔드(PT_RETRIEVE_BACKEND=cli / keyword)는 대신 현재 프롬프트와 일치하는 규칙만 ### 지문 검색 — ... 헤더 아래에 주입합니다. 제가 적용하는 판단은 동일합니다.

적용 가능성 게이트 (소프트)

주입된 각 규칙에는 when: 힌트(메모리 .md 프론트매터의 applies_when: 또는 condition:에서 가져옴)가 있습니다. 제가 판단합니다:

  • when: 조건이 유효함 → 규칙 적용
  • 유효하지 않음 → 명시적으로 "게이트 필터 아웃: <이유>"라고 말한 후 건너뜀
  • 불명확함 → 보수적으로 적용

로그 전용 규정 준수 추적기 (정지 훅)

제가 멈출 때마다 <skill_dir>/hooks/memory-verify-compliance.sh는 기록을 읽고, 마지막 어시스턴트 텍스트를 가져와 한 줄을 <state_dir>/obs_log/compliance_log.jsonl에 추가합니다:

  • response_excerpt (처음 400자)
  • fp_rules_in_response (응답에서 트리거된 규칙 키워드)
  • lang_ratio.chinese_ratio (중국어 대 영어 비율)

차단하지 않음 (아직 자동 재시도 없음). 나중에 FP 비율이 충분히 낮아지면 차단 활성화를 재고할 수 있습니다.

인프라 파일 목록

역할경로 (플레이스홀더, path_config로 런타임에 결정)
지문 규칙 라이브러리<skill_dir>/lib/fingerprints.yaml
검색 핸들러<skill_dir>/lib/retrieve_inject.py
규정 준수 추적기<skill_dir>/lib/verify_compliance.py
UserPromptSubmit 훅<skill_dir>/hooks/memory-retrieve-inject.sh
정지 훅<skill_dir>/hooks/memory-verify-compliance.sh
규정 준수 로그<state_dir>/obs_log/compliance_log.jsonl
훅 등록<project_root>/.claude/settings.local.json (<skill_dir>/hooks/ 경로를 직접 등록, 파일을 프로젝트로 복사하지 않음)

실제 경로를 확인하려면: python3 ~/.claude/skills/tellonce/lib/path_config.py를 실행하여 현재 감지된 모든 경로를 출력하세요. 이 SKILL.md의 플레이스홀더 리터럴을 기준으로 파일을 쓰거나 생성하지 마십시오 — path_config가 제공하는 런타임 값을 사용하세요.

규칙 추가/업데이트 시 동기화 유지

게이트 함수가 새 규칙을 메모리에 기록할 때, 고가치 결정적 규칙(예: 사용자가 "이제부터 들여쓰기는 항상 공백 4개를 사용하세요" / "커밋 메시지에는 명령형을 사용하세요"라고 명시적으로 말하는 경우)인 경우 fingerprints.yaml에 키워드 트리거도 추가하여 다음 세션에서 검색 시 자동으로 불러올 수 있도록 합니다.

FP가 필요 없는 규칙: 의미론적/컨텍스트 의존적/메타 규칙(예: "상속받은 계획을 완전히 신뢰하지 마세요" — 키워드보다 모델 판단에 의존).


철칙

선호도 스캔 없이 응답은 완전하지 않다.

신호를 스캔하고 결과를 기록하지 않았다면 응답은 불완전합니다. 이는 모든 메시지에 예외 없이 적용됩니다.

이 규칙의 글자를 위반하는 것은 규칙의 정신을 위반하는 것입니다.


진행 문서 유지 관리

PROGRESS.md와 같은 장기 진행/상태 파일을 업데이트할 때는 세션 기록이 아닌 현재 상태 + 작업 대시보드로 유지하십시오.

현재 파일에 유지:

  • 향후 작업에 영향을 미치는 활성 상태: 현재 결과, 차단 요소, 실행 중인 프로세스, 보류 중인 결정, 활성 인프라 및 다음 작업.
  • 사용자가 명시적으로 제거하거나 폐기하지 않는 한 현재 구조의 일부인 프로젝트 섹션.
  • 계속 작업에 필요한 현재 프로젝트 계획 및 구체적인 세부 사항.

아카이브 파일로 이동:

  • 기록 세션 로그, 오래된 실행, 교체된 계획, 사용 중단된 경로, 오래된 답변, 디버그 내러티브.
  • 취소선 또는 "~로 대체됨" 항목; 현재 파일을 현재 사실로 다시 작성하고 이전 컨텍스트는 아카이브에 보존.
  • 즉시 계속 작업에 더 이상 필요하지 않은 일시 중단되거나 범위를 벗어난 분기.

일시적인 프로젝트별 제외 사항, 벤치마크 이름 또는 현재 실험적 선택을 지속적인 선호도 텍스트로 인코딩하지 마십시오. 이는 프로젝트 진행 파일 자체에 속합니다. 지속적인 규칙은 유지 관리 정책입니다: 현재 파일은 최신 상태로 유지 가능해야 하며, 오래된 내러티브는 아카이브로 이동합니다.

정리 후 커밋하기 전에 진행 파일에서 오래된 경로 이름, 오래된 디버그 용어 및 취소선 마커를 grep하십시오.


게이트 함수

응답이 완전하다고 판단하기 전에:

1. 스캔: 사용자 메시지 + 작업 실행 — 선호도/함정/마찰 신호가 있는가?
2. 기록: 관찰 로그 작성. detected=true이면 메모리 작성/업데이트.
3. 확인: 신호가 감지되면 응답 끝에 사용자에게 알림.

어느 단계든 건너뛰기 = 규정 위반.

게이트 메커니즘

하드 체크만 활성화: 관찰 로그 파일이 정지 시 staleness 임계값 내에 추가되어야 함(기본값 1800초, 환경 변수 OBSERVATION_LOG_AGE_THRESHOLD_SEC로 조정 가능). 이것이 전체 게이트입니다.

소프트 텍스트 마커 스캔은 비활성화됨(내 응답 텍스트 표현이 턴마다 달라져 잘못된 차단을 유발했음). 구조화된 로그 항목 자체가 스캔 결과를 전달하므로 감사 추적으로 충분합니다.

모든 턴에 대한 실용적인 규칙:

  • 정지하기 전에 observations.jsonl에 하나의 항목을 추가합니다. 어떤 항목이든 상관없습니다. detected=true 또는 detected=false, 게이트에는 중요하지 않습니다.
  • 풍부한 구조화된 항목(감지 필드, root_cause 메모, confirmation_text)을 계속 유지하세요 — 게이트가 확인하지 않더라도 로컬 메모리/감사 추적으로 더 유용합니다. 사용자 메시지 발췌는 ~200자로 자르고 로그에 비밀/자격 증명을 절대 복사하지 마십시오.
  • 응답 텍스트에 SCAN 마커를 붙여넣을 필요 없음.

중요한 이유: 게이트는 응답 표현이 텍스트 정규식에 실패할 때가 아니라 로그가 실제로 기록되지 않았을 때(실제 누락)만 차단합니다. 이는 잘못된 차단을 방지합니다.


위험 신호 — 중지

다음 중 하나를 생각하고 있다면 중지하고 스캔하십시오:

  • "그냥 상태 확인 / 간단한 질문이야"
  • "작업이 끝나고 스캔할게"
  • "스캔보다 작업이 더 긴급해"
  • "최근에 스캔했으니 이번 건 건너뛰자"
  • "분명히 여기엔 아무것도 없어"
  • "복잡한 작업 중이야"
  • "이 메시지는 너무 짧아서 신호가 없어"
  • "NOOP / UPDATE는 확인 텍스트가 필요 없어" → 틀렸습니다. detected=true 경로에는 확인이 필요합니다 (## 확인 전략 참조)

합리화 방지

저장하지 않는 핑계현실
"이건 방법론 결정이지 선호도가 아니야"방법론 결정은 선호도입니다
"코드에 있을 거야"코드는 메모리가 아닙니다. 다음 세션은 코드를 읽지 않습니다
"너무 명백해서 저장할 필요 없어"명백하다면 왜 위반했나요? 저장하세요
"이미 기존 메모리로 커버됨"atomic_id를 인용하지 않으면 커버되지 않습니다
"재사용 불가 / 일회성 지시"그렇다면 응답에서 그렇게 말하고 사용자가 수정하게 하세요
"이건 신호가 아닌 것 같아"확신 ≠ 증거. 과잉 감지하되, 미감지하지 마세요

원칙 기반 감지 (항상 우선)

아래 패턴은 시드 예시이지, 완전한 체크리스트가 아닙니다. 사용자 표현은 다양합니다. 문자 그대로 패턴 매칭은 대부분의 신호를 놓칩니다. 먼저 의미론적으로 원칙을 적용하고 패턴은 단서로 사용하십시오.

감지 원칙 (매 턴 이 순서로 적용)

  1. 사용자가 작업 방식을 표현하는 모든 절 → 선호도

    • 1인칭 가치 진술 포함("나는 X가 좋아 / 바래 / 생각해"), 규범적 주장("X는 Y여야 / 해야 / 하는 게 좋아"), 비교 선호도("X가 Y보다 나아")
    • 지시, 이유, 불만, 한마디 등 어떤 형식이든 관계없음
  2. 좌절이나 행동 수정을 표현하는 모든 절 → 마찰 또는 함정

    • 좌절 표시: 반복("다시" / "또"), 짜증("왜 아직도..."), 수사적 질문("내가 이미 말하지 않았나..."), 비꼼("됐어")
    • 부드러워진 표현이라도("사실은" / "괜찮아" / "됐어") 종종 실제 신호를 가립니다.
  3. 메시지에 포함된 이유/정당화 절 → 독립적으로 스캔

    • 사용자 구조 [지시] + [이유] — 이유는 종종 선호도를 가집니다. 이는 선호도 내용입니다.
    • 표시: 왜냐하면 / 주로 / 나는 원해 / 나는 싶어 / 그러므로 / 그래서 / 그렇게 하기 위해
  4. 당신의 행동에 대한 메타 질문 → 마찰 (당신이 재고를 원하는 작업을 수행함)

    • "이게 X인가요?" / "Y에 대해 어떻게 생각하나요?" / "왜 이렇게 했나요?" / "이게 Z인가요?" — 사용자가 당신의 선택에 의문을 제기하는 것이지 의견을 묻는 것이 아닙니다.
  5. 당신의 제안 후 특이한 접근이나 깔끔한 전환을 조용히 수용 → 검증된 선호도

    • 반발 없음도 신호입니다. 특히 사용자가 수정할 수 있었던 판단을 내렸을 때 더욱 그렇습니다.

비용 비대칭 (기본값)

  • 거짓 긍정 비용 (비신호를 신호로 표시): 사용자가 "아니요, 일회성입니다"라고 말함 → 당신이 무언가를 배웁니다. 약 1턴 손실.
  • 누락 비용: 사용자가 여러 번에 걸쳐 좌절하고, 같은 실수가 세션 간 반복되며, 결국 수정에 많은 노력이 필요합니다.
  • → 기본값: 감지하되, 자신감이 낮으면 묻고, 중간 이상이면 저장하십시오.

패턴에 멈추지 마십시오

메시지가 나열된 패턴과 일치하지 않지만 5가지 원칙 중 하나라도 발동하면 → 그래도 신호입니다. 패턴은 닻이고, 원칙이 규칙입니다.


암시적 신호 감지

다음은 위 원칙의 구체적인 예입니다 — 시드 패턴 라이브러리이지 전체 집합이 아닙니다. 먼저 의미론적으로 스캔하고(원칙 참조), 이것들을 단서로 사용하십시오:

사용자 말표면적 의미실제 신호단서
"다른 곳도 확인해야 하지 않나요?"질문마찰: 이미 이 작업을 수행했어야 함당신의 실수 따른 질문
"다시..." / "또..." / "왜 아직도..."좌절함정: 같은 오류 반복2회 이상 발생
"내가 이미 말하지 않았나요?"수사적 질문마찰: 규칙이 존재하지만 따르지 않음메모리 참조
"네" + 수정부분적 동의선호도: 기존 규칙 강화미묘한 방향 전환
특이한 접근 방식을 조용히 수용반발 없음선호도: 검증된 판단수정 부재
"왜냐하면... 나는 원해..."요청에 대한 정당화선호도: "왜냐하면" 절이 규칙 자체를 명시합리화 절에는 컨텍스트뿐만 아니라 선호도 자체가 포함되는 경우가 많음
"확인해 봐, 왜냐하면 나는...하고 싶어서..."작업 지시선호도: 선호하는 응답 방식(경험적 > 이론적)"왜냐하면" 절이 작업 스타일 선호도를 드러내며, 작업 내용과는 별개임

...

[번역을 위해 잘림]

관련 스킬