aiwf 0.3.1 → 0.3.2

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

@@ -0,0 +1,253 @@
+# 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/guides/ai-personas-guide-ko.md

@@ -0,0 +1,239 @@
+[Read in English](ai-personas-guide.md)
+
+# AI 페르소나 사용 가이드
+
+## 개요
+
+AIWF의 AI 페르소나 시스템은 개발 작업의 특성에 맞춰 Claude Code의 행동 패턴을 최적화하는 기능입니다. 5개의 전문화된 페르소나를 통해 각 작업에 가장 적합한 AI 어시스턴트를 활용할 수 있습니다.
+
+## 페르소나 유형
+
+### 1. Architect (아키텍트)
+**목적**: 시스템 설계 및 아키텍처 결정
+
+**특징**:
+- 큰 그림과 시스템 전체 구조에 집중
+- 확장성과 유지보수성 우선 고려
+- 디자인 패턴과 아키텍처 원칙 적용
+- 기술 스택 선택과 통합 전략 수립
+
+**사용 시나리오**:
+- 새로운 기능의 설계 단계
+- 시스템 리팩토링 계획
+- 기술 스택 결정
+- 모듈 간 인터페이스 설계
+
+**명령어**:
+```bash
+/project:aiwf:ai_persona:architect
+# 또는 한국어
+/프로젝트:aiwf:ai_페르소나:아키텍트
+```
+
+### 2. Debugger (디버거)
+**목적**: 버그 찾기 및 문제 해결
+
+**특징**:
+- 상세한 코드 분석과 오류 추적
+- 단계별 실행 흐름 검증
+- 엣지 케이스와 예외 상황 고려
+- 성능 병목 현상 식별
+
+**사용 시나리오**:
+- 버그 재현 및 원인 분석
+- 성능 문제 해결
+- 메모리 누수 추적
+- 예외 처리 개선
+
+**명령어**:
+```bash
+/project:aiwf:ai_persona:debugger
+# 또는 한국어
+/프로젝트:aiwf:ai_페르소나:디버거
+```
+
+### 3. Reviewer (리뷰어)
+**목적**: 코드 품질 검토 및 개선
+
+**특징**:
+- 코딩 표준 준수 검증
+- 보안 취약점 식별
+- 최적화 기회 발견
+- 가독성과 유지보수성 평가
+
+**사용 시나리오**:
+- PR 리뷰 준비
+- 코드 품질 개선
+- 보안 감사
+- 리팩토링 제안
+
+**명령어**:
+```bash
+/project:aiwf:ai_persona:reviewer
+# 또는 한국어
+/프로젝트:aiwf:ai_페르소나:리뷰어
+```
+
+### 4. Documenter (문서화 전문가)
+**목적**: 문서 작성 및 관리
+
+**특징**:
+- 명확하고 이해하기 쉬운 설명
+- API 문서 자동 생성
+- 사용 예시와 튜토리얼 작성
+- 다국어 문서 지원
+
+**사용 시나리오**:
+- README 작성
+- API 문서화
+- 사용자 가이드 작성
+- 기술 사양서 작성
+
+**명령어**:
+```bash
+/project:aiwf:ai_persona:documenter
+# 또는 한국어
+/프로젝트:aiwf:ai_페르소나:문서화전문가
+```
+
+### 5. Optimizer (최적화 전문가)
+**목적**: 성능 최적화 및 효율성 개선
+
+**특징**:
+- 알고리즘 복잡도 분석
+- 메모리 사용량 최적화
+- 실행 시간 단축
+- 리소스 효율성 개선
+
+**사용 시나리오**:
+- 성능 병목 지점 개선
+- 알고리즘 최적화
+- 데이터베이스 쿼리 개선
+- 메모리 사용량 감소
+
+**명령어**:
+```bash
+/project:aiwf:ai_persona:optimizer
+# 또는 한국어
+/프로젝트:aiwf:ai_페르소나:최적화전문가
+```
+
+## 페르소나 전환 방법
+
+### 기본 사용법
+1. 작업 시작 전 적절한 페르소나 선택
+2. 명령어 입력으로 페르소나 활성화
+3. 작업 수행
+4. 필요시 다른 페르소나로 전환
+
+### 예시 워크플로우
+```bash
+# 1. 새 기능 설계
+/project:aiwf:ai_persona:architect
+"새로운 사용자 인증 시스템을 설계해주세요"
+
+# 2. 구현 후 버그 발견
+/project:aiwf:ai_persona:debugger
+"로그인 시 세션이 유지되지 않는 문제를 해결해주세요"
+
+# 3. 코드 리뷰
+/project:aiwf:ai_persona:reviewer
+"구현한 인증 시스템 코드를 리뷰해주세요"
+
+# 4. 문서 작성
+/project:aiwf:ai_persona:documenter
+"인증 API 문서를 작성해주세요"
+```
+
+## 페르소나별 컨텍스트 규칙
+
+각 페르소나는 고유한 컨텍스트 처리 규칙을 가지고 있습니다:
+
+### Architect 컨텍스트
+- **우선순위**: 시스템 설계 문서, 아키텍처 다이어그램
+- **포커스**: 인터페이스, 모듈 구조, 의존성
+- **제외**: 구현 세부사항, 임시 코드
+
+### Debugger 컨텍스트
+- **우선순위**: 오류 로그, 스택 트레이스, 테스트 결과
+- **포커스**: 실행 흐름, 변수 상태, 조건문
+- **제외**: 문서, 주석, 스타일 관련 코드
+
+### Reviewer 컨텍스트
+- **우선순위**: 변경된 코드, 커밋 히스토리
+- **포커스**: 코딩 표준, 보안 패턴, 성능 영향
+- **제외**: 테스트 데이터, 빌드 파일
+
+### Documenter 컨텍스트
+- **우선순위**: 공개 API, 사용 예시, README
+- **포커스**: 사용자 관점, 명확성, 완전성
+- **제외**: 내부 구현, 디버그 코드
+
+### Optimizer 컨텍스트
+- **우선순위**: 성능 측정 결과, 프로파일링 데이터
+- **포커스**: 시간 복잡도, 공간 복잡도, 리소스 사용
+- **제외**: 문서, UI 코드, 테스트 코드
+
+## 모범 사례
+
+### 1. 작업에 맞는 페르소나 선택
+- 작업의 성격을 고려하여 가장 적합한 페르소나 선택
+- 한 작업에 여러 페르소나가 필요한 경우 순차적으로 전환
+
+### 2. 페르소나 전환 타이밍
+- 작업 단계가 바뀔 때 적절한 페르소나로 전환
+- 같은 유형의 작업은 동일한 페르소나로 일관성 유지
+
+### 3. 컨텍스트 관리
+- 페르소나 전환 시 이전 작업 결과를 명확히 전달
+- 각 페르소나의 강점을 활용한 작업 분담
+
+### 4. 협업 시나리오
+```bash
+# 팀 프로젝트에서의 페르소나 활용
+1. Architect: 전체 시스템 설계
+2. Developer: 기능 구현 (기본 모드)
+3. Debugger: 통합 테스트 및 버그 수정
+4. Reviewer: 코드 리뷰 및 개선
+5. Documenter: 최종 문서화
+```
+
+## 문제 해결
+
+### 페르소나가 예상대로 작동하지 않을 때
+1. 명령어가 정확히 입력되었는지 확인
+2. 현재 프로젝트 컨텍스트가 AIWF인지 확인
+3. 페르소나 전환 후 2-3초 대기
+4. 문제 지속 시 기본 모드로 리셋 후 재시도
+
+### 성능 저하
+- 복잡한 작업 시 페르소나 전환 최소화
+- 대용량 코드베이스에서는 관련 파일만 포함
+- 필요 없는 컨텍스트는 제외 설정 활용
+
+### 컨텍스트 충돌
+- 페르소나별 컨텍스트 규칙 확인
+- 충돌하는 정보는 명시적으로 우선순위 지정
+- 필요시 수동으로 컨텍스트 정리
+
+## 고급 활용법
+
+### 1. 페르소나 체인
+여러 페르소나를 연속적으로 활용하여 복잡한 작업 수행:
+```bash
+Architect → Developer → Debugger → Optimizer → Documenter
+```
+
+### 2. 페르소나 커스터마이징
+프로젝트별 특수 요구사항에 맞춰 페르소나 동작 조정 가능
+(향후 업데이트 예정)
+
+### 3. 팀 워크플로우 통합
+Git 브랜치나 PR 상태에 따라 자동 페르소나 전환
+(Feature-Git 연동 기능과 함께 사용)
+
+## 결론
+
+AI 페르소나 시스템은 개발 작업의 효율성과 품질을 크게 향상시킬 수 있는 강력한 도구입니다. 각 페르소나의 특성을 이해하고 적절히 활용하면, Claude Code와의 협업이 더욱 생산적이고 효과적이 됩니다.
+
+지속적인 사용과 피드백을 통해 각 프로젝트에 최적화된 페르소나 활용 전략을 개발하시기 바랍니다.