Skill

tokenhabit — 토큰 습관 코칭 스킬

이 스킬의 정체성. tokenhabit = "무의식중에 토큰을 태우는 대화/사용 습관을 자각시키고 고치는 사용자 코칭 스킬." 하네스·에이전트·모델 티어·캐싱 설계 감사 → tokensave 스킬을 쓰라. 우리는 운전자의 습관을 다룬다.

🎯 목표를 착각하지 마라 — "낭비 제거"이지 "적게 쓰기"가 아니다. 진단 결과를 "그러니 Claude를 덜 쓰세요"로 번역하는 순간 이 스킬은 해로워진다. 목표는 같은 결과를 더 싸게 얻어, 아낀 예산을 실제 작업에 쓰는 것이다. 토큰을 아껴서 할 일을 못 하는 것은 낭비보다 비싼 실수다. (이 긴장에 대한 근거와 반론은 references/measurement_and_hooks.md §5 참고.)

⚡ 핵심 엔진은 본문 모드가 아니라 scripts/habit_scan.py다 — 진단 요청을 받으면 이걸 먼저 실행하라. 이 스크립트는 ~/.claude/projects/*.jsonl의 과거 전체 세션을 LLM 0회로 사후 스캔해 Token Waste Score(A~F)·습관 순위·즉시 fix를 낸다. 설치형 CLI는 tokenhabit(없으면 python3 scripts/habit_scan.py). 아래 트리거 문구의 "이 세션"에 속아 현재 대화만 보고 "진단할 내용이 없다"고 답하지 말 것. 세션이 종료돼도, 새 세션이라 현재 대화가 비어도 — 진단의 SSOT는 디스크에 영속된 과거 로그이고 그걸로 항상 진단한다. 📂 스킬 로드 시 scripts/·references/를 먼저 훑어라. 본문 설명만 읽고 단정하지 말 것 — 그 추측·도구 점검 생략이 바로 이 스킬이 잡으려는 습관(H5·H8)이다.

지금 당장 바꾸는 5가지 습관 (퀵카드)

31패턴 중 빈도·임팩트 최상위 5개. 이것만 바꿔도 세션 비용을 크게 줄일 수 있다.

4가지 모드

MODE 1: SESSION COACH — 세션 토큰 진단

트리거: "이 세션 토큰 진단", "왜 토큰을 많이 써", "지금 세션 어때", "내 토큰 습관 진단", "전체 세션 진단", "새 세션에서 진단", "토큰 습관 봐줘"

철칙 — 반드시 준수. 진단 요청을 받으면 현재 대화만 보고 단정하지 말고, 먼저 scripts/habit_scan.py(설치본 tokenhabit CLI)를 실행한다. 범위는 사용자가 선택 — 전체 누적(--days N) 또는 이 세션만(--current). 새 세션이라 현재 대화가 비어 있어도 절대 "진단할 내용이 없다"고 답하지 말 것. 진단의 단일 진실 원천(SSOT)은 현재 대화가 아니라 디스크에 영속된 세션 로그(~/.claude/projects/**/*.jsonl)다 — 세션이 종료돼도 jsonl은 남으므로 끝난 세션도 진단 대상이다. 현재 대화 직접 관찰(아래 1~3번)은 --current 결과를 정성적으로 보강하는 보조 단계일 뿐, 그것만으로 "내용 없음" 판정 금지.

진단 절차 (순서대로):

