aiwf/docs/DEVELOPMENT_GUIDE.md

AI Workflow Framework for Claude Code with multi-language support (Korean/English)

# 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/
├── index.js                    # 메인 CLI 실행 파일
├── package.json               # NPM 패키지 설정
├── claude-code/aiwf/      # AIWF 프레임워크 소스
│   ├── .claude/commands/       # Claude Code 커스텀 명령어
│   └── .aiwf/            # 프로젝트 관리 구조
├── rules/                     # IDE별 개발 규칙
│   ├── global/                # 항상 적용되는 규칙
│   └── manual/                # 필요시 적용하는 규칙
├── docs/                      # 프로젝트 문서
├── tests/                     # 테스트 파일 (생성 예정)
└── scripts/                   # 빌드/배포 스크립트
```

---

## 2. 개발 도구 설정

### 2.1 Jest 테스트 프레임워크 설정

aiwf는 ES 모듈 기반 프로젝트이므로 Jest 설정 시 ES 모듈 지원이 필요합니다.

#### 설치

```bash
npm install --save-dev jest @jest/globals
```

#### jest.config.js 설정

```javascript
export default {
  preset: "jest-esm",
  extensionsToTreatAsEsm: [".js"],
  globals: {
    "ts-jest": {
      useESM: true,
    },
  },
  moduleNameMapping: {
    "^(\\.{1,2}/.*)\\.js$": "$1",
  },
  transform: {},
  testEnvironment: "node",
  collectCoverageFrom: ["index.js", "!node_modules/**", "!coverage/**"],
  coverageReporters: ["text", "lcov", "html"],
  testMatch: ["<rootDir>/tests/**/*.test.js"],
};
```

#### package.json 테스트 스크립트

```json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",
    "test:ci": "jest --ci --coverage --watchAll=false"
  }
}
```

### 2.2 ESLint & Prettier 설정

코드 품질과 일관성을 위한 린팅 및 포맷팅 도구 설정입니다.

#### 설치

```bash
npm install --save-dev eslint prettier eslint-config-prettier eslint-plugin-prettier
```

#### .eslintrc.json 설정

```json
{
  "env": {
    "es2022": true,
    "node": true,
    "jest": true
  },
  "extends": ["eslint:recommended", "prettier"],
  "plugins": ["prettier"],
  "parserOptions": {
    "ecmaVersion": 2022,
    "sourceType": "module"
  },
  "rules": {
    "prettier/prettier": "error",
    "no-console": "off",
    "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "prefer-const": "error",
    "no-var": "error"
  }
}
```

#### .prettierrc 설정

```json
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false
}
```

#### package.json 린팅 스크립트

```json
{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write ."
  }
}
```

### 2.3 IDE 통합 설정

#### VS Code 설정 (.vscode/settings.json)

```json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": ["javascript"],
  "files.associations": {
    "*.md": "markdown"
  }
}
```

---

## 3. 개발 워크플로우

### 3.1 Git 브랜치 전략

aiwf 프로젝트는 Git Flow 기반의 브랜치 전략을 사용합니다:

- **main**: 프로덕션 준비 코드
- **develop**: 개발용 통합 브랜치
- **feature/**: 기능 개발 브랜치
- **hotfix/**: 긴급 수정 브랜치
- **release/**: 릴리스 준비 브랜치

#### 기능 개발 워크플로우

```bash
# 1. develop 브랜치에서 기능 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# 2. 개발 진행
# 코드 작성 및 테스트

# 3. 변경사항 커밋
git add .
git commit -m "feat: 새로운 기능 설명"

# 4. 원격 저장소에 푸시
git push origin feature/your-feature-name

