aiwf 0.3.15 → 0.3.16

package/docs/GETTING_STARTED.ko.md

@@ -0,0 +1,219 @@
+# AIWF 시작하기
+
+[한국어](GETTING_STARTED.ko.md) | [English](GETTING_STARTED.md)
+
+> AIWF를 사용하여 AI 지원 개발을 시작하는 빠른 가이드
+
+## 📋 목차
+
+1. [설치](#설치)
+2. [첫 프로젝트 설정](#첫-프로젝트-설정)
+3. [기본 워크플로우](#기본-워크플로우)
+4. [핵심 개념](#핵심-개념)
+5. [다음 단계](#다음-단계)
+
+## 설치
+
+### 전역 설치 (권장)
+
+```bash
+npm install -g aiwf
+```
+
+### 프로젝트에 AIWF 설치
+
+프로젝트 디렉토리로 이동한 후:
+
+```bash
+aiwf install
+```
+
+설치 프로그램이 다음을 안내합니다:
+1. **언어 선택**: 한국어 또는 영어 선택
+2. **프로젝트 설정**: 현재 디렉토리에 AIWF 초기화
+3. **Claude 명령어**: 언어별 명령어 설치
+4. **문서**: 가이드 및 템플릿 다운로드
+
+## 첫 프로젝트 설정
+
+### 1. 새 프로젝트 생성
+
+```bash
+# 대화형 프로젝트 생성
+aiwf create-project
+
+# 템플릿 사용
+aiwf create-project my-api --template api-server
+aiwf create-project my-lib --template npm-library
+aiwf create-project my-app --template web-app
+```
+
+### 2. 기존 프로젝트에 AIWF 추가
+
+```bash
+cd my-existing-project
+aiwf install
+```
+
+### 3. 프로젝트 상태 초기화
+
+```bash
+aiwf state init
+```
+
+## 기본 워크플로우
+
+### 1. 마일스톤 계획
+
+```bash
+# PRD로부터 마일스톤 생성
+aiwf create-milestone-plan
+
+# 마일스톤으로부터 스프린트 생성
+aiwf create-sprints-from-milestone
+```
+
+### 2. 태스크 관리
+
+```bash
+# 일반 태스크 생성
+aiwf create-general-task "기능 구현" --description "사용자 인증 추가"
+
+# 스프린트에 태스크 추가
+aiwf add-sprint-task S01 "API 엔드포인트 구현"
+
+# 스마트 태스크 시작
+aiwf smart-start
+
+# 태스크 완료
+aiwf smart-complete
+```
+
+### 3. 상태 추적
+
+```bash
+# 상태 업데이트
+aiwf state update
+
+# 현재 상태 확인
+aiwf state show
+
+# 다음 추천 작업
+aiwf state next
+```
+
+### 4. YOLO 모드 (자율 실행)
+
+```bash
+# 전체 스프린트 자동 실행
+aiwf yolo
+
+# 안전 모드로 실행
+aiwf yolo --safe
+
+# 드라이런 (시뮬레이션)
+aiwf yolo --dry-run
+```
+
+## 핵심 개념
+
+### 📂 프로젝트 구조
+
+```
+my-project/
+├── .aiwf/                    # AIWF 구성 및 상태
+│   ├── config.json          # 프로젝트 설정
+│   ├── state/               # 상태 파일
+│   └── checkpoints/         # YOLO 체크포인트
+├── milestones/              # 마일스톤 정의
+├── sprints/                 # 스프린트 정의
+└── tasks/                   # 태스크 파일
+```
+
+### 🎯 워크플로우 단계
+
+1. **계획 (Planning)**
+   - PRD 작성
+   - 마일스톤 정의
+   - 스프린트 분할
+
+2. **개발 (Development)**
+   - 태스크 생성 및 할당
+   - 코드 구현
+   - 테스트 작성
+
+3. **리뷰 (Review)**
+   - 코드 리뷰
+   - 테스트 실행
+   - 품질 평가
+
+4. **배포 (Deployment)**
+   - 최종 검증
+   - 릴리스 준비
+   - 문서 업데이트
+
+### 🤖 AI 페르소나
+
+AIWF는 전문 AI 페르소나를 제공합니다:
+
+- **Architect**: 시스템 설계 및 아키텍처
+- **Backend**: 백엔드 개발 및 API
+- **Frontend**: UI/UX 및 프론트엔드
+- **Security**: 보안 검토 및 개선
+- **Data Analyst**: 데이터 분석 및 최적화
+
+페르소나 사용 예:
+
+```bash
+# 아키텍처 리뷰
+aiwf persona apply architect
+
+# 보안 검토
+aiwf persona apply security
+```
+
+### 💾 체크포인트 시스템
+
+YOLO 모드 실행 중 진행 상황 자동 저장:
+
+```bash
+# 체크포인트 목록
+aiwf checkpoint list
+
+# 특정 체크포인트에서 재개
+aiwf yolo --resume checkpoint-id
+```
+
+## 다음 단계
+
+### 📚 추천 문서
+
+1. **[명령어 가이드](COMMANDS_GUIDE.ko.md)** - 모든 AIWF 명령어 상세 설명
+2. **[상태 관리 가이드](STATE_MANAGEMENT_GUIDE.ko.md)** - 고급 상태 관리 기법
+3. **[AI 페르소나 가이드](guides/ai-personas-guide-ko.md)** - 페르소나 활용법
+4. **[독립 스프린트 가이드](guides/independent-sprint-guide-ko.md)** - YOLO 최적화 스프린트
+
+### 🎓 학습 경로
+
+1. **초급**: 기본 명령어와 워크플로우 익히기
+2. **중급**: 상태 관리와 AI 페르소나 활용
+3. **고급**: YOLO 모드와 커스터마이징
+
+### 💡 팁
+
+- 항상 `aiwf state update`로 상태 동기화
+- 큰 작업은 작은 태스크로 분할
+- YOLO 모드는 충분한 컨텍스트와 함께 사용
+- 정기적으로 체크포인트 확인
+
+## 🆘 도움말
+
+문제가 발생하면:
+
+1. `aiwf --help` 명령어 도움말 확인
+2. [문제 해결 가이드](TROUBLESHOOTING.ko.md) 참조
+3. [GitHub 이슈](https://github.com/moonklabs/aiwf/issues) 제출
+
+---
+
+🎉 이제 AIWF로 AI 지원 개발을 시작할 준비가 되었습니다!

package/docs/GETTING_STARTED.md

@@ -169,7 +169,6 @@ my-project/
 │   │   └── S03_M01_integration_testing/
 │   ├── 04_GENERAL_TASKS/           # Non-sprint tasks
 │   ├── 05_ARCHITECTURAL_DECISIONS/  # ADRs
-│   ├── 06_FEATURE_LEDGERS/         # Feature tracking
 │   └── 99_TEMPLATES/               # Reusable templates
 ├── .claude/commands/aiwf/          # Claude commands
 ├── src/                            # Your source code

package/docs/PERFORMANCE_GUIDELINES.ko.md

@@ -0,0 +1,388 @@
+# AIWF 성능 가이드라인
+
+[한국어](PERFORMANCE_GUIDELINES.ko.md) | [English](PERFORMANCE_GUIDELINES.md)
+
+> AIWF 프로젝트의 성능을 최적화하기 위한 모범 사례와 가이드라인
+
+## 📋 목차
+
+1. [개요](#개요)
+2. [토큰 최적화](#토큰-최적화)
+3. [파일 시스템 성능](#파일-시스템-성능)
+4. [상태 관리 최적화](#상태-관리-최적화)
+5. [메모리 관리](#메모리-관리)
+6. [명령어 실행 최적화](#명령어-실행-최적화)
+7. [AI 상호작용 최적화](#ai-상호작용-최적화)
+8. [모니터링과 프로파일링](#모니터링과-프로파일링)
+
+## 개요
+
+AIWF의 성능은 다음 요소들에 의해 결정됩니다:
+- AI 모델과의 토큰 교환량
+- 파일 시스템 작업 효율성
+- 상태 관리 오버헤드
+- 메모리 사용량
+- 명령어 실행 시간
+
+이 가이드는 각 영역에서 성능을 최적화하는 방법을 설명합니다.
+
+## 토큰 최적화
+
+### 컨텍스트 압축 전략
+
+토큰 사용량을 줄이는 것은 비용과 성능 모두에 중요합니다.
+
+#### 1. 적절한 압축 레벨 선택
+
+```bash
+# 최소 압축 (중요 정보 보존)
+aiwf compress minimal
+
+# 균형 압축 (권장)
+aiwf compress balanced
+
+# 공격적 압축 (최대 토큰 절약)
+aiwf compress aggressive
+```
+
+#### 2. 페르소나 기반 압축
+
+활성 페르소나에 맞춰 관련 정보만 보존:
+
+```bash
+# 백엔드 작업 시
+aiwf persona apply backend
+aiwf compress with-persona
+
+# 프론트엔드 작업 시
+aiwf persona apply frontend
+aiwf compress with-persona
+```
+
+#### 3. 파일 필터링
+
+불필요한 파일 제외:
+
+```bash
+# .aiwfignore 파일 생성
+cat > .aiwfignore << EOF
+# 빌드 산출물
+dist/
+build/
+*.min.js
+*.map
+
+# 의존성
+node_modules/
+vendor/
+
+# 로그 및 캐시
+*.log
+.cache/
+coverage/
+
+# 대용량 파일
+*.jpg
+*.png
+*.mp4
+*.zip
+EOF
+```
+
+### 토큰 사용량 모니터링
+
+```bash
+# 현재 세션 토큰 사용량
+aiwf token status
+
+# 일일 리포트
+aiwf token report daily
+
+# 주간 리포트
+aiwf token report weekly
+```
+
+### 토큰 한도 설정
+
+```bash
+# 세션당 한도 설정
+aiwf token limit session 50000
+
+# 일일 한도 설정
+aiwf token limit daily 200000
+
+# 경고 임계값 설정
+aiwf token limit warning 0.8
+```
+
+## 파일 시스템 성능
+
+### 인덱싱 최적화
+
+#### 1. 선택적 인덱싱
+
+```bash
+# 특정 디렉토리만 인덱싱
+aiwf index --include src/ docs/
+
+# 특정 파일 타입만 인덱싱
+aiwf index --types js,ts,md
+```
+
+#### 2. 인덱스 캐싱
+
+```bash
+# 인덱스 캐시 활성화
+aiwf config set index.cache true
+
+# 캐시 TTL 설정 (초 단위)
+aiwf config set index.cacheTTL 3600
+```
+
+### 파일 감시 최적화
+
+```bash
+# 감시 제외 패턴 설정
+aiwf config set watch.ignore "node_modules/**,dist/**"
+
+# 디바운스 시간 설정 (밀리초)
+aiwf config set watch.debounce 500
+```
+
+## 상태 관리 최적화
+
+### 상태 파일 크기 관리
+
+#### 1. 정기적인 정리
+
+```bash
+# 완료된 태스크 아카이브
+aiwf state archive --older-than 30d
+
+# 상태 파일 압축
+aiwf state compact
+```
+
+#### 2. 증분 업데이트
+
+```bash
+# 전체 업데이트 대신 증분 업데이트 사용
+aiwf state update --incremental
+
+# 특정 스프린트만 업데이트
+aiwf state update --sprint S01
+```
+
+### 상태 검증 최적화
+
+```bash
+# 빠른 검증 (기본 체크만)
+aiwf state validate --quick
+
+# 비동기 검증
+aiwf state validate --async
+```
+
+## 메모리 관리
+
+### Node.js 메모리 설정
+
+```bash
+# 힙 메모리 증가
+export NODE_OPTIONS="--max-old-space-size=4096"
+
+# 또는 .aiwf/config.json에 설정
+{
+  "performance": {
+    "nodeOptions": "--max-old-space-size=4096"
+  }
+}
+```
+
+### 메모리 누수 방지
+
+#### 1. 리소스 정리
+
+```bash
+# 임시 파일 정리
+aiwf cleanup temp
+
+# 오래된 체크포인트 제거
+aiwf checkpoint prune --keep-last 5
+```
+
+#### 2. 캐시 관리
+
+```bash
+# 캐시 크기 제한
+aiwf config set cache.maxSize "100MB"
+
+# 캐시 정리
+aiwf cache clear
+```
+
+## 명령어 실행 최적화
+
+### 병렬 처리
+
+```bash
+# 병렬 태스크 실행
+aiwf task run --parallel 4
+
+# 독립적인 스프린트 병렬 실행
+aiwf sprint run S01 S02 --parallel
+```
+
+### 배치 작업
+
+```bash
+# 여러 태스크 일괄 생성
+aiwf task create-batch tasks.json
+
+# 일괄 상태 업데이트
+aiwf state update-batch
+```
+
+### 지연 로딩
+
+```bash
+# 필요시에만 리소스 로드
+aiwf config set lazy.loading true
+
+# 명령어별 지연 로딩
+aiwf config set lazy.commands true
+```
+
+## AI 상호작용 최적화
+
+### 효율적인 프롬프트
+
+#### 1. 프롬프트 템플릿 사용
+
+```bash
+# 프롬프트 템플릿 생성
+aiwf prompt create backend-api
+
+# 템플릿 재사용
+aiwf task create --prompt-template backend-api
+```
+
+#### 2. 컨텍스트 재사용
+
+```bash
+# 컨텍스트 캐싱 활성화
+aiwf config set ai.contextCache true
+
+# 캐시 수명 설정
+aiwf config set ai.contextCacheTTL 1800
+```
+
+### 응답 최적화
+
+```bash
+# 응답 길이 제한
+aiwf config set ai.maxResponseTokens 2000
+
+# 스트리밍 응답 활성화
+aiwf config set ai.streaming true
+```
+
+## 모니터링과 프로파일링
+
+### 성능 메트릭
+
+```bash
+# 성능 모니터링 활성화
+aiwf monitor start
+
+# 실시간 메트릭 보기
+aiwf monitor status
+
+# 성능 리포트 생성
+aiwf monitor report
+```
+
+### 프로파일링
+
+```bash
+# CPU 프로파일링
+aiwf profile cpu --duration 30s
+
+# 메모리 프로파일링
+aiwf profile memory
+
+# 프로파일 분석
+aiwf profile analyze
+```
+
+### 벤치마크
+
+```bash
+# 기본 벤치마크 실행
+aiwf benchmark
+
+# 특정 명령어 벤치마크
+aiwf benchmark --command "state update"
+
+# 비교 벤치마크
+aiwf benchmark --compare v0.3.0
+```
+
+## 모범 사례 체크리스트
+
+### 일일 최적화
+- [ ] 토큰 사용량 확인
+- [ ] 임시 파일 정리
+- [ ] 캐시 상태 확인
+
+### 주간 최적화
+- [ ] 상태 파일 압축
+- [ ] 오래된 체크포인트 정리
+- [ ] 성능 리포트 검토
+
+### 월간 최적화
+- [ ] 전체 인덱스 재구축
+- [ ] 완료된 태스크 아카이브
+- [ ] 성능 벤치마크 실행
+
+## 성능 문제 해결
+
+### 느린 시작 시간
+
+1. **원인 파악**:
+   ```bash
+   aiwf debug startup
+   ```
+
+2. **해결책**:
+   - 지연 로딩 활성화
+   - 불필요한 플러그인 제거
+   - 캐시 프리로드
+
+### 높은 메모리 사용
+
+1. **메모리 프로파일**:
+   ```bash
+   aiwf profile memory --heap-snapshot
+   ```
+
+2. **해결책**:
+   - 캐시 크기 제한
+   - 리소스 풀 크기 조정
+   - 가비지 컬렉션 튜닝
+
+### 느린 파일 작업
+
+1. **I/O 분석**:
+   ```bash
+   aiwf debug io
+   ```
+
+2. **해결책**:
+   - SSD 사용
+   - 파일 감시 최적화
+   - 배치 I/O 작업
+
+---
+
+💡 **프로 팁**: 성능 최적화는 지속적인 과정입니다. 정기적으로 모니터링하고 조정하세요!