tokenhabit

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 결과를 정성적으로 보강하는 보조 단계일 뿐, 그것만으로 "내용 없음" 판정 금지.

진단 절차 (순서대로):

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 → 작업 성격별로 티어를 정해 시작. 린트·포맷·리네임은 모델 없이 도구로

출력 형식:

발견된 낭비 패턴: [패턴명] — [관찰 신호] → 즉시 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대 원칙:

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 없이 행동 가이드).

#	룰	발동 조건
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와 스킬의 숫자가 갈라진다.