wing-ops/docs/_backup_20260301/DEVELOPMENT-GUIDE.md

# WING 개발 워크플로우 가이드

## 목차
1. [전체 흐름 요약](#1-전체-흐름-요약)
2. [계획 수립 (Plan)](#2-계획-수립-plan)
3. [브랜치 생성 및 개발](#3-브랜치-생성-및-개발)
4. [커밋 & 푸시](#4-커밋--푸시)
5. [MR 생성 (feature → develop)](#5-mr-생성-feature--develop)
6. [릴리즈 PR (develop → main)](#6-릴리즈-pr-develop--main)
7. [자동 배포](#7-자동-배포)
8. [프로젝트 문서 최신화](#8-프로젝트-문서-최신화)
9. [실전 예시: 기능 추가 A to Z](#9-실전-예시-기능-추가-a-to-z)

---

## 1. 전체 흐름 요약

```
계획 수립 → 브랜치 생성 → 개발 → 커밋/푸시 → develop MR → main PR → 자동 배포
```

```
[Plan Mode]          Claude가 코드베이스 분석 후 구현 계획 작성
     ↓
[Branch]             feature/기능명 브랜치 생성 (develop 기반)
     ↓
[Develop]            코드 작성 + TypeScript/ESLint 검증
     ↓
[Commit & Push]      Conventional Commits 형식 + pre-commit 자동 검증
     ↓
[MR → develop]       코드 리뷰 + 머지
     ↓
[PR → main]          릴리즈 MR + 머지
     ↓
[Auto Deploy]        Gitea Actions → 빌드 → 서버 배포
```

---

## 2. 계획 수립 (Plan)

3개 이상 파일 수정이 예상되거나 아키텍처에 영향을 주는 작업은 **Plan Mode**로 시작합니다.

### Claude에게 요청하는 방법

```
"사용자 프로필 페이지를 추가해줘"
→ Claude가 자동으로 Plan Mode 진입 → 코드베이스 분석 → 구현 계획 제시
→ 사용자 승인 후 구현 시작
```

### 계획에 포함되는 내용
- 수정/생성할 파일 목록
- 변경 범위 및 영향도
- 기술적 선택지와 권장안
- 구현 순서

### Plan Mode가 불필요한 경우
- 단순 버그 수정 (1~2개 파일)
- 텍스트/스타일 수정
- 설정 변경

---

## 3. 브랜치 생성 및 개발

### 브랜치 네이밍 규칙

| 유형 | 형식 | 예시 |
|------|------|------|
| 기능 | `feature/설명` | `feature/user-profile` |
| 이슈 | `feature/ISSUE-번호-설명` | `feature/ISSUE-42-login-fix` |
| 버그 | `bugfix/ISSUE-번호-설명` | `bugfix/ISSUE-15-token-expired` |
| 긴급 | `hotfix/설명` | `hotfix/security-patch` |

### 브랜치 생성

```bash
# develop에서 분기
git checkout develop
git pull origin develop
git checkout -b feature/user-profile
```

### 개발 중 검증

로컬에서 타입 체크와 린트를 수시로 확인합니다:

```bash
# Frontend
cd frontend && npx tsc --noEmit && npx eslint src/

# Backend
cd backend && npx tsc --noEmit
```

---

## 4. 커밋 & 푸시

### Conventional Commits 형식

```
type(scope): 한국어 설명
```

| type | 용도 | 예시 |
|------|------|------|
| `feat` | 새 기능 | `feat(auth): Google OAuth 로그인 추가` |
| `fix` | 버그 수정 | `fix(map): 레이어 겹침 오류 수정` |
| `refactor` | 리팩토링 | `refactor(api): 중복 호출 제거` |
| `docs` | 문서 | `docs: API 엔드포인트 문서 추가` |
| `chore` | 설정/빌드 | `chore: 의존성 버전 업데이트` |
| `ci` | CI/CD | `ci: 백엔드 빌드 스텝 추가` |
| `style` | 포맷팅 | `style: ESLint 경고 수정` |

### pre-commit 자동 검증

커밋 시 `.githooks/pre-commit`이 자동 실행됩니다:
1. Frontend TypeScript 타입 체크
2. Frontend ESLint 검증
3. Backend TypeScript 타입 체크

**하나라도 실패하면 커밋이 차단됩니다.**

### 푸시

```bash
git push origin feature/user-profile
```

### Claude 스킬 활용

```
/push                    # 변경사항 확인 → 커밋 → 푸시 (한 번에)
/mr                      # 커밋 → 푸시 → MR 생성 (한 번에)
/mr main                 # 커밋 → 푸시 → main으로 MR 생성
```

---

## 5. MR 생성 (feature → develop)

### Gitea에서 MR 생성

1. https://gitea.gc-si.dev/gc/wing-ops/compare/develop...feature/user-profile
2. 제목: Conventional Commits 형식
3. 본문: 변경 내용 요약 + 테스트 계획

### Claude로 MR 생성

```
/create-mr develop       # feature → develop MR 자동 생성
```

### MR 본문 템플릿

```markdown
## Summary
- 사용자 프로필 페이지 추가
- 프로필 수정 API 연동

## 변경 파일
- frontend/src/components/views/ProfileView.tsx (신규)
- backend/src/users/userRouter.ts (수정)

## Test plan
- [ ] 프로필 페이지 접근 확인
- [ ] 프로필 수정 후 저장 확인
```

### 머지 후

```bash
# 로컬 develop 동기화
git checkout develop
git pull origin develop
```

---

## 6. 릴리즈 PR (develop → main)

develop에 기능이 머지된 후, 배포를 위해 main으로 릴리즈 MR을 생성합니다.

### Claude로 릴리즈 MR 생성

```
/release                 # develop → main 릴리즈 MR 자동 생성
```

### 릴리즈 MR 체크리스트

```markdown
## Release v2.x.x

### 포함 기능
1. feat(auth): Google OAuth 로그인
2. fix(map): 레이어 오류 수정

### 배포 전 확인
- [ ] 로컬 빌드 성공 (frontend + backend)
- [ ] 서버 환경변수 설정 완료
- [ ] DB 마이그레이션 적용 (필요 시)
```

### main 머지 → 자동 배포 트리거

main에 머지되면 `.gitea/workflows/deploy.yml`이 자동 실행됩니다.

---

## 7. 자동 배포

### CI/CD 파이프라인 (Gitea Actions)

```
main 브랜치 push
  ↓
[Frontend]  npm ci → vite build → /deploy/wing-demo/
  ↓
[Backend]   npm ci → tsc → /deploy/wing-demo-backend/
  ↓
[Server]    .deploy-trigger 감지 → wing-demo-api 재시작
```

### 배포 환경

| 항목 | 값 |
|------|---|
| 프론트엔드 | https://wing-demo.gc-si.dev |
| 백엔드 API | https://wing-demo.gc-si.dev/api/ |
| 서버 | rocky-211 (Rocky Linux 9.6) |
| 프로세스 | systemd `wing-demo-api.service` |

### 배포 확인

```bash
# 프론트엔드 응답 확인
curl -s -o /dev/null -w '%{http_code}' https://wing-demo.gc-si.dev/

# 백엔드 API 확인
curl -s https://wing-demo.gc-si.dev/api/auth/me
```

### 환경변수 관리

| 위치 | 용도 |
|------|------|
| systemd 서비스 파일 | 서버 런타임 환경변수 (DB, JWT 등) |
| Gitea Secrets | CI/CD 빌드 시 환경변수 (API 키 등) |

```bash
# Gitea Secret 등록 (API)
curl -X PUT "https://gitea.gc-si.dev/api/v1/repos/gc/wing-ops/actions/secrets/KEY_NAME" \
  -H "Authorization: token <token>" \
  -H "Content-Type: application/json" \
  -d '{"data":"secret-value"}'

# Gitea Secret 등록 (Web UI)
# Settings → Actions → Secrets → Add Secret
```

---

## 8. 프로젝트 문서 최신화

### 자동 관리되는 문서

Claude 세션 중 커밋/컴팩트 시 hook이 자동으로 갱신을 안내합니다:

| 문서 | 위치 | 갱신 시점 |
|------|------|----------|
| MEMORY.md | `~/.claude/projects/.../memory/` | 매 세션 |
| project-snapshot.md | 위와 동일 | 구조 변경 시 |
| project-history.md | 위와 동일 | 매 커밋 |
| api-types.md | 위와 동일 | API 변경 시 |
| CHANGELOG.md | `docs/CHANGELOG.md` | 매 커밋 |

### 수동으로 최신화해야 하는 문서

| 문서 | 위치 | 갱신 주기 |
|------|------|----------|
| CLAUDE.md | 프로젝트 루트 | 기술 스택 변경 시 |
| INSTALL_GUIDE.md | `docs/` | 배포 환경 변경 시 |
| auth_init.sql | `database/` | DB 스키마 변경 시 |

### 주기적 최신화 체크리스트

**매 기능 개발 완료 시:**
```
Claude에게: "memory 파일 최신화해줘"
→ project-snapshot.md 갱신
→ api-types.md 갱신 (API 변경 시)
→ project-history.md에 변경 이력 추가
```

**매주 또는 스프린트 종료 시:**
```
Claude에게: "프로젝트 문서 전체 점검해줘"
→ CLAUDE.md 기술 스택 확인
→ CHANGELOG.md 누락 항목 보충
→ 의존성 버전 확인 (npm outdated)
```

**팀 워크플로우 업데이트 시:**
```
/sync-team-workflow      # Gitea에서 최신 팀 규칙 동기화
```

---

## 9. 실전 예시: 기능 추가 A to Z

### 시나리오: "사고 상세 조회 페이지 추가"

#### Step 1. 계획

```
사용자: "사고 상세 조회 페이지를 추가해줘. 사고 목록에서 클릭하면 상세 정보를 보여주는 페이지야"

Claude: (Plan Mode 진입)
  → 코드베이스 분석
  → 구현 계획 제시:
    1. backend/src/incidents/incidentService.ts - 상세 조회 함수
    2. backend/src/incidents/incidentRouter.ts - GET /api/incidents/:id
    3. frontend/src/services/incidentApi.ts - API 함수
    4. frontend/src/components/views/IncidentDetailView.tsx - 상세 화면
    5. frontend/src/App.tsx - 라우팅 연결

사용자: (계획 승인)
```

#### Step 2. 브랜치 생성

```bash
git checkout develop
git pull origin develop
git checkout -b feature/incident-detail
```

#### Step 3. 개발

Claude가 계획에 따라 코드 작성 (5개 파일 수정/생성)

#### Step 4. 커밋 & 푸시

```
사용자: "커밋하고 푸시해줘"

Claude:
  git add backend/src/incidents/... frontend/src/...
  git commit -m "feat(incidents): 사고 상세 조회 페이지 추가"
  # pre-commit: TypeScript ✓, ESLint ✓
  git push origin feature/incident-detail
```

또는 스킬 사용:

```
/push feat(incidents): 사고 상세 조회 페이지 추가
```

#### Step 5. develop MR

```
사용자: "develop MR 만들어줘"

Claude:
  → Gitea API로 MR 생성
  → feature/incident-detail → develop
  → MR #5: https://gitea.gc-si.dev/gc/wing-ops/pulls/5
```

또는:
```
/create-mr develop
```

#### Step 6. 코드 리뷰 & 머지

- Gitea에서 MR 리뷰
- 승인 후 Squash Merge

#### Step 7. 릴리즈 PR

```
사용자: "main으로 릴리즈 MR 만들어줘"

Claude:
  → develop → main MR 생성
  → MR #6 (release)
```

또는:
```
/release
```

#### Step 8. main 머지 → 자동 배포

- main에 머지 → Gitea Actions 실행
- Frontend 빌드 (Vite) → /deploy/wing-demo/
- Backend 빌드 (tsc) → /deploy/wing-demo-backend/
- .deploy-trigger → cron이 감지 → wing-demo-api 재시작
- https://wing-demo.gc-si.dev 에서 확인

#### Step 9. 문서 최신화

```
사용자: "memory 파일 최신화해줘"

Claude:
  → project-snapshot.md: incidents 모듈 추가 반영
  → api-types.md: GET /api/incidents/:id 추가
  → project-history.md: "사고 상세 조회 페이지 추가" 기록
```

---

## 부록: 자주 쓰는 Claude 명령

| 명령 | 설명 |
|------|------|
| `"커밋하고 푸시해줘"` | 변경사항 커밋 + 푸시 |
| `"develop MR 만들어줘"` | feature → develop MR |
| `"memory 최신화해줘"` | 프로젝트 문서 갱신 |
| `/push` | 커밋 + 푸시 (스킬) |
| `/mr` | 커밋 + 푸시 + MR (스킬) |
| `/release` | develop → main 릴리즈 MR (스킬) |
| `/create-mr develop` | MR만 생성 (스킬) |
| `/sync-team-workflow` | 팀 워크플로우 동기화 (스킬) |
| `/changelog` | CHANGELOG.md 갱신 (스킬) |