0. [필수·먼저 실행] 진단 범위를 정하고 habit_scan.py 실행 사용자가 어느 범위를 원하는지 판단한다. 불명확하면 전체를 기본으로 보여주고 "이 세션만 따로 볼 수도 있다"고 한 줄 안내:

   • 전체 누적 습관 (기본): python3 scripts/habit_scan.py --days 7 — 과거 모든 세션. "내 토큰 습관", "전체 진단", "요즘 왜 많이 써", 모호한 요청.
   • 이 세션만: python3 scripts/habit_scan.py --current — 현재(가장 최근) 세션 1개만. "지금 이 세션 어때", "방금 작업 진단".

   (설치본은 tokenhabit --days 7 / tokenhabit --current, 한국어 --lang ko.) 출력 = Token Waste Score(A~F) + 패턴 순위 + 즉시 fix — 이게 진단 본체. 파일 0개일 때만 "기록 없음" 안내 후 --days 확대 재시도.

   서브에이전트 트랜스크립트는 기본 제외된다. 이 스킬은 운전자의 습관을 채점하지, 에이전트가 자기 컨텍스트에서 한 일을 사용자에게 청구하지 않는다. 굳이 포함해 보려면 --include-subagents.

   ⚠️ 수치는 스크립트 출력을 그대로 인용하라. 세션 수·Token Waste Score·패턴 카운트를 Claude가 직접 세거나 어림·재계산하지 말 것 — ls로 파일 개수를 추측하거나 대화 기반으로 점수를 지어내면 CLI와 다른 가짜 숫자가 나온다. 스킬의 역할은 그 숫자에 해석·코칭을 얹는 것이지 숫자를 만드는 게 아니다. 수치 SSOT = habit_scan.py 표준출력. (단, 세션 수·점수가 실행 시점과 --days 범위에 따라 달라지는 것은 정상 — 로그는 계속 쌓인다. 비교하려면 같은 범위로 같은 시각에 돌려라.)

1. 세션 위생 점검 (현재 대화를 정성 보강할 때)

   • 작업 주제가 2개 이상 섞여 있나? → H1-01 / H1-04 → /clear
   • 같은 이슈로 3턴 이상 보정 중인가? → H1-02 → /compact "실패 제외" 또는 /rewind
   • 세션이 길어지고 컨텍스트가 무거운데 compact 미실행? → H1-03 → /compact [포커스]

2. 반복 입력 점검

   • 같은 파일이 반복 읽혔나? → H2-01 → 재읽기 없이 컨텍스트 내 참조 유도
   • 수천 줄 로그가 통째로 붙여넣어졌나? → H2-02 → 30줄 선별 또는 PreToolUse 훅 설정
   • 세션 첫 메시지가 프로젝트 설명인가? → H7-01 → /init + CLAUDE.md 작성

3. 프롬프트 습관 점검

   • "전반적으로", "파악해줘" 같은 열린 탐색을 메인에서 직접 시켰나? → H5-02 / H8-01 → 서브에이전트로 위임
   • "다시 짜줘"로 전체 재생성을 유발했나? → H6-01 → 줄 번호 범위 명시
   • 단순 작업에 "깊이 분석해줘"를 썼나? → H4-02 → "1줄로만. 이유 생략."
   • "혹시 몰라서" 파일을 여러 개 붙였나? → H2-05 → 경로만 알려주고 필요하면 읽게 두기

4. 라우팅·지불 점검 (CLI가 잡거나, 아예 못 잡는 축)

   • 기간 내 모델이 100% 최상위 티어인가? → H4-04 → 작업 성격별로 티어를 정해 새 세션에서 시작. 린트·포맷·리네임은 모델 없이 도구로
   • 세션 중 모델·MCP·플러그인을 토글했나? → H4-03 → 구성 변경은 세션 시작 전에
   • 구독을 몇 개 결제 중인가? 그중 최근 30일 실사용 0인 것은? → H9-01 → 해지. CLI가 절대 못 잡는 축이니 진단 때 반드시 말로 물어라 — 토큰을 아무리 줄여도 미사용 구독료는 그대로 나간다

출력 형식:

발견된 낭비 패턴: [패턴명] — [관찰 신호] → 즉시 fix: [커맨드]
지금 당장 실행: 1. [액션] 2. [액션]
이후 세션에서 바꿀 습관: - [습관]

상세 체크리스트 → references/session_coach_checklist.md

MODE 2: HABIT CATALOG — 토큰 새는 습관 카탈로그

트리거: "토큰 새는 습관 알려줘", "어떤 습관이 낭비야", "전체 패턴 보여줘"

9카테고리 31패턴을 빠르게 훑는 자각 카탈로그. (R1 14 + R2 13 → 중복 통합 24, v1.1 거대 디렉토리 차단(H3-04) → 25, v1.2 최신 기능 신규 3(H2-04·H3-05·H8-03) → 28, v1.3 비용 라우팅 신규 3(H2-05·H4-04·H9-01) → 31.)

