aiwf 0.3.13 → 0.3.15

package/docs/git-feature-integration-guide.md

@@ -1,253 +0,0 @@
-# Git-Feature 통합 가이드
-
-이 문서는 AIWF의 Git 연동 Feature 추적 시스템 사용법을 설명합니다.
-
-## 개요
-
-Git-Feature 통합 시스템은 Git 커밋과 Feature Ledger를 자동으로 연결하여, 개발 진행 상황을 효과적으로 추적할 수 있게 합니다.
-
-## 주요 기능
-
-1. **커밋 메시지 파싱**: 다양한 형식의 Feature ID 자동 인식
-2. **자동 동기화**: Git hooks를 통한 실시간 Feature 업데이트
-3. **히스토리 스캔**: 기존 커밋 히스토리와 Feature 연결
-4. **리포트 생성**: Feature-커밋 매핑 리포트 자동 생성
-
-## 커밋 메시지 규칙
-
-### 지원하는 Feature ID 형식
-
-```bash
-# 직접 참조
-git commit -m "FL001 사용자 인증 기능 구현"
-
-# 대괄호 참조
-git commit -m "[FL001] 로그인 폼 스타일 수정"
-
-# Conventional Commit 형식
-git commit -m "feat(FL001): JWT 토큰 발급 로직 추가"
-git commit -m "fix(FL001): 로그인 오류 수정"
-
-# 해시 참조
-git commit -m "Update authentication flow #FL001"
-
-# 여러 Feature 참조
-git commit -m "FL001, FL002 관련 공통 유틸리티 추가"
-```
-
-### 브랜치 명명 규칙
-
-```bash
-# Feature 브랜치 형식
-git checkout -b feature/FL001-user-authentication
-git checkout -b feature/FL002-dashboard-redesign
-```
-
-## 명령어 사용법
-
-### 1. sync_feature_commits - Feature 동기화
-
-```bash
-# 특정 Feature 동기화
-node claude-code/aiwf/ko/commands/sync_feature_commits.js FL001
-
-# 모든 활성 Feature 동기화
-node claude-code/aiwf/ko/commands/sync_feature_commits.js --all
-
-# 최근 100개 커밋에서 Feature 찾기
-node claude-code/aiwf/ko/commands/sync_feature_commits.js --recent 100
-
-# 특정 날짜 이후 커밋 검색
-node claude-code/aiwf/ko/commands/sync_feature_commits.js --since 2025-01-01
-
-# 상세 로그 출력
-node claude-code/aiwf/ko/commands/sync_feature_commits.js --verbose
-```
-
-### 2. scan_git_history - 히스토리 스캔
-
-```bash
-# 기본 스캔 (2025-01-01부터)
-node claude-code/aiwf/ko/commands/scan_git_history.js
-
-# 날짜 범위 지정
-node claude-code/aiwf/ko/commands/scan_git_history.js --since 2024-01-01 --until 2024-12-31
-
-# 특정 Feature만 스캔
-node claude-code/aiwf/ko/commands/scan_git_history.js --feature FL001
-
-# Dry-run 모드 (실제 업데이트 없음)
-node claude-code/aiwf/ko/commands/scan_git_history.js --dry-run
-
-# 누락된 Feature 파일 자동 생성
-node claude-code/aiwf/ko/commands/scan_git_history.js --create-missing
-```
-
-### 3. feature_commit_report - 리포트 생성
-
-```bash
-# 기본 Markdown 리포트 생성
-node claude-code/aiwf/ko/commands/feature_commit_report.js
-
-# 특정 Feature 리포트
-node claude-code/aiwf/ko/commands/feature_commit_report.js --feature FL001
-
-# 활성 Feature만 포함
-node claude-code/aiwf/ko/commands/feature_commit_report.js --status active
-
-# JSON 형식으로 출력
-node claude-code/aiwf/ko/commands/feature_commit_report.js --format json --output report.json
-
-# HTML 형식 + 상세 정보
-node claude-code/aiwf/ko/commands/feature_commit_report.js --format html --detailed --output report.html
-
-# 타임라인 뷰 포함
-node claude-code/aiwf/ko/commands/feature_commit_report.js --timeline
-```
-
-## Git Hooks 설정
-
-### 자동 설치
-
-```bash
-# 설치 스크립트 실행
-./claude-code/aiwf/ko/hooks/install-hooks.sh
-
-# 환경 변수 설정 (활성화)
-export AIWF_HOOKS_ENABLED=true
-
-# 상세 로그 활성화 (선택사항)
-export AIWF_HOOKS_VERBOSE=true
-
-# 영구 설정 (~/.bashrc 또는 ~/.zshrc에 추가)
-echo 'export AIWF_HOOKS_ENABLED=true' >> ~/.bashrc
-```
-
-### 수동 설치
-
-```bash
-# post-commit hook 복사
-cp claude-code/aiwf/ko/hooks/post-commit .git/hooks/
-chmod +x .git/hooks/post-commit
-
-# 환경 변수 설정
-export AIWF_HOOKS_ENABLED=true
-```
-
-### Hook 동작 확인
-
-```bash
-# Feature ID를 포함한 커밋 생성
-git add .
-git commit -m "feat(FL001): 새로운 기능 추가"
-
-# 콘솔에 다음과 같은 메시지가 표시됩니다:
-# 🔄 AIWF Feature Ledger 동기화 중...
-# ✅ Feature ID 발견: FL001
-# 📝 FL001 동기화 중...
-# ✅ FL001 동기화 완료
-# ✨ Feature Ledger 동기화 완료!
-```
-
-## 워크플로우 예시
-
-### 1. 새 Feature 시작
-
-```bash
-# 1. Feature Ledger 생성
-/project:aiwf:create_feature_ledger "User Authentication"
-
-# 2. Feature 브랜치 생성
-git checkout -b feature/FL001-user-authentication
-
-# 3. 개발 및 커밋
-git add src/auth/*
-git commit -m "feat(FL001): 사용자 인증 모듈 구현"
-
-# 4. Feature 자동 업데이트 확인
-cat .aiwf/06_FEATURE_LEDGERS/active/FL001_User_Authentication.md
-```
-
-### 2. 기존 프로젝트에 적용
-
-```bash
-# 1. Git 히스토리 스캔
-node claude-code/aiwf/ko/commands/scan_git_history.js --since 2024-01-01
-
-# 2. 누락된 Feature 확인 및 생성
-node claude-code/aiwf/ko/commands/scan_git_history.js --create-missing
-
-# 3. 리포트 생성
-node claude-code/aiwf/ko/commands/feature_commit_report.js --detailed
-
-# 4. Git hooks 설치
-./claude-code/aiwf/ko/hooks/install-hooks.sh
-export AIWF_HOOKS_ENABLED=true
-```
-
-### 3. 진행 상황 모니터링
-
-```bash
-# 전체 Feature 상태 확인
-node claude-code/aiwf/ko/commands/feature_commit_report.js
-
-# 특정 Feature 상세 정보
-node claude-code/aiwf/ko/commands/sync_feature_commits.js FL001 --verbose
-
-# 최근 활동 확인
-node claude-code/aiwf/ko/commands/sync_feature_commits.js --recent 50 --verbose
-```
-
-## 문제 해결
-
-### Git hooks가 실행되지 않음
-
-```bash
-# 환경 변수 확인
-echo $AIWF_HOOKS_ENABLED
-
-# Hook 파일 권한 확인
-ls -la .git/hooks/post-commit
-
-# 수동으로 동기화 실행
-node claude-code/aiwf/ko/commands/sync_feature_commits.js --all
-```
-
-### Feature ID가 인식되지 않음
-
-```bash
-# 커밋 메시지 패턴 확인
-git log --oneline | grep "FL[0-9]\{3\}"
-
-# 지원하는 형식 사용
-git commit -m "feat(FL001): 기능 설명"  # 권장
-git commit -m "[FL001] 기능 설명"       # 가능
-git commit -m "FL001 기능 설명"         # 가능
-```
-
-### 동기화 오류
-
-```bash
-# Feature 파일 존재 확인
-find .aiwf/06_FEATURE_LEDGERS -name "FL001*"
-
-# 수동으로 Feature 파일 생성
-/project:aiwf:create_feature_ledger "Feature Name"
-
-# 다시 동기화 시도
-node claude-code/aiwf/ko/commands/sync_feature_commits.js FL001
-```
-
-## 모범 사례
-
-1. **일관된 커밋 메시지**: Conventional Commit 형식 사용 권장
-2. **브랜치 전략**: Feature별 브랜치 생성 및 명명 규칙 준수
-3. **정기적 동기화**: 주기적으로 `--all` 옵션으로 전체 동기화
-4. **리포트 활용**: 스프린트 종료 시 리포트 생성하여 진행 상황 공유
-5. **Hook 활성화**: 팀 전체가 Git hooks를 활성화하여 일관성 유지
-
-## 추가 리소스
-
-- [Feature Ledger 시스템 사양](/.aiwf/02_REQUIREMENTS/M02_Context_Engineering_Enhancement/SPECS_Feature_Ledger_System.md)
-- [Git 통합 사양](/.aiwf/06_FEATURE_LEDGERS/FEATURE_GIT_INTEGRATION.md)
-- [통합 가이드](/.aiwf/06_FEATURE_LEDGERS/FEATURE_INTEGRATION_GUIDE.md)

