aiwf 0.3.3 → 0.3.5

package/.claude/commands/aiwf/aiwf_project_review.md

@@ -0,0 +1,261 @@
+# 프로젝트 리뷰 - 탑 다운 실행
+
+아키텍처, 진행 상황, 기술 결정에 초점을 맞춘 포괄적인 프로젝트 수준 리뷰를 수행합니다.
+
+**중요사항:**
+
+- 이는 최근 변경 사항이 아닌 전체 프로젝트 상태에 대한 고수준 리뷰입니다.
+- 프로젝트 문서에 명확히 언급되지 않은 한, 타임라인과 일정은 관련이 없습니다
+
+## 정확히 다음 9개 항목으로 TODO 생성
+
+1. 리뷰 범위 및 타이밍 분석
+2. 테스트 인프라 상태 실행 및 평가
+3. 프로젝트 문서 정렬 평가
+4. 마일스톤 및 스프린트 진행 상황 검토
+5. 코드베이스 아키텍처 및 구조 분석
+6. 파일 구성 및 워크플로우 준수 감사
+7. 기술적 결정 및 복잡성 평가
+8. 구현 품질 비평 (John Carmack 관점)
+9. 권장 사항과 함께 포괄적인 평가 제공
+
+단계별로 진행하며 각 단계에 대한 다음 지침을 엄격히 준수하세요.
+
+## 모든 TODO 항목에 대한 세부사항
+
+### 1. 리뷰 범위 및 타이밍 분석
+
+확인: <$ARGUMENTS>
+
+비어있다면 전체 프로젝트 리뷰를 수행합니다. 그렇지 않으면 <$ARGUMENTS>를 해석하여 특정 초점 영역(마일스톤, 스프린트, 아키텍처 구성 요소 등)을 식별합니다. Argument에 명시되지 않은 한 `.aiwf/10_STATE_OF_PROJECT`의 이전 프로젝트 리뷰와 비교하지 마세요.
+
+**중요:** 이 리뷰는 최근 변경사항의 맥락에서 전체 프로젝트 상태를 살펴봅니다.
+
+**핵심:** `.aiwf/00_PROJECT_MANIFEST.md`를 **먼저** 읽어서 다음을 이해하세요:
+
+- 현재 마일스톤 및 스프린트 상태
+- 완료된 작업 vs 진행 중인 작업 vs 계획된 작업
+- 활성 스프린트 목표 및 결과물
+
+**맥락 확인:** 기능 평가 전에:
+
+- `.aiwf/03_SPRINTS/`로 이동하여 현재 스프린트 찾기
+- 스프린트 메타 파일을 읽어 범위 내에 있는 것 이해하기
+- 스프린트 내에서 완료된 태스크 vs 계획된 태스크 확인
+- 향후 스프린트가 제공할 내용 이해하기
+
+**리뷰 원칙:** 전체 마일스톤 범위가 아닌 현재 스프린트 결과물에 대해 평가합니다.
+
+### 2. 테스트 인프라 상태 실행 및 평가
+
+**핵심:** 테스트 인프라 상태는 스프린트/마일스톤 진행의 차단 기준입니다.
+
+- 전체 테스트 스위트 실행을 위해 test.md 명령 사용 (@.claude/commands/aiwf/aiwf_test.md)
+- 테스트 결과 분석: 통과/실패/건너뛴 개수 및 실패 카테고리
+- 테스트 상태 점수 계산 (0-10 스케일):
+  - 10: 100% 통과율, 인프라 문제 없음
+  - 8-9: >95% 통과율, 사소한 문제만 있음
+  - 6-7: 80-95% 통과율, 일부 비핵심 실패
+  - 4-5: 60-80% 통과율, 중대한 문제
+  - 0-3: <60% pass rate, critical infrastructure problems
+- CATEGORIZE failures:
+  - Infrastructure: Import errors, missing modules
+  - Configuration: Environment variables, database connections
+  - Logic: Assertion failures, actual bugs
+  - Flaky: Intermittent failures
+- DETERMINE blocking status:
+  - Score < 6: BLOCKS sprint progression
+  - Score < 8: BLOCKS milestone completion
+  - Score < 4: TRIGGERS emergency escalation
+- IDENTIFY root causes of any infrastructure failures
+- TRACK trend vs previous review (improvement/degradation)
+- ASSESS test strategy validity for scope of the project. Tests should be pragmatic and help assuring functionality but not get in the way of development progress too much.
+
+### 3. Assess project documentation alignment
+
+**USE PARALLEL AGENTS** to follow these steps:
+
+- READ all core documents in `.aiwf/01_PROJECT_DOCS/` especially ARCHITECTURE.md
+- READ current milestone requirements in `.aiwf/02_REQUIREMENTS/`
+- READ architecture decisions in `.aiwf/05_ARCHITECTURE_DECISIONS` as they might extend/contradict other documents
+- IDENTIFY any gaps between documentation and current implementation
+- CHECK if the project is still following the documented architecture vision
+- VERIFY that current code structure matches documented patterns
+
+**IMPORTANT:** Documentation is our source of truth. Any deviation needs justification.
+
+### 4. Review milestone and sprint progress
+
+**USE PARALLEL AGENTS** to follow these steps:
+
+- READ `.aiwf/00_PROJECT_MANIFEST.md` for current status
+- ANALYZE completed sprints in `.aiwf/03_SPRINTS/`
+- COMPARE actual progress against CURRENT SPRINT deliverables (not full milestone)
+- DISTINGUISH between sprint-level tasks vs milestone-level features
+- ASSESS if current sprint focus aligns with milestone goals
+
+### 5. Analyze codebase architecture and structure
+
+#
+
+**USE PARALLEL AGENTS** to follow these steps:
+
+- EXAMINE overall project structure and organization
+- ANALYZE import patterns and dependency relationships
+- REVIEW database models and API structure for consistency
+- CHECK for architectural patterns: are we following DDD, clean architecture, etc.?
+- IDENTIFY any architectural debt or inconsistencies
+
+**Focus areas:**
+
+- **Directory structure** — logical organization, separation of concerns
+- **Dependencies** — are we over-engineering? unnecessary libraries?
+- **Models/Schemas** — consistency, proper relationships, normalization
+- **APIs** — RESTful design, proper HTTP methods, consistent patterns
+- **Configuration** — environment management, secrets handling
+
+### 6. Audit file organization and workflow compliance
+
+**IMPORTANT:** Check for workflow discipline and architectural boundary violations.
+
+- **Root directory audit** — identify files that don't belong in project root
+- **Development scripts** — verify all dev scripts follow `run_dev.py` pattern
+- **Test file organization** — check tests are in `tests/` directory, not scattered
+- **Documentation placement** — verify docs are in proper locations
+- **Temporary/experimental files** — flag any `.py` files that look ad-hoc or experimental
+
+**File Organization Rules to Enforce:**
+
+- **Development scripts** — MUST go through `run_dev.py`, not standalone files
+- **Test files** — MUST be in `tests/` directory with proper naming (`test_*.py`)
+- **Documentation** — MUST be in `docs/` or `.aiwf/01_PROJECT_DOCS/`
+- **Configuration** — MUST follow established patterns (`.env.example`, `pyproject.toml`)
+- **Temporary files** — SHOULD NOT exist in committed code
+
+**Red Flags to Identify:**
+
+- Multiple scripts doing similar things (duplicate functionality)
+- Random `.py` files in root directory
+- Test files outside `tests/` directory
+- Development scripts bypassing `run_dev.py`
+- Unclear file purposes or experimental code
+
+**CRITICAL:** File proliferation indicates workflow breakdown. Flag for immediate cleanup task creation.
+
+### 7. Evaluate technical decisions and complexity
+
+- ASSESS complexity vs. business value ratio
+- REVIEW choice of frameworks, libraries, and tools
+- ANALYZE if current patterns will scale with project growth
+- IDENTIFY areas where we might be over-complicating simple problems
+- CHECK for premature optimization or under-optimization
+
+**IMPORTANT:** Think like an experienced developer. Are we solving the right problems the right way?
+
+### 8. Critique implementation quality (John Carmack perspective)
+
+Think as John Carmack would: focus on simplicity, performance, and maintainability, but keep the projects goal in mind. Especially long term vision as well. Don't over simplify.
+
+- **Simplicity:** Are we solving problems in the most straightforward way?
+- **Performance:** Are there obvious performance issues or bottlenecks?
+- **Maintainability:** Will a new developer understand this code in 6 months?
+- **Robustness:** How does the system handle edge cases and failures?
+- **Technical debt:** What shortcuts are we taking that will hurt us later?
+
+Be **brutally honest**. Carmack-level critique means no sugar-coating but still staying true to the project's reality.
+Be thorough and **go above and beyond** in your analysis - leave no stone unturned.
+
+### 9. Provide comprehensive assessment with recommendations
+
+**IMPORTANT:** Get current timestamp and create output file
+
+- Get current timestamp using system date command
+- Create filename: `YYYY-MM-DD-HH-MM-<judgment-slug>.md` in `.aiwf/10_STATE_OF_PROJECT/`
+- Judgment slug should be 2-3 words describing overall project health (e.g., "solid-progress", "needs-focus", "critical-issues", "doing-great", "on-track")
+
+**IMPORTANT:** Write full report to the timestamped file with this format:
+
+```markdown
+# Project Review - [YYYY-MM-DD HH:MM]
+
+## 🎭 Review Sentiment
+
+[3 emojis only - no explanations]
+
+## Executive Summary
+
+- **Result:** EXCELLENT | GOOD | NEEDS_WORK | CRITICAL_ISSUES
+- **Scope:** What areas were reviewed
+- **Overall Judgment:** [2-3 word assessment used in filename]
+
+## Test Infrastructure Assessment
+
+- **Test Suite Status**: [PASSING/FAILING/BLOCKED] (X/Y tests)
+- **Test Pass Rate**: X% (Y passed, Z failed)
+- **Test Health Score**: X/10
+- **Infrastructure Health**: [HEALTHY/DEGRADED/BROKEN]
+  - Import errors: [count]
+  - Configuration errors: [count]
+  - Fixture issues: [count]
+- **Test Categories**:
+  - Unit Tests: X/Y passing
+  - Integration Tests: X/Y passing
+  - API Tests: X/Y passing
+- **Critical Issues**:
+  - [List of blocking test infrastructure problems]
+  - [Module import mismatches]
+  - [Environment configuration failures]
+- **Sprint Coverage**: [% of sprint deliverables with passing tests]
+- **Blocking Status**: [CLEAR/BLOCKED - reason]
+- **Recommendations**:
+  - [Immediate fixes required]
+  - [Test infrastructure improvements needed]
+
+## Development Context
+
+- **Current Milestone:** [ID and status from manifest]
+- **Current Sprint:** [ID and focus]
+- **Expected Completeness:** [what SHOULD be done at this stage]
+
+## Progress Assessment
+
+- **Milestone Progress:** [percentage complete]
+- **Sprint Status:** [current sprint assessment]
+- **Deliverable Tracking:** [what's done vs planned]
+
+## Architecture & Technical Assessment
+
+- **Architecture Score:** 1-10 rating with explanation
+- **Technical Debt Level:** LOW | MEDIUM | HIGH with specific examples
+- **Code Quality:** [overall assessment with examples]
+
+## File Organization Audit
+
+- **Workflow Compliance:** GOOD | NEEDS_ATTENTION | CRITICAL_VIOLATIONS
+- **File Organization Issues:** [list any misplaced files, duplicate scripts, etc.]
+- **Cleanup Tasks Needed:** [specific file moves/deletions/consolidations required]
+
+## Critical Findings
+
+### Critical Issues (Severity 8-10)
+
+[Lists of must-fix problems headed with #### heading, one empty line and then list of details]
+
+### Improvement Opportunities (Severity 4-7)
+
+[List of recommended enhancements headed with #### heading, one empty line and then list of details]
+
+## John Carmack Critique 🔥
+
+[Top 3 brutally honest observations about technical decisions]
+
+## Recommendations
+
+Based on your findings recommend Action items - chose whatever fits your findings
+
+- **Important fixes:** What needs to be fixed immediately?
+- **Optional fixes/changes:** What would still be recommended though optional?
+- **Next Sprint Focus:** Can the user move to the next sprint?
+```
+
+**IMPORTANT:** Be specific with file paths and line numbers. This review should be actionable and permanently archived.

