wing-ops/docs/DEVELOPMENT-GUIDE.md

WING 개발 워크플로우 가이드

목차

1. 전체 흐름 요약
2. 계획 수립 (Plan)
3. 브랜치 생성 및 개발
4. 커밋 & 푸시
5. MR 생성 (feature → develop)
6. 릴리즈 PR (develop → main)
7. 자동 배포
8. 프로젝트 문서 최신화
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

브랜치 생성

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

개발 중 검증

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

# 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 타입 체크

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

푸시

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 본문 템플릿

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

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

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

머지 후

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

---

6. 릴리즈 PR (develop → main)

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

Claude로 릴리즈 MR 생성

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

릴리즈 MR 체크리스트

## 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

배포 확인

# 프론트엔드 응답 확인
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 키 등)

# 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. 브랜치 생성

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 갱신 (스킬)