aiwf 0.3.8 → 0.3.12

package/docs/DEVELOPMENT_GUIDE.ko.md

@@ -0,0 +1,440 @@
+# aiwf 개발 가이드
+
+aiwf (AI Workflow Framework)는 Claude Code와 통합된 AIWF 프로젝트 관리 프레임워크를 설치하는 NPM CLI 패키지입니다. 이 문서는 aiwf 프로젝트에 기여하고자 하는 개발자들을 위한 종합적인 개발 환경 설정 및 워크플로우 가이드입니다.
+
+## 목차
+
+1. [시작하기](#1-시작하기)
+2. [개발 도구 설정](#2-개발-도구-설정)
+3. [개발 워크플로우](#3-개발-워크플로우)
+4. [코딩 표준](#4-코딩-표준)
+5. [테스트 작성](#5-테스트-작성)
+6. [CI/CD 파이프라인](#6-cicd-파이프라인)
+7. [문제 해결](#7-문제-해결)
+8. [기여하기](#8-기여하기)
+
+---
+
+## 1. 시작하기
+
+### 1.1 개발 환경 요구사항
+
+aiwf 프로젝트 개발을 위해 다음 도구들이 필요합니다:
+
+- **Node.js**: 14.0.0 이상 (ES 모듈 지원)
+- **npm**: Node.js와 함께 설치됨
+- **Git**: 버전 관리
+- **추천 IDE**: VS Code, Cursor, 또는 Windsurf
+
+### 1.2 프로젝트 클론 및 설정
+
+```bash
+# 1. 리포지토리 클론
+git clone https://github.com/moonklabs/aiwf.git
+cd aiwf
+
+# 2. 의존성 설치
+npm install
+
+# 3. 로컬 테스트 실행
+node index.js --force
+
+# 4. 개발 환경 검증
+npm test  # Jest 테스트 실행 (설정 후)
+npm run lint  # ESLint 검사 (설정 후)
+```
+
+### 1.3 프로젝트 구조 이해
+
+```
+aiwf/
+├── src/                    # 소스 코드 디렉토리
+│   ├── cli/               # CLI 진입점 및 도구
+│   ├── commands/          # AIWF 명령어 구현
+│   ├── lib/               # 핵심 라이브러리 모듈
+│   └── utils/             # 유틸리티 함수
+├── ai-tools/              # AI 도구별 설정
+├── config/                # 설정 파일
+├── docs/                  # 프로젝트 문서
+├── feature-ledger/        # 기능 추적 시스템
+├── hooks/                 # Git hooks
+├── personas/              # AI 페르소나 정의
+├── templates/             # 프로젝트 템플릿
+├── tests/                 # 테스트 스위트
+├── package.json           # NPM 설정
+└── CLAUDE.md             # Claude Code 가이드
+```
+
+---
+
+## 2. 개발 도구 설정
+
+### 2.1 VS Code 설정
+
+`.vscode/settings.json` 생성:
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  },
+  "files.exclude": {
+    "node_modules": true,
+    ".aiwf/backup_*": true
+  },
+  "eslint.validate": ["javascript"],
+  "javascript.preferences.importModuleSpecifier": "relative"
+}
+```
+
+### 2.2 ESLint 설정
+
+`.eslintrc.json` 생성:
+
+```json
+{
+  "env": {
+    "es2021": true,
+    "node": true
+  },
+  "extends": ["eslint:recommended"],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "rules": {
+    "indent": ["error", 2],
+    "quotes": ["error", "single"],
+    "semi": ["error", "always"]
+  }
+}
+```
+
+### 2.3 Git Hooks 설정
+
+```bash
+# Git hooks 설치
+./hooks/install-hooks.sh
+
+# 또는 수동 설치
+cp hooks/pre-commit .git/hooks/
+cp hooks/post-commit .git/hooks/
+chmod +x .git/hooks/*
+```
+
+---
+
+## 3. 개발 워크플로우
+
+### 3.1 브랜치 전략
+
+```bash
+# 기능 브랜치 생성
+git checkout -b feature/your-feature-name
+
+# 버그 수정 브랜치
+git checkout -b fix/bug-description
+
+# 문서 업데이트 브랜치
+git checkout -b docs/update-description
+```
+
+### 3.2 개발 프로세스
+
+1. **기능 계획**
+   ```bash
+   # Feature Ledger에 새 기능 추가
+   node commands/feature-create.js "새 기능 설명"
+   ```
+
+2. **구현**
+   ```bash
+   # 코드 작성
+   # 테스트 작성
+   # 문서 업데이트
+   ```
+
+3. **테스트**
+   ```bash
+   npm test
+   npm run test:watch  # 감시 모드
+   ```
+
+4. **커밋**
+   ```bash
+   # Feature ID와 함께 커밋
+   git commit -m "feat(FL001): 새 기능 구현"
+   ```
+
+### 3.3 디버깅
+
+```bash
+# Node.js 디버거로 실행
+node --inspect index.js
+
+# VS Code 디버그 설정 (.vscode/launch.json)
+{
+  "version": "0.2.0",
+  "configurations": [{
+    "type": "node",
+    "request": "launch",
+    "name": "Debug AIWF",
+    "program": "${workspaceFolder}/index.js",
+    "args": ["--force"],
+    "console": "integratedTerminal"
+  }]
+}
+```
+
+---
+
+## 4. 코딩 표준
+
+### 4.1 명명 규칙
+
+```javascript
+// 파일명: kebab-case
+// create-project.js, resource-loader.js
+
+// 클래스명: PascalCase
+class ResourceLoader {}
+class EngineeringGuard {}
+
+// 함수/변수명: camelCase
+function createProject() {}
+const projectRoot = '/path/to/project';
+
+// 상수: UPPER_SNAKE_CASE
+const MAX_RETRIES = 3;
+const DEFAULT_TIMEOUT = 5000;
+```
+
+### 4.2 ES 모듈 사용
+
+```javascript
+// 올바른 예시
+import fs from 'fs/promises';
+import path from 'path';
+import { createRequire } from 'module';
+
+// 잘못된 예시 (CommonJS)
+const fs = require('fs');  // 사용하지 않음
+```
+
+### 4.3 비동기 프로그래밍
+
+```javascript
+// async/await 선호
+async function loadResource(path) {
+  try {
+    const data = await fs.readFile(path, 'utf-8');
+    return JSON.parse(data);
+  } catch (error) {
+    console.error(`Failed to load resource: ${path}`, error);
+    throw error;
+  }
+}
+
+// Promise 체이닝보다 async/await 사용
+```
+
+### 4.4 오류 처리
+
+```javascript
+// 구체적인 오류 메시지
+throw new Error(`File not found: ${filePath}`);
+
+// 오류 타입 구분
+class ValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+```
+
+---
+
+## 5. 테스트 작성
+
+### 5.1 단위 테스트
+
+```javascript
+// tests/unit/resource-loader.test.js
+import { describe, it, expect, jest } from '@jest/globals';
+import ResourceLoader from '../../src/lib/resource-loader.js';
+
+describe('ResourceLoader', () => {
+  it('should load bundled resources', async () => {
+    const loader = new ResourceLoader();
+    const resource = await loader.loadResource('personas/architect.json');
+    expect(resource).toBeDefined();
+    expect(resource.name).toBe('architect');
+  });
+});
+```
+
+### 5.2 통합 테스트
+
+```javascript
+// tests/integration/cli.test.js
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+describe('CLI Integration', () => {
+  it('should install AIWF successfully', async () => {
+    const { stdout } = await execAsync('node index.js --force');
+    expect(stdout).toContain('AIWF installed successfully');
+  });
+});
+```
+
+### 5.3 테스트 커버리지
+
+```bash
+# 커버리지 보고서 생성
+npm run test:coverage
+
+# 커버리지 임계값 설정 (package.json)
+"jest": {
+  "coverageThreshold": {
+    "global": {
+      "branches": 80,
+      "functions": 80,
+      "lines": 80,
+      "statements": 80
+    }
+  }
+}
+```
+
+---
+
+## 6. CI/CD 파이프라인
+
+### 6.1 GitHub Actions 워크플로우
+
+`.github/workflows/ci.yml`:
+
+```yaml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [14.x, 16.x, 18.x]
+    
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+    
+    - run: npm ci
+    - run: npm test
+    - run: npm run lint
+```
+
+### 6.2 릴리스 프로세스
+
+```bash
+# 버전 업데이트
+npm version patch  # 0.3.11 -> 0.3.12
+npm version minor  # 0.3.12 -> 0.4.0
+npm version major  # 0.4.0 -> 1.0.0
+
+# 릴리스 태그 생성
+git tag -a v0.3.12 -m "Release v0.3.12"
+git push origin v0.3.12
+
+# NPM 배포
+npm publish
+```
+
+---
+
+## 7. 문제 해결
+
+### 7.1 일반적인 문제
+
+**ES 모듈 오류**
+```bash
+# package.json에 "type": "module" 확인
+# import 문에서 파일 확장자 포함
+```
+
+**권한 오류**
+```bash
+# 실행 권한 부여
+chmod +x index.js
+chmod +x src/cli/*.js
+```
+
+**캐시 문제**
+```bash
+# npm 캐시 정리
+npm cache clean --force
+rm -rf node_modules
+npm install
+```
+
+### 7.2 디버깅 팁
+
+```javascript
+// 상세 로깅 활성화
+const DEBUG = process.env.DEBUG === 'true';
+if (DEBUG) console.log('Debug info:', data);
+
+// 실행 시간 측정
+console.time('operation');
+await someOperation();
+console.timeEnd('operation');
+```
+
+---
+
+## 8. 기여하기
+
+### 8.1 기여 프로세스
+
+1. **이슈 생성**: 버그 리포트나 기능 제안
+2. **포크 및 브랜치**: 자신의 저장소에서 작업
+3. **개발**: 코딩 표준 준수
+4. **테스트**: 모든 테스트 통과 확인
+5. **PR 생성**: 상세한 설명과 함께
+
+### 8.2 PR 체크리스트
+
+- [ ] 모든 테스트 통과
+- [ ] 새 기능에 대한 테스트 추가
+- [ ] 문서 업데이트
+- [ ] CHANGELOG.md 업데이트
+- [ ] 린트 오류 없음
+- [ ] 커밋 메시지 규칙 준수
+
+### 8.3 코드 리뷰 가이드라인
+
+- 건설적인 피드백 제공
+- 코드 스타일보다 로직에 집중
+- 개선 제안 시 예시 포함
+- 긍정적인 부분도 언급
+
+---
+
+## 추가 리소스
+
+- [AIWF 공식 문서](https://github.com/moonklabs/aiwf/docs)
+- [Node.js ES 모듈 가이드](https://nodejs.org/api/esm.html)
+- [Jest 테스팅 가이드](https://jestjs.io/docs/getting-started)
+- [GitHub Actions 문서](https://docs.github.com/en/actions)
+
+---
+
+이 가이드는 지속적으로 업데이트됩니다. 개선 사항이나 제안이 있으면 이슈를 생성해 주세요.

package/docs/DEVELOPMENT_GUIDE.md

@@ -30,7 +30,7 @@ aiwf 프로젝트 개발을 위해 다음 도구들이 필요합니다:
 
 ```bash
 # 1. 리포지토리 클론
-git clone https://github.com/aiwf/aiwf.git
+git clone https://github.com/moonklabs/aiwf.git
 cd aiwf
 
 # 2. 의존성 설치

package/docs/EXAMPLES.md

@@ -29,7 +29,7 @@ mkdir my-ecommerce
 cd my-ecommerce
 
 # Initialize AIWF
-npx aiwf
+aiwf install
 
 # Initialize project with AIWF
 /project:aiwf:initialize
@@ -445,7 +445,9 @@ jobs:
         node-version: '18'
     
     - name: Install AIWF
-      run: npx aiwf --ci
+      run: |
+        npm install -g aiwf
+        aiwf install --ci
     
     - name: Run Performance Benchmark
       run: |
@@ -453,11 +455,11 @@ jobs:
         
     - name: Check Feature Completion
       run: |
-        npx aiwf check-feature-status ${{ github.event.pull_request.title }}
+        aiwf check-feature-status ${{ github.event.pull_request.title }}
         
     - name: Generate Reports
       run: |
-        npx aiwf generate-ci-report
+        aiwf generate-ci-report
         
     - name: Comment on PR
       uses: actions/github-script@v6
@@ -494,7 +496,7 @@ fi
 npm run test:quick
 
 # Check code quality
-npx aiwf code-quality-check
+aiwf code-quality-check
 EOF
 
 chmod +x .git/hooks/pre-commit
@@ -688,4 +690,4 @@ These examples demonstrate AIWF's flexibility and power in real-world scenarios.
 4. **Proactive management**: Monitor tokens, performance, and progress
 5. **Team alignment**: Document and share conventions
 
-For more examples and community contributions, visit our [GitHub repository](https://github.com/aiwf/aiwf/tree/main/examples).
+For more examples and community contributions, visit our [GitHub repository](https://github.com/moonklabs/aiwf/tree/main/examples).

package/docs/GETTING_STARTED.md

@@ -41,11 +41,14 @@ Before you begin, ensure you have:
 ### 1. Install AIWF
 
 ```bash
+# Install globally (if not already installed)
+npm install -g aiwf
+
 # Navigate to your project directory
 cd my-project
 
-# Install AIWF
-npx aiwf
+# Initialize AIWF in your project
+aiwf install
 ```
 
 ### 2. Choose Your Language
@@ -416,7 +419,7 @@ import { PerformanceBenchmark } from '@aiwf/performance';
 
 ### 3. Join the Community
 
-- **GitHub**: [github.com/aiwf/aiwf](https://github.com/aiwf/aiwf)
+- **GitHub**: [github.com/moonklabs/aiwf](https://github.com/moonklabs/aiwf)
 - **Discord**: [discord.gg/aiwf](https://discord.gg/aiwf)
 - **Discussions**: Share your experiences and learn from others