aiwf 0.3.22 → 0.4.0

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

@@ -1,313 +0,0 @@
-[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와의 효율적인 협업을 위한 필수 도구입니다. 각 모드의 특성을 이해하고 작업에 맞는 모드를 선택하면, 토큰 제한 없이 대규모 프로젝트에서도 원활한 개발이 가능합니다.
-
-지속적인 사용을 통해 여러분의 프로젝트에 최적화된 압축 전략을 개발하시기 바랍니다.

package/docs/guides/context-compression-guide.md

@@ -1,313 +0,0 @@
-[Read in Korean (한국어로 보기)](context-compression-guide-ko.md)
-
-# Context Compression Mode User Guide
-
-## Overview
-
-The Context Compression feature optimizes token usage in conversations with Claude Code, enabling longer conversations and processing of more information. Through 3 compression modes, you can select the optimal compression strategy suited to your project characteristics and work requirements.
-
-## Need for Compression
-
-### Token Limitation Issues
-- Claude Code has per-conversation token limits
-- Context overflow frequent when working with large codebases
-- Possible information loss in long conversation sessions
-
-### Benefits of Context Compression
-- Average token usage reduction of 50% or more
-- Simultaneous processing of more files and information
-- Improved conversation continuity
-- Increased cost efficiency
-
-## Compression Mode Details
-
-### 1. Aggressive Mode
-
-**Compression Rate**: 70-80%  
-**Quality Loss**: Medium-High  
-**Processing Speed**: Fast
-
-**Characteristics**:
-- Maximum token savings
-- Retains only core information
-- Some loss of details and context
-- Uses short and concise expressions
-
-**Compression Strategy**:
-- Remove comments and documentation
-- Summarize repetitive code patterns
-- Shorten variable names
-- Minimize whitespace and formatting
-- Remove duplicate information
-
-**Suitable Situations**:
-- Exploring very large codebases
-- When general understanding is needed
-- Fast prototyping
-- When token budget is very limited
-
-**Usage Example**:
-```bash
-/project:aiwf:compress_context:aggressive
-# or
-/프로젝트:aiwf:컨텍스트_압축:공격적
-```
-
-### 2. Balanced Mode
-
-**Compression Rate**: 50-60%  
-**Quality Loss**: Low  
-**Processing Speed**: Medium
-
-**Characteristics**:
-- Balance between compression rate and quality
-- Preserves important information
-- Maintains readability
-- Ensures structural integrity
-
-**Compression Strategy**:
-- Clean up duplicate comments
-- Summarize long descriptions
-- Remove unused code
-- Smart whitespace management
-- Context-based compression
-
-**Suitable Situations**:
-- General development tasks
-- Code review and analysis
-- Bug fixing tasks
-- Feature implementation and modification
-
-**Usage Example**:
-```bash
-/project:aiwf:compress_context:balanced
-# or
-/프로젝트:aiwf:컨텍스트_압축:균형
-```
-
-### 3. Conservative Mode
-
-**Compression Rate**: 30-40%  
-**Quality Loss**: Very Low  
-**Processing Speed**: Slow
-
-**Characteristics**:
-- Minimal information loss
-- Preserves all important details
-- High similarity to original
-- Enables precise work
-
-**Compression Strategy**:
-- Remove only obvious duplicates
-- Maintain formatting
-- Preserve comments and documentation
-- Keep meaningful whitespace
-- Apply only safe compression
-
-**Suitable Situations**:
-- Precise debugging
-- Security audits
-- Performance optimization
-- Working with critical production code
-
-**Usage Example**:
-```bash
-/project:aiwf:compress_context:conservative
-# or
-/프로젝트:aiwf:컨텍스트_압축:보수적
-```
-
-## Mode Selection Guide
-
-### Decision Tree
-
-```
-What's the nature of the task?
-├─ Exploration/Overview → Aggressive
-├─ General development → Balanced
-└─ Precise/Critical work → Conservative
-
-Token budget?
-├─ Very limited → Aggressive
-├─ Normal → Balanced
-└─ Abundant → Conservative
-
-Required information level?
-├─ Overview only → Aggressive
-├─ Main logic → Balanced
-└─ All details → Conservative
-```
-
-### Recommended Mode by Task Type
-
-| Task Type | Recommended Mode | Reason |
-|-----------|------------------|--------|
-| Architecture Review | Aggressive | Overall structure understanding important |
-| Bug Fixing | Balanced | Need balance of context and details |
-| Performance Optimization | Conservative | All details important |
-| Code Refactoring | Balanced | Need to maintain structure while improving |
-| Security Audit | Conservative | Can't miss any details |
-| Documentation Generation | Aggressive | Only core functionality needed |
-| Test Writing | Balanced | Need to understand main logic |
-
-## Usage Methods
-
-### Basic Command Structure
-```bash
-/project:aiwf:compress_context[:<mode>]
-```
-
-### Usage Examples by Mode
-
-**Compress entire project with Aggressive mode**:
-```bash
-/project:aiwf:compress_context:aggressive
-"Please compress and show all JavaScript files in the src folder"
-```
-
-**Compress specific module with Balanced mode**:
-```bash
-/project:aiwf:compress_context:balanced
-"Please compress and analyze the main logic of the authentication module"
-```
-
-**Compress important file with Conservative mode**:
-```bash
-/project:aiwf:compress_context:conservative
-"Please compress payment.js file minimally and review for security vulnerabilities"
-```
-
-### Advanced Usage
-
-**1. Selective Compression**
-Compress only specific files or directories:
-```bash
-/project:aiwf:compress_context:balanced
-"Please compress only the src/api folder and exclude the tests folder"
-```
-
-**2. Multi-stage Compression**
-Compress large projects in stages:
-```bash
-# Stage 1: Understand overall structure
-/project:aiwf:compress_context:aggressive
-"Please show the overall project structure"
-
-# Stage 2: Detailed analysis of areas of interest
-/project:aiwf:compress_context:balanced
-"Please analyze authentication-related modules in more detail"
-```
-
-**3. Compression Exclusion Settings**
-Exclude important parts from compression:
-```bash
-/project:aiwf:compress_context:aggressive
-"Please compress everything but don't compress security.js"
-```
-
-## Compression Quality Metrics
-
-### Compression Rate Calculation
-```
-Compression Rate = (Original Tokens - Compressed Tokens) / Original Tokens × 100
-```
-
-### Quality Indicators
-
-**Information Preservation Rate**:
-- Aggressive: 60-70%
-- Balanced: 85-90%
-- Conservative: 95-98%
-
-**Structural Integrity**:
-- Aggressive: Basic structure only
-- Balanced: Maintains overall structure
-- Conservative: Complete preservation
-
-**Readability Score**:
-- Aggressive: Low (machine-friendly)
-- Balanced: Medium (developer-friendly)
-- Conservative: High (similar to original)
-
-## Performance Considerations
-
-### Processing Time
-- Aggressive: Fastest (simple rule application)
-- Balanced: Medium (includes context analysis)
-- Conservative: Slow (requires detailed analysis)
-
-### Memory Usage
-- All modes: 1.5-2x original size memory required
-- Large files processed in chunks
-
-### Compression Caching
-- Cache utilization when recompressing same files
-- Cache validity period: 15 minutes
-- Automatic refresh when files change
-
-## Troubleshooting
-
-### Excessive Information Loss
-**Symptoms**: Important information is missing
-**Solutions**:
-1. Change to more conservative mode
-2. Exclude important parts from compression
-3. Use selective compression
-
-### Minimal Compression Effect
-**Symptoms**: Token savings don't meet expectations
-**Solutions**:
-1. Try more aggressive mode
-2. Exclude unnecessary files
-3. Manual cleanup before compression
-
-### Compression Errors
-**Symptoms**: Errors occur during compression
-**Solutions**:
-1. Check file encoding
-2. Review special characters or formats
-3. Compress in smaller units
-
-## Best Practices
-
-### 1. Select Mode Before Starting Work
-- First understand the nature of the task
-- Pre-select appropriate mode
-- Change mid-way if necessary
-
-### 2. Progressive Compression
-- Use staged approach for large projects
-- Start with Aggressive to understand overall
-- Detailed analysis of needed parts with Balanced/Conservative
-
-### 3. Utilize Compression Exclusion
-- Exclude important configuration files
-- Exclude security-related code
-- Exclude complex algorithms
-
-### 4. Mode Combination
-```bash
-# Example: Hybrid approach
-1. Overall structure: Aggressive
-2. Core modules: Balanced
-3. Problem areas: Conservative
-```
-
-## Future Improvements
-
-### Planned Features
-1. **Smart Auto Mode**: AI determines task nature and automatically selects
-2. **Custom Compression Rules**: Project-specific compression settings
-3. **Compression Presets**: Save frequently used settings
-4. **Real-time Compression Preview**: Preview compression results beforehand
-
-### Performance Goals
-- 30% improvement in compression speed
-- 20% reduction in memory usage
-- Additional 10% improvement in compression rate
-
-## Conclusion
-
-The Context Compression feature is an essential tool for efficient collaboration with Claude Code. By understanding the characteristics of each mode and selecting the appropriate mode for your tasks, you can develop smoothly even in large projects without token limitations.
-
-We encourage you to develop compression strategies optimized for your projects through continuous use.