전체 31패턴 상세(무의식 시나리오·왜 새는가·자각신호·고치는습관·절감추정) → references/habit_catalog.md CLI 자동감지(JSONL 사후 스캔)는 31패턴 중 11개: H1-01·H1-03·H2-01·H2-02·H2-04·H4-03·H4-04·H5-04·H8-01·H8-02·H8-03 → tokenhabit CLI 또는 scripts/habit_scan.py H9는 토큰 로그에 흔적이 없다 — 자가점검 전용. CLI가 조용하다고 새지 않는 게 아니다.

낭비 수치는 근거가 셋으로 갈린다. 뭉개지 말 것.

• 실측(observed) — 로그의 토큰 카운터 그대로: H4-03(전환 직후 cache_creation), H1-03(usage 기반 컨텍스트 초과분)
• 환산(estimated) — 실제 내용이지만 문자 수를 토큰으로 변환: H2-02·H8-02
• 추정(heuristic) — 시나리오 상수 × 횟수: H2-01·H5-04·H8-01
• 신호(signal) — 세지만 Waste Score 미합산: H1-01·H2-04·H4-04·H8-03. 장시간 세션·웹 툴·서브에이전트·상위 티어는 그 자체로 낭비가 아니다

v1.3.0은 H2-02·H8-02를 "실측"으로 잘못 표기했고 v1.3.1에서 정정했다. 사용자에게 설명할 때 환산과 실측을 같은 말로 쓰지 마라.

MODE 3: PROMPT FIX — 프롬프트 토큰 효율화

트리거: "프롬프트 고쳐줘", "이 요청 더 효율적으로 쓰는 법", "before/after 보여줘"

모호·광범위·재작업 유발 프롬프트를 토큰 효율적으로 다시 쓰는 before/after 가이드.

3대 원칙:

1. 위치 + 완료 기준 명시

   Before: "성능 개선해줘"
   After:  "@src/api/search.ts의 fetchUser 함수. N+1 의심. 수정 후 기존 테스트 통과 여부 확인."
   

2. 범위 제한 명시

   Before: "이 코드 다시 써줘"
   After:  "35~42줄에만 try/catch 추가. 나머지는 그대로. diff만 보여줘."
   

3. 출력 범위 명시

   Before: "이 함수 설명해줘"
   After:  "이 함수 목적을 2줄로만. 코드·예시 없이."
   

CLAUDE.md에 넣으면 전 세션에 영속 적용되는 출력 기본값:

# 응답 기본값
- 코드 설명: 3줄 이하. 추가 요청 시에만 확장.
- 분석 보고: 핵심 포인트 불릿 3개 이하.
- 불필요한 서론·배경 생략.
- 파일 전체 재출력 금지 — 수정된 부분 diff만.

MODE 4: HABIT GUARD — 런타임 자가점검 룰

트리거: "습관 가드 알려줘", "매 작업에서 체크할 것"

어시스턴트가 매 작업에서 self-check하는 런타임 행동 룰 (hook 없이 행동 가이드).

설계자 관점(모델 티어·멀티에이전트·캐싱·SKILL.md 비대화) → tokensave 스킬을 쓰라.

참고 자료

references/
├── habit_catalog.md             9카테고리 31패턴 전체 (무의식 시나리오·자각신호·fix·절감추정)
├── session_coach_checklist.md   MODE 1 진단 체크리스트 (관찰신호 → 패턴 → 즉시 fix 매핑)
└── measurement_and_hooks.md     탐지 규칙·측정 방법·공식 수치 표·hook 설치법

scripts/
├── habit_scan.py                진단 본체 진입점 (로직은 _vendor/tokenhabit/ 에 있음)
├── hook_check.py                MODE 4 런타임 훅 (stderr 경고만, 차단 없음)
├── sync_vendor.py               tokenhabit/ → _vendor/ 동기화 (--check 는 CI 용)
└── _vendor/tokenhabit/          레포 루트 tokenhabit/ 패키지의 사본 (직접 편집 금지)

로직 SSOT는 레포 루트 tokenhabit/ 패키지 하나다. scripts/habit_scan.py는 얇은 진입점이고, _vendor/는 pip 설치 없이도 스킬이 돌게 하려고 둔 복사본이다. 탐지 규칙을 고칠 일이 생기면 tokenhabit/을 고치고 python3 scripts/sync_vendor.py를 돌려라 — 사본을 직접 손대면 CLI와 스킬의 숫자가 갈라진다.