# 5. Pull Request 생성
# GitHub에서 PR 생성하여 코드 리뷰 요청
```

### 3.2 커밋 메시지 컨벤션

Conventional Commits 형식을 따릅니다:

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

#### 커밋 타입

- **feat**: 새로운 기능 추가
- **fix**: 버그 수정
- **docs**: 문서 변경
- **style**: 코드 포맷팅 변경
- **refactor**: 코드 리팩토링
- **test**: 테스트 추가/수정
- **chore**: 빌드 과정 또는 도구 변경

#### 예시

```bash
feat(cli): GitHub API 에러 처리 개선
fix(installer): 백업 파일 생성 시 타임스탬프 오류 수정
docs(readme): 설치 가이드 업데이트
```

### 3.3 코드 리뷰 프로세스

1. **자체 검토**: PR 생성 전 자신의 코드 검토
2. **테스트 통과**: 모든 테스트가 통과하는지 확인
3. **린팅 통과**: ESLint 및 Prettier 검사 통과
4. **PR 생성**: 명확한 제목과 설명으로 PR 생성
5. **리뷰 대응**: 리뷰어의 피드백에 적극적으로 대응
6. **승인 후 머지**: 승인 받은 후 squash merge 수행

---

## 4. 코딩 표준

### 4.1 JavaScript/ES6+ 스타일 가이드

#### 변수 선언

```javascript
// 좋음: const 우선 사용
const apiUrl = "https://api.github.com";
let mutableValue = 0;

// 피하기: var 사용 금지
var oldStyle = "avoid";
```

#### 함수 선언

```javascript
// 좋음: 화살표 함수 사용
const fetchData = async (url) => {
  try {
    const response = await fetch(url);
    return await response.json();
  } catch (error) {
    console.error("데이터 가져오기 실패:", error);
    throw error;
  }
};

// 좋음: 명시적 함수 선언
function processData(data) {
  return data.filter((item) => item.isValid);
}
```

#### 객체와 배열

```javascript
// 좋음: 구조 분해 할당 사용
const { name, version } = packageJson;
const [first, ...rest] = items;

// 좋음: 스프레드 연산자 사용
const newObject = { ...existingObject, newProperty: "value" };
const newArray = [...existingArray, newItem];
```

### 4.2 파일 및 디렉토리 명명 규칙

- **파일명**: kebab-case 또는 camelCase
  - `github-api.js`, `fileOperations.js`
- **디렉토리명**: kebab-case
  - `test-fixtures/`, `github-api/`
- **상수**: UPPER_SNAKE_CASE
  - `const API_BASE_URL = 'https://api.github.com';`

### 4.3 주석 및 문서화

```javascript
/**
 * GitHub API에서 파일 콘텐츠를 가져옵니다.
 * @param {string} url - GitHub API URL
 * @param {Object} options - 요청 옵션
 * @returns {Promise<Object>} API 응답 데이터
 * @throws {Error} 네트워크 또는 API 오류 시 발생
 */
async function fetchGitHubContent(url, options = {}) {
  // 구현 내용...
}

// 복잡한 로직에 대한 인라인 주석
const backupTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
// ISO 문자열에서 파일명에 사용할 수 없는 문자들을 대시로 변경
```

### 4.4 에러 처리 가이드라인

```javascript
// 좋음: 구체적인 에러 처리
try {
  const result = await someAsyncOperation();
  return result;
} catch (error) {
  if (error.code === "ENOENT") {
    console.error("파일을 찾을 수 없습니다:", error.path);
  } else if (error.code === "EACCES") {
    console.error("파일 접근 권한이 없습니다:", error.path);
  } else {
    console.error("예상치 못한 오류:", error.message);
  }

  throw new Error(`작업 실패: ${error.message}`);
}
```

---

## 5. 테스트 작성

### 5.1 테스트 디렉토리 구조

```
tests/
├── unit/                       # 단위 테스트
│   ├── github-api.test.js
│   ├── file-operations.test.js
│   └── cli-interface.test.js
├── integration/                # 통합 테스트
│   └── installer.test.js
├── fixtures/                   # 테스트 데이터
│   ├── mock-github-response.json
│   └── sample-project-structure/
└── helpers/                    # 테스트 헬퍼
    ├── test-utils.js
    └── mock-setup.js
```

### 5.2 단위 테스트 작성 가이드

```javascript
// github-api.test.js
import { jest } from "@jest/globals";
import { fetchGitHubContent } from "../../index.js";

// 네트워크 호출 모킹
jest.mock("https");

