# 토큰 절감 시스템 전면 적용 (공식 문서 기반 12건)

## 작업 개요
Claude Code 공식 문서(https://code.claude.com/docs/en/costs#reduce-token-usage)에서 도출된 미적용 토큰 절감 기법 12건을 시스템에 적용한다.
문서화 + 코드화 + 시스템화까지 완료.

## 적용 항목 (12건)

### 항목 1: 커스텀 압축 지시 (CLAUDE.md)
- **현재**: Compact instructions 섹션 없음
- **적용**: 아누 CLAUDE.md(`/home/jay/.cokacdir/workspace/autoset/CLAUDE.md`)에 Compact instructions 섹션 추가
- **내용**: "compact 시 task ID, 팀 배정, 제이회장님 피드백, 진행 중 작업 상태를 우선 보존"
- 각 프로젝트 CLAUDE.md에도 해당 프로젝트에 맞는 compact 지시 추가

### 항목 2: CLAUDE.md → Skills 분리
- **현재**: CLAUDE.md에 위임 규칙, QC 규칙, 작업 레벨 판정 등 상세 내용 포함 → 매 세션 토큰 소비
- **적용**: 특정 워크플로우 지시를 `/home/jay/.claude/commands/` 스킬로 분리
  - 위임 규칙 상세 → `/home/jay/.claude/commands/dispatch-rules.md`
  - QC 규칙 상세 → `/home/jay/.claude/commands/qc-rules.md`
  - 작업 레벨 판정 상세 → `/home/jay/.claude/commands/work-level.md`
- CLAUDE.md에는 핵심 원칙 + 스킬 참조만 유지 (200줄 이하 목표)

### 항목 3: MCP 서버 정리
- **현재**: 어떤 MCP 서버가 등록되어 있는지 미점검
- **적용**: `/home/jay/.claude/settings.json`의 mcpServers 섹션 확인
  - 미사용 서버 비활성화
  - 대안 CLI 도구가 있는 경우 CLI 우선 사용 가이드 작성

### 항목 4: 테스트 출력 필터링 훅
- **현재**: 테스트 실행 시 전체 출력이 컨텍스트에 들어감
- **적용**: PreToolUse 훅 추가 — pytest/npm test 등 감지 시 FAIL/ERROR만 필터링
- **파일**: `/home/jay/workspace/hooks/filter-test-output.sh`
- **등록**: `settings.json`의 hooks.PreToolUse에 Bash 매처로 추가
- 공식 문서 예제 코드 참고

### 항목 5: Extended Thinking 예산 조정
- **현재**: 기본값 사용 (수만 토큰/요청)
- **적용**: 단순 작업용 thinking 예산 제한 검토
  - dispatch.py에서 작업 레벨별 thinking 예산 차등 설정 가능성 분석
  - Lv.0~1: `MAX_THINKING_TOKENS=8000`
  - Lv.2+: 기본값 유지
  - 설정 방법: 환경변수 또는 settings.json

### 항목 6: `/cost` 상시 모니터링 (status line)
- **적용**: settings.json에 status line 설정 추가
  - 컨텍스트 윈도우 사용량 상시 표시
  - 참고: https://code.claude.com/docs/en/statusline#context-window-usage

### 항목 7: 세션 종료 규칙 강화
- **현재**: 팀 봇이 작업 완료 후 세션 유지 → 불필요한 컨텍스트 누적
- **적용**: dispatch.py 위임 프롬프트에 "작업 완료 후 /clear 불필요한 컨텍스트 정리" 규칙 추가
- DIRECT-WORKFLOW.md에 "작업 완료 → 보고서 작성 → .done 생성 → 세션 종료" 명시

### 항목 8: LSP 활용 권장 명시
- **현재**: `ENABLE_LSP_TOOL=1` 설정됨 but 팀 봇에 활용 가이드 없음
- **적용**: 위임 지시서 템플릿에 "코드 탐색 시 LSP(go-to-definition, find-references) 우선 사용. grep보다 효율적" 명시

### 항목 9: 구체적 프롬프트 규칙 강화
- **적용**: dispatch 지시서 템플릿에 필수 항목 추가
  - "대상 파일 경로 (필수)"
  - "구체적 변경 사항 (필수)"
  - "모호한 지시 금지 — 'improve' 대신 구체적 행동 동사 사용"

### 항목 10: 서브에이전트 haiku 모델 적용 ⚠️ 신중 검토 필요
- **목표**: 단순 서브에이전트에 `model: haiku` 적용하여 비용 3-5배 절감
- **신중 검토 기준**:
  1. 현재 팀 봇의 서브에이전트(Task tool) 사용 패턴 분석
  2. 어떤 작업이 "단순"인지 명확한 기준 수립
  3. haiku 적용 시 품질 저하 위험 평가
  4. **적용 가능 후보**: 파일 읽기/검색, grep/find, 테스트 실행, 단순 파일 수정
  5. **적용 불가 후보**: 코드 설계, 리서치, 보고서 작성, 디자인 관련
  6. 다각도 분석 후 안전한 agent만 선별 적용
  7. 적용 후 품질 모니터링 방안 제시

### 항목 11: Plan 모드 활용 규칙
- **적용**: DIRECT-WORKFLOW.md에 "Lv.2+ 작업은 구현 전 plan 모드로 접근법 제안 → 확인 후 구현" 추가
- dispatch.py에서 작업 레벨 기반 plan 모드 권장 메시지 추가

### 항목 12: 점진적 테스트 규칙
- **적용**: QC-RULES.md에 "파일 단위 점진적 테스트 — 전체 작성 후 일괄 테스트 금지" 추가

## 문서화 요구사항
- `/home/jay/workspace/memory/specs/token-reduction-guide.md` 작성
  - 12개 항목 상세 설명 + 적용 현황 + 효과 예상치
- 각 적용 항목에 대한 before/after 비교

## 코드화/시스템화 체크리스트
- [ ] CLAUDE.md compact instructions 추가
- [ ] CLAUDE.md → Skills 분리 (3개 스킬)
- [ ] MCP 서버 점검 + 미사용 비활성화
- [ ] filter-test-output.sh 훅 생성 + 등록
- [ ] thinking 예산 분석 + 설정
- [ ] status line 설정
- [ ] 세션 종료 규칙 WORKFLOW 반영
- [ ] LSP 활용 가이드 WORKFLOW 반영
- [ ] 구체적 프롬프트 규칙 template 반영
- [ ] haiku 서브에이전트 다각도 분석 + 선별 적용
- [ ] plan 모드 규칙 WORKFLOW 반영
- [ ] 점진적 테스트 규칙 QC-RULES 반영
- [ ] 통합 가이드 문서 작성

## 완료 기준
- 12건 모두 적용 (항목 10은 안전한 agent만 선별)
- 기존 시스템 동작 영향 없음
- 통합 가이드 문서 작성 완료
- 각 설정 변경에 대한 rollback 방법 명시

## 파일 목록 (수정/생성 대상)
- `/home/jay/.cokacdir/workspace/autoset/CLAUDE.md` — compact instructions + skills 참조
- `/home/jay/.claude/settings.json` — hooks, status line, MCP
- `/home/jay/.claude/commands/dispatch-rules.md` — 신규 스킬
- `/home/jay/.claude/commands/qc-rules.md` — 신규 스킬
- `/home/jay/.claude/commands/work-level.md` — 신규 스킬
- `/home/jay/workspace/hooks/filter-test-output.sh` — 신규 훅
- `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md` — 규칙 추가
- `/home/jay/workspace/prompts/team_prompts.py` — 지시서 템플릿 강화
- `/home/jay/workspace/teams/shared/QC-RULES.md` — 규칙 추가
- `/home/jay/workspace/memory/specs/token-reduction-guide.md` — 신규 가이드