aiwf 0.3.1 → 0.3.3

package/docs/guides/ai-personas-guide.md

@@ -0,0 +1,239 @@
+[Read in Korean (한국어로 보기)](ai-personas-guide-ko.md)
+
+# AI Personas User Guide
+
+## Overview
+
+AIWF's AI Persona system is a feature that optimizes Claude Code's behavior patterns according to the characteristics of development tasks. Through 5 specialized personas, you can leverage the most suitable AI assistant for each task.
+
+## Persona Types
+
+### 1. Architect
+**Purpose**: System design and architecture decisions
+
+**Characteristics**:
+- Focus on big picture and overall system structure
+- Prioritize scalability and maintainability
+- Apply design patterns and architectural principles
+- Establish technology stack selection and integration strategies
+
+**Use Cases**:
+- Design phase of new features
+- System refactoring planning
+- Technology stack decisions
+- Inter-module interface design
+
+**Commands**:
+```bash
+/project:aiwf:ai_persona:architect
+# or in Korean
+/프로젝트:aiwf:ai_페르소나:아키텍트
+```
+
+### 2. Debugger
+**Purpose**: Bug detection and problem solving
+
+**Characteristics**:
+- Detailed code analysis and error tracking
+- Step-by-step execution flow verification
+- Consider edge cases and exception scenarios
+- Identify performance bottlenecks
+
+**Use Cases**:
+- Bug reproduction and root cause analysis
+- Performance issue resolution
+- Memory leak tracking
+- Exception handling improvements
+
+**Commands**:
+```bash
+/project:aiwf:ai_persona:debugger
+# or in Korean
+/프로젝트:aiwf:ai_페르소나:디버거
+```
+
+### 3. Reviewer
+**Purpose**: Code quality review and improvement
+
+**Characteristics**:
+- Verify compliance with coding standards
+- Identify security vulnerabilities
+- Find optimization opportunities
+- Evaluate readability and maintainability
+
+**Use Cases**:
+- PR review preparation
+- Code quality improvement
+- Security audits
+- Refactoring suggestions
+
+**Commands**:
+```bash
+/project:aiwf:ai_persona:reviewer
+# or in Korean
+/프로젝트:aiwf:ai_페르소나:리뷰어
+```
+
+### 4. Documenter
+**Purpose**: Documentation writing and management
+
+**Characteristics**:
+- Clear and understandable explanations
+- Automatic API documentation generation
+- Write usage examples and tutorials
+- Support for multilingual documentation
+
+**Use Cases**:
+- README writing
+- API documentation
+- User guide creation
+- Technical specification writing
+
+**Commands**:
+```bash
+/project:aiwf:ai_persona:documenter
+# or in Korean
+/프로젝트:aiwf:ai_페르소나:문서화전문가
+```
+
+### 5. Optimizer
+**Purpose**: Performance optimization and efficiency improvement
+
+**Characteristics**:
+- Algorithm complexity analysis
+- Memory usage optimization
+- Execution time reduction
+- Resource efficiency improvement
+
+**Use Cases**:
+- Performance bottleneck improvements
+- Algorithm optimization
+- Database query improvements
+- Memory usage reduction
+
+**Commands**:
+```bash
+/project:aiwf:ai_persona:optimizer
+# or in Korean
+/프로젝트:aiwf:ai_페르소나:최적화전문가
+```
+
+## How to Switch Personas
+
+### Basic Usage
+1. Select appropriate persona before starting work
+2. Activate persona by entering command
+3. Perform work
+4. Switch to different persona if needed
+
+### Example Workflow
+```bash
+# 1. Design new feature
+/project:aiwf:ai_persona:architect
+"Please design a new user authentication system"
+
+# 2. Debug after implementation
+/project:aiwf:ai_persona:debugger
+"Please solve the issue where session is not maintained during login"
+
+# 3. Code review
+/project:aiwf:ai_persona:reviewer
+"Please review the implemented authentication system code"
+
+# 4. Write documentation
+/project:aiwf:ai_persona:documenter
+"Please write authentication API documentation"
+```
+
+## Context Rules by Persona
+
+Each persona has unique context processing rules:
+
+### Architect Context
+- **Priority**: System design documents, architecture diagrams
+- **Focus**: Interfaces, module structure, dependencies
+- **Exclude**: Implementation details, temporary code
+
+### Debugger Context
+- **Priority**: Error logs, stack traces, test results
+- **Focus**: Execution flow, variable states, conditional statements
+- **Exclude**: Documentation, comments, style-related code
+
+### Reviewer Context
+- **Priority**: Changed code, commit history
+- **Focus**: Coding standards, security patterns, performance impact
+- **Exclude**: Test data, build files
+
+### Documenter Context
+- **Priority**: Public APIs, usage examples, README
+- **Focus**: User perspective, clarity, completeness
+- **Exclude**: Internal implementation, debug code
+
+### Optimizer Context
+- **Priority**: Performance measurement results, profiling data
+- **Focus**: Time complexity, space complexity, resource usage
+- **Exclude**: Documentation, UI code, test code
+
+## Best Practices
+
+### 1. Select Appropriate Persona for Task
+- Choose the most suitable persona considering the nature of the task
+- Switch sequentially when multiple personas are needed for one task
+
+### 2. Persona Switching Timing
+- Switch to appropriate persona when work phase changes
+- Maintain consistency with same persona for same type of tasks
+
+### 3. Context Management
+- Clearly convey previous work results when switching personas
+- Distribute work leveraging each persona's strengths
+
+### 4. Collaboration Scenarios
+```bash
+# Persona utilization in team projects
+1. Architect: Overall system design
+2. Developer: Feature implementation (default mode)
+3. Debugger: Integration testing and bug fixing
+4. Reviewer: Code review and improvements
+5. Documenter: Final documentation
+```
+
+## Troubleshooting
+
+### When Persona Doesn't Work as Expected
+1. Check if command was entered correctly
+2. Verify current project context is AIWF
+3. Wait 2-3 seconds after persona switch
+4. If problem persists, reset to default mode and retry
+
+### Performance Degradation
+- Minimize persona switching for complex tasks
+- Include only relevant files in large codebases
+- Use exclusion settings for unnecessary context
+
+### Context Conflicts
+- Check context rules for each persona
+- Explicitly set priority for conflicting information
+- Manually clean up context when necessary
+
+## Advanced Usage
+
+### 1. Persona Chaining
+Use multiple personas consecutively for complex tasks:
+```bash
+Architect → Developer → Debugger → Optimizer → Documenter
+```
+
+### 2. Persona Customization
+Adjust persona behavior for project-specific requirements
+(Planned for future updates)
+
+### 3. Team Workflow Integration
+Automatic persona switching based on Git branch or PR status
+(Use with Feature-Git integration feature)
+
+## Conclusion
+
+The AI Persona system is a powerful tool that can significantly improve the efficiency and quality of development work. By understanding the characteristics of each persona and utilizing them appropriately, collaboration with Claude Code becomes more productive and effective.
+
+We encourage you to develop persona utilization strategies optimized for each project through continuous use and feedback.

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

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