package/docs/lightweight-evaluation.md

@@ -1,198 +0,0 @@
-# 경량 평가 시스템
-
-## 개요
-
-AIWF의 경량 평가 시스템은 AI 응답 품질을 간단하고 효율적으로 모니터링합니다. 복잡한 수동 평가 대신 백그라운드 자동 평가를 통해 사용자 작업 흐름을 방해하지 않으면서도 품질을 유지합니다.
-
-## 핵심 원칙
-
-### 1. Invisible by Default
-- 평가는 백그라운드에서 자동 실행
-- 사용자가 인지하지 못하도록 설계
-- 필요할 때만 피드백 제공
-
-### 2. Simple Metrics
-- 3가지 핵심 지표만 사용
-- 복잡한 계산 없이 빠른 평가
-- 실용적인 피드백 중심
-
-### 3. Non-Intrusive
-- 품질이 낮을 때만 알림 (60% 미만)
-- 간단한 한 줄 피드백
-- 작업 흐름을 방해하지 않음
-
-## 평가 지표
-
-### 1. 역할 일치도 (Role Alignment) - 50%
-페르소나의 핵심 키워드가 응답에 포함되었는지 확인합니다.
-
-```javascript
-// 페르소나별 핵심 키워드
-architect: ['시스템', '설계', '구조', '아키텍처']
-security: ['보안', '취약점', '암호화', '위협']
-frontend: ['UI', 'UX', '사용자', '화면']
-backend: ['API', '데이터베이스', '서버', '성능']
-data_analyst: ['데이터', '분석', '통계', '인사이트']
-```
-
-### 2. 작업 관련성 (Task Relevance) - 30%
-응답의 길이와 내용으로 작업 관련성을 간단히 평가합니다.
-- 50자 미만: 0.3
-- 50-200자: 0.6
-- 200자 이상: 0.8
-
-### 3. 기본 품질 (Response Quality) - 20%
-응답의 구조와 내용 풍부도를 확인합니다.
-- 구조화된 응답 (줄바꿈, 목록 등): +0.2
-- 충분한 내용 (100자 이상): +0.2
-
-## 자동 평가 시점
-
-### 1. 페르소나 전환 시
-```bash
-$ aiwf persona architect
-✓ Architect 페르소나 활성화
-# (백그라운드에서 자동 평가 시작)
-```
-
-### 2. 컨텍스트 압축 시
-```bash
-$ aiwf compress-with-persona
-✓ 압축 완료!
-# (압축 품질 자동 체크)
-💡 시스템 설계 관점을 더 포함해보세요  # 품질이 낮을 때만
-```
-
-## 수동 평가 명령어
-
-필요할 때 수동으로 평가 정보를 확인할 수 있습니다.
-
-### 빠른 확인
-```bash
-$ aiwf evaluate
-🔍 최근 응답 평가
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-현재 페르소나: architect
-평균 점수: 0.75
-평가 횟수: 23
-추세: 📈 개선 중
-```
-
-### 상세 분석
-```bash
-$ aiwf evaluate --detailed
-📊 상세 평가 분석
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-전체 통계:
-- 총 평가: 47회
-- 평균 점수: 0.72
-- 추세: 📈 개선 중
-
-페르소나별 성과:
-- 아키텍트: 0.85 (15회)
-- 보안 전문가: 0.62 (8회)
-- 프론트엔드: 0.74 (12회)
-- 백엔드: 0.70 (9회)
-- 데이터 분석가: 0.58 (3회)
-
-개선 제안:
-📊 데이터 기반 인사이트를 더 제공해보세요
-```
-
-### 평가 히스토리
-```bash
-$ aiwf evaluate --history
-📈 평가 히스토리
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-14:32 | 아키텍트 | 0.85
-14:25 | 프론트엔드 | 0.72
-14:18 | 아키텍트 | 0.90
-...
-```
-
-### 주간 통계
-```bash
-$ aiwf evaluate --stats
-📊 주간 통계
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-평가 횟수: 142회
-평균 점수: 0.74
-추세: 📈 개선 중
-
-페르소나별 활용도:
-아키텍트    ████████████ 45회
-프론트엔드  ████████ 32회
-백엔드      ██████ 28회
-보안 전문가  ████ 20회
-데이터 분석가 ████ 17회
-```
-
-## 피드백 메시지
-
-각 페르소나별로 간단한 피드백 메시지가 준비되어 있습니다:
-
-- **Architect**: "💡 시스템 설계 관점을 더 포함해보세요"
-- **Security**: "🔒 보안 측면을 좀 더 고려해보세요"
-- **Frontend**: "🎨 사용자 경험 관점을 추가해보세요"
-- **Backend**: "⚙️ 서버/데이터 처리 관점을 강화해보세요"
-- **Data Analyst**: "📊 데이터 기반 인사이트를 더 제공해보세요"
-
-## 데이터 저장
-
-평가 데이터는 `.aiwf/.evaluation-stats.json`에 자동 저장됩니다:
-
-```json
-{
-  "recentEvaluations": [
-    {
-      "persona": "architect",
-      "score": 0.85,
-      "timestamp": "2024-01-10T14:32:00Z",
-      "responseLength": 350
-    }
-  ],
-  "lastUpdated": "2024-01-10T14:32:00Z"
-}
-```
-
-## 구현 세부사항
-
-### SimplifiedEvaluator 클래스
-- 200줄 이하의 간단한 구현
-- 빠른 평가 알고리즘
-- 최소한의 의존성
-
-### BackgroundMonitor 클래스
-- 싱글톤 패턴으로 리소스 효율성
-- 비동기 평가로 성능 영향 최소화
-- 자동 데이터 정리 (최대 100개 기록)
-
-## 마이그레이션 가이드
-
-### 기존 시스템에서 전환
-1. 기존 평가 명령어들이 자동으로 제거됨
-2. 새로운 `aiwf evaluate` 명령어만 사용
-3. 대부분의 평가는 자동으로 백그라운드에서 수행
-
-### 주요 변경사항
-- 5개 지표 → 3개 지표
-- 수동 평가 → 자동 평가
-- 5개 명령어 → 1개 명령어
-- 복잡한 리포트 → 간단한 피드백
-
-## 성능 영향
-
-- **CPU 사용**: 거의 없음 (< 0.1%)
-- **메모리 사용**: 최소 (< 5MB)
-- **평가 시간**: 즉시 (< 10ms)
-- **저장 공간**: 작음 (< 100KB)
-
-## 향후 계획
-
-1. **AI 응답 후 자동 평가**: Claude API 응답 후킹
-2. **주간 리포트 자동 생성**: 매주 월요일 아침
-3. **팀 통계 공유**: 팀원 간 평가 통계 공유 기능
-
-## 결론
-
-경량 평가 시스템은 "적을수록 좋다"는 철학을 따릅니다. 필수적인 기능만 유지하면서도 AI 응답 품질을 효과적으로 모니터링할 수 있습니다. 사용자는 평가 시스템의 존재를 거의 인지하지 못하면서도 품질 개선의 혜택을 받습니다.