describe("GitHub API functions", () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  describe("fetchGitHubContent", () => {
    test("성공적으로 데이터를 가져와야 함", async () => {
      // Given
      const mockUrl = "https://api.github.com/repos/test/repo";
      const mockResponse = { name: "test-repo" };

      // Mock 설정
      // ...

      // When
      const result = await fetchGitHubContent(mockUrl);

      // Then
      expect(result).toEqual(mockResponse);
    });

    test("네트워크 오류 시 적절한 에러를 발생시켜야 함", async () => {
      // Given & When & Then
      await expect(fetchGitHubContent("invalid-url")).rejects.toThrow(
        "네트워크 오류"
      );
    });
  });
});
```

### 5.3 통합 테스트 작성 가이드

```javascript
// installer.test.js
import fs from "fs/promises";
import path from "path";
import { fileURLToPath } from "url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

describe("Installer Integration Tests", () => {
  let tempDir;

  beforeEach(async () => {
    // 임시 디렉토리 생성
    tempDir = await fs.mkdtemp(path.join(__dirname, "temp-"));
  });

  afterEach(async () => {
    // 임시 디렉토리 정리
    await fs.rm(tempDir, { recursive: true, force: true });
  });

  test("전체 설치 프로세스가 정상 동작해야 함", async () => {
    // 전체 설치 프로세스 테스트
    // ...
  });
});
```

### 5.4 테스트 베스트 프랙티스

1. **AAA 패턴**: Arrange, Act, Assert 구조 사용
2. **명확한 테스트명**: 테스트가 무엇을 검증하는지 명확히 표현
3. **독립성**: 각 테스트는 독립적으로 실행 가능해야 함
4. **모킹**: 외부 의존성은 적절히 모킹하여 테스트 안정성 확보
5. **커버리지**: 중요한 비즈니스 로직은 높은 커버리지 유지

---

## 6. CI/CD 파이프라인

### 6.1 GitHub Actions 워크플로우

aiwf 프로젝트는 GitHub Actions를 사용하여 CI/CD를 구성합니다.

#### .github/workflows/ci.yml

```yaml
name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]

    steps:
      - uses: actions/checkout@v3

      - name: Node.js ${{ matrix.node-version }} 설정
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"

      - name: 의존성 설치
        run: npm ci

      - name: 린팅 검사
        run: npm run lint

      - name: 테스트 실행
        run: npm run test:ci

      - name: 커버리지 업로드
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
      - uses: actions/checkout@v3

      - name: Node.js 설정
        uses: actions/setup-node@v3
        with:
          node-version: "18.x"
          registry-url: "https://registry.npmjs.org"

      - name: 의존성 설치
        run: npm ci

      - name: NPM 배포
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

### 6.2 배포 프로세스

1. **자동 배포**: main 브랜치에 머지 시 자동으로 NPM에 배포
2. **버전 관리**: semantic versioning 사용
3. **릴리스 노트**: GitHub Releases를 통한 변경사항 문서화

### 6.3 모니터링 및 알림

- **빌드 상태**: GitHub Actions 배지를 통한 빌드 상태 확인
- **커버리지**: Codecov를 통한 테스트 커버리지 모니터링
- **의존성 보안**: Dependabot을 통한 의존성 보안 검사

---

## 7. 문제 해결

### 7.1 일반적인 설치 문제

#### Node.js 버전 문제

```bash
# 문제: Node.js 버전이 14.0.0 미만
# 해결: nvm을 사용하여 적절한 버전 설치
nvm install 18
nvm use 18
```

#### 권한 문제

```bash
# 문제: npm install 시 권한 오류
# 해결: npm 글로벌 디렉토리 권한 변경
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```

### 7.2 테스트 관련 문제 해결

#### ES 모듈 관련 오류

```javascript
// 문제: Jest에서 ES 모듈을 인식하지 못함
// 해결: jest.config.js에서 ES 모듈 설정 확인

// package.json에 다음 추가
{
  "type": "module",
  "jest": {
    "preset": "jest-esm"
  }
}
```

#### 네트워크 테스트 불안정성

