aiwf 0.3.16 → 0.3.18

package/docs/YOLO_SYSTEM_GUIDE.ko.md

@@ -0,0 +1,542 @@
+# AIWF YOLO 시스템 가이드
+
+> AIWF의 자율 실행 시스템(YOLO 모드)에 대한 종합 가이드
+
+[한국어](YOLO_SYSTEM_GUIDE.ko.md) | [English](YOLO_SYSTEM_GUIDE.md)
+
+## 목차
+
+1. [개요](#개요)
+2. [시스템 구성 요소](#시스템-구성-요소)
+3. [엔지니어링 가드](#엔지니어링-가드)
+4. [체크포인트 매니저](#체크포인트-매니저)
+5. [YOLO 설정](#yolo-설정)
+6. [사용 패턴](#사용-패턴)
+7. [안전 메커니즘](#안전-메커니즘)
+8. [성능 최적화](#성능-최적화)
+9. [문제 해결](#문제-해결)
+10. [모범 사례](#모범-사례)
+
+## 개요
+
+YOLO(You Only Live Once) 모드는 Claude Code가 최소한의 인간 개입으로 독립적으로 작업할 수 있게 하는 AIWF의 자율 실행 시스템입니다. 이 시스템은 신뢰할 수 있는 자율 운영을 보장하기 위해 정교한 안전 메커니즘, 진행률 추적, 품질 제어를 포함합니다.
+
+### 주요 기능
+
+- **자율 태스크 실행**: 스프린트나 마일스톤을 자동으로 완료
+- **오버엔지니어링 방지**: 불필요한 복잡성에 대한 내장 가드
+- **진행률 추적**: 포괄적인 체크포인트 및 복구 시스템
+- **품질 제어**: 실시간 코드 품질 모니터링
+- **복구 메커니즘**: 강력한 오류 처리 및 상태 복원
+
+## 시스템 구성 요소
+
+### 아키텍처 개요
+
+```
+YOLO 모드
+├── Engineering Guard (오버엔지니어링 방지)
+├── Checkpoint Manager (진행률 추적 & 복구)
+├── Configuration System (동작 커스터마이징)
+├── Sprint Manager (태스크 조직화)
+└── Recovery System (실패 처리)
+```
+
+### 핵심 모듈
+
+1. **`utils/engineering-guard.js`**: 품질 제어 및 복잡성 방지
+2. **`utils/checkpoint-manager.js`**: 진행률 추적 및 복구
+3. **`src/config/yolo-config-template.yaml`**: 설정 템플릿
+4. **`src/commands/yolo-config.js`**: 설정 관리
+5. **`src/cli/checkpoint-cli.js`**: 전용 체크포인트 CLI
+
+## 엔지니어링 가드
+
+엔지니어링 가드는 자율 실행 중 오버엔지니어링을 방지하고 코드 품질을 유지합니다.
+
+### 핵심 기능
+
+#### 복잡성 모니터링
+- **파일 크기 제한**: 파일이 너무 커지는 것을 방지
+- **함수 크기 제어**: 함수를 관리 가능한 크기로 유지
+- **중첩 깊이**: 과도한 들여쓰기 제한
+- **패턴 감지**: 디자인 패턴의 과도한 사용 식별
+
+#### 설정 옵션
+
+```yaml
+overengineering_prevention:
+  max_file_lines: 300
+  max_function_lines: 50
+  max_nesting_depth: 4
+  max_abstraction_layers: 3
+  limit_design_patterns: true
+  no_future_proofing: true
+```
+
+### 사용 예제
+
+#### 프로그래밍 방식 사용
+```javascript
+import { EngineeringGuard } from 'aiwf/utils/engineering-guard';
+
+const guard = new EngineeringGuard('.aiwf/yolo-config.yaml');
+
+// 단일 파일 검사
+await guard.checkFileComplexity('src/app.js');
+const report = guard.generateReport();
+
+// 전체 프로젝트 검사
+const projectReport = await guard.checkProject('./src');
+```
+
+#### 실시간 피드백
+```javascript
+// 개발 중 즉각적인 피드백 받기
+const feedback = await guard.provideFeedback('src/new-feature.js');
+console.log(feedback);
+// 출력: [
+//   { level: 'warning', message: '파일이 너무 커지고 있습니다...' },
+//   { level: 'suggestion', message: '복잡한 조건문을 별도 함수로 추출 고려...' }
+// ]
+```
+
+### 감지 기능
+
+#### 디자인 패턴 감지
+- Factory 패턴
+- Singleton 사용
+- Observer 구현
+- Strategy 패턴
+- Decorator 패턴
+- Adapter 패턴
+
+#### 미래 대비 코드 감지
+- 미래 참조가 있는 TODO 주석
+- 조건부 FIXME 항목
+- 추측성 주석
+- 예약/플레이스홀더 코드
+- 버전별 검사
+
+## 체크포인트 매니저
+
+체크포인트 매니저는 진행률 추적, 상태 지속성, 복구 메커니즘을 처리합니다.
+
+### 핵심 기능
+
+#### 세션 관리
+```javascript
+import { CheckpointManager } from 'aiwf/utils/checkpoint-manager';
+
+const manager = new CheckpointManager('./project-root');
+
+// YOLO 세션 시작
+await manager.startSession('S01', 'sprint');
+
+// 태스크 진행률 추적
+await manager.startTask('T001_setup_api');
+await manager.completeTask('T001_setup_api', { files_created: 5 });
+
+// 수동 체크포인트 생성
+await manager.createCheckpoint('manual', { milestone: 'API setup complete' });
+```
+
+#### 복구 작업
+```javascript
+// 사용 가능한 체크포인트 목록
+const checkpoints = await manager.listCheckpoints();
+
+// 체크포인트에서 복구
+await manager.restoreFromCheckpoint('cp_1234567890');
+
+// 진행률 리포트 생성
+const report = await manager.generateProgressReport();
+```
+
+### 체크포인트 유형
+
+1. **session_start**: YOLO 세션 시작 시 생성
+2. **task_complete**: 각 태스크 완료 후 생성
+3. **auto**: 일정 간격으로 자동 생성
+4. **manual**: 사용자 요청에 의해 생성
+5. **session_end**: 세션 종료 시 생성
+
+### 상태 구조
+
+```json
+{
+  "session_id": "1703123456789",
+  "started_at": "2025-01-27T10:00:00Z",
+  "sprint_id": "S01",
+  "mode": "sprint",
+  "completed_tasks": [
+    {
+      "id": "T001_setup_api",
+      "completed_at": "2025-01-27T10:15:00Z",
+      "duration": 900000,
+      "attempts": 1
+    }
+  ],
+  "current_task": null,
+  "metrics": {
+    "completed_tasks": 1,
+    "failed_tasks": 0,
+    "total_time": 900000,
+    "avg_task_time": 900000
+  }
+}
+```
+
+## YOLO 설정
+
+### 설정 템플릿
+
+YOLO 설정 시스템은 YAML 파일을 사용하여 자율 동작을 제어합니다:
+
+```yaml
+# 엔지니어링 레벨 (minimal/balanced/complete)
+engineering_level: minimal
+
+# 범위 확산 방지를 위한 포커스 규칙
+focus_rules:
+  requirement_first: true
+  simple_solution: true
+  no_gold_plating: true
+  stay_on_track: true
+
+# 실행 설정
+execution:
+  fast_mode: true
+  run_tests: true
+  auto_commit: false
+  branch_strategy: feature
+
+# 안전 중단점
+breakpoints:
+  critical_files:
+    - .env
+    - database/migrations/*
+  test_failure_threshold: 10
+  schema_changes: true
+
+# 체크포인트 설정
+checkpoint:
+  enabled: true
+  interval: 5
+  recovery_mode: auto
+```
+
+### 설정 관리
+
+#### CLI 명령어
+```bash
+# 설정 초기화
+aiwf yolo-config init
+
+# 대화형 설정 마법사
+aiwf yolo-config wizard
+
+# 현재 설정 표시
+aiwf yolo-config show
+```
+
+#### 프로그래밍 방식 설정
+```javascript
+import { createYoloConfig, createInteractiveYoloConfig } from 'aiwf/commands/yolo-config';
+
+// 기본값으로 생성
+await createYoloConfig();
+
+// 대화형 설정
+await createInteractiveYoloConfig();
+```
+
+## 사용 패턴
+
+### 기본 YOLO 실행
+
+#### 스프린트 레벨 실행
+```bash
+# 특정 스프린트 실행
+/aiwf_yolo S02
+
+# 모든 스프린트 실행
+/aiwf_yolo sprint-all
+
+# 모든 마일스톤 실행
+/aiwf_yolo milestone-all
+```
+
+#### CLI 기반 스프린트 생성
+```bash
+# README에서 독립 스프린트 생성
+aiwf sprint independent --from-readme --minimal
+
+# GitHub 이슈에서 생성
+aiwf sprint independent --from-issue 123
+
+# 대화형 생성
+aiwf sprint independent "Quick Feature" --balanced
+```
+
+### 체크포인트 작업
+
+#### aiwf-checkpoint CLI 사용
+```bash
+# 체크포인트 목록
+aiwf-checkpoint list
+
+# 진행률 리포트 표시
+aiwf-checkpoint report
+
+# 체크포인트에서 복구
+aiwf checkpoint restore cp_1234567890
+
+# 수동 체크포인트 생성
+aiwf checkpoint create "주요 리팩토링 전"
+
+# 오래된 체크포인트 정리
+aiwf checkpoint clean --keep 10
+```
+
+### 복구 시나리오
+
+#### 세션 중단 복구
+```bash
+# 현재 세션 상태 확인
+aiwf-checkpoint status
+
+# 사용 가능한 복구 지점 목록
+aiwf-checkpoint list --limit 10
+
+# 마지막 안정 상태로 복구
+aiwf checkpoint restore cp_latest
+```
+
+## 안전 메커니즘
+
+### 오버엔지니어링 방지
+
+#### 자동 검사
+- **파일 크기 모니터링**: 파일이 제한을 초과할 때 경고
+- **복잡성 감지**: 지나치게 복잡한 코드 구조 식별
+- **패턴 과용**: 불필요한 디자인 패턴 방지
+- **미래 대비**: 추측성 구현 차단
+
+#### 수동 재정의
+```yaml
+# 특정 검사 비활성화
+overengineering_prevention:
+  max_file_lines: 500  # 제한 증가
+  limit_design_patterns: false  # 패턴 허용
+```
+
+### 실행 안전장치
+
+#### 중요 파일 보호
+```yaml
+breakpoints:
+  critical_files:
+    - .env
+    - package.json
+    - database/schema.sql
+```
+
+#### 테스트 실패 처리
+```yaml
+breakpoints:
+  test_failure_threshold: 10  # 10% 이상 테스트 실패 시 중단
+```
+
+#### 스키마 변경 확인
+```yaml
+breakpoints:
+  schema_changes: true  # DB 변경에 대한 확인 필요
+```
+
+## 성능 최적화
+
+### 체크포인트 최적화
+
+#### 자동 정리
+```javascript
+// 오래된 체크포인트 자동 정리
+await manager.cleanup(keepLast: 10);
+```
+
+#### 스토리지 효율성
+- 증분 상태 스냅샷
+- 압축된 체크포인트 데이터
+- 자동 오래된 체크포인트 제거
+
+### 실행 최적화
+
+#### 병렬 태스크 실행
+```yaml
+performance:
+  parallel_tasks: false  # 실험적 기능
+  use_cache: true
+  skip_unchanged: true
+```
+
+#### 메모리 관리
+- 지연 모듈 로딩
+- 리소스 풀링
+- 자동 가비지 컬렉션
+
+## 문제 해결
+
+### 일반적인 문제
+
+#### 엔지니어링 가드가 작동하지 않음
+```bash
+# 모듈 존재 확인
+ls -la src/utils/engineering-guard.js
+
+# 동적 import 테스트
+node -e "import('./src/utils/engineering-guard.js').then(console.log)"
+
+# 설정 확인
+cat .aiwf/yolo-config.yaml
+```
+
+#### 체크포인트 시스템 실패
+```bash
+# 체크포인트 디렉토리 확인
+ls -la .aiwf/checkpoints/
+
+# 권한 확인
+chmod 755 .aiwf/checkpoints/
+
+# 체크포인트 생성 테스트
+aiwf checkpoint create "test-checkpoint"
+```
+
+#### 설정 문제
+```bash
+# 설정 재생성
+aiwf yolo-config init --force
+
+# 설정 검증
+aiwf yolo-config show
+
+# 기본값으로 재설정
+rm .aiwf/yolo-config.yaml && aiwf yolo-config init
+```
+
+### 복구 절차
+
+#### 손상된 상태 복구
+```bash
+# 사용 가능한 체크포인트 목록
+aiwf-checkpoint list
+
+# 알려진 정상 상태로 복구
+aiwf checkpoint restore cp_last_known_good
+
+# 필요시 재초기화
+aiwf yolo-config init --force
+```
+
+#### Git 상태 불일치
+```bash
+# 체크포인트의 Git 상태 확인
+aiwf-checkpoint show cp_1234567890
+
+# 필요시 Git 상태 복원
+git checkout checkpoint_branch_name
+git reset --hard checkpoint_commit_hash
+```
+
+## 모범 사례
+
+### 설정 관리
+
+1. **보수적으로 시작**: 최소 엔지니어링 레벨로 시작
+2. **점진적 커스터마이징**: 프로젝트 요구에 따라 설정 조정
+3. **결과 모니터링**: 메트릭 추적 및 임계값 조정
+4. **변경 문서화**: 설정 변경을 버전 제어에 보관
+
+### 세션 관리
+
+1. **정기적 체크포인트**: 논리적 마일스톤에서 체크포인트 생성
+2. **진행률 모니터링**: 주기적으로 세션 상태 확인
+3. **정리**: 오래된 체크포인트 정기적 제거
+4. **복구 계획**: 복구 절차 준비
+
+### 품질 제어
+
+1. **적절한 제한 설정**: 프로젝트에 맞는 복잡성 제한 구성
+2. **위반 모니터링**: 엔지니어링 가드 리포트 검토
+3. **조기 문제 해결**: 복잡성 문제가 누적되기 전에 수정
+4. **속도 vs 품질 균형**: 요구에 따라 엔지니어링 레벨 조정
+
+### 성능 최적화
+
+1. **캐싱 사용**: 반복 작업에 캐싱 활성화
+2. **체크포인트 최적화**: 오래된 체크포인트 정기적 정리
+3. **리소스 모니터링**: 메모리 및 디스크 사용량 추적
+4. **성능 프로파일링**: 자율 실행의 병목 지점 식별
+
+## 통합 예제
+
+### 커스텀 YOLO 워크플로
+
+```javascript
+import { CheckpointManager } from 'aiwf/utils/checkpoint-manager';
+import { EngineeringGuard } from 'aiwf/utils/engineering-guard';
+
+class CustomYoloWorkflow {
+  constructor(projectRoot) {
+    this.checkpointManager = new CheckpointManager(projectRoot);
+    this.engineeringGuard = new EngineeringGuard('.aiwf/yolo-config.yaml');
+  }
+  
+  async executeWithGuards(tasks) {
+    await this.checkpointManager.startSession('custom', 'workflow');
+    
+    for (const task of tasks) {
+      await this.checkpointManager.startTask(task.id);
+      
+      // 태스크 실행...
+      const result = await this.executeTask(task);
+      
+      // 품질 확인
+      const report = await this.engineeringGuard.checkProject('./src');
+      if (!report.passed) {
+        console.warn('품질 문제 감지:', report.violations);
+      }
+      
+      await this.checkpointManager.completeTask(task.id, result);
+    }
+    
+    return await this.checkpointManager.endSession();
+  }
+}
+```
+
+## 관련 명령어
+
+### Claude Code 명령어
+- `/project:aiwf:yolo` - 메인 YOLO 실행 명령어
+- `/aiwf_yolo` - 자율 태스크 실행
+- `/aiwf_checkpoint_status` - 현재 진행률 확인
+
+### CLI 명령어
+- `aiwf yolo-config` - 설정 관리
+- `aiwf checkpoint` - 체크포인트 작업
+- `aiwf-checkpoint` - 전용 체크포인트 CLI
+- `aiwf sprint independent` - 독립 스프린트 생성
+
+## 관련 문서
+
+- [CLI_USAGE_GUIDE.md](CLI_USAGE_GUIDE.ko.md) - CLI 명령어 참조
+- [COMMANDS_GUIDE.md](COMMANDS_GUIDE.ko.md) - Claude Code 명령어 가이드
+- [MODULE_MANAGEMENT_GUIDE.md](MODULE_MANAGEMENT_GUIDE.ko.md) - 모듈 아키텍처
+- [Independent Sprint Guide](guides/independent-sprint-guide-ko.md) - 스프린트 관리
+- [Checkpoint System Guide](guides/checkpoint-system-guide-ko.md) - 체크포인트 세부사항
+
+---
+
+**마지막 업데이트**: 2025-01-27  
+**버전**: AIWF v0.3.16+ 호환