package/docs/performance-benchmark-report.md

@@ -1,159 +0,0 @@
-# M02 Performance Benchmark Report
-
-## Executive Summary
-
-M02 마일스톤의 핵심 성능 목표인 "토큰 사용량 50% 절감"을 성공적으로 달성했습니다. Context Compression 시스템을 통해 평균 53.5%의 토큰 절감을 실현했으며, 실시간 처리 성능도 목표치를 충족했습니다.
-
-## Token Usage Reduction
-
-### Benchmark Scenarios
-
-#### 1. Feature Implementation Scenario
-- **작업 내용**: 새로운 기능 구현 시 필요한 컨텍스트
-- **원본 토큰**: 10,000 tokens
-- **압축 후 토큰**: 4,500 tokens  
-- **절감률**: 55% ✅
-- **절감 토큰**: 5,500 tokens
-
-#### 2. Code Review Scenario  
-- **작업 내용**: PR 리뷰 시 필요한 파일 컨텍스트
-- **원본 토큰**: 8,000 tokens
-- **압축 후 토큰**: 3,800 tokens
-- **절감률**: 52.5% ✅
-- **절감 토큰**: 4,200 tokens
-
-#### 3. Documentation Scenario
-- **작업 내용**: 문서 작성/업데이트 시 참조 컨텍스트
-- **원본 토큰**: 5,000 tokens
-- **압축 후 토큰**: 2,400 tokens
-- **절감률**: 52% ✅
-- **절감 토큰**: 2,600 tokens
-
-### Overall Performance
-
-| Metric | Value | Target | Status |
-|--------|-------|--------|--------|
-| **평균 토큰 절감률** | 53.5% | 50% | ✅ 초과 달성 |
-| **총 원본 토큰** | 23,000 | - | - |
-| **총 압축 토큰** | 10,700 | - | - |
-| **총 절감 토큰** | 12,300 | - | - |
-
-## Compression Performance
-
-### Speed Metrics
-
-| File Size | Compression Time | Decompression Time | Status |
-|-----------|-----------------|-------------------|---------|
-| 1KB | < 10ms | < 5ms | ✅ |
-| 10KB | < 50ms | < 20ms | ✅ |
-| 100KB | < 200ms | < 80ms | ✅ |
-| 1MB | < 1000ms | < 400ms | ✅ |
-
-### Memory Usage
-
-- **Base Memory**: 15MB
-- **Peak Memory (1MB file)**: 48MB
-- **Memory Overhead**: < 50MB ✅
-
-## AI Persona Performance
-
-### Context Switching Speed
-
-| Operation | Time | Target | Status |
-|-----------|------|--------|--------|
-| Persona Activation | 120ms | < 200ms | ✅ |
-| Context Loading | 85ms | < 100ms | ✅ |
-| Template Application | 45ms | < 50ms | ✅ |
-
-### Persona Usage Statistics
-
-| Persona | Usage Count | Avg. Session | Token Savings |
-|---------|------------|--------------|---------------|
-| developer | 156 | 25 min | 54% |
-| architect | 89 | 35 min | 56% |
-| reviewer | 124 | 15 min | 51% |
-| analyst | 67 | 40 min | 53% |
-| tester | 92 | 20 min | 52% |
-
-## Feature Ledger Performance
-
-### Operation Metrics
-
-| Operation | Avg. Time | 95th Percentile | Status |
-|-----------|-----------|-----------------|--------|
-| Create Feature | 25ms | 40ms | ✅ |
-| Update Status | 15ms | 25ms | ✅ |
-| Link to Git | 35ms | 50ms | ✅ |
-| List Features | 45ms | 80ms | ✅ |
-
-### Git Integration
-
-- **Auto-link Success Rate**: 98.5%
-- **Commit Parse Time**: < 20ms
-- **Branch Detection**: 100%
-
-## Cost Analysis
-
-### Token Cost Savings (Based on GPT-4 Pricing)
-
-| Scenario | Monthly Volume | Original Cost | Compressed Cost | Savings |
-|----------|---------------|---------------|-----------------|---------|
-| Development | 1M tokens | $30 | $13.95 | $16.05 |
-| Code Review | 800K tokens | $24 | $11.40 | $12.60 |
-| Documentation | 500K tokens | $15 | $7.20 | $7.80 |
-| **Total** | **2.3M tokens** | **$69** | **$32.55** | **$36.45** |
-
-**Monthly Savings**: $36.45 (52.8%)
-**Annual Savings**: $437.40
-
-## Optimization Recommendations
-
-### 1. Further Token Reduction
-- Implement semantic compression for code comments
-- Use reference-based compression for repeated patterns
-- Potential additional savings: 5-10%
-
-### 2. Performance Improvements
-- Implement compression caching
-- Use worker threads for large files
-- Optimize memory allocation
-
-### 3. User Experience
-- Add compression level presets
-- Provide real-time savings feedback
-- Implement batch compression
-
-## Benchmark Methodology
-
-### Test Environment
-- **CPU**: Intel Core i7-9700K
-- **RAM**: 16GB DDR4
-- **OS**: Ubuntu 22.04 LTS
-- **Node.js**: v20.19.3
-
-### Test Data
-- Real project files from 10 different repositories
-- File sizes ranging from 1KB to 5MB
-- Various file types: .js, .ts, .md, .json
-
-### Measurement Tools
-- Node.js Performance API
-- Memory profiling with --inspect
-- Custom token counting based on tiktoken
-
-## Conclusion
-
-M02 마일스톤의 성능 목표를 모두 달성했습니다:
-
-1. ✅ **토큰 사용량 50% 이상 절감** (실제: 53.5%)
-2. ✅ **실시간 압축 처리** (< 200ms for 99% of files)
-3. ✅ **낮은 메모리 오버헤드** (< 50MB)
-4. ✅ **높은 압축 품질** (무손실 압축)
-
-Context Engineering Enhancement는 AI 도구 사용 비용을 크게 절감하면서도 사용자 경험을 해치지 않는 성능을 제공합니다.
-
----
-
-**Report Generated**: 2025-07-08
-**Test Period**: 2025-07-01 to 2025-07-08
-**Next Review**: 2025-08-01