```javascript
// 문제: GitHub API 호출 테스트가 불안정함
// 해결: 적절한 모킹과 타임아웃 설정

jest.setTimeout(10000); // 10초 타임아웃

// 네트워크 호출 모킹
jest.mock("https", () => ({
  request: jest.fn(),
}));
```

### 7.3 빌드 및 배포 문제

#### GitHub Actions 실패

```yaml
# 문제: CI 파이프라인에서 테스트 실패
# 해결: 로컬에서 CI 환경과 동일한 조건으로 테스트

# 로컬에서 CI 테스트 실행
npm run test:ci

# 환경 변수 확인
env | grep NODE
```

### 7.4 IDE 설정 문제

#### VS Code에서 ESLint 동작하지 않음

```json
// .vscode/settings.json
{
  "eslint.workingDirectories": ["./"],
  "eslint.validate": ["javascript"]
}
```

---

## 8. 기여하기

### 8.1 기여 가이드라인

aiwf 프로젝트에 기여하기 위한 단계별 가이드입니다.

#### 첫 번째 기여 준비

1. **이슈 확인**: GitHub Issues에서 작업할 이슈 선택
2. **포크 생성**: 개인 계정으로 프로젝트 포크
3. **로컬 설정**: 개발 환경 설정 및 테스트 실행
4. **브랜치 생성**: feature/issue-번호-설명 형식으로 브랜치 생성

#### 코드 작성 가이드

1. **코딩 표준 준수**: ESLint 및 Prettier 규칙 따르기
2. **테스트 작성**: 새로운 기능에 대한 테스트 포함
3. **문서 업데이트**: 필요시 관련 문서 업데이트
4. **커밋 메시지**: Conventional Commits 형식 준수

### 8.2 코드 리뷰 기준

#### 리뷰어 체크리스트

- [ ] 코딩 표준 준수 여부
- [ ] 테스트 커버리지 적절성
- [ ] 에러 처리 적절성
- [ ] 성능 영향 고려
- [ ] 보안 취약점 여부
- [ ] 문서화 완성도

#### 기여자 체크리스트

- [ ] 모든 테스트 통과
- [ ] 린팅 검사 통과
- [ ] 브랜치 최신 상태 유지
- [ ] PR 설명 명확히 작성
- [ ] 관련 이슈 링크 포함

### 8.3 커뮤니티 가이드라인

#### 행동강령

1. **존중**: 모든 기여자를 존중하고 건설적인 피드백 제공
2. **포용성**: 다양한 배경의 기여자들을 환영
3. **투명성**: 의사결정 과정을 투명하게 공유
4. **협력**: 문제 해결을 위한 협력적 자세 유지

#### 커뮤니케이션 채널

- **GitHub Issues**: 버그 리포트 및 기능 요청
- **GitHub Discussions**: 일반적인 토론 및 질문
- **Pull Requests**: 코드 리뷰 및 기술적 논의

---

## 부록

### A. 유용한 명령어

```bash
# 프로젝트 초기 설정
npm install
npm run setup  # 개발 환경 초기 설정 (구현 예정)

# 개발 중 자주 사용하는 명령어
npm run dev     # 개발 모드 실행
npm test        # 테스트 실행
npm run lint    # 린팅 검사
npm run format  # 코드 포맷팅

# 배포 관련
npm run build   # 프로덕션 빌드
npm run release # 릴리스 준비 (구현 예정)
```

### B. 참고 자료

- [Node.js 공식 문서](https://nodejs.org/docs/)
- [Jest 공식 문서](https://jestjs.io/docs/getting-started)
- [ESLint 공식 문서](https://eslint.org/docs/user-guide/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [GitHub Actions 문서](https://docs.github.com/en/actions)

### C. 문의 및 지원

프로젝트 관련 문의나 지원이 필요한 경우:

1. **GitHub Issues**: 버그 리포트 및 기능 요청
2. **GitHub Discussions**: 일반적인 질문 및 토론
3. **이메일**: 긴급한 보안 문제 등

---

이 문서는 aiwf 프로젝트의 발전과 함께 지속적으로 업데이트됩니다. 개선 사항이나 추가할 내용이 있다면 언제든지 기여해 주세요!