aiwf/docs/guides/context-compression-guide-ko.md

AI Workflow Framework for Claude Code with multi-language support (Korean/English)

[Read in English](context-compression-guide.md)

# Context 압축 모드 사용 가이드

## 개요

Context 압축 기능은 Claude Code와의 대화에서 토큰 사용량을 최적화하여 더 긴 대화와 더 많은 정보를 처리할 수 있도록 돕는 기능입니다. 3가지 압축 모드를 통해 프로젝트의 특성과 작업 요구사항에 맞는 최적의 압축 전략을 선택할 수 있습니다.

## 압축의 필요성

### 토큰 제한 문제
- Claude Code는 대화당 토큰 제한이 있음
- 대규모 코드베이스 작업 시 컨텍스트 초과 빈번
- 긴 대화 세션에서 이전 정보 손실 가능

### Context 압축의 이점
- 토큰 사용량 평균 50% 이상 절감
- 더 많은 파일과 정보 동시 처리
- 대화 지속성 향상
- 비용 효율성 증대

## 압축 모드 상세

### 1. Aggressive (공격적) 모드

**압축률**: 70-80%  
**품질 손실**: 중간-높음  
**처리 속도**: 빠름

**특징**:
- 최대한의 토큰 절약
- 핵심 정보만 유지
- 세부사항과 컨텍스트 일부 손실
- 짧고 간결한 표현 사용

**압축 전략**:
- 주석과 문서화 제거
- 반복 코드 패턴 요약
- 변수명 단축
- 공백과 포맷팅 최소화
- 중복 정보 제거

**적합한 상황**:
- 매우 큰 코드베이스 탐색
- 개괄적인 이해가 필요한 경우
- 빠른 프로토타이핑
- 토큰 예산이 매우 제한적인 경우

**사용 예시**:
```bash
/project:aiwf:compress_context:aggressive
# 또는
/프로젝트:aiwf:컨텍스트_압축:공격적
```

### 2. Balanced (균형) 모드

**압축률**: 50-60%  
**품질 손실**: 낮음  
**처리 속도**: 보통

**특징**:
- 압축률과 품질의 균형
- 중요 정보 보존
- 가독성 유지
- 구조적 무결성 보장

**압축 전략**:
- 중복 주석 정리
- 긴 설명을 요약
- 사용하지 않는 코드 제거
- 스마트 공백 관리
- 컨텍스트 기반 압축

**적합한 상황**:
- 일반적인 개발 작업
- 코드 리뷰와 분석
- 버그 수정 작업
- 기능 구현과 수정

**사용 예시**:
```bash
/project:aiwf:compress_context:balanced
# 또는
/프로젝트:aiwf:컨텍스트_압축:균형
```

### 3. Conservative (보수적) 모드

**압축률**: 30-40%  
**품질 손실**: 매우 낮음  
**처리 속도**: 느림

**특징**:
- 최소한의 정보 손실
- 모든 중요 세부사항 보존
- 원본과 높은 유사성
- 정밀한 작업 가능

**압축 전략**:
- 명백한 중복만 제거
- 포맷팅 유지
- 주석과 문서 보존
- 의미 있는 공백 유지
- 안전한 압축만 적용

**적합한 상황**:
- 정밀한 디버깅
- 보안 감사
- 성능 최적화
- 중요한 프로덕션 코드 작업

**사용 예시**:
```bash
/project:aiwf:compress_context:conservative
# 또는
/프로젝트:aiwf:컨텍스트_압축:보수적
```

## 모드 선택 가이드

### 의사결정 트리

```
작업의 성격은?
├─ 탐색/개요 파악 → Aggressive
├─ 일반 개발 작업 → Balanced
└─ 정밀/중요 작업 → Conservative

토큰 예산은?
├─ 매우 제한적 → Aggressive
├─ 보통 → Balanced
└─ 여유 있음 → Conservative

필요한 정보 수준은?
├─ 개요만 → Aggressive
├─ 주요 로직 → Balanced
└─ 모든 세부사항 → Conservative
```

### 작업별 권장 모드

| 작업 유형 | 권장 모드 | 이유 |
|----------|----------|------|
| 아키텍처 리뷰 | Aggressive | 전체 구조 파악 중요 |
| 버그 수정 | Balanced | 컨텍스트와 세부사항 균형 필요 |
| 성능 최적화 | Conservative | 모든 세부사항 중요 |
| 코드 리팩토링 | Balanced | 구조 유지하며 개선 |
| 보안 감사 | Conservative | 세부사항 놓치면 안됨 |
| 문서 생성 | Aggressive | 핵심 기능만 필요 |
| 테스트 작성 | Balanced | 주요 로직 이해 필요 |

## 사용 방법

### 기본 명령어 구조
```bash
/project:aiwf:compress_context[:<mode>]
```

### 모드별 사용 예시