package/.claude/commands/aiwf/aiwf_switch_language.md

@@ -0,0 +1,160 @@
+# AIWF 언어 전환
+
+사용자가 AIWF 프레임워크의 언어 설정을 변경할 수 있도록 하는 명령어입니다.
+
+## 사용법
+
+이 명령어는 다음과 같은 경우에 사용됩니다:
+- 현재 언어 설정을 다른 언어로 변경하고 싶은 경우
+- 언어 설정 상태를 확인하고 싶은 경우
+- 언어 감지 문제를 해결하고 싶은 경우
+
+## 파라미터
+
+- `<언어코드>` (선택사항): 변경할 언어 (`ko` 또는 `en`)
+- 파라미터 없이 실행하면 현재 언어 상태를 표시
+
+## 실행 단계
+
+### 1. 현재 언어 상태 확인
+
+먼저 현재 언어 설정 상태를 확인합니다:
+
+```bash
+node -e "
+import('./language-utils.js').then(async ({ getLanguageStatus }) => {
+  const status = await getLanguageStatus();
+  console.log('=== AIWF 언어 설정 상태 ===');
+  console.log('감지된 언어:', status.detectedLanguage);
+  console.log('설정된 언어:', status.configuredLanguage || '없음');
+  console.log('현재 사용 언어:', status.effectiveLanguage);
+  console.log('자동 감지:', status.autoDetect ? '활성화' : '비활성화');
+  console.log('폴백 언어:', status.fallbackLanguage);
+  console.log('설정 파일 경로:', status.configPath);
+  if (status.error) console.log('오류:', status.error);
+});
+"
+```
+
+### 2. 인수 분석
+
+`<$ARGUMENTS>` 값을 확인하여 다음 중 하나를 수행합니다:
+
+- **인수 없음**: 현재 상태만 표시하고 종료
+- **유효한 언어코드 (`ko` 또는 `en`)**: 해당 언어로 전환
+- **무효한 인수**: 오류 메시지 표시 후 사용법 안내
+
+### 3. 언어 전환 실행
+
+유효한 언어코드가 제공된 경우 언어를 전환합니다:
+
+```bash
+node -e "
+import('./language-utils.js').then(async ({ switchLanguage }) => {
+  const targetLanguage = process.argv[1];
+  const result = await switchLanguage(targetLanguage);
+  
+  if (result.success) {
+    console.log('✅ 언어 전환 성공!');
+    console.log('이전 언어:', result.previousLanguage);
+    console.log('새 언어:', result.newLanguage);
+    console.log('메시지:', result.message);
+  } else {
+    console.error('❌ 언어 전환 실패:', result.error);
+    console.log('메시지:', result.message);
+  }
+});
+" -- $ARGUMENTS
+```
+
+### 4. 전환 후 검증
+
+언어 전환 후 설정이 제대로 적용되었는지 확인합니다:
+
+```bash
+node -e "
+import('./language-utils.js').then(async ({ getLanguageStatus }) => {
+  const status = await getLanguageStatus();
+  console.log('\n=== 전환 후 언어 설정 상태 ===');
+  console.log('현재 사용 언어:', status.effectiveLanguage);
+  console.log('설정 파일:', status.configuredLanguage ? '저장됨' : '없음');
+});
+"
+```
+
+### 5. 명령어 경로 테스트
+
+새 언어로 명령어 경로가 제대로 해결되는지 테스트합니다:
+
+```bash
+node -e "
+import('./language-utils.js').then(async ({ resolveCommandPath, detectLanguage }) => {
+  const currentLang = await detectLanguage();
+  const testCommands = ['aiwf_do_task', 'aiwf_commit', 'aiwf_initialize'];
+  
+  console.log('\n=== 명령어 경로 테스트 ===');
+  console.log('현재 언어:', currentLang);
+  
+  for (const cmd of testCommands) {
+    const result = await resolveCommandPath(cmd);
+    if (result.path) {
+      console.log('✅', cmd, '->', result.path, result.fallback ? '(폴백)' : '(직접)');
+    } else {
+      console.log('❌', cmd, '-> 찾을 수 없음:', result.error);
+    }
+  }
+});
+"
+```
+
+## 출력 형식
+
+### 성공적인 언어 전환
+```
+✅ 언어 전환 성공!
+이전 언어: en
+새 언어: ko
+메시지: 언어가 성공적으로 변경되었습니다
+
+=== 전환 후 언어 설정 상태 ===
+현재 사용 언어: ko
+설정 파일: 저장됨
+
+=== 명령어 경로 테스트 ===
+현재 언어: ko
+✅ aiwf_do_task -> claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_do_task.md (직접)
+✅ aiwf_commit -> claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_commit.md (직접)
+✅ aiwf_initialize -> claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_initialize.md (직접)
+```
+
+### 현재 상태 확인만 수행
+```
+=== AIWF 언어 설정 상태 ===
+감지된 언어: ko
+설정된 언어: ko
+현재 사용 언어: ko
+자동 감지: 활성화
+폴백 언어: en
+설정 파일 경로: .aiwf/config/language.json
+```
+
+### 오류 발생 시
+```
+❌ 언어 전환 실패: 지원되지 않는 언어입니다
+메시지: 언어 변경에 실패했습니다
+
+사용법: /project:aiwf:switch_language [ko|en]
+지원 언어: ko (한국어), en (English)
+```
+
+## 주의사항
+
+1. **설정 파일 권한**: `.aiwf/config/` 디렉토리에 쓰기 권한이 필요합니다
+2. **명령어 파일 존재**: 전환하려는 언어의 명령어 파일들이 존재해야 합니다
+3. **프로젝트 루트**: AIWF가 초기화된 프로젝트에서만 사용 가능합니다
+
+## 관련 명령어
+
+- `/project:aiwf:initialize` - AIWF 프로젝트 초기화
+- `/project:aiwf:update_docs` - 문서 업데이트 (언어별)
+- `/project:aiwf:help` - 도움말 (현재 언어로 표시)

