gc/wing-ops
8
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동

docs: v1.0.0 버저닝 릴리즈 노트 작성 #65

병합
htlee docs/version-history 에서 develop 로 33 commits 를 머지했습니다 2026-03-03 08:09:49 +09:00
대화 0 커밋 33 파일 변경됨 11 +439 -1
2개의 변경된 파일과 439개의 추가작업 그리고 1개의 파일을 삭제
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 75503ee477 - Show all commits

7
.gitea/workflows/deploy.yml
파일 보기

@ -48,13 +48,18 @@ jobs:
- name: Install backend dependencies
run: |
cd backend
npm ci --omit=dev
npm ci
- name: Build backend
run: |
cd backend
npx tsc
- name: Prune dev dependencies
run: |
cd backend
npm prune --omit=dev
- name: Deploy backend
run: |
mkdir -p /deploy/wing-demo-backend/dist

433
docs/DEVELOPMENT-GUIDE.md Normal file
파일 보기

@ -0,0 +1,433 @@
# 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 갱신 (스킬) |