**Aggressive 모드로 전체 프로젝트 압축**:
```bash
/project:aiwf:compress_context:aggressive
"src 폴더의 모든 JavaScript 파일을 압축해서 보여주세요"
```

**Balanced 모드로 특정 모듈 압축**:
```bash
/project:aiwf:compress_context:balanced
"authentication 모듈의 주요 로직을 압축해서 분석해주세요"
```

**Conservative 모드로 중요 파일 압축**:
```bash
/project:aiwf:compress_context:conservative
"payment.js 파일을 최소한만 압축해서 보안 취약점을 검토해주세요"
```

### 고급 사용법

**1. 선택적 압축**
특정 파일이나 디렉토리만 압축:
```bash
/project:aiwf:compress_context:balanced
"src/api 폴더만 압축하고, tests 폴더는 제외해주세요"
```

**2. 다단계 압축**
큰 프로젝트를 단계적으로 압축:
```bash
# 1단계: 전체 구조 파악
/project:aiwf:compress_context:aggressive
"전체 프로젝트 구조를 보여주세요"

# 2단계: 관심 영역 상세 분석
/project:aiwf:compress_context:balanced
"인증 관련 모듈을 더 자세히 분석해주세요"
```

**3. 압축 제외 설정**
중요한 부분은 압축에서 제외:
```bash
/project:aiwf:compress_context:aggressive
"전체를 압축하되, security.js는 압축하지 마세요"
```

## 압축 품질 메트릭

### 압축률 계산
```
압축률 = (원본 토큰 - 압축 토큰) / 원본 토큰 × 100
```

### 품질 지표

**정보 보존율**:
- Aggressive: 60-70%
- Balanced: 85-90%
- Conservative: 95-98%

**구조 무결성**:
- Aggressive: 기본 구조만
- Balanced: 전체 구조 유지
- Conservative: 완전 보존

**가독성 점수**:
- Aggressive: 낮음 (기계 친화적)
- Balanced: 중간 (개발자 친화적)
- Conservative: 높음 (원본과 유사)

## 성능 고려사항

### 처리 시간
- Aggressive: 가장 빠름 (단순 규칙 적용)
- Balanced: 보통 (컨텍스트 분석 포함)
- Conservative: 느림 (세밀한 분석 필요)

### 메모리 사용량
- 모든 모드: 원본 크기의 1.5-2배 메모리 필요
- 대용량 파일은 청크 단위로 처리

### 압축 캐싱
- 동일 파일 재압축 시 캐시 활용
- 캐시 유효 기간: 15분
- 파일 변경 시 자동 갱신

## 문제 해결

### 과도한 정보 손실
**증상**: 중요한 정보가 누락됨
**해결**:
1. 더 보수적인 모드로 변경
2. 중요 부분 압축 제외
3. 선택적 압축 사용

### 압축 효과 미미
**증상**: 토큰 절약이 기대에 못 미침
**해결**:
1. 더 공격적인 모드 시도
2. 불필요한 파일 제외
3. 압축 전 수동 정리

### 압축 오류
**증상**: 압축 중 오류 발생
**해결**:
1. 파일 인코딩 확인
2. 특수 문자나 형식 검토
3. 작은 단위로 나누어 압축

## 모범 사례

### 1. 작업 시작 전 모드 선택
- 작업 성격을 먼저 파악
- 적절한 모드 미리 선택
- 필요시 중간에 변경

### 2. 점진적 압축
- 큰 프로젝트는 단계적 접근
- Aggressive로 시작해 전체 파악
- 필요 부분만 Balanced/Conservative로 상세 분석

### 3. 압축 제외 활용
- 중요 설정 파일은 제외
- 보안 관련 코드는 제외
- 복잡한 알고리즘은 제외

### 4. 모드 조합
```bash
# 예시: 하이브리드 접근
1. 전체 구조: Aggressive
2. 핵심 모듈: Balanced  
3. 문제 영역: Conservative
```

## 미래 개선사항

### 계획된 기능
1. **스마트 자동 모드**: AI가 작업 성격을 파악해 자동 선택
2. **커스텀 압축 규칙**: 프로젝트별 맞춤 압축 설정
3. **압축 프리셋**: 자주 사용하는 설정 저장
4. **실시간 압축 미리보기**: 압축 결과 사전 확인

### 성능 목표
- 압축 속도 30% 개선
- 메모리 사용량 20% 감소
- 압축률 10% 추가 개선

## 결론

Context 압축 기능은 Claude Code와의 효율적인 협업을 위한 필수 도구입니다. 각 모드의 특성을 이해하고 작업에 맞는 모드를 선택하면, 토큰 제한 없이 대규모 프로젝트에서도 원활한 개발이 가능합니다.

지속적인 사용을 통해 여러분의 프로젝트에 최적화된 압축 전략을 개발하시기 바랍니다.