aiwf 0.3.15 → 0.3.16

package/docs/TROUBLESHOOTING.ko.md

@@ -0,0 +1,366 @@
+# AIWF 문제 해결 가이드
+
+[한국어](TROUBLESHOOTING.ko.md) | [English](TROUBLESHOOTING.md)
+
+> AIWF 사용 중 발생할 수 있는 일반적인 문제와 해결 방법
+
+## 📋 목차
+
+1. [설치 문제](#설치-문제)
+2. [명령어 실행 오류](#명령어-실행-오류)
+3. [상태 관리 문제](#상태-관리-문제)
+4. [Git 통합 문제](#git-통합-문제)
+5. [YOLO 모드 문제](#yolo-모드-문제)
+6. [성능 문제](#성능-문제)
+7. [호환성 문제](#호환성-문제)
+8. [FAQ](#faq)
+
+## 설치 문제
+
+### 전역 설치 실패
+
+**문제**: `npm install -g aiwf` 실행 시 권한 오류
+
+**해결책**:
+```bash
+# macOS/Linux
+sudo npm install -g aiwf
+
+# Windows (관리자 권한으로 실행)
+npm install -g aiwf
+
+# 또는 npm 권한 설정 변경
+npm config set prefix ~/.npm-global
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### 프로젝트 설치 실패
+
+**문제**: `aiwf install` 실행 시 오류
+
+**원인 및 해결책**:
+1. **Node.js 버전**: Node.js 16.0.0 이상 필요
+   ```bash
+   node --version  # 버전 확인
+   ```
+
+2. **기존 설치 충돌**: 
+   ```bash
+   # 기존 설치 제거
+   rm -rf .aiwf
+   # 재설치
+   aiwf install --force
+   ```
+
+3. **권한 문제**:
+   ```bash
+   # 현재 디렉토리 권한 확인
+   ls -la
+   # 필요시 권한 변경
+   chmod -R 755 .
+   ```
+
+## 명령어 실행 오류
+
+### "Command not found" 오류
+
+**문제**: `aiwf: command not found`
+
+**해결책**:
+```bash
+# PATH 확인
+echo $PATH
+
+# npm 전역 경로 확인
+npm config get prefix
+
+# PATH에 추가 (bash)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# PATH에 추가 (zsh)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### ES 모듈 오류
+
+**문제**: `Cannot use import statement outside a module`
+
+**해결책**:
+```bash
+# Node.js 버전 확인 (16+ 필요)
+node --version
+
+# package.json에 type 추가
+{
+  "type": "module"
+}
+```
+
+### 리소스를 찾을 수 없음
+
+**문제**: `Resource not found: commands/...`
+
+**해결책**:
+```bash
+# AIWF 재설치
+aiwf install --force
+
+# 캐시 정리
+npm cache clean --force
+npm install -g aiwf@latest
+```
+
+## 상태 관리 문제
+
+### 상태 동기화 실패
+
+**문제**: `aiwf state update` 실행 시 오류
+
+**해결책**:
+1. **상태 파일 확인**:
+   ```bash
+   ls -la .aiwf/state/
+   ```
+
+2. **상태 초기화**:
+   ```bash
+   aiwf state init --force
+   ```
+
+3. **권한 문제 해결**:
+   ```bash
+   chmod -R 644 .aiwf/state/*
+   ```
+
+### 순환 의존성 감지
+
+**문제**: "Circular dependency detected"
+
+**해결책**:
+1. 의존성 확인:
+   ```bash
+   aiwf state validate
+   ```
+
+2. 의존성 제거:
+   - 태스크 파일에서 순환 참조 수정
+   - 의존성 재구성
+
+### 상태 파일 손상
+
+**문제**: "Invalid state file format"
+
+**해결책**:
+```bash
+# 백업에서 복원
+cp .aiwf/state/task-state-index.json.backup .aiwf/state/task-state-index.json
+
+# 또는 상태 재구성
+aiwf state rebuild
+```
+
+## Git 통합 문제
+
+### Git Hook 오류
+
+**문제**: 커밋 시 hook 오류 발생
+
+**해결책**:
+1. **Hook 확인**:
+   ```bash
+   ls -la .git/hooks/
+   ```
+
+2. **Hook 재설치**:
+   ```bash
+   ./hooks/install-hooks.sh
+   ```
+
+3. **Hook 비활성화** (임시):
+   ```bash
+   git commit --no-verify
+   ```
+
+### Feature ID 추출 실패
+
+**문제**: 커밋 메시지에서 Feature ID가 인식되지 않음
+
+**해결책**:
+- 올바른 형식 사용: `FL001`, `FL002` 등
+- 커밋 메시지 예:
+  ```
+  feat(FL001): 사용자 인증 구현
+  ```
+
+## YOLO 모드 문제
+
+### YOLO 실행 중단
+
+**문제**: YOLO 모드가 예기치 않게 중단됨
+
+**해결책**:
+1. **체크포인트에서 재개**:
+   ```bash
+   # 마지막 체크포인트 확인
+   aiwf checkpoint list
+   
+   # 재개
+   aiwf yolo --resume
+   ```
+
+2. **안전 모드 사용**:
+   ```bash
+   aiwf yolo --safe
+   ```
+
+### 메모리 부족
+
+**문제**: "JavaScript heap out of memory"
+
+**해결책**:
+```bash
+# Node.js 메모리 증가
+export NODE_OPTIONS="--max-old-space-size=4096"
+
+# 또는 명령어 실행 시
+NODE_OPTIONS="--max-old-space-size=4096" aiwf yolo
+```
+
+### 무한 루프 감지
+
+**문제**: YOLO가 같은 태스크를 반복 실행
+
+**해결책**:
+1. 태스크 상태 확인
+2. 의존성 검증
+3. 필요시 수동으로 태스크 완료:
+   ```bash
+   aiwf state complete TASK_ID
+   ```
+
+## 성능 문제
+
+### 느린 명령어 실행
+
+**원인 및 해결책**:
+1. **큰 프로젝트**: 
+   ```bash
+   # 인덱싱 최적화
+   aiwf optimize index
+   ```
+
+2. **많은 파일**:
+   ```bash
+   # .aiwfignore 파일 생성
+   echo "node_modules/" > .aiwfignore
+   echo "dist/" >> .aiwfignore
+   ```
+
+3. **캐시 문제**:
+   ```bash
+   # 캐시 정리
+   rm -rf .aiwf/cache/*
+   ```
+
+### 높은 토큰 사용량
+
+**해결책**:
+1. **컨텍스트 압축 사용**:
+   ```bash
+   aiwf compress aggressive
+   ```
+
+2. **불필요한 파일 제외**:
+   ```bash
+   # .aiwfignore에 추가
+   *.log
+   *.tmp
+   coverage/
+   ```
+
+## 호환성 문제
+
+### Windows 경로 문제
+
+**문제**: Windows에서 경로 오류
+
+**해결책**:
+```bash
+# Git Bash 또는 WSL 사용 권장
+# 또는 경로에 슬래시 사용
+aiwf create-task "태스크" --path ./tasks/
+```
+
+### 인코딩 문제
+
+**문제**: 한글 깨짐 현상
+
+**해결책**:
+1. **터미널 인코딩 설정**:
+   ```bash
+   export LANG=ko_KR.UTF-8
+   export LC_ALL=ko_KR.UTF-8
+   ```
+
+2. **파일 인코딩 확인**:
+   - 모든 파일을 UTF-8로 저장
+
+## FAQ
+
+### Q: AIWF 버전을 확인하려면?
+```bash
+aiwf --version
+```
+
+### Q: 업데이트하려면?
+```bash
+npm update -g aiwf
+```
+
+### Q: 설정을 초기화하려면?
+```bash
+aiwf reset --all
+```
+
+### Q: 로그를 확인하려면?
+```bash
+# 상세 로그 활성화
+export AIWF_DEBUG=true
+aiwf [명령어]
+
+# 로그 파일 확인
+cat .aiwf/logs/aiwf.log
+```
+
+### Q: 백업을 생성하려면?
+```bash
+# 전체 백업
+tar -czf aiwf-backup.tar.gz .aiwf/
+
+# 상태만 백업
+cp -r .aiwf/state/ .aiwf/state.backup/
+```
+
+## 추가 도움말
+
+### 디버그 모드
+```bash
+# 디버그 모드 활성화
+AIWF_DEBUG=true aiwf [명령어]
+```
+
+### 지원 받기
+1. [공식 문서](https://github.com/moonklabs/aiwf/docs) 확인
+2. [GitHub 이슈](https://github.com/moonklabs/aiwf/issues) 검색
+3. 새 이슈 생성 시 포함할 정보:
+   - AIWF 버전 (`aiwf --version`)
+   - Node.js 버전 (`node --version`)
+   - 운영체제
+   - 오류 메시지 전문
+   - 재현 단계
+
+---
+
+💡 **팁**: 대부분의 문제는 `aiwf install --force`로 해결됩니다!

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "aiwf",
-    "version": "0.3.15",
+    "version": "0.3.16",
     "description": "AI Workflow Framework for Claude Code with multi-language support (Korean/English)",
     "main": "index.js",
     "type": "module",
@@ -59,7 +59,6 @@
         "hooks/",
         "scripts/",
         "ai-tools/",
-        "feature-ledger/",
         "index.js",
         "README.md",
         "README.ko.md",
@@ -83,5 +82,54 @@
     },
     "devDependencies": {
         "jest": "^30.0.3"
+    },
+    "aiwf": {
+        "moduleCategories": {
+            "core": [
+                "utils/paths.js",
+                "utils/messages.js",
+                "utils/language-utils.js"
+            ],
+            "yolo": [
+                "utils/engineering-guard.js",
+                "utils/checkpoint-manager.js"
+            ],
+            "persona": [
+                "lib/ai-persona-manager.js",
+                "lib/context-engine.js",
+                "lib/metrics-collector.js",
+                "lib/task-analyzer.js",
+                "lib/token-optimizer.js"
+            ],
+            "installer": [
+                "lib/installer.js",
+                "lib/backup-manager.js",
+                "lib/file-downloader.js",
+                "lib/rollback-manager.js",
+                "lib/validator.js"
+            ],
+            "cache": [
+                "lib/template-cache-system.js",
+                "lib/offline-detector.js",
+                "lib/template-downloader.js",
+                "lib/template-version-manager.js"
+            ],
+            "github": [
+                "lib/github-integration.js",
+                "lib/state/state-index.js",
+                "lib/state/priority-calculator.js",
+                "lib/state/task-scanner.js"
+            ],
+            "common": [
+                "lib/resource-loader.js"
+            ]
+        },
+        "criticalModules": [
+            "utils/engineering-guard.js",
+            "utils/checkpoint-manager.js"
+        ],
+        "dynamicImports": [
+            "utils/engineering-guard.js"
+        ]
     }
 }

package/src/DEPENDENCY_MAP.md

@@ -0,0 +1,90 @@
+# AIWF 모듈 의존성 매트릭스
+
+## 📊 CLI 명령어별 의존성
+
+| 명령어 | 직접 의존성 | 간접 의존성 | 특수 사용 |
+|--------|-------------|-------------|-----------|
+| `aiwf install` | installer.js | backup-manager.js, file-downloader.js, rollback-manager.js, validator.js | - |
+| `aiwf persona` | persona.js, ai-persona-manager.js | context-engine.js, metrics-collector.js, task-analyzer.js, token-optimizer.js | - |
+| `aiwf compress` | compress.js, resource-loader.js | - | - |
+| `aiwf token` | token.js, resource-loader.js | - | - |
+| `aiwf evaluate` | evaluate.js, resource-loader.js | - | - |
+| `aiwf state` | state.js | - | - |
+| `aiwf create-project` | create-project.js, resource-loader.js | - | - |
+| `aiwf ai-tool` | ai-tool.js | - | - |
+| `aiwf sprint-task` | sprint-task.js | - | - |
+| `aiwf sprint` | sprint-independent.js | - | - |
+| `aiwf yolo-config` | yolo-config.js | - | - |
+| `aiwf checkpoint` | checkpoint-manager.js | - | ⚠️ YOLO 전용 |
+| `aiwf-checkpoint` | checkpoint-manager.js | - | ⚠️ YOLO 전용 |
+| `aiwf cache` | cache-cli.js | template-cache-system.js, offline-detector.js, template-downloader.js, template-version-manager.js | - |
+| `aiwf github` | github-integration.js | state/state-index.js | - |
+| `YOLO 모드` | engineering-guard.js | - | ⚠️ 동적 import |
+
+## 🏗️ 모듈 분류
+
+### 🔧 핵심 유틸리티 (삭제 금지)
+- **paths.js** - 경로 관리 (8곳에서 사용)
+- **messages.js** - 다국어 메시지 시스템 (5곳에서 사용)
+- **language-utils.js** - 언어 설정 관리 (3곳에서 사용)
+
+### 🚀 YOLO 시스템 (삭제 금지)
+- **engineering-guard.js** - 오버엔지니어링 방지 ⚠️ 동적 로드
+- **checkpoint-manager.js** - 체크포인트 관리
+
+### 🎯 명령어별 전용 모듈
+
+#### AI Persona 시스템
+- **ai-persona-manager.js** → persona 명령어
+- **context-engine.js** → ai-persona-manager가 사용
+- **metrics-collector.js** → ai-persona-manager가 사용  
+- **task-analyzer.js** → ai-persona-manager가 사용
+- **token-optimizer.js** → context-engine이 사용
+
+#### 설치/백업 시스템
+- **installer.js** → install 명령어
+- **backup-manager.js** → installer가 사용
+- **file-downloader.js** → installer가 사용
+- **rollback-manager.js** → installer가 사용
+- **validator.js** → installer가 사용
+
+#### 캐시 시스템
+- **template-cache-system.js** → cache 명령어
+- **offline-detector.js** → cache 명령어
+- **template-downloader.js** → cache 명령어
+- **template-version-manager.js** → cache 명령어
+
+#### GitHub 통합
+- **github-integration.js** → github 명령어
+- **state/state-index.js** → github-integration이 사용
+
+#### 공통 리소스
+- **resource-loader.js** → 5개 명령어에서 사용
+
+## ⚠️ 삭제 위험 모듈
+
+### 동적 로드 모듈 (CLI에서 직접 참조되지 않음)
+- **engineering-guard.js** - YOLO 템플릿에서 `import()`로 로드
+- **state/priority-calculator.js** - github-integration에서 사용
+- **state/task-scanner.js** - github-integration에서 사용
+
+### 간접 의존성 모듈
+- AI Persona 시스템의 하위 모듈들
+- 설치 시스템의 백업/복구 모듈들
+
+## 🚨 삭제하기 전 확인사항
+
+1. **이 파일에서 모듈 위치 확인**
+2. **`@warning 삭제 금지` 주석 확인**
+3. **YOLO 전용 모듈인지 확인**
+4. **동적 import 사용 여부 확인**
+5. **간접 의존성 체인 확인**
+
+## 📁 미사용 모듈 (삭제 가능)
+
+현재 완전히 미사용되는 모듈은 없습니다. 모든 모듈이 직간접적으로 CLI 시스템에서 사용됩니다.
+
+---
+
+**마지막 업데이트**: 2024-01-27  
+**검증 방법**: `grep -r "모듈명" src/` 으로 사용처 확인

package/src/lib/installer.js

@@ -36,6 +36,7 @@ import {
   TOOL_DIRS,
   TEMP_DIRS,
   AIWF_DIRS,
+  BASE_DIRS,
   getAllAiwfDirectories,
   getAllClaudeMdFiles
 } from '../utils/paths.js';

package/src/lib/resources/templates/api-server/template/src/controllers/aiwfController.ts

@@ -3,20 +3,6 @@ import fs from 'fs/promises';
 import path from 'path';
 
 export const aiwfController = {
-  getFeatures: async (req: Request, res: Response, next: NextFunction) => {
-    try {
-      const ledgerPath = path.join(process.cwd(), '.aiwf', 'feature-ledger.json');
-      const ledgerData = await fs.readFile(ledgerPath, 'utf-8');
-      const ledger = JSON.parse(ledgerData);
-
-      res.json({
-        success: true,
-        data: ledger,
-      });
-    } catch (error) {
-      next(error);
-    }
-  },
 
   getTokenUsage: async (req: Request, res: Response, next: NextFunction) => {
     try {

package/src/lib/resources/templates/api-server/template/src/routes/aiwf.ts

@@ -3,17 +3,6 @@ import { aiwfController } from '@controllers/aiwfController';
 
 const router = Router();
 
-/**
- * @swagger
- * /api/aiwf/features:
- *   get:
- *     summary: Feature Ledger 조회
- *     tags: [AIWF]
- *     responses:
- *       200:
- *         description: Feature 목록
- */
-router.get('/features', aiwfController.getFeatures);
 
 /**
  * @swagger

package/src/lib/resources/templates/web-app/template/src/pages/AiwfDashboard.tsx

@@ -1,19 +1,17 @@
 import { useState, useEffect } from 'react'
 import { useAiwfStore } from '@/stores/aiwfStore'
-import FeatureLedger from '@/components/aiwf/FeatureLedger'
 import TokenUsage from '@/components/aiwf/TokenUsage'
 import ContextStatus from '@/components/aiwf/ContextStatus'
 
 export default function AiwfDashboard() {
-  const { features, tokenUsage, contextStatus, loadDashboardData } = useAiwfStore()
-  const [activeTab, setActiveTab] = useState('features')
+  const { tokenUsage, contextStatus, loadDashboardData } = useAiwfStore()
+  const [activeTab, setActiveTab] = useState('tokens')
 
   useEffect(() => {
     loadDashboardData()
   }, [loadDashboardData])
 
   const tabs = [
-    { id: 'features', name: 'Feature Ledger', icon: '📋' },
     { id: 'tokens', name: '토큰 사용량', icon: '🪙' },
     { id: 'context', name: 'Context 상태', icon: '📊' },
   ]
@@ -51,7 +49,6 @@ export default function AiwfDashboard() {
       </div>
 
       <div className="mt-8">
-        {activeTab === 'features' && <FeatureLedger features={features} />}
         {activeTab === 'tokens' && <TokenUsage usage={tokenUsage} />}
         {activeTab === 'context' && <ContextStatus status={contextStatus} />}
       </div>

package/src/lib/resources/utils/token-reporter.js

@@ -37,9 +37,8 @@ export class TokenReporter {
         '.aiwf/02_REQUIREMENTS',
         '.aiwf/03_SPRINTS',
         '.aiwf/04_GENERAL_TASKS',
-        '.aiwf/05_COMPLETED_TASKS',
-        '.aiwf/06_FEATURE_LEDGERS',
-        '.aiwf/07_AI_PERSONAS'
+        '.aiwf/05_ARCHITECTURAL_DECISIONS',
+        '.aiwf/10_STATE_OF_PROJECT'
       ];
 
       // 각 디렉토리별 토큰 수 분석

package/src/utils/checkpoint-manager.js

@@ -1,6 +1,16 @@
 /**
- * YOLO 모드 체크포인트 매니저
+ * Checkpoint Manager - YOLO 모드 체크포인트 매니저
+ * 
+ * @usage YOLO 모드 및 CLI 명령어에서 사용
+ * @used_by src/cli/index.js, src/cli/checkpoint-cli.js
+ * @commands aiwf checkpoint, aiwf-checkpoint
+ * @warning 삭제 금지 - YOLO 시스템 핵심 구성 요소
+ * 
  * 진행 상황을 저장하고 복구할 수 있는 시스템
+ * - 세션 상태 관리
+ * - 체크포인트 생성/복구
+ * - 진행률 추적
+ * - 복구 가능한 상태 유지
  */
 
 import fs from 'fs/promises';

package/src/utils/engineering-guard.js

@@ -1,6 +1,16 @@
 /**
- * 오버엔지니어링 방지 가드
+ * Engineering Guard - 오버엔지니어링 방지 가드
+ * 
+ * @usage YOLO 모드 전용 - 동적 import로 사용됨
+ * @used_by /claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_yolo.md
+ * @phase 프로젝트 복잡도 모니터링 (5단계)
+ * @warning 삭제 금지 - YOLO 시스템 핵심 구성 요소
+ * 
  * YOLO 모드에서 과도한 복잡성을 방지하는 유틸리티
+ * - 초기 복잡도 측정
+ * - 사전 체크 및 실시간 모니터링  
+ * - 태스크 완료 후 검증
+ * - 최종 보고서 생성
  */
 
 import fs from 'fs/promises';

package/templates/api-server/template/src/controllers/aiwfController.ts

@@ -3,20 +3,6 @@ import fs from 'fs/promises';
 import path from 'path';
 
 export const aiwfController = {
-  getFeatures: async (req: Request, res: Response, next: NextFunction) => {
-    try {
-      const ledgerPath = path.join(process.cwd(), '.aiwf', 'feature-ledger.json');
-      const ledgerData = await fs.readFile(ledgerPath, 'utf-8');
-      const ledger = JSON.parse(ledgerData);
-
-      res.json({
-        success: true,
-        data: ledger,
-      });
-    } catch (error) {
-      next(error);
-    }
-  },
 
   getTokenUsage: async (req: Request, res: Response, next: NextFunction) => {
     try {

package/templates/api-server/template/src/routes/aiwf.ts

@@ -3,17 +3,6 @@ import { aiwfController } from '@controllers/aiwfController';
 
 const router = Router();
 
-/**
- * @swagger
- * /api/aiwf/features:
- *   get:
- *     summary: Feature Ledger 조회
- *     tags: [AIWF]
- *     responses:
- *       200:
- *         description: Feature 목록
- */
-router.get('/features', aiwfController.getFeatures);
 
 /**
  * @swagger