aiwf 0.3.1 → 0.3.3

package/.aiwf/01_PROJECT_DOCS/FEATURE_LEDGER_FAQ.md

@@ -0,0 +1,365 @@
+# Feature Ledger FAQ & Troubleshooting Guide
+
+## 자주 묻는 질문 (FAQ)
+
+### 일반 질문
+
+#### Q: Feature Ledger와 일반 Task의 차이점은 무엇인가요?
+
+**A:** Feature Ledger는 더 큰 범위의 기능 개발을 추적합니다:
+
+| 항목 | Feature Ledger | Task |
+|------|----------------|------|
+| 범위 | 전체 기능 (1-2주) | 단일 작업 (1-2일) |
+| 추적 | Git, PR, 진행률 | 완료 여부 |
+| 팀 | 여러 명 가능 | 보통 1명 |
+| 출력물 | 배포 가능한 기능 | 코드 변경 |
+
+#### Q: Feature ID는 어떻게 생성되나요?
+
+**A:** Feature ID는 자동으로 순차 생성됩니다:
+- 형식: `FL###` (FL001, FL002, ...)
+- 재사용 불가
+- 삭제된 ID도 재사용하지 않음
+- 수동 지정 불가
+
+#### Q: 완료된 Feature를 다시 활성화할 수 있나요?
+
+**A:** 아니요, 완료된 Feature는 다시 활성화할 수 없습니다. 추가 작업이 필요한 경우:
+1. 새로운 Feature를 생성하여 개선 사항 추적
+2. 원본 Feature를 참조 (`depends_on: [FL001]`)
+3. 명확한 범위로 새 작업 정의
+
+#### Q: Feature와 GitHub Issue를 어떻게 연결하나요?
+
+**A:** 여러 방법이 있습니다:
+
+1. **자동 연결**: PR 제목에 Feature ID 포함
+   ```
+   feat(FL001): Implement user authentication
+   ```
+
+2. **수동 연결**: 명령어 사용
+   ```bash
+   /project:aiwf:link_feature_issue FL001 #42
+   ```
+
+3. **Issue 본문에 참조**:
+   ```markdown
+   Related Feature: FL001
+   ```
+
+### 사용법 질문
+
+#### Q: 여러 스프린트에 걸친 Feature는 어떻게 관리하나요?
+
+**A:** `sprint_ids` 배열을 사용합니다:
+
+```yaml
+sprint_ids: [S01_M02, S02_M02, S03_M02]
+```
+
+각 스프린트에서:
+1. 해당 스프린트의 작업만 Task로 생성
+2. Feature 진행률은 전체 기준으로 업데이트
+3. 스프린트별 진행 상황을 Progress Log에 기록
+
+#### Q: Feature 진행률은 어떻게 계산하나요?
+
+**A:** 세 가지 방법이 있습니다:
+
+1. **수동 업데이트**:
+   ```bash
+   /project:aiwf:update_feature_progress FL001 75
+   ```
+
+2. **체크리스트 기반**:
+   ```
+   완료 항목 / 전체 항목 × 100
+   ```
+
+3. **연결된 Task 기반**:
+   ```
+   완료 Task / 전체 Task × 100
+   ```
+
+#### Q: Feature 템플릿을 커스터마이징할 수 있나요?
+
+**A:** 네, 가능합니다:
+
+1. 기본 템플릿 복사:
+   ```bash
+   cp .aiwf/99_TEMPLATES/feature_template.md .aiwf/99_TEMPLATES/my_feature_template.md
+   ```
+
+2. 템플릿 수정
+
+3. 사용:
+   ```bash
+   /project:aiwf:create_feature_ledger new_feature --template my_feature_template
+   ```
+
+### 통합 질문
+
+#### Q: CI/CD 파이프라인과 어떻게 통합하나요?
+
+**A:** GitHub Actions 예제:
+
+```yaml
+- name: Update Feature on Deploy
+  if: success()
+  run: |
+    FEATURE_ID=$(git log -1 --pretty=%B | grep -oP 'FL\d{3}')
+    if [ ! -z "$FEATURE_ID" ]; then
+      npx aiwf update_feature_progress $FEATURE_ID 90 --comment "Deployed to staging"
+    fi
+```
+
+#### Q: 여러 저장소에서 하나의 Feature를 작업할 때는?
+
+**A:** Cross-repo Feature 추적:
+
+1. 메인 저장소에 Feature Ledger 생성
+2. 다른 저장소에서 커밋 시 Feature ID 참조
+3. 정기적으로 동기화:
+   ```bash
+   /project:aiwf:feature_sync --cross-repo
+   ```
+
+## 문제 해결 가이드
+
+### 일반적인 오류
+
+#### Error E001: Feature ID not found
+
+**증상**:
+```
+Error E001: Feature ID 'FL099' not found
+```
+
+**원인**:
+- 잘못된 Feature ID
+- Feature가 다른 디렉토리에 있음
+
+**해결**:
+```bash
+# 올바른 ID 확인
+cat .aiwf/06_FEATURE_LEDGERS/FEATURE_LEDGER_INDEX.md
+
+# 모든 Feature 검색
+find .aiwf/06_FEATURE_LEDGERS -name "*.md" | grep -v INDEX
+```
+
+#### Error E002: Invalid status transition
+
+**증상**:
+```
+Error E002: Cannot transition from 'completed' to 'active'
+```
+
+**원인**:
+- 허용되지 않는 상태 전환
+- Feature가 이미 archived 상태
+
+**해결**:
+1. 현재 상태 확인
+2. [상태 전이 다이어그램](./FEATURE_LEDGER_SYSTEM_OVERVIEW.md#상태-전이-다이어그램) 참조
+3. 필요시 새 Feature 생성
+
+#### Error E003: Duplicate feature ID
+
+**증상**:
+```
+Error E003: Feature ID 'FL001' already exists
+```
+
+**원인**:
+- ID 생성 시퀀스 오류
+- 수동으로 파일 생성
+
+**해결**:
+```bash
+# 인덱스 재구성
+/project:aiwf:feature_index --rebuild
+
+# 다음 가용 ID 확인
+/project:aiwf:feature_next_id
+```
+
+### Git 통합 문제
+
+#### 브랜치 생성 실패
+
+**증상**:
+```
+Failed to create branch: feature/FL001-user-auth
+```
+
+**원인**:
+- 브랜치가 이미 존재
+- Git 저장소가 아님
+- 권한 부족
+
+**해결**:
+```bash
+# 기존 브랜치 확인
+git branch -a | grep FL001
+
+# 강제 생성
+/project:aiwf:feature_branch FL001 create --force
+
+# 수동 생성
+git checkout -b feature/FL001-user-auth
+```
+
+#### 커밋 연결 안 됨
+
+**증상**: 커밋했는데 Feature에 반영되지 않음
+
+**원인**:
+- 커밋 메시지에 Feature ID 없음
+- 자동 동기화 비활성화
+
+**해결**:
+```bash
+# 수동 연결
+/project:aiwf:link_feature_commit FL001 --commit HEAD
+
+# 자동 동기화 활성화
+export AIWF_AUTO_SYNC=true
+```
+
+### 성능 문제
+
+#### 대시보드 생성이 느림
+
+**증상**: Feature가 많을 때 대시보드 생성 지연
+
+**해결**:
+```bash
+# 캐시 재구성
+/project:aiwf:feature_cache --rebuild
+
+# 특정 범위만 표시
+/project:aiwf:feature_dashboard --limit 50 --status active
+```
+
+#### 검색이 느림
+
+**증상**: Feature 검색 시 응답 지연
+
+**해결**:
+```bash
+# 인덱스 최적화
+/project:aiwf:feature_index --optimize
+
+# 검색 범위 제한
+/project:aiwf:feature_search "query" --status active --limit 20
+```
+
+### 데이터 복구
+
+#### Feature 파일 손상
+
+**증상**: Feature 파일을 열 수 없음
+
+**해결**:
+```bash
+# 백업에서 복구
+cp .aiwf/backups/FL001_*.md .aiwf/06_FEATURE_LEDGERS/active/
+
+# Git 히스토리에서 복구
+git checkout HEAD~1 -- .aiwf/06_FEATURE_LEDGERS/active/FL001_*.md
+```
+
+#### 인덱스 불일치
+
+**증상**: 인덱스와 실제 파일이 다름
+
+**해결**:
+```bash
+# 전체 인덱스 재구성
+/project:aiwf:feature_index --rebuild --verbose
+
+# 무결성 검사
+/project:aiwf:feature_validate --fix
+```
+
+## 고급 문제 해결
+
+### 디버깅 모드
+
+상세한 로그를 보려면:
+
+```bash
+# 디버그 모드 활성화
+export AIWF_DEBUG=true
+
+# 상세 로그와 함께 실행
+/project:aiwf:create_feature_ledger test_feature --verbose
+```
+
+### 로그 분석
+
+```bash
+# 오류 로그만 보기
+grep ERROR .aiwf/logs/feature_ledger.log
+
+# 특정 Feature 추적
+grep FL001 .aiwf/logs/feature_ledger.log | tail -20
+
+# 시간대별 분석
+grep "2025-07-09" .aiwf/logs/feature_ledger.log | grep ERROR
+```
+
+### 수동 수정
+
+직접 파일을 수정해야 할 때:
+
+1. **백업 생성**:
+   ```bash
+   cp -r .aiwf/06_FEATURE_LEDGERS .aiwf/06_FEATURE_LEDGERS.backup
+   ```
+
+2. **파일 수정**
+
+3. **검증**:
+   ```bash
+   /project:aiwf:feature_validate FL001
+   ```
+
+4. **인덱스 업데이트**:
+   ```bash
+   /project:aiwf:feature_index --update FL001
+   ```
+
+## 지원 받기
+
+### 1. 문서 참조
+- [User Guide](./FEATURE_LEDGER_USER_GUIDE.md)
+- [API Reference](./FEATURE_LEDGER_API_REFERENCE.md)
+- [System Overview](./FEATURE_LEDGER_SYSTEM_OVERVIEW.md)
+
+### 2. 커뮤니티
+- GitHub Issues: `https://github.com/aiwf/aiwf/issues`
+- Discord: AIWF 커뮤니티 채널
+
+### 3. 버그 리포트
+
+버그 발견 시:
+1. 재현 가능한 단계 기록
+2. 로그 파일 수집
+3. GitHub Issue 생성:
+   ```markdown
+   **버그 설명**: [간단한 설명]
+   **재현 단계**:
+   1. ...
+   2. ...
+   **예상 동작**: [예상했던 결과]
+   **실제 동작**: [실제 발생한 결과]
+   **로그**: [관련 로그 첨부]
+   ```
+
+---
+
+*이 문서는 지속적으로 업데이트됩니다. 최신 버전은 [GitHub](https://github.com/aiwf/aiwf)에서 확인하세요.*

package/.aiwf/01_PROJECT_DOCS/FEATURE_LEDGER_SYSTEM_OVERVIEW.md

@@ -0,0 +1,305 @@
+# Feature Ledger System Overview
+
+## 시스템 개요
+
+Feature Ledger System은 AIWF의 핵심 구성 요소로, 프로젝트의 모든 기능 개발을 추적하고 관리합니다. 이 시스템은 개발 프로세스의 투명성을 높이고, 팀 협업을 강화하며, 프로젝트 진행 상황을 실시간으로 파악할 수 있게 합니다.
+
+## 아키텍처
+
+### 시스템 구성도
+
+```mermaid
+graph TB
+    subgraph "User Interface"
+        CLI[CLI Commands]
+        API[API Endpoints]
+    end
+    
+    subgraph "Core System"
+        FL[Feature Ledger Core]
+        VM[Validation Module]
+        SM[State Manager]
+        IM[Index Manager]
+    end
+    
+    subgraph "Integration Layer"
+        GI[Git Integration]
+        SI[Sprint Integration]
+        AI[AI Context Integration]
+    end
+    
+    subgraph "Storage"
+        FS[File System]
+        IDX[Index Files]
+        TMPL[Templates]
+    end
+    
+    CLI --> FL
+    API --> FL
+    FL --> VM
+    FL --> SM
+    FL --> IM
+    FL --> GI
+    FL --> SI
+    FL --> AI
+    VM --> FS
+    SM --> FS
+    IM --> IDX
+    GI --> FS
+    SI --> FS
+    AI --> FS
+```
+
+### 데이터 플로우
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant FeatureLedger
+    participant StateManager
+    participant FileSystem
+    participant GitIntegration
+    
+    User->>CLI: create_feature_ledger
+    CLI->>FeatureLedger: parseCommand()
+    FeatureLedger->>StateManager: validateState()
+    StateManager->>FileSystem: checkExisting()
+    FileSystem-->>StateManager: notExists
+    StateManager->>FileSystem: createFeature()
+    FileSystem-->>StateManager: created
+    StateManager->>GitIntegration: createBranch()
+    GitIntegration-->>StateManager: branchCreated
+    StateManager-->>FeatureLedger: success
+    FeatureLedger-->>CLI: featureCreated
+    CLI-->>User: FL001 Created
+```
+
+### 상태 전이 다이어그램
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: create_feature
+    Active --> Paused: pause_feature
+    Active --> Completed: complete_feature
+    Active --> Archived: archive_feature
+    Paused --> Active: resume_feature
+    Paused --> Archived: archive_feature
+    Completed --> Archived: archive_feature
+    Archived --> [*]
+    
+    Active: Active\n- 개발 진행 중\n- 리소스 할당됨\n- 진행률 추적
+    Paused: Paused\n- 일시 중단\n- 리소스 재할당\n- 이유 문서화
+    Completed: Completed\n- 개발 완료\n- 테스트 통과\n- 문서 업데이트
+    Archived: Archived\n- 보관 상태\n- 읽기 전용\n- 히스토리 보존
+```
+
+## 핵심 구성 요소
+
+### 1. Feature Ledger Core
+
+시스템의 중앙 처리 엔진으로 다음 기능을 담당합니다:
+
+- **명령어 파싱**: 사용자 입력을 해석하고 검증
+- **비즈니스 로직**: Feature 생성, 업데이트, 상태 관리
+- **이벤트 처리**: 상태 변경 시 관련 시스템에 알림
+
+### 2. State Manager
+
+Feature의 생명주기를 관리합니다:
+
+- **상태 검증**: 유효한 상태 전환만 허용
+- **히스토리 추적**: 모든 상태 변경 기록
+- **일관성 보장**: 데이터 무결성 유지
+
+### 3. Index Manager
+
+빠른 검색과 조회를 위한 인덱싱 시스템:
+
+- **실시간 인덱싱**: Feature 변경 시 즉시 업데이트
+- **다중 인덱스**: ID, 상태, 태그, 담당자별 인덱스
+- **성능 최적화**: 캐싱 및 증분 업데이트
+
+### 4. Integration Modules
+
+#### Git Integration
+```mermaid
+graph LR
+    A[Feature] --> B{Git Action}
+    B --> C[Create Branch]
+    B --> D[Link Commit]
+    B --> E[Link PR]
+    C --> F[feature/FL001-name]
+    D --> G[Commit History]
+    E --> H[PR Status]
+```
+
+#### Sprint Integration
+- Feature와 Sprint/Task의 양방향 연결
+- 진행률 자동 계산
+- 마일스톤 추적
+
+#### AI Context Integration
+- 활성 Feature를 AI 컨텍스트에 포함
+- 토큰 효율을 위한 압축
+- 관련 Feature 자동 제안
+
+## 디렉토리 구조
+
+```
+.aiwf/06_FEATURE_LEDGERS/
+├── active/                    # 진행 중인 Feature
+│   ├── FL001_User_Auth.md
+│   └── FL002_Dashboard.md
+├── completed/                 # 완료된 Feature
+│   └── FL000_Initial.md
+├── archived/                  # 보관된 Feature
+│   └── FL_Archive_2025Q1/
+├── paused/                    # 일시 중단된 Feature
+│   └── FL003_Analytics.md
+├── FEATURE_LEDGER_INDEX.md    # 메인 인덱스
+├── FEATURE_SCHEMA.md          # 데이터 스키마
+├── FEATURE_STATE_DIAGRAM.md   # 상태 다이어그램
+├── FEATURE_INTEGRATION_GUIDE.md # 통합 가이드
+└── FEATURE_GIT_INTEGRATION.md # Git 통합 상세
+```
+
+## 데이터 모델
+
+### Feature Entity
+
+```yaml
+# 핵심 식별 정보
+feature_id: string (required, unique)
+title: string (required)
+status: enum [active, completed, paused, archived]
+created_date: date
+last_updated: datetime
+
+# 프로젝트 연결
+milestone: string
+sprint_ids: array<string>
+tasks: array<string>
+
+# 팀 정보
+assignee: string
+contributors: array<string>
+reviewers: array<string>
+
+# 분류
+priority: enum [critical, high, medium, low]
+complexity: enum [simple, moderate, complex]
+category: enum [feature, enhancement, bugfix, refactor]
+tags: array<string>
+
+# 시간 추적
+estimated_hours: number
+actual_hours: number
+estimated_completion: date
+actual_completion: date
+
+# Git 통합
+git_branch: string
+git_commits: array<commit_hash>
+pull_requests: array<pr_object>
+
+# 의존성
+depends_on: array<feature_id>
+blocks: array<feature_id>
+
+# 진행 상황
+progress_percentage: number (0-100)
+checklist_items_total: number
+checklist_items_completed: number
+
+# 리스크 관리
+risk_level: enum [low, medium, high]
+known_issues: array<string>
+mitigation_plans: array<string>
+```
+
+## 통합 지점
+
+### 1. AIWF 프로젝트 구조
+
+```mermaid
+graph TD
+    PM[Project Manifest] --> FL[Feature Ledgers]
+    MS[Milestones] --> FL
+    SP[Sprints] --> FL
+    TK[Tasks] --> FL
+    FL --> GH[GitHub]
+    FL --> AI[AI Context]
+    FL --> RP[Reports]
+```
+
+### 2. 외부 시스템 연동
+
+- **GitHub API**: PR, Issue, Commit 자동 연결
+- **CI/CD**: 빌드 상태와 Feature 진행률 연동
+- **프로젝트 관리 도구**: JIRA, Trello 등과 동기화 가능
+
+## 성능 고려사항
+
+### 인덱싱 성능
+
+- 인덱스 업데이트: < 100ms
+- Feature 검색: < 50ms (1000개 기준)
+- 대시보드 생성: < 1s
+
+### 확장성
+
+- Feature 수: 10,000개까지 테스트됨
+- 동시 사용자: 100명까지 지원
+- 파일 크기: 각 Feature 최대 1MB
+
+### 최적화 전략
+
+1. **증분 업데이트**: 전체 재생성 대신 변경된 부분만 업데이트
+2. **캐싱**: 자주 조회되는 데이터 메모리 캐싱
+3. **비동기 처리**: 무거운 작업은 백그라운드에서 처리
+
+## 보안 고려사항
+
+### 접근 제어
+
+- 파일 시스템 권한 기반
+- Git 권한과 연동
+- 민감 정보 마스킹
+
+### 감사 추적
+
+- 모든 변경사항 로깅
+- 사용자별 활동 추적
+- 변경 이력 보존
+
+## 향후 로드맵
+
+### Phase 1 (현재)
+- ✅ 기본 CRUD 기능
+- ✅ Git 통합
+- ✅ Sprint/Task 연동
+- ⏳ 대시보드 생성
+
+### Phase 2 (계획)
+- 📋 웹 UI 인터페이스
+- 📋 고급 검색 기능
+- 📋 자동화된 보고서
+- 📋 AI 기반 인사이트
+
+### Phase 3 (미래)
+- 🔮 다국어 지원
+- 🔮 플러그인 시스템
+- 🔮 외부 도구 통합 API
+- 🔮 모바일 앱 지원
+
+## 관련 문서
+
+- [API Reference](./FEATURE_LEDGER_API_REFERENCE.md)
+- [User Guide](./FEATURE_LEDGER_USER_GUIDE.md)
+- [Technical Specification](../02_REQUIREMENTS/M02_Context_Engineering_Enhancement/SPECS_Feature_Ledger_System.md)
+- [Integration Guide](../06_FEATURE_LEDGERS/FEATURE_INTEGRATION_GUIDE.md)
+
+---
+
+*Feature Ledger System v1.0 - AIWF Project*