package/.claude/commands/aiwf/aiwf_test.md

@@ -0,0 +1,124 @@
+# 테스트 실행 및 일반적인 문제 수정
+
+다음 지시사항을 위에서 아래로 순서대로 따르세요.
+
+## 정확히 다음 4개 항목으로 TODO 생성
+
+1. 테스트 스위트 실행
+2. 결과 분석 및 문제 식별
+3. 발견된 일반적인 문제 수정
+4. 테스트 요약 제공
+
+---
+
+## 1 · 테스트 스위트 실행
+
+### 먼저 프로젝트의 테스트 러너 감지:
+
+1. **Python 프로젝트:**
+
+   - `[tool.poetry]`가 있는 `pyproject.toml`이 존재하면: `poetry run pytest` 시도
+   - `setup.py` 또는 `requirements.txt`가 있으면: `pytest` 또는 `python -m pytest` 시도
+   - 커스텀 테스트 스크립트 존재시 (예: `run_tests.py`, `run_dev.py`): 해당 스크립트 사용
+   - 일반적인 플래그 추가: pytest용 `--tb=short`
+
+2. **JavaScript/TypeScript 프로젝트:**
+
+   - `package.json`이 존재하면: "scripts" 섹션에서 "test" 명령어 확인
+   - 일반적인 명령어: `npm test`, `npm run test`, `yarn test`, `pnpm test`
+   - 프레임워크별: `jest`, `vitest`, `mocha`
+
+3. **기타 언어:**
+   - Rust: `cargo test`
+   - Go: `go test ./...`
+   - Java: `mvn test` 또는 `gradle test`
+   - Ruby: `bundle exec rspec` 또는 `rake test`
+   - PHP: `composer test` 또는 `phpunit`
+
+### 감지된 테스트 명령어 실행:
+
+- 적절한 테스트 명령어 실행
+- 오류를 포함한 전체 출력 캡처
+- 실행 시간 및 테스트 개수 기록
+
+**테스트 러너를 찾을 수 없는 경우:** 사용자에게 보고하고 올바른 테스트 명령어 요청
+
+## 2 · 결과 분석 및 문제 식별
+
+다음 순서로 일반적인 문제 확인:
+
+### 언어별 문제:
+
+**Python:**
+
+- **__init__.py** 파일 누락 (import 오류, 테스트 미발견)
+- Import 경로 문제
+- Fixture 문제 (pytest)
+- 가상 환경 문제
+
+**JavaScript/TypeScript:**
+
+- 모듈 해결 오류
+- node_modules의 의존성 누락
+- Jest/Vitest 구성 문제
+- TypeScript 컴파일 오류
+
+**모든 언어 공통:**
+
+- 환경 변수 문제 (구성 누락)
+- 데이터베이스/외부 서비스 연결 오류
+- 파일 경로 문제 (절대 경로 vs 상대 경로)
+- 권한 문제
+
+## 3 · 발견된 일반적인 문제 수정
+
+**오직** 다음 특정 문제들만 자동으로 수정:**
+
+### Python 전용 수정:
+
+- 필요한 곳에 빈 `__init__.py` 파일 생성
+- 간단한 import 경로 문제 수정
+- 필요한 경우 Python 경로에 누락된 테스트 디렉토리 추가
+
+### JavaScript/TypeScript 수정:
+
+- node_modules가 누락된 경우 `npm install` 실행
+- jest.config.js의 간단한 모듈 해결 문제 수정
+- 누락된 테스트 설정 파일 생성
+
+### 일반 수정:
+
+- 누락된 테스트 디렉토리 생성
+- 가능한 경우 파일 권한 수정
+- 누락된 환경 변수 식별 및 사용자에게 알림
+
+**수정하지 않을 것:**
+
+- 실제 테스트 로직 실패
+- 비즈니스 로직 버그
+- 복잡한 구성 문제
+- 데이터베이스 스키마 문제
+- 외부 서비스 의존성
+
+## 4 · 테스트 요약 제공
+
+간단한 요약 생성:
+
+```
+테스트 결과:
+- 총 개수: X개 테스트
+- 통과: Y개 (Z%)
+- 실패: A개
+- 건너뜀: B개
+- 시간: C초
+
+수정된 문제:
+- [적용된 수정사항 목록]
+
+발견된 문제 (수동 수정 필요):
+- [주의가 필요한 문제 목록]
+
+상태: PASSING | FAILING | BLOCKED
+```
+
+**중요:** 간결하게 유지하세요. 이 명령어는 빠르고 테스트 실행에 집중해야 하며, 상세한 분석에 집중하지 않아야 합니다.