| name | tokenhabit |
| description | 무의식중에 토큰을 태우는 대화·사용 습관(9카테고리 31패턴)을 자각시키고 고치는 사용자 코칭 스킬. 한국어명: 토큰 습관 / 세션 다이어트. tokensave가 하네스·빌더 설계를 감사한다면, tokenhabit은 운전자(사용자)의 대화 습관을 코칭한다 — 이 두 스킬은 렌즈가 전혀 다르다. 트리거 문구: "토큰 습관", "tokenhabit", "토큰햅빗", "habit scan", "세션 다이어트", "토큰 낭비 점수", "Token Waste Score", "왜 이렇게 토큰을 많이 써", "내가 토큰을 낭비하는 습관", "세션이 너무 길어졌어", "대화가 너무 쌓였어", "/clear 언제 해야 해", "토큰 새는 습관 알려줘", "이 세션 토큰 진단", "대화 토큰 아끼는 법", "프롬프트 잘 못 쓰는 것 같아", "compact 언제 써야 해", "컨텍스트 꽉 찼어", "auto-compact 자꾸 떠", "사용량 한도 자꾸 걸려", "내 사용 습관 때문에 요금 많이 나오나", "어떤 모델로 돌려야 아껴", "why am I burning tokens", "token diet", "am I wasting tokens". 후속 작업 트리거: "패턴 더 알려줘", "습관 점검", "프롬프트 고쳐줘", "진단 다시 해줘", "구독 정리". |
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개. 이것만 바꿔도 세션 비용을 크게 줄일 수 있다.
| # | 습관 | 즉시 fix |
|---|
| 1 | 작업이 바뀌면 /clear — 다른 주제로 넘어갈 때 이전 컨텍스트를 그냥 끌고 간다 | 작업 전환마다 /clear. 돌아올 세션은 /rename으로 이름 붙여두고 나중에 claude --resume(CLI) 또는 /resume(인터랙티브)으로 복귀 |
| 2 | 로그·에러는 30줄만 — 빌드 로그 전체를 Ctrl+V로 붙여넣는다 | 에러 핵심 20~30줄만 선별. 파일 저장 후 경로만 전달 |
| 3 | 프롬프트에 파일 경로·완료 기준 명시 — "이 코드 좀 고쳐줘"처럼 모호하게 요청한다 | @src/auth.ts 35~42줄 try/catch 추가. 나머지는 그대로. |
| 4 | CLAUDE.md에 반복 입력을 1회만 작성 — 매 세션마다 스택·규칙을 손으로 다시 입력한다 | /init → CLAUDE.md 작성. 반복 워크플로우는 .claude/skills/로 영속화 |
| 5 | 탐색은 "서브에이전트로 해줘" — 메인 세션에서 "파악해줘"를 시킨다 | "서브에이전트로 src/auth/ 탐색 후 함수명·위치만 요약해줘" |
4가지 모드
MODE 1: SESSION COACH — 세션 토큰 진단
트리거: "이 세션 토큰 진단", "왜 토큰을 많이 써", "지금 세션 어때", "내 토큰 습관 진단", "전체 세션 진단", "새 세션에서 진단", "토큰 습관 봐줘"
철칙 — 반드시 준수. 진단 요청을 받으면 현재 대화만 보고 단정하지 말고, 먼저 scripts/habit_scan.py(설치본 tokenhabit CLI)를 실행한다. 범위는 사용자가 선택 — 전체 누적(--days N) 또는 이 세션만(--current).
새 세션이라 현재 대화가 비어 있어도 절대 "진단할 내용이 없다"고 답하지 말 것. 진단의 단일 진실 원천(SSOT)은 현재 대화가 아니라 디스크에 영속된 세션 로그(~/.claude/projects/**/*.jsonl)다 — 세션이 종료돼도 jsonl은 남으므로 끝난 세션도 진단 대상이다. 현재 대화 직접 관찰(아래 1~3번)은 --current 결과를 정성적으로 보강하는 보조 단계일 뿐, 그것만으로 "내용 없음" 판정 금지.
진단 절차 (순서대로):
-
[필수·먼저 실행] 진단 범위를 정하고 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 범위에 따라 달라지는 것은 정상 — 로그는 계속 쌓인다. 비교하려면 같은 범위로 같은 시각에 돌려라.)
-
세션 위생 점검 (현재 대화를 정성 보강할 때)
- 작업 주제가 2개 이상 섞여 있나? → H1-01 / H1-04 →
/clear
- 같은 이슈로 3턴 이상 보정 중인가? → H1-02 →
/compact "실패 제외" 또는 /rewind
- 세션이 길어지고 컨텍스트가 무거운데 compact 미실행? → H1-03 →
/compact [포커스]
-
반복 입력 점검
- 같은 파일이 반복 읽혔나? → H2-01 → 재읽기 없이 컨텍스트 내 참조 유도
- 수천 줄 로그가 통째로 붙여넣어졌나? → H2-02 → 30줄 선별 또는 PreToolUse 훅 설정
- 세션 첫 메시지가 프로젝트 설명인가? → H7-01 →
/init + CLAUDE.md 작성
-
프롬프트 습관 점검
- "전반적으로", "파악해줘" 같은 열린 탐색을 메인에서 직접 시켰나? → H5-02 / H8-01 → 서브에이전트로 위임
- "다시 짜줘"로 전체 재생성을 유발했나? → H6-01 → 줄 번호 범위 명시
- 단순 작업에 "깊이 분석해줘"를 썼나? → H4-02 → "1줄로만. 이유 생략."
- "혹시 몰라서" 파일을 여러 개 붙였나? → H2-05 → 경로만 알려주고 필요하면 읽게 두기
-
라우팅·지불 점검 (CLI가 잡거나, 아예 못 잡는 축)
- 기간 내 모델이 100% 최상위 티어인가? → H4-04 → 작업 성격별로 티어를 정해 시작. 린트·포맷·리네임은 모델 없이 도구로
출력 형식:
발견된 낭비 패턴: [패턴명] — [관찰 신호] → 즉시 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.)
| 카테고리 | 패턴 수 | 대표 습관 | 절감 레버 |
|---|
| H1 세션 위생 | 4개 | 작업 전환 시 /clear 안 함 | 2~5× |
| H2 반복 입력 | 5개 | 로그 전체 덤프, 파일 재읽기, 웹 결과 방치, 보험성 첨부 | 90~99%+ |
| H3 상시 주입 | 5개 | 과비대 CLAUDE.md, MCP 상시 연결, 거대 디렉토리·스킬/플러그인 과다 | 세션당 고정 절감 |
| H4 Thinking·모델 | 4개 | 단순 작업에 높은 effort, 캐시 킬, 최상위 티어 고정 주행 | 5~12.5× |
| H5 프롬프트 명료성 | 4개 | 안개 프롬프트, 무제한 탐색 요청 | 40~95% |
| H6 재작업 루프 | 2개 | 전체 재생성 요청, 반복 검증 | 90% |
| H7 영속화 미활용 | 3개 | 매 세션 맥락 재타이핑, 출력 휘발 | 세션간 재생성 제거 |
| H8 컨텍스트 오염 | 3개 | 메인 스레드 탐색, stdout 홍수, 서브에이전트 남발 | 90~99%+ |
| H9 지불 습관 | 1개 | 구독 3개 중 실제로 쓰는 건 하나 | 미사용 구독료 전액 |
전체 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대 원칙:
-
위치 + 완료 기준 명시
Before: "성능 개선해줘"
After: "@src/api/search.ts의 fetchUser 함수. N+1 의심. 수정 후 기존 테스트 통과 여부 확인."
-
범위 제한 명시
Before: "이 코드 다시 써줘"
After: "35~42줄에만 try/catch 추가. 나머지는 그대로. diff만 보여줘."
-
출력 범위 명시
Before: "이 함수 설명해줘"
After: "이 함수 목적을 2줄로만. 코드·예시 없이."
CLAUDE.md에 넣으면 전 세션에 영속 적용되는 출력 기본값:
# 응답 기본값
- 코드 설명: 3줄 이하. 추가 요청 시에만 확장.
- 분석 보고: 핵심 포인트 불릿 3개 이하.
- 불필요한 서론·배경 생략.
- 파일 전체 재출력 금지 — 수정된 부분 diff만.
MODE 4: HABIT GUARD — 런타임 자가점검 룰
트리거: "습관 가드 알려줘", "매 작업에서 체크할 것"
어시스턴트가 매 작업에서 self-check하는 런타임 행동 룰 (hook 없이 행동 가이드).
| # | 룰 | 발동 조건 |
|---|
| 1 | 로그 덤프 전 필터 — stdout 전체를 컨텍스트에 올리기 전 에러 30줄만 선별한다 | Bash 툴로 빌드·테스트 실행 전 |
| 2 | 탐색은 서브에이전트로 — "파악해줘", "분석해줘" 요청은 메인이 아닌 서브에이전트로 격리한다 | 범위 미지정 탐색 요청 감지 시 |
| 3 | 2회 실패 후 컨텍스트 리셋 제안 — 같은 이슈로 2번 보정이 실패하면 /compact(실패 접근법 제외) 또는 /rewind(Esc+Esc)를 권유한다. /rewind는 대화만/코드만/둘다 복원 + "Summarize from/up to here"식 부분 요약 옵션을 제공하므로, 전체 압축 대신 실패 지점 기준 부분 압축이 가능하다 | 보정 2회 연속 실패 감지 시 |
| 4 | 작업 완료 후 /clear 권유 — 주제가 다른 새 작업을 시작하려는 신호가 보이면 먼저 /clear 를 제안한다 | 작업 전환 신호 감지 시 |
| 5 | 단순 작업 = 짧은 응답 — "변수명 바꿔줘", "한 줄 수정" 같은 단순 요청에는 thinking 없이 1~3줄로만 응답한다 | 단순 결정·수정 요청 감지 시 |
| 6 | 산출물은 파일로 — 분석·계획·스펙 결과는 파일(ANALYSIS.md, PLAN.md)로 저장하도록 권유한다 | 중간 산출물 생성 시 |
| 7 | 재읽기 전 컨텍스트 확인 — 이미 이 세션에서 읽은 파일을 다시 Read 요청받으면 컨텍스트 내 참조를 먼저 시도한다. 단 offset/limit로 나눠 읽는 것은 정상이므로 경고하지 않는다 | 파일 Read 요청 시 |
| 8 | 결정적 작업은 모델 없이 — 린트·포맷·리네임·정형 변환은 LLM이 아니라 도구(ruff format, eslint --fix, LSP rename)로 처리하도록 먼저 제안한다 | 기계적 편집 요청 감지 시 |
| 9 | 구성 변경은 세션 밖에서 — 작업 도중 MCP 서버·플러그인·모델 전환을 요청받으면 그것이 프롬프트 캐시 전체를 무효화함을 알리고, 새 세션에서 하도록 권한다 | 세션 중 구성 변경 신호 감지 시 |
설계자 관점(모델 티어·멀티에이전트·캐싱·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와 스킬의 숫자가 갈라진다.
