Skill

---
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". 후속 작업 트리거: "패턴 더 알려줘", "습관 점검", "프롬프트 고쳐줘", "진단 다시 해줘", "구독 정리".
version: 1.3
---

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

| 카테고리 | 패턴 수 | 대표 습관 | 절감 레버 |
|---------|---------|---------|---------|
| 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에 넣으면 전 세션에 영속 적용되는 출력 기본값:**
```markdown
# 응답 기본값
- 코드 설명: 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와 스킬의 숫자가 갈라진다.