claude-distill 0.4.0 → 0.4.1

package/README.md

@@ -1,5 +1,7 @@
 # claude-distill
 
+> **한 줄 요약** — Claude를 매일 새로 출근하는 알바생이라고 생각해보세요. 어제 가르친 요령을 오늘도 똑같이 다시 설명해야 합니다. `claude-distill`은 어제 배운 걸 **자동으로 인수인계 노트에 적어두는 도구**예요. 다음 날의 Claude가 출근하자마자 그 노트를 읽고 시작하니까, 같은 설명을 두 번 할 필요가 없습니다.
+
 > Claude한테 같은 함정을 세 번째 설명하고 계신가요?
 
 세션마다 트레이드오프 결정 (`A 대신 B 선택, 이유는…`), 환경 함정 (`Cursor webview는 confirm() 차단됨`), 같은 실수 (`Claude Code JSONL의 promptId는 항상 null`)가 쌓입니다. 그런데 세션이 끝나면 다 잊혀집니다. CLAUDE.md를 매번 갱신하면 좋겠지만 — 솔직히 안 하죠.
@@ -12,6 +14,40 @@
 
 사용자가 하는 일: `claude-distill init` **한 번. 끝.**
 
+### 한눈에 보기 — 설치 전 vs 설치 후
+
+```
+설치 전:
+  1번째 대화  →  주의할 점 발견 ❌  →  "Claude야, 이거 주의해"
+  2번째 대화  →  같은 주의할 점 ❌  →  "Claude야, 이거 주의해"      (또?)
+  3번째 대화  →  같은 주의할 점 ❌  →  "Claude야, 이거 주의해"      (세 번째…)
+                                       └─ 대화마다 기억이 리셋, 영원히 반복
+
+설치 후 (claude-distill init 한 번):
+  1번째 대화  →  주의할 점 발견 ❌  →  자동으로 인수인계 노트에 기록
+  2번째 대화  →  Claude가 이미 알고 시작 ✓  (출근하자마자 노트 읽음)
+  3번째 대화  →  Claude가 이미 알고 시작 ✓
+                                       └─ 한 번 배우면 모든 미래 대화가 공유
+```
+
+```mermaid
+flowchart LR
+    A[당신이 Claude와 대화] -->|대화 끝| B[자동으로 분석 시작]
+    B --> C{쓸 만한 배움이<br/>있었나?}
+    C -->|없음| X[조용히 종료<br/>비용 0원]
+    C -->|있음| D[AI가 핵심만 추출]
+    D --> E[인수인계 노트에 추가<br/>판례 / 사고 기록]
+    E -.다음 대화 시작 시<br/>Claude가 자동으로 읽음.-> F[다음 대화는<br/>'이미 아는 상태'로 시작]
+    F -.대화 끝나면 또.-> A
+    style F fill:#d4edda
+    style E fill:#fff3cd
+    style X fill:#f8f9fa
+```
+
+> **용어**:
+> - "인수인계 노트" = `~/.claude/knowledge.md` (판례) / `~/.claude/gotchas.md` (사고). 그냥 markdown 파일이라 직접 열어보고 편집 가능합니다.
+> - "AI가 핵심만 추출" = Claude(Sonnet 또는 Haiku)가 대화 내용을 요약. 거의 모든 대화는 "쓸 만한 배움 없음"으로 분류돼 비용 0원으로 종료.
+
 부담 없는 이유:
 - **별도 서버 / 계정 없음** — 본인 머신 → Anthropic API 직통. distill 운영자한테도 transcript 안 감
 - **의존성 0개, 50KB 미만** — [GitHub](https://github.com/parksubeom/claude-distill)에서 코드 그대로 검수
@@ -50,6 +86,27 @@
 
 법률은 사람이 쓰지만, 판례와 사고 보고서는 매일 쌓이는 거니까 — 그건 자동화될 수 있습니다.
 
+```
+   ┌──────────────────────────────────────────┐
+   │  ~/.claude/CLAUDE.md  (법률 — 사람이 작성)│
+   │                                          │
+   │    @~/.claude/knowledge.md  ─────────────┼──┐
+   │    @~/.claude/gotchas.md    ─────────────┼──┤
+   └──────────────────────────────────────────┘  │
+                    ▲                            │
+                    │ Claude가 매 대화 시작 시   │ 자동 로드
+                    │ 자동으로 위 파일들을 읽음  │
+                    │                            │
+                    │   ┌────────────────────────┘
+                    │   ▼
+              ┌─────┴───────────────────┐
+              │  knowledge.md  (판례)   │ ← claude-distill이
+              │  gotchas.md    (사고)   │   대화 끝마다 자동 추가
+              └─────────────────────────┘
+```
+
+`claude-distill init` 한 번이 위 그림의 **`@reference` 두 줄**을 `CLAUDE.md`에 자동 등록 → 그 후 매 대화 끝마다 distill이 노트에 자동 추가 → 다음 대화가 시작될 때 Claude가 자동으로 읽음.
+
 ---
 
 ## 설치
@@ -92,7 +149,9 @@ source ~/.zshrc
 
 ---
 
-## 어떻게 동작
+## 어떻게 동작 (내부 파이프라인 — 개발자용)
+
+> 비개발자라면 위의 플로우차트만 보셔도 충분합니다. 아래는 내부를 검수하고 싶은 분을 위한 상세 단계.
 
 ```
 세션 끝

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-distill",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Distill knowledge and gotchas from Claude Code session transcripts. Hook-based feedback loop: session → extract → review → accumulate.",
   "bin": {
     "claude-distill": "bin/distill.js",