Merge pull request 'release: 2026-04-07 (3건 커밋)' (#2) from develop into main

2026-04-07 11:06:17 +09:00 · 2026-04-07 11:06:17 +09:00 · 4886a96344
--- a/.claude/agents/explorer.md
+++ b/.claude/agents/explorer.md
@ -0,0 +1,47 @@
+---
+name: explorer
+description: 코드베이스 탐색 및 분석 에이전트. 3개 이상의 파일을 탐색하거나 프로젝트 구조를 파악할 때 사용한다.
+model: sonnet
+tools: Read, Glob, Grep
+maxTurns: 12
+---
+
+지정된 영역 내에서 코드베이스를 분석하고 구조화된 결과를 반환한다.
+읽기 전용 — 파일을 수정하지 않는다.
+
+## 자율 범위
+
+- 메인 세션이 지정한 **탐색 영역**(디렉토리 또는 파일 목록) 내에서 자유롭게 탐색
+- 영역 내 파일 간 의존성 추적, 임포트 체인 분석은 자율 수행
+- 탐색 영역 밖 파일은 임포트/참조 관계 확인 목적으로만 열람 가능
+
+## 입력 (메인 세션이 제공)
+
+- **탐색 영역**: 디렉토리 경로 또는 파일 목록
+- **목적**: 분석 목적이나 답변할 질문 (구체적일수록 좋음)
+
+## 출력 형식
+
+```
+## 분석 결과
+
+### 구조
+- 핵심 파일/디렉토리 구성 (파일:라인 근거)
+
+### 발견사항
+- 목적에 대한 답변 (파일:라인 근거 포함)
+
+### 패턴
+- 코드 컨벤션, 반복 패턴, 아키텍처 특성
+
+### 확신도
+- 각 발견사항별: 확정 / 추정(근거) / 판단불가(필요 정보)
+
+### 범위 외 참고
+- 탐색 영역 밖에서 발견된 관련 사항 (해당 시)
+```
+
+## 제약
+
+- 파일 수정/생성 금지
+- 정보 부족 시 추측하지 않고 "판단불가 — [필요한 정보]"로 표시
--- a/.claude/agents/implementer.md
+++ b/.claude/agents/implementer.md
@ -0,0 +1,55 @@
+---
+name: implementer
+description: 모듈 단위 코드 구현 에이전트. 독립 모듈 구현이나 병렬 작업이 필요할 때 사용한다.
+model: sonnet
+tools: Read, Write, Edit, Glob, Grep, Bash
+maxTurns: 20
+---
+
+메인 세션이 정의한 계약(인터페이스, 타입, 제약)에 따라 코드를 구현한다.
+내부 구현 방식은 자율 판단하되, 계약과 제약을 벗어나지 않는다.
+
+## 자율 범위
+
+- 계약(함수 시그니처, API 스펙, 타입)은 메인 세션이 확정 — 변경 불가
+- 내부 구현 로직, 헬퍼 함수, 에러 처리 방식은 자율 판단
+- **[참조]** 파일이 제공되면 해당 파일의 코드 패턴(네이밍, 구조, 에러 처리)을 따름
+
+## 입력 (메인 세션이 제공)
+
+- **[파일]**: 수정/생성할 파일 경로
+- **[계약]**: 인터페이스, 타입, 함수 시그니처, API 스펙 등 외부 계약
+- **[참조]**: 패턴을 따를 기존 파일 (선택, 제공 시 해당 패턴 준수)
+- **[제약]**: 특별한 요구사항 (선택)
+
+## 출력 형식
+
+```
+## 구현 결과
+
+### 수정 파일
+- 파일 경로 목록
+
+### 파일별 변경
+- 각 파일에서 추가/수정한 내용 요약
+
+### 자체 검증
+- tsc --noEmit: 통과 / 실패(에러 내용)
+- [추가 검증 항목]: 결과
+
+### 계약 외 판단
+- 자율 판단한 구현 결정 사항 (메인 세션 참고용)
+
+### 보고 사항 (해당 시)
+- 계약 불충분: 추가 정보가 필요한 항목
+- 아키텍처 영향: 범위 밖 변경이 필요한 사항
+```
+
+## 제약
+
+- [파일]에 명시되지 않은 파일 수정 금지
+- [계약]의 시그니처/타입 임의 변경 금지
+- 아키텍처 변경이 필요하면 구현하지 않고 "보고 사항"에 기록
+- 커밋/푸시 금지
+- any 타입 금지, strict 모드 준수
+- 구현 완료 후 tsc --noEmit 자체 검증 수행
--- a/.claude/agents/reviewer.md
+++ b/.claude/agents/reviewer.md
@ -0,0 +1,53 @@
+---
+name: reviewer
+description: 코드 리뷰 및 품질 검증 에이전트. 커밋 전 검증이나 MR 리뷰 시 사용한다.
+model: sonnet
+tools: Read, Glob, Grep, Bash
+maxTurns: 12
+---
+
+변경된 코드를 체크리스트 기반으로 검증한다.
+읽기 전용 — 파일을 수정하지 않는다.
+
+## 자율 범위
+
+- 지정된 변경 파일을 자유롭게 분석
+- 관련 파일(임포트 대상, 호출자)도 열람하여 영향 범위 확인 가능
+- 기본 체크리스트 + 자체 판단으로 추가 이슈 탐지
+
+## 입력 (메인 세션이 제공)
+
+- **[대상]**: 리뷰할 파일 경로 목록 또는 git diff 범위
+- **[체크리스트]**: 검증 항목 (선택, 미제공 시 기본 체크리스트 사용)
+
+## 기본 체크리스트
+
+1. 타입 안전성 — any, 타입 단언(as), non-null 단언(!) 사용
+2. 에러 처리 — try-catch 누락, empty catch, 에러 무시
+3. 보안 — 하드코딩 인증정보, injection 가능성, XSS
+4. 미사용 코드 — 미사용 import, 변수, 함수
+5. 팀 정책 — team-policy.md 위반 사항
+6. 일관성 — 기존 코드 패턴과의 불일치
+
+## 출력 형식
+
+```
+## 리뷰 결과
+
+| # | 항목 | 판정 | 근거 |
+|---|------|------|------|
+| 1 | [항목명] | PASS / FAIL | [파일:라인] 설명 |
+
+### 추가 발견 (자체 판단)
+- [파일:라인] 설명 (심각도: Critical / Warning / Info)
+
+### 요약
+- 전체: N개 PASS / M개 FAIL
+- 커밋 가능 여부: 가능 / 차단 권고(사유)
+```
+
+## 제약
+
+- 파일 수정/생성 금지
+- 각 항목에 반드시 PASS 또는 FAIL 판정 (애매하면 FAIL + 사유)
+- 스타일 개선 제안은 "추가 발견"에 Info로만 기록
--- a/.claude/rules/frontend-code-style.md
+++ b/.claude/rules/frontend-code-style.md
@ -0,0 +1,68 @@
+# TypeScript/React 코드 스타일 규칙
+
+## TypeScript 일반
+- strict 모드 필수 (`tsconfig.json`)
+- `any` 사용 금지 (불가피한 경우 주석으로 사유 명시)
+- 타입 정의: `interface` 우선 (type은 유니온/인터섹션에만)
+- 들여쓰기: 2 spaces
+- 세미콜론: 사용
+- 따옴표: single quote
+- trailing comma: 사용
+
+## React 규칙
+
+### 컴포넌트
+- 함수형 컴포넌트 + hooks 패턴만 사용
+- 클래스 컴포넌트 사용 금지
+- 컴포넌트 파일 당 하나의 export default 컴포넌트
+- Props 타입은 interface로 정의 (ComponentNameProps)
+
+```tsx
+interface UserCardProps {
+  name: string;
+  email: string;
+  onEdit?: () => void;
+}
+
+const UserCard = ({ name, email, onEdit }: UserCardProps) => {
+  return (
+    <div>
+      <h3>{name}</h3>
+      <p>{email}</p>
+      {onEdit && <button onClick={onEdit}>편집</button>}
+    </div>
+  );
+};
+
+export default UserCard;
+```
+
+### Hooks
+- 커스텀 훅은 `use` 접두사 (예: `useAuth`, `useFetch`)
+- 훅은 `src/hooks/` 디렉토리에 분리
+- 복잡한 상태 로직은 커스텀 훅으로 추출
+
+### 상태 관리
+- 컴포넌트 로컬 상태: `useState`
+- 공유 상태: Context API 또는 Zustand
+- 서버 상태: React Query (TanStack Query) 권장
+
+### 이벤트 핸들러
+- `handle` 접두사: `handleClick`, `handleSubmit`
+- Props로 전달 시 `on` 접두사: `onClick`, `onSubmit`
+
+## 스타일링
+- Tailwind CSS 사용
+- 인라인 스타일 지양
+- !important 사용 금지
+
+## API 호출
+- API 호출 로직은 `src/services/`에 분리
+- Axios 또는 fetch wrapper 사용
+- 에러 처리: try-catch + 사용자 친화적 에러 메시지
+
+## 기타
+- console.log 커밋 금지 (디버깅 후 제거)
+- 매직 넘버/문자열 → 상수 파일로 추출
+- 사용하지 않는 import, 변수 제거 (ESLint로 검증)
+- 이미지/아이콘은 `src/assets/`에 관리
--- a/.claude/rules/release-notes-guide.md
+++ b/.claude/rules/release-notes-guide.md
@ -0,0 +1,38 @@
+# 릴리즈 노트 관리 정책
+
+## 원칙
+
+- MR은 반드시 `/mr` 또는 `/release` 스킬을 통해 생성한다
+- 웹에서 직접 생성한 MR은 릴리즈 노트 누락으로 리뷰에서 반려한다
+- 코드 리뷰 시 `docs/RELEASE-NOTES.md` 변경 여부를 확인한다
+
+## 2계층 구조
+
+### Tier 1: 내부 릴리즈 노트 — `docs/RELEASE-NOTES.md`
+- 대상: 내부 개발자
+- 형식: [Keep a Changelog](https://keepachangelog.com/ko/1.0.0/) 기반
+- 관리: `/mr` → [Unreleased] 항목 추가, `/release` → 날짜 버전 전환 + 압축
+- 모든 커밋 타입 기록
+
+### Tier 2: 버저닝 릴리즈 노트 — `docs/VERSION-HISTORY.md`
+- 대상: 개발자 + 비개발자 + 외부 공유
+- 형식: Semantic Versioning, 사용자 관점의 변화 중심
+- 관리: `/version` 스킬로 RELEASE-NOTES.md 기반 생성
+
+## 변경 타입 매핑 (RELEASE-NOTES.md)
+
+| Conventional Commits | 릴리즈 노트 섹션 |
+|---------------------|-----------------|
+| feat | **추가** |
+| fix | **수정** |
+| refactor, perf | **변경** |
+| docs | **문서** |
+| test | **테스트** |
+| style, chore, ci | **기타** |
+
+## 권한 기반 스킬 접근
+
+- `/push`, `/mr`: `permissions.push` (write 이상)
+- `/release`, `/version`: `permissions.admin` (프로젝트 관리자)
+- 권한은 Gitea API `repos/{owner}/{repo}` → `permissions` 필드로 확인
+- Gitea site admin이 아닌 **리포 단위 팀 권한** 기준
--- a/.claude/rules/subagent-policy.md
+++ b/.claude/rules/subagent-policy.md
@ -0,0 +1,61 @@
+# 서브에이전트 활용 정책
+
+커스텀 에이전트(`.claude/agents/`)를 활용하여 컨텍스트를 보호하고 병렬 작업을 수행한다.
+메인 세션은 리더 역할(설계, 조율, 최종 판단)에 집중하고, 실제 작업은 서브에이전트에 위임한다.
+
+## 에이전트 구성
+
+| 에이전트 | 역할 | 자율성 | 모델 |
+|----------|------|--------|------|
+| explorer | 코드베이스 탐색/분석 (읽기 전용) | 높음 | sonnet |
+| implementer | 모듈 단위 코드 구현 | 중간 | sonnet |
+| reviewer | 코드 리뷰/품질 검증 (읽기 전용) | 높음 | sonnet |
+
+## 사용 시점
+
+### explorer
+- 3개 이상의 파일/디렉토리를 탐색해야 할 때
+- 프로젝트 구조나 패턴을 파악할 때
+- 의존성 체인, 임포트 관계를 추적할 때
+
+### implementer
+- 독립 모듈/컴포넌트를 구현할 때
+- 여러 모듈을 병렬로 구현할 때 (각각 별도 implementer)
+- 반복 패턴을 여러 파일에 적용할 때
+
+### reviewer
+- 구현 완료 후 커밋 전 검증
+- MR 생성 전 자체 리뷰
+- 변경 범위가 클 때 (5개 이상 파일)
+
+## 사용하지 않는 경우
+
+- 단일 파일의 간단한 수정
+- 위치를 이미 아는 코드 수정
+- 설정 파일 변경
+
+## 메인 세션 작업 흐름
+
+### 단일 모듈
+1. 메인: 계약(인터페이스, 타입) 설계
+2. implementer: 계약 기반 구현 + 자체 검증
+3. reviewer: 변경 파일 리뷰
+4. 메인: 결과 확인 → 커밋
+
+### 다중 모듈 (병렬)
+1. 메인: 모듈 간 공유 인터페이스 확정
+2. implementer A + B: 각 모듈 동시 구현
+3. 메인: 통합 확인 (인터페이스 일치)
+4. reviewer: 전체 변경 리뷰
+5. 메인: 최종 확인 → 커밋
+
+### 분석
+1. explorer: 탐색 영역 + 목적 전달 → 분석 결과 반환
+2. 메인: "추정" 항목만 직접 확인 → 판단
+
+## 핵심 원칙
+
+- **읽기 전용 에이전트(explorer/reviewer)**: 결과가 부정확해도 손해 없음 → 높은 자율성 부여
+- **쓰기 에이전트(implementer)**: 계약은 고정, 내부 구현은 자율 → 중간 자율성
+- **같은 파일을 두 에이전트가 동시에 수정하지 않는다**
+- **커밋/푸시는 반드시 메인 세션에서 수행**
--- a/.claude/scripts/on-commit.sh
+++ b/.claude/scripts/on-commit.sh
@ -0,0 +1,14 @@
+#!/bin/bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json;print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null || echo "")
+if echo "$COMMAND" | grep -qE 'git commit'; then
+  cat <<RESP
+{
+  "hookSpecificOutput": {
+    "additionalContext": "커밋이 감지되었습니다. 다음을 수행하세요:\n1. docs/CHANGELOG.md에 변경 내역 추가\n2. memory/project-snapshot.md에서 변경된 부분 업데이트\n3. memory/project-history.md에 이번 변경사항 추가\n4. API 인터페이스 변경 시 memory/api-types.md 갱신\n5. 프로젝트에 lint 설정이 있다면 lint 결과를 확인하고 문제를 수정"
+  }
+}
+RESP
+else
+  echo '{}'
+fi
--- a/.claude/scripts/on-post-compact.sh
+++ b/.claude/scripts/on-post-compact.sh
@ -0,0 +1,23 @@
+#!/bin/bash
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | python3 -c "import sys,json;print(json.load(sys.stdin).get('cwd',''))" 2>/dev/null || echo "")
+if [ -z "$CWD" ]; then
+  CWD=$(pwd)
+fi
+PROJECT_HASH=$(echo "$CWD" | sed 's|/|-|g')
+MEMORY_DIR="$HOME/.claude/projects/$PROJECT_HASH/memory"
+CONTEXT=""
+if [ -f "$MEMORY_DIR/MEMORY.md" ]; then
+  SUMMARY=$(head -100 "$MEMORY_DIR/MEMORY.md" | python3 -c "import sys;print(sys.stdin.read().replace('\\\\','\\\\\\\\').replace('\"','\\\\\"').replace('\n','\\\\n'))" 2>/dev/null)
+  CONTEXT="컨텍스트가 압축되었습니다.\\n\\n[세션 요약]\\n${SUMMARY}"
+fi
+if [ -f "$MEMORY_DIR/project-snapshot.md" ]; then
+  SNAP=$(head -50 "$MEMORY_DIR/project-snapshot.md" | python3 -c "import sys;print(sys.stdin.read().replace('\\\\','\\\\\\\\').replace('\"','\\\\\"').replace('\n','\\\\n'))" 2>/dev/null)
+  CONTEXT="${CONTEXT}\\n\\n[프로젝트 최신 상태]\\n${SNAP}"
+fi
+if [ -n "$CONTEXT" ]; then
+  CONTEXT="${CONTEXT}\\n\\n위 내용을 참고하여 작업을 이어가세요. 상세 내용은 memory/ 디렉토리의 각 파일을 참조하세요."
+  echo "{\"hookSpecificOutput\":{\"additionalContext\":\"${CONTEXT}\"}}"
+else
+  echo "{\"hookSpecificOutput\":{\"additionalContext\":\"컨텍스트가 압축되었습니다. memory 파일이 없으므로 사용자에게 이전 작업 내용을 확인하세요.\"}}"
+fi
--- a/.claude/scripts/on-pre-compact.sh
+++ b/.claude/scripts/on-pre-compact.sh
@ -0,0 +1,8 @@
+#!/bin/bash
+# PreCompact hook: systemMessage만 지원 (hookSpecificOutput 사용 불가)
+INPUT=$(cat)
+cat <<RESP
+{
+  "systemMessage": "컨텍스트 압축이 시작됩니다. 반드시 다음을 수행하세요:\n\n1. memory/MEMORY.md - 핵심 작업 상태 갱신 (200줄 이내)\n2. memory/project-snapshot.md - 변경된 패키지/타입 정보 업데이트\n3. memory/project-history.md - 이번 세션 변경사항 추가\n4. memory/api-types.md - API 인터페이스 변경이 있었다면 갱신\n5. 미완료 작업이 있다면 TodoWrite에 남기고 memory에도 기록"
+}
+RESP
--- a/.claude/skills/create-mr/SKILL.md
+++ b/.claude/skills/create-mr/SKILL.md
@ -1,7 +1,6 @@
 ---
 name: create-mr
 description: 현재 브랜치에서 Gitea MR(Merge Request)을 생성합니다
-allowed-tools: "Bash, Read, Grep"
 argument-hint: "[target-branch: develop|main] (기본: develop)"
 ---

--- a/.claude/skills/fix-issue/SKILL.md
+++ b/.claude/skills/fix-issue/SKILL.md
@ -1,7 +1,6 @@
 ---
 name: fix-issue
 description: Gitea 이슈를 분석하고 수정 브랜치를 생성합니다
-allowed-tools: "Bash, Read, Write, Edit, Glob, Grep"
 argument-hint: "<issue-number>"
 ---

--- a/.claude/skills/init-project/SKILL.md
+++ b/.claude/skills/init-project/SKILL.md
@ -1,7 +1,6 @@
 ---
 name: init-project
 description: 팀 표준 워크플로우로 프로젝트를 초기화합니다
-allowed-tools: "Bash, Read, Write, Edit, Glob, Grep"
 argument-hint: "[project-type: java-maven|java-gradle|react-ts|auto]"
 ---

@ -22,22 +21,164 @@ $ARGUMENTS가 "auto"이거나 비어있으면 다음 순서로 감지:
 - 빌드 파일, 설정 파일, 디렉토리 구조 파악
 - 사용 중인 프레임워크, 라이브러리 감지
 - 기존 `.claude/` 디렉토리 존재 여부 확인
+- eslint, prettier, checkstyle, spotless 등 lint 도구 설치 여부 확인

 ### 2. CLAUDE.md 생성
 프로젝트 루트에 CLAUDE.md를 생성하고 다음 내용 포함:
 - 프로젝트 개요 (이름, 타입, 주요 기술 스택)
 - 빌드/실행 명령어 (감지된 빌드 도구 기반)
 - 테스트 실행 명령어
+- lint 실행 명령어 (감지된 도구 기반)
 - 프로젝트 디렉토리 구조 요약
 - 팀 컨벤션 참조 (`.claude/rules/` 안내)

-### 3. .claude/ 디렉토리 구성
-이미 팀 표준 파일이 존재하면 건너뜀. 없는 경우:
- `.claude/settings.json` — 프로젝트 타입별 표준 권한 설정
- `.claude/rules/` — 팀 규칙 파일 (team-policy, git-workflow, code-style, naming, testing)
- `.claude/skills/` — 팀 스킬 (create-mr, fix-issue, sync-team-workflow)
+### Gitea 파일 다운로드 URL 패턴
+⚠️ Gitea raw 파일은 반드시 **web raw URL**을 사용해야 합니다 (`/api/v1/` 경로 사용 불가):
+```bash
+GITEA_URL="${GITEA_URL:-https://gitea.gc-si.dev}"
+# common 파일: ${GITEA_URL}/gc/template-common/raw/branch/develop/<파일경로>
+# 타입별 파일: ${GITEA_URL}/gc/template-<타입>/raw/branch/develop/<파일경로>
+# 예시:
+curl -sf "${GITEA_URL}/gc/template-common/raw/branch/develop/.claude/rules/team-policy.md"
+curl -sf "${GITEA_URL}/gc/template-react-ts/raw/branch/develop/.editorconfig"
+```

-### 4. Git Hooks 설정
+### 3. .claude/ 디렉토리 구성
+이미 팀 표준 파일이 존재하면 건너뜀. 없는 경우 위의 URL 패턴으로 Gitea에서 다운로드:
+- `.claude/settings.json` — 프로젝트 타입별 표준 권한 설정 + env(CLAUDE_BOT_TOKEN 등) + hooks 섹션 (4단계 참조)
+
+⚠️ 팀 규칙(.claude/rules/), 에이전트(.claude/agents/), 스킬 6종, 스크립트는 12단계(sync-team-workflow)에서 자동 다운로드된다. 여기서는 settings.json만 설정한다.
+
+### 3.5. Gitea 토큰 설정
+
+**CLAUDE_BOT_TOKEN** (팀 공용): `settings.json`의 `env` 필드에 이미 포함되어 있음 (3단계에서 설정됨). 별도 조치 불필요.
+
+**GITEA_TOKEN** (개인): `/push`, `/mr`, `/release` 등 Git 스킬에 필요한 개인 토큰.
+
+```bash
+# 현재 GITEA_TOKEN 설정 여부 확인
+if [ -z "$GITEA_TOKEN" ]; then
+  echo "GITEA_TOKEN 미설정"
+fi
+```
+
+**GITEA_TOKEN이 없는 경우**, 다음 안내를 **AskUserQuestion**으로 표시:
+
+**질문**: "GITEA_TOKEN이 설정되지 않았습니다. Gitea 개인 토큰을 생성하시겠습니까?"
+- 옵션 1: 토큰 생성 안내 보기 (추천)
+- 옵션 2: 이미 있음 (토큰 입력)
+- 옵션 3: 나중에 하기
+
+**토큰 생성 안내 선택 시**, 다음 내용을 표시:
+
+```
+📋 Gitea 토큰 생성 방법:
+
+1. 브라우저에서 접속:
+   https://gitea.gc-si.dev/user/settings/applications
+
+2. "Manage Access Tokens" 섹션에서 "Generate New Token" 클릭
+
+3. 입력:
+   - Token Name: "claude-code" (자유롭게 지정)
+   - Repository and Organization Access: ✅ All (public, private, and limited)
+
+4. Select permissions (아래 4개만 설정, 나머지는 No Access 유지):
+
+   ┌─────────────────┬──────────────────┬──────────────────────────────┐
+   │ 항목             │ 권한             │ 용도                          │
+   ├─────────────────┼──────────────────┼──────────────────────────────┤
+   │ issue           │ Read and Write   │ /fix-issue 이슈 조회/코멘트   │
+   │ organization    │ Read             │ gc 조직 리포 접근              │
+   │ repository      │ Read and Write   │ /push, /mr, /release API 호출 │
+   │ user            │ Read             │ API 사용자 인증 확인           │
+   └─────────────────┴──────────────────┴──────────────────────────────┘
+
+5. "Generate Token" 클릭 → ⚠️ 토큰이 한 번만 표시됩니다! 반드시 복사하세요.
+```
+
+표시 후 **AskUserQuestion**: "생성한 토큰을 입력하세요"
+- 옵션 1: 토큰 입력 (Other로 입력)
+- 옵션 2: 나중에 하기
+
+**토큰 입력 시**:
+
+1. Gitea API로 유효성 검증:
+```bash
+curl -sf "https://gitea.gc-si.dev/api/v1/user" \
+  -H "Authorization: token <입력된 토큰>"
+```
+- 성공: `✅ <login> (<full_name>) 인증 확인` 출력
+- 실패: `❌ 토큰이 유효하지 않습니다. 다시 확인해주세요.` 출력 → 재입력 요청
+
+2. `.claude/settings.local.json`에 저장 (이 파일은 .gitignore에 포함, 리포 커밋 안됨):
+```json
+{
+  "env": {
+    "GITEA_TOKEN": "<입력된 토큰>"
+  }
+}
+```
+
+기존 `settings.local.json`이 있으면 `env.GITEA_TOKEN`만 추가/갱신.
+
+**나중에 하기 선택 시**: 경고 표시 후 다음 단계로 진행:
+```
+⚠️ GITEA_TOKEN 없이는 /push, /mr, /release 스킬을 사용할 수 없습니다.
+   나중에 토큰을 생성하면 .claude/settings.local.json에 다음을 추가하세요:
+   { "env": { "GITEA_TOKEN": "your-token-here" } }
+```
+
+### 4. Hook 스크립트 설정
+
+⚠️ `.claude/scripts/` 스크립트 파일은 12단계(sync-team-workflow)에서 서버로부터 자동 다운로드된다.
+여기서는 `settings.json`에 hooks 섹션만 설정한다.
+
+`.claude/settings.json`에 hooks 섹션이 없으면 추가 (기존 settings.json의 내용에 병합):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/on-post-compact.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/on-pre-compact.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/on-commit.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 5. Git Hooks 설정
 ```bash
 git config core.hooksPath .githooks
 ```
@ -46,7 +187,14 @@ git config core.hooksPath .githooks
 chmod +x .githooks/*
 ```

-### 5. 프로젝트 타입별 추가 설정
+**pre-commit 훅 검증**: `.githooks/pre-commit`을 실행하여 빌드 검증이 정상 동작하는지 확인.
+에러 발생 시 (예: 모노레포가 아닌 특수 구조, 빌드 명령 불일치 등):
+1. 프로젝트에 맞게 `.githooks/pre-commit`을 커스텀 수정
+2. `.claude/workflow-version.json`에 `"custom_pre_commit": true` 추가
+3. 이후 `/sync-team-workflow` 실행 시 pre-commit은 덮어쓰지 않고 보존됨
+   (`commit-msg`, `post-checkout`은 항상 팀 표준으로 동기화)
+
+### 6. 프로젝트 타입별 추가 설정

 #### java-maven
 - `.sdkmanrc` 생성 (java=17.0.18-amzn 또는 프로젝트에 맞는 버전)
@ -63,7 +211,7 @@ chmod +x .githooks/*
 - `.npmrc` Nexus 레지스트리 설정 확인
 - `npm install && npm run build` 성공 확인

-### 6. .gitignore 확인
+### 7. .gitignore 확인
 다음 항목이 .gitignore에 포함되어 있는지 확인하고, 없으면 추가:
 ```
 .claude/settings.local.json
@ -73,18 +221,75 @@ chmod +x .githooks/*
 *.local
 ```

-### 7. workflow-version.json 생성
-`.claude/workflow-version.json` 파일을 생성하여 현재 글로벌 워크플로우 버전 기록:
+**팀 워크플로우 관리 경로** (sync로 생성/관리되는 파일, 리포에 커밋하지 않음):
+```
+# Team workflow (managed by /sync-team-workflow)
+.claude/rules/
+.claude/agents/
+.claude/skills/push/
+.claude/skills/mr/
+.claude/skills/create-mr/
+.claude/skills/release/
+.claude/skills/version/
+.claude/skills/fix-issue/
+.claude/scripts/
+```
+
+### 8. Git exclude 설정
+`.git/info/exclude` 파일을 읽고, 기존 내용을 보존하면서 하단에 추가:
+
+```gitignore
+
+# Claude Code 워크플로우 (로컬 전용)
+docs/CHANGELOG.md
+*.tmp
+```
+
+### 9. Memory 초기화
+프로젝트 memory 디렉토리의 위치를 확인하고 (보통 `~/.claude/projects/<project-hash>/memory/`) 다음 파일들을 생성:
+
+- `memory/MEMORY.md` — 프로젝트 분석 결과 기반 핵심 요약 (200줄 이내)
+  - 현재 상태, 프로젝트 개요, 기술 스택, 주요 패키지 구조, 상세 참조 링크
+- `memory/project-snapshot.md` — 디렉토리 구조, 패키지 구성, 주요 의존성, API 엔드포인트
+- `memory/project-history.md` — "초기 팀 워크플로우 구성" 항목으로 시작
+- `memory/api-types.md` — 주요 인터페이스/DTO/Entity 타입 요약
+- `memory/decisions.md` — 빈 템플릿 (# 의사결정 기록)
+- `memory/debugging.md` — 빈 템플릿 (# 디버깅 경험 & 패턴)
+
+### 10. Lint 도구 확인
+- TypeScript: eslint, prettier 설치 여부 확인. 미설치 시 사용자에게 설치 제안
+- Java: checkstyle, spotless 등 설정 확인
+- CLAUDE.md에 lint 실행 명령어가 이미 기록되었는지 확인
+
+### 11. workflow-version.json 생성
+Gitea API로 최신 팀 워크플로우 버전을 조회:
+```bash
+curl -sf --max-time 5 "https://gitea.gc-si.dev/gc/template-common/raw/branch/develop/workflow-version.json"
+```
+조회 성공 시 해당 `version` 값 사용, 실패 시 "1.0.0" 기본값 사용.
+
+`.claude/workflow-version.json` 파일 생성:
 ```json
 {
-  "applied_global_version": "1.0.0",
-  "applied_date": "현재날짜",
-  "project_type": "감지된타입"
+  "applied_global_version": "<조회된 버전>",
+  "applied_date": "<현재날짜>",
+  "project_type": "<감지된타입>",
+  "gitea_url": "https://gitea.gc-si.dev"
 }
 ```

-### 8. 검증 및 요약
+### 12. 팀 워크플로우 최신화
+
+`/sync-team-workflow`를 자동으로 1회 실행하여 최신 팀 파일(rules, agents, skills 6종, scripts, hooks)을 서버에서 다운로드하고 로컬에 적용한다.
+
+이 단계에서 `.claude/rules/`, `.claude/agents/`, `.claude/skills/push/` 등 팀 관리 파일이 생성된다.
+(이 파일들은 7단계에서 .gitignore에 추가되었으므로 리포에 커밋되지 않음)
+
+### 13. 검증 및 요약
 - 생성/수정된 파일 목록 출력
 - `git config core.hooksPath` 확인
 - 빌드 명령 실행 가능 확인
- 다음 단계 안내 (개발 시작, 첫 커밋 방법 등)
+- Hook 스크립트 실행 권한 확인
+- 다음 단계 안내:
+  - 개발 시작, 첫 커밋 방법
+  - 범용 스킬: `/api-registry`, `/changelog`, `/swagger-spec`
--- a/.claude/skills/mr/SKILL.md
+++ b/.claude/skills/mr/SKILL.md
@ -0,0 +1,279 @@
+---
+name: mr
+description: 커밋 + 푸시 + Gitea MR을 한 번에 생성합니다
+user-invokable: true
+argument-hint: "[target-branch: develop|main] (기본: develop)"
+---
+
+현재 브랜치의 변경 사항을 커밋+푸시하고, Gitea에 MR을 생성합니다.
+타겟 브랜치: $ARGUMENTS (기본: develop)
+
+## 수행 단계
+
+### 0. 권한 확인
+
+```bash
+# GITEA_TOKEN 확인
+if [ -z "$GITEA_TOKEN" ]; then
+  echo "GITEA_TOKEN이 필요합니다. Gitea → Settings → Applications에서 생성하세요"
+  exit 1
+fi
+
+# Gitea API로 리포 권한 조회
+REMOTE_URL=$(git remote get-url origin)
+GITEA_HOST=$(echo "$REMOTE_URL" | sed -E 's|^https?://([^/]+)/.*|\1|')
+REPO_PATH=$(echo "$REMOTE_URL" | grep -oE '[^/]+/[^/]+\.git$' | sed 's/.git$//')
+PERMISSIONS=$(curl -sf "https://${GITEA_HOST}/api/v1/repos/${REPO_PATH}" \
+  -H "Authorization: token ${GITEA_TOKEN}")
+CAN_PUSH=$(echo "$PERMISSIONS" | python3 -c "import sys,json; print(json.load(sys.stdin)['permissions']['push'])")
+```
+
+- `CAN_PUSH`가 `False`이면: "MR 생성 권한이 필요합니다. 프로젝트 관리자에게 요청하세요." 안내 후 종료
+
+### 0.5. 팀 워크플로우 최신화 확인
+
+`.claude/workflow-version.json`이 존재하지 않으면 이 단계를 건너뛴다 (팀 프로젝트가 아닌 경우).
+
+```bash
+# 로컬 설정 읽기
+GITEA_URL=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('gitea_url', 'https://gitea.gc-si.dev'))" 2>/dev/null)
+PROJECT_TYPE=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('project_type', ''))" 2>/dev/null)
+CUSTOM_PRECOMMIT=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('custom_pre_commit', False))" 2>/dev/null)
+
+# 서버 해시 조회 (custom_pre_commit이면 pre-commit 제외 해시 사용)
+SERVER_VER=$(curl -sf --max-time 5 "${GITEA_URL}/gc/template-common/raw/branch/develop/workflow-version.json")
+if [ "$CUSTOM_PRECOMMIT" = "True" ]; then
+  SERVER_HASH=$(echo "$SERVER_VER" | python3 -c "import sys,json; print(json.load(sys.stdin).get('content_hashes_custom_precommit',{}).get('${PROJECT_TYPE}',''))" 2>/dev/null)
+else
+  SERVER_HASH=$(echo "$SERVER_VER" | python3 -c "import sys,json; print(json.load(sys.stdin).get('content_hashes',{}).get('${PROJECT_TYPE}',''))" 2>/dev/null)
+fi
+
+# 로컬 해시 계산 (custom_pre_commit이면 .githooks/pre-commit 제외)
+if [ "$CUSTOM_PRECOMMIT" = "True" ]; then
+  LOCAL_HASH=$(find .claude/rules .claude/agents .claude/scripts .githooks \
+    .claude/skills/push .claude/skills/mr .claude/skills/create-mr \
+    .claude/skills/release .claude/skills/version .claude/skills/fix-issue \
+    -type f ! -path '.githooks/pre-commit' 2>/dev/null | sort | xargs cat 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+else
+  LOCAL_HASH=$(find .claude/rules .claude/agents .claude/scripts .githooks \
+    .claude/skills/push .claude/skills/mr .claude/skills/create-mr \
+    .claude/skills/release .claude/skills/version .claude/skills/fix-issue \
+    -type f 2>/dev/null | sort | xargs cat 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+fi
+```
+
+**비교 결과 처리**:
+- **서버 조회 실패** (`SERVER_HASH` 비어있음): "⚠️ 서버 연결 불가, 워크플로우 체크를 건너뜁니다" 경고 후 다음 단계 진행
+- **일치** (`LOCAL_HASH == SERVER_HASH`): 다음 단계 진행
+- **불일치**: "⚠️ 팀 워크플로우가 최신이 아닙니다. 동기화를 실행합니다..." 출력 → **sync-team-workflow 절차를 자동 실행** → 완료 후 원래 작업 계속
+
+### 1. 사전 검증
+
+```bash
+# 현재 브랜치 확인 (main/develop이면 중단)
+BRANCH=$(git branch --show-current)
+```
+
+- 현재 브랜치가 `main` 또는 `develop`이면: "feature 브랜치에서 실행해주세요" 안내 후 종료
+
+### 2. 커밋 + 푸시 (변경 사항이 있을 때만)
+
+```bash
+git status --short
+```
+
+**커밋되지 않은 변경이 있으면**:
+- 변경 범위(파일 목록, 추가/수정/삭제) 요약 표시
+- Conventional Commits 형식 커밋 메시지 자동 생성
+- **사용자 확인** (AskUserQuestion): 커밋 메시지 수락/수정/취소
+- 수락 시: `git add -A` → `git commit` → `git push`
+
+**변경이 없으면**:
+- 이미 커밋된 내용으로 MR 생성 진행
+- 리모트에 push되지 않은 커밋이 있으면 `git push`
+
+### 3. MR 대상 브랜치 결정
+
+타겟 브랜치 후보를 분석하여 표시:
+
+```bash
+# develop과의 차이
+git log develop..HEAD --oneline 2>/dev/null
+# main과의 차이
+git log main..HEAD --oneline 2>/dev/null
+```
+
+**사용자 확인** (AskUserQuestion):
+- **질문**: "MR 타겟 브랜치를 선택하세요"
+- 옵션 1: develop (추천, N건 커밋 차이)
+- 옵션 2: main (N건 커밋 차이)
+- 옵션 3: 취소
+
+인자($ARGUMENTS)로 브랜치가 지정되었으면 확인 없이 바로 진행.
+
+### 4. RELEASE-NOTES.md 갱신 (develop 대상 MR일 때만)
+
+타겟이 `develop`일 때 릴리즈 노트를 자동 갱신한다.
+
+**4-1. 커밋 분석**
+
+```bash
+# develop 대비 현재 브랜치의 커밋 목록 (Conventional Commits 파싱)
+git log develop..HEAD --format="%s"
+```
+
+모든 커밋 타입을 타입별 섹션으로 분류:
+
+| 타입 | 섹션 |
+|------|------|
+| feat | 추가 |
+| fix | 수정 |
+| refactor, perf | 변경 |
+| docs | 문서 |
+| test | 테스트 |
+| style, chore, ci | 기타 |
+
+- 커밋 메시지에서 이슈 번호를 자동 추출하여 `(#번호)` 형태로 연결
+- 커밋 메시지의 scope는 제거하고, 설명부만 사람이 읽기 좋은 형태로 변환
+  - 예: `feat(auth): 로그인 검증 로직 추가` → `- 로그인 검증 로직 추가`
+
+**4-2. RELEASE-NOTES.md 갱신**
+
+`docs/RELEASE-NOTES.md` 파일이 없으면 새로 생성:
+
+```markdown
+# Release Notes
+
+이 문서는 [Keep a Changelog](https://keepachangelog.com/ko/1.0.0/) 형식을 따릅니다.
+
+## [Unreleased]
+```
+
+기존 파일이 있으면 `[Unreleased]` 섹션에 항목을 추가한다.
+이미 같은 내용이 있으면 중복 추가하지 않는다.
+
+**4-3. 사용자 첨삭 확인**
+
+사용자에게 릴리즈 노트 초안을 표시하고 **AskUserQuestion**으로 확인:
+- **질문**: "릴리즈 노트 초안입니다. 수정할 내용이 있으면 알려주세요."
+- 옵션 1: 이대로 진행 (추천)
+- 옵션 2: 수정 (Other 입력)
+- 옵션 3: 릴리즈 노트 생략
+
+사용자가 수정 사항을 입력하면 반영 후 커밋.
+생략을 선택하면 릴리즈 노트 변경 없이 MR 생성 진행.
+
+**4-4. 추가 커밋 + 푸시**
+
+릴리즈 노트 변경이 있으면:
+```bash
+git add docs/RELEASE-NOTES.md
+git commit -m "docs: 릴리즈 노트 업데이트"
+git push
+```
+
+### 5. MR 정보 구성
+
+```bash
+# 커밋 목록
+git log {target}..HEAD --oneline
+# 변경 파일 통계
+git diff {target}..HEAD --stat
+```
+
+- **제목**: 커밋이 1개면 커밋 메시지 사용, 여러 개면 브랜치명에서 추출
+  - `feature/ISSUE-42-user-login` → `feat: ISSUE-42 user-login`
+  - `bugfix/fix-timeout` → `fix: fix-timeout`
+- **본문**:
+  ```markdown
+  ## 변경 사항
+  - (커밋 목록 기반 자동 생성)
+
+  ## 관련 이슈
+  - closes #이슈번호 (브랜치명에서 추출, 없으면 생략)
+
+  ## 테스트
+  - [ ] 빌드 성공 확인
+  - [ ] 기존 테스트 통과
+  ```
+
+### 6. Gitea API로 MR 생성
+
+```bash
+curl -X POST "https://{host}/api/v1/repos/{owner}/{repo}/pulls" \
+  -H "Authorization: token ${GITEA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "MR 제목",
+    "body": "MR 본문",
+    "head": "현재브랜치",
+    "base": "타겟브랜치"
+  }'
+```
+
+### 7. PR 승인 + 머지 (선택)
+
+**사용자 확인** (AskUserQuestion):
+- **질문**: "MR을 어떻게 처리하시겠습니까?"
+- 옵션 1: 리뷰 대기 (추천) — MR만 생성, 리뷰어 지정 후 수동 머지
+- 옵션 2: 승인 + 머지 — claude-bot으로 즉시 승인하고 머지
+
+**승인 + 머지 선택 시**:
+
+```bash
+# CLAUDE_BOT_TOKEN 확인
+if [ -z "$CLAUDE_BOT_TOKEN" ]; then
+  echo "CLAUDE_BOT_TOKEN이 설정되지 않아 자동 승인이 불가합니다. MR만 생성합니다."
+  # MR URL 출력 후 종료
+fi
+
+# 1. claude-bot이 PR 리뷰 승인
+curl -X POST "https://{host}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews" \
+  -H "Authorization: token ${CLAUDE_BOT_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"event": "APPROVED", "body": "MR 승인 (via /mr skill)"}'
+
+# 2. 머지 실행
+curl -X POST "https://{host}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/merge" \
+  -H "Authorization: token ${GITEA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"Do": "merge", "merge_message_field": "MR 제목", "delete_branch_after_merge": true}'
+```
+
+⚠️ `delete_branch_after_merge: true` — feature 브랜치는 머지 후 삭제한다 (develop/main과 달리).
+
+### 8. 결과 출력
+
+**승인 + 머지한 경우**:
+```
+✅ MR 머지 완료
+  브랜치: feature/my-branch → develop
+  MR: https://gitea.gc-si.dev/gc/my-project/pulls/42
+  커밋: 3건, 파일: 5개 변경
+  릴리즈 노트: docs/RELEASE-NOTES.md [Unreleased] 갱신됨
+  PR 승인: claude-bot ✅
+  머지: 완료 ✅
+  브랜치 삭제: feature/my-branch ✅
+```
+
+**리뷰 대기 선택 시**:
+```
+✅ MR 생성 완료
+  브랜치: feature/my-branch → develop
+  MR: https://gitea.gc-si.dev/gc/my-project/pulls/42
+  커밋: 3건, 파일: 5개 변경
+  릴리즈 노트: docs/RELEASE-NOTES.md [Unreleased] 갱신됨
+
+  다음 단계: 리뷰어 지정 → 승인 대기 → 머지
+```
+
+## 필요 환경변수
+
+- `GITEA_TOKEN`: Gitea API 접근 토큰
+  - 없으면: "Gitea 토큰이 필요합니다. Settings → Applications에서 생성하세요" 안내
+- `CLAUDE_BOT_TOKEN`: claude-bot PR 승인용 토큰 (선택, 없으면 자동 승인 건너뜀)
+
+## 기존 /create-mr과의 차이
+
+- `/mr`: 커밋+푸시 + 릴리즈 노트 포함, 빠른 실행 (일상적 사용)
+- `/create-mr`: MR 생성만, 세부 옵션 지원 (상세 제어)
--- a/.claude/skills/push/SKILL.md
+++ b/.claude/skills/push/SKILL.md
@ -0,0 +1,148 @@
+---
+name: push
+description: 변경 사항을 확인하고 커밋 + 푸시합니다
+user-invokable: true
+argument-hint: "[commit-message] (생략 시 자동 생성)"
+---
+
+현재 브랜치의 변경 사항을 확인하고, 사용자 승인 후 커밋 + 푸시합니다.
+커밋 메시지 인자: $ARGUMENTS (생략 시 변경 내용 기반 자동 생성)
+
+## 수행 단계
+
+### 0. 권한 확인
+
+```bash
+# GITEA_TOKEN 확인
+if [ -z "$GITEA_TOKEN" ]; then
+  echo "GITEA_TOKEN이 필요합니다. Gitea → Settings → Applications에서 생성하세요"
+  exit 1
+fi
+
+# Gitea API로 리포 권한 조회
+REMOTE_URL=$(git remote get-url origin)
+GITEA_HOST=$(echo "$REMOTE_URL" | sed -E 's|^https?://([^/]+)/.*|\1|')
+REPO_PATH=$(echo "$REMOTE_URL" | grep -oE '[^/]+/[^/]+\.git$' | sed 's/.git$//')
+PERMISSIONS=$(curl -sf "https://${GITEA_HOST}/api/v1/repos/${REPO_PATH}" \
+  -H "Authorization: token ${GITEA_TOKEN}")
+CAN_PUSH=$(echo "$PERMISSIONS" | python3 -c "import sys,json; print(json.load(sys.stdin)['permissions']['push'])")
+```
+
+- `CAN_PUSH`가 `False`이면: "push 권한이 필요합니다. 프로젝트 관리자에게 요청하세요." 안내 후 종료
+
+### 0.5. 팀 워크플로우 최신화 확인
+
+`.claude/workflow-version.json`이 존재하지 않으면 이 단계를 건너뛴다 (팀 프로젝트가 아닌 경우).
+
+```bash
+# 로컬 설정 읽기
+GITEA_URL=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('gitea_url', 'https://gitea.gc-si.dev'))" 2>/dev/null)
+PROJECT_TYPE=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('project_type', ''))" 2>/dev/null)
+CUSTOM_PRECOMMIT=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('custom_pre_commit', False))" 2>/dev/null)
+
+# 서버 해시 조회 (custom_pre_commit이면 pre-commit 제외 해시 사용)
+SERVER_VER=$(curl -sf --max-time 5 "${GITEA_URL}/gc/template-common/raw/branch/develop/workflow-version.json")
+if [ "$CUSTOM_PRECOMMIT" = "True" ]; then
+  SERVER_HASH=$(echo "$SERVER_VER" | python3 -c "import sys,json; print(json.load(sys.stdin).get('content_hashes_custom_precommit',{}).get('${PROJECT_TYPE}',''))" 2>/dev/null)
+else
+  SERVER_HASH=$(echo "$SERVER_VER" | python3 -c "import sys,json; print(json.load(sys.stdin).get('content_hashes',{}).get('${PROJECT_TYPE}',''))" 2>/dev/null)
+fi
+
+# 로컬 해시 계산 (custom_pre_commit이면 .githooks/pre-commit 제외)
+if [ "$CUSTOM_PRECOMMIT" = "True" ]; then
+  LOCAL_HASH=$(find .claude/rules .claude/agents .claude/scripts .githooks \
+    .claude/skills/push .claude/skills/mr .claude/skills/create-mr \
+    .claude/skills/release .claude/skills/version .claude/skills/fix-issue \
+    -type f ! -path '.githooks/pre-commit' 2>/dev/null | sort | xargs cat 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+else
+  LOCAL_HASH=$(find .claude/rules .claude/agents .claude/scripts .githooks \
+    .claude/skills/push .claude/skills/mr .claude/skills/create-mr \
+    .claude/skills/release .claude/skills/version .claude/skills/fix-issue \
+    -type f 2>/dev/null | sort | xargs cat 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+fi
+```
+
+**비교 결과 처리**:
+- **서버 조회 실패** (`SERVER_HASH` 비어있음): "⚠️ 서버 연결 불가, 워크플로우 체크를 건너뜁니다" 경고 후 다음 단계 진행
+- **일치** (`LOCAL_HASH == SERVER_HASH`): 다음 단계 진행
+- **불일치**: "⚠️ 팀 워크플로우가 최신이 아닙니다. 동기화를 실행합니다..." 출력 → **sync-team-workflow 절차를 자동 실행** → 완료 후 원래 작업 계속
+
+### 1. 현재 상태 수집
+
+```bash
+# 현재 브랜치
+git branch --show-current
+
+# 커밋되지 않은 변경 사항
+git status --short
+
+# 변경 통계
+git diff --stat
+git diff --cached --stat
+```
+
+### 2. 변경 범위 표시
+
+사용자에게 다음 정보를 **표 형태**로 요약하여 보여준다:
+
+- 현재 브랜치명
+- 변경된 파일 목록 (추가/수정/삭제 구분)
+- staged vs unstaged 구분
+- 변경 라인 수 요약
+
+변경 사항이 없으면 "커밋할 변경 사항이 없습니다" 출력 후 종료.
+
+### 3. 커밋 메시지 결정
+
+**인자가 있는 경우** ($ARGUMENTS가 비어있지 않으면):
+- 전달받은 메시지를 커밋 메시지로 사용
+- Conventional Commits 형식인지 검증 (아니면 자동 보정 제안)
+
+**인자가 없는 경우**:
+- 변경 내용을 분석하여 Conventional Commits 형식 메시지 자동 생성
+- 형식: `type(scope): 한국어 설명`
+- type 판단 기준:
+  - 새 파일 추가 → `feat`
+  - 기존 파일 수정 → `fix` 또는 `refactor`
+  - 테스트 파일 → `test`
+  - 설정/빌드 파일 → `chore`
+  - 문서 파일 → `docs`
+
+### 4. 사용자 확인
+
+AskUserQuestion으로 다음을 확인:
+
+**질문**: "다음 내용으로 커밋하시겠습니까?"
+- 옵션 1: 제안된 메시지로 커밋 (추천)
+- 옵션 2: 메시지 수정 (Other 입력)
+- 옵션 3: 취소
+
+### 5. 커밋 + 푸시 실행
+
+사용자가 수락하면:
+
+```bash
+# 모든 변경 사항 스테이징 (untracked 포함)
+# 단, .env, secrets/ 등 민감 파일은 제외
+git add -A
+
+# 커밋 (.githooks/commit-msg가 형식 검증)
+git commit -m "커밋메시지"
+
+# 푸시 (리모트 트래킹 없으면 -u 추가)
+git push origin $(git branch --show-current)
+```
+
+**주의사항**:
+- `git add` 전에 `.env`, `*.key`, `secrets/` 등 민감 파일이 포함되어 있으면 경고
+- pre-commit hook 실패 시 에러 메시지 표시 후 수동 해결 안내
+- 리모트에 브랜치가 없으면 `git push -u origin {branch}` 사용
+
+### 6. 결과 출력
+
+```
+✅ 푸시 완료
+  브랜치: feature/my-branch
+  커밋: abc1234 feat(auth): 로그인 검증 로직 추가
+  변경: 3 files changed, 45 insertions(+), 12 deletions(-)
+```
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@ -0,0 +1,233 @@
+---
+name: release
+description: develop에서 main으로 릴리즈 MR을 생성합니다
+user-invokable: true
+---
+
+develop 브랜치와 원격 동기화를 확인하고, 릴리즈 노트를 정리하고, develop → main 릴리즈 MR을 생성합니다.
+사용자 승인 시 claude-bot으로 PR 승인 + 머지까지 자동 처리합니다.
+
+## 수행 단계
+
+### 0. 권한 확인
+
+```bash
+# GITEA_TOKEN 확인
+if [ -z "$GITEA_TOKEN" ]; then
+  echo "GITEA_TOKEN이 필요합니다. Gitea → Settings → Applications에서 생성하세요"
+  exit 1
+fi
+
+# Gitea API로 리포 권한 조회
+REMOTE_URL=$(git remote get-url origin)
+GITEA_HOST=$(echo "$REMOTE_URL" | sed -E 's|^https?://([^/]+)/.*|\1|')
+REPO_PATH=$(echo "$REMOTE_URL" | grep -oE '[^/]+/[^/]+\.git$' | sed 's/.git$//')
+PERMISSIONS=$(curl -sf "https://${GITEA_HOST}/api/v1/repos/${REPO_PATH}" \
+  -H "Authorization: token ${GITEA_TOKEN}")
+IS_ADMIN=$(echo "$PERMISSIONS" | python3 -c "import sys,json; print(json.load(sys.stdin)['permissions']['admin'])")
+```
+
+- `IS_ADMIN`이 `False`이면: "릴리즈는 프로젝트 관리자만 실행할 수 있습니다." 안내 후 종료
+
+### 0.5. 팀 워크플로우 최신화 확인
+
+`.claude/workflow-version.json`이 존재하지 않으면 이 단계를 건너뛴다 (팀 프로젝트가 아닌 경우).
+
+```bash
+# 로컬 설정 읽기
+GITEA_URL=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('gitea_url', 'https://gitea.gc-si.dev'))" 2>/dev/null)
+PROJECT_TYPE=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('project_type', ''))" 2>/dev/null)
+CUSTOM_PRECOMMIT=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('custom_pre_commit', False))" 2>/dev/null)
+
+# 서버 해시 조회 (custom_pre_commit이면 pre-commit 제외 해시 사용)
+SERVER_VER=$(curl -sf --max-time 5 "${GITEA_URL}/gc/template-common/raw/branch/develop/workflow-version.json")
+if [ "$CUSTOM_PRECOMMIT" = "True" ]; then
+  SERVER_HASH=$(echo "$SERVER_VER" | python3 -c "import sys,json; print(json.load(sys.stdin).get('content_hashes_custom_precommit',{}).get('${PROJECT_TYPE}',''))" 2>/dev/null)
+else
+  SERVER_HASH=$(echo "$SERVER_VER" | python3 -c "import sys,json; print(json.load(sys.stdin).get('content_hashes',{}).get('${PROJECT_TYPE}',''))" 2>/dev/null)
+fi
+
+# 로컬 해시 계산 (custom_pre_commit이면 .githooks/pre-commit 제외)
+if [ "$CUSTOM_PRECOMMIT" = "True" ]; then
+  LOCAL_HASH=$(find .claude/rules .claude/agents .claude/scripts .githooks \
+    .claude/skills/push .claude/skills/mr .claude/skills/create-mr \
+    .claude/skills/release .claude/skills/version .claude/skills/fix-issue \
+    -type f ! -path '.githooks/pre-commit' 2>/dev/null | sort | xargs cat 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+else
+  LOCAL_HASH=$(find .claude/rules .claude/agents .claude/scripts .githooks \
+    .claude/skills/push .claude/skills/mr .claude/skills/create-mr \
+    .claude/skills/release .claude/skills/version .claude/skills/fix-issue \
+    -type f 2>/dev/null | sort | xargs cat 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+fi
+```
+
+**비교 결과 처리**:
+- **서버 조회 실패** (`SERVER_HASH` 비어있음): "⚠️ 서버 연결 불가, 워크플로우 체크를 건너뜁니다" 경고 후 다음 단계 진행
+- **일치** (`LOCAL_HASH == SERVER_HASH`): 다음 단계 진행
+- **불일치**: "⚠️ 팀 워크플로우가 최신이 아닙니다. 동기화를 실행합니다..." 출력 → **sync-team-workflow 절차를 자동 실행** → 완료 후 원래 작업 계속
+
+### 1. 사전 검증
+
+- 커밋되지 않은 변경 사항이 있으면 경고 ("먼저 /push로 커밋하세요")
+
+### 2. develop 브랜치 동기화 확인
+
+```bash
+git fetch origin
+LOCAL=$(git rev-parse develop 2>/dev/null)
+REMOTE=$(git rev-parse origin/develop 2>/dev/null)
+BASE=$(git merge-base develop origin/develop 2>/dev/null)
+```
+
+| 상태 | 조건 | 행동 |
+|------|------|------|
+| 동일 | LOCAL == REMOTE | 바로 진행 |
+| 로컬 뒤처짐 | LOCAL == BASE, LOCAL != REMOTE | "origin/develop에 새 커밋이 있습니다. `git pull origin develop` 후 다시 시도하세요" |
+| 로컬 앞섬 | REMOTE == BASE, LOCAL != REMOTE | "push되지 않은 커밋이 있습니다" → 사용자 확인 후 push |
+| 분기됨 | 그 외 | "분기되었습니다. 수동으로 해결해주세요" |
+
+### 3. develop → main 차이 분석
+
+```bash
+git log main..origin/develop --oneline
+git diff main..origin/develop --stat
+git rev-list --count main..origin/develop
+```
+
+차이가 없으면 "릴리즈할 변경이 없습니다" 출력 후 종료.
+
+### 4. 미기록 커밋 감지
+
+`docs/RELEASE-NOTES.md`에 기록되지 않은 커밋이 있는지 확인:
+
+```bash
+# develop의 커밋 중 RELEASE-NOTES.md에 언급되지 않은 feat/fix 커밋 추출
+git log main..origin/develop --format="%s" | grep -E "^(feat|fix|refactor|perf|docs|test|style|chore|ci)"
+```
+
+- 릴리즈 노트의 [Unreleased] + 날짜 릴리즈 항목과 비교
+- 미기록 커밋이 있으면 경고 표시 + 보충 기회 제공
+  - 사용자에게 미기록 커밋 목록 표시
+  - [Unreleased]에 추가할지 확인
+
+### 5. 이전 날짜 넘버링 릴리즈 압축
+
+`docs/RELEASE-NOTES.md`에서 **오늘 이전 날짜에 넘버링된 릴리즈**가 있으면 압축:
+
+```
+[2026-02-28.1] + [2026-02-28.2] → [2026-02-28]
+```
+
+압축 규칙:
+- 같은 기능의 반복 수정 → 최종 상태만 유지
+- 추가 후 수정된 항목 → "추가" 섹션에 최종 상태로 합침
+- 추가 후 제거된 항목 → 양쪽 모두에서 삭제
+- 오늘 날짜의 넘버링은 유지 (압축 대상 아님)
+
+### 6. [Unreleased] → 날짜 버전 전환
+
+```
+## [Unreleased]    →    ## [2026-03-01] 또는 ## [2026-03-01.2]
+```
+
+- 같은 날 이전 릴리즈가 있으면 순번 부여: `.1`, `.2`, `.3`
+- [Unreleased]는 빈 섹션으로 다시 생성
+
+### 7. 사용자 첨삭 확인
+
+최종 릴리즈 노트를 표시하고 **AskUserQuestion**으로 확인:
+- **질문**: "릴리즈 노트 최종 초안입니다. 수정할 내용이 있으면 알려주세요."
+- 옵션 1: 이대로 진행 (추천)
+- 옵션 2: 수정 (Other 입력)
+
+### 8. develop 커밋 + 푸시
+
+```bash
+git checkout develop
+git add docs/RELEASE-NOTES.md
+git commit -m "docs: 릴리즈 노트 정리 ($(date +%Y-%m-%d))"
+git push origin develop
+```
+
+### 9. MR 정보 구성 + 생성
+
+**제목**: `release: YYYY-MM-DD (N건 커밋)`
+
+**본문**: 릴리즈 노트 내용 포함 (커밋 type별 그룹핑)
+
+```bash
+curl -X POST "https://{host}/api/v1/repos/{owner}/{repo}/pulls" \
+  -H "Authorization: token ${GITEA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "release: 2026-03-01 (12건 커밋)",
+    "body": "릴리즈 본문 (RELEASE-NOTES.md 내용 포함)",
+    "head": "develop",
+    "base": "main"
+  }'
+```
+
+### 10. PR 승인 + 머지 (선택)
+
+**사용자 확인** (AskUserQuestion):
+- **질문**: "MR을 승인하고 머지하시겠습니까?"
+- 옵션 1: 승인 + 머지 (추천)
+- 옵션 2: MR만 생성 (수동 리뷰/머지)
+
+**승인 + 머지 선택 시**:
+
+```bash
+# CLAUDE_BOT_TOKEN 확인
+if [ -z "$CLAUDE_BOT_TOKEN" ]; then
+  echo "CLAUDE_BOT_TOKEN이 설정되지 않아 자동 승인이 불가합니다. MR만 생성합니다."
+  # MR URL 출력 후 종료
+fi
+
+# 1. claude-bot이 PR 리뷰 승인
+curl -X POST "https://{host}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews" \
+  -H "Authorization: token ${CLAUDE_BOT_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"event": "APPROVED", "body": "릴리즈 승인 (via /release skill)"}'
+
+# 2. 머지 실행
+curl -X POST "https://{host}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/merge" \
+  -H "Authorization: token ${GITEA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"Do": "merge", "merge_message_field": "release: YYYY-MM-DD", "delete_branch_after_merge": false}'
+```
+
+⚠️ `delete_branch_after_merge: false` — develop 브랜치는 삭제하지 않는다.
+
+### 11. 결과 출력
+
+```
+✅ 릴리즈 완료
+  브랜치: develop → main
+  MR: https://gitea.gc-si.dev/gc/my-project/pulls/50
+  커밋: 12건, 파일: 28개 변경
+  릴리즈 노트: [2026-03-01] 생성됨
+  PR 승인: claude-bot ✅
+  머지: 완료 ✅
+  CI/CD: 자동 배포 시작됨
+
+  다음 단계: CI/CD 배포 결과 확인
+```
+
+또는 MR만 생성한 경우:
+
+```
+✅ 릴리즈 MR 생성 완료
+  브랜치: develop → main
+  MR: https://gitea.gc-si.dev/gc/my-project/pulls/50
+  릴리즈 노트: [2026-03-01] 생성됨
+
+  다음 단계:
+  1. 리뷰어 지정 (main 브랜치는 1명 이상 리뷰 필수)
+  2. 승인 후 머지
+  3. CI/CD 자동 배포 확인
+```
+
+## 필요 환경변수
+
+- `GITEA_TOKEN`: Gitea API 접근 토큰 (필수)
+- `CLAUDE_BOT_TOKEN`: claude-bot PR 승인용 토큰 (선택, 없으면 자동 승인 건너뜀)
--- a/.claude/skills/sync-team-workflow/SKILL.md
+++ b/.claude/skills/sync-team-workflow/SKILL.md
@ -1,73 +1,165 @@
 ---
 name: sync-team-workflow
 description: 팀 글로벌 워크플로우를 현재 프로젝트에 동기화합니다
-allowed-tools: "Bash, Read, Write, Edit, Glob, Grep"
 ---

-팀 글로벌 워크플로우의 최신 버전을 현재 프로젝트에 적용합니다.
+팀 글로벌 워크플로우의 최신 파일을 서버에서 다운로드하여 로컬에 적용합니다.
+호출 시 항상 서버 기준으로 전체 동기화합니다 (버전 비교 없음).

 ## 수행 절차

-### 1. 글로벌 버전 조회
-Gitea API로 template-common 리포의 workflow-version.json 조회:
-```bash
-GITEA_URL=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('gitea_url', 'http://211.208.115.83:3000'))" 2>/dev/null || echo "http://211.208.115.83:3000")
+### 1. 사전 조건 확인

-curl -sf "${GITEA_URL}/api/v1/repos/gcsc/template-common/raw/workflow-version.json"
+`.claude/workflow-version.json` 존재 확인:
+- 없으면 → "/init-project를 먼저 실행해주세요" 안내 후 종료
+
+설정 읽기:
+```bash
+GITEA_URL=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('gitea_url', 'https://gitea.gc-si.dev'))" 2>/dev/null || echo "https://gitea.gc-si.dev")
+PROJECT_TYPE=$(python3 -c "import json; print(json.load(open('.claude/workflow-version.json')).get('project_type', ''))" 2>/dev/null || echo "")
 ```

-### 2. 버전 비교
-로컬 `.claude/workflow-version.json`과 비교:
- 버전 일치 → "최신 버전입니다" 안내 후 종료
- 버전 불일치 → 미적용 변경 항목 추출하여 표시
+프로젝트 타입이 비어있으면 자동 감지:
+1. `pom.xml` → java-maven
+2. `build.gradle` / `build.gradle.kts` → java-gradle
+3. `package.json` + `tsconfig.json` → react-ts
+4. 감지 실패 → 사용자에게 선택 요청

-### 3. 프로젝트 타입 감지
-자동 감지 순서:
-1. `.claude/workflow-version.json`의 `project_type` 필드 확인
-2. 없으면: `pom.xml` → java-maven, `build.gradle` → java-gradle, `package.json` → react-ts
+### Gitea 파일 다운로드 URL 패턴
+⚠️ Gitea raw 파일은 반드시 **web raw URL** 사용:
+```bash
+# common 파일: ${GITEA_URL}/gc/template-common/raw/branch/develop/<파일경로>
+# 타입별 파일: ${GITEA_URL}/gc/template-${PROJECT_TYPE}/raw/branch/develop/<파일경로>
+```

-### 4. 파일 다운로드 및 적용
-Gitea API로 해당 타입 + common 템플릿 파일 다운로드:
+### 2. 디렉토리 준비

-#### 4-1. 규칙 파일 (덮어쓰기)
-팀 규칙은 로컬 수정 불가 — 항상 글로벌 최신으로 교체:
+필요한 디렉토리가 없으면 생성:
+```bash
+mkdir -p .claude/rules .claude/agents .claude/scripts
+mkdir -p .claude/skills/push .claude/skills/mr .claude/skills/create-mr
+mkdir -p .claude/skills/release .claude/skills/version .claude/skills/fix-issue
+mkdir -p .githooks
+```
+
+### 3. 서버 파일 다운로드 + 적용
+
+각 파일을 `curl -sf` 로 다운로드하여 프로젝트 루트의 동일 경로에 저장.
+다운로드 실패한 파일은 경고 출력 후 건너뜀.
+
+#### 3-1. template-common 파일 (덮어쓰기)
+
+**규칙 파일**:
 ```
 .claude/rules/team-policy.md
 .claude/rules/git-workflow.md
-.claude/rules/code-style.md    (타입별)
-.claude/rules/naming.md        (타입별)
-.claude/rules/testing.md       (타입별)
+.claude/rules/release-notes-guide.md
+.claude/rules/subagent-policy.md
 ```

-#### 4-2. settings.json (부분 갱신)
- `deny` 목록: 글로벌 최신으로 교체
- `allow` 목록: 기존 사용자 커스텀 유지 + 글로벌 기본값 병합
- `hooks`: 글로벌 최신으로 교체
-
-#### 4-3. 스킬 파일 (덮어쓰기)
+**에이전트 파일**:
 ```
+.claude/agents/explorer.md
+.claude/agents/implementer.md
+.claude/agents/reviewer.md
+```
+
+**스킬 파일 (6종)**:
+```
+.claude/skills/push/SKILL.md
+.claude/skills/mr/SKILL.md
 .claude/skills/create-mr/SKILL.md
+.claude/skills/release/SKILL.md
+.claude/skills/version/SKILL.md
 .claude/skills/fix-issue/SKILL.md
-.claude/skills/sync-team-workflow/SKILL.md
 ```

-#### 4-4. Git Hooks (덮어쓰기 + 실행 권한)
+**Hook 스크립트**:
+```
+.claude/scripts/on-pre-compact.sh
+.claude/scripts/on-post-compact.sh
+.claude/scripts/on-commit.sh
+```
+
+**Git Hooks** (commit-msg, post-checkout은 항상 교체):
+```
+.githooks/commit-msg
+.githooks/post-checkout
+```
+
+다운로드 예시:
 ```bash
-chmod +x .githooks/*
+curl -sf "${GITEA_URL}/gc/template-common/raw/branch/develop/.claude/rules/team-policy.md" -o ".claude/rules/team-policy.md"
 ```

-### 5. 로컬 버전 업데이트
-`.claude/workflow-version.json` 갱신:
+#### 3-2. template-{type} 파일 (타입별 덮어쓰기)
+
+```
+.claude/rules/code-style.md
+.claude/rules/naming.md
+.claude/rules/testing.md
+```
+
+**pre-commit hook**:
+`.claude/workflow-version.json`의 `custom_pre_commit` 플래그 확인:
+- `"custom_pre_commit": true` → pre-commit 건너뜀, "⚠️ pre-commit은 프로젝트 커스텀 유지" 로그
+- 플래그 없거나 false → `.githooks/pre-commit` 교체
+
+다운로드 예시:
+```bash
+curl -sf "${GITEA_URL}/gc/template-${PROJECT_TYPE}/raw/branch/develop/.claude/rules/code-style.md" -o ".claude/rules/code-style.md"
+```
+
+#### 3-3. 실행 권한 부여
+```bash
+chmod +x .githooks/* 2>/dev/null
+chmod +x .claude/scripts/*.sh 2>/dev/null
+```
+
+### 4. settings.json 부분 머지
+
+⚠️ settings.json은 **타입별 템플릿**에서 다운로드 (template-common에는 없음):
+```bash
+SERVER_SETTINGS=$(curl -sf "${GITEA_URL}/gc/template-${PROJECT_TYPE}/raw/branch/develop/.claude/settings.json")
+```
+
+다운로드한 최신 settings.json과 로컬 `.claude/settings.json`을 비교하여 부분 갱신:
+- `env`: 서버 최신으로 교체
+- `deny` 목록: 서버 최신으로 교체
+- `allow` 목록: 기존 사용자 커스텀 유지 + 서버 기본값 병합
+- `hooks`: 서버 최신으로 교체
+
+### 5. workflow-version.json 갱신
+
+서버의 최신 `workflow-version.json` 조회:
+```bash
+SERVER_VER=$(curl -sf "${GITEA_URL}/gc/template-common/raw/branch/develop/workflow-version.json")
+SERVER_VERSION=$(echo "$SERVER_VER" | python3 -c "import sys,json; print(json.load(sys.stdin).get('version',''))")
+```
+
+`.claude/workflow-version.json` 업데이트:
 ```json
 {
-  "applied_global_version": "새버전",
-  "applied_date": "오늘날짜",
-  "project_type": "감지된타입"
+  "applied_global_version": "<서버 version>",
+  "applied_date": "<현재날짜>",
+  "project_type": "<프로젝트타입>",
+  "gitea_url": "<GITEA_URL>"
 }
 ```
+기존 필드(`custom_pre_commit` 등)는 보존.

 ### 6. 변경 보고
- `git diff`로 변경 내역 확인
- 업데이트된 파일 목록 출력
- 변경 로그(글로벌 workflow-version.json의 changes) 표시
- 필요한 추가 조치 안내 (빌드 확인, 의존성 업데이트 등)
+
+- 다운로드/갱신된 파일 목록 출력
+- 서버 `workflow-version.json`의 `changes` 중 최신 항목 표시
+- 결과 형태:
+```
+✅ 팀 워크플로우 동기화 완료
+  버전: v1.6.0
+  갱신 파일: 22개 (rules 7, agents 3, skills 6, scripts 3, hooks 3)
+  settings.json: 부분 갱신 (env, deny, hooks)
+```
+
+## 필요 환경변수
+
+없음 (Gitea raw URL은 인증 불필요)
--- a/.claude/skills/version/SKILL.md
+++ b/.claude/skills/version/SKILL.md
@ -0,0 +1,124 @@
+---
+name: version
+description: RELEASE-NOTES.md 기반으로 버저닝 릴리즈 노트(VERSION-HISTORY.md)를 생성합니다
+user-invokable: true
+argument-hint: "[version: 1.0.0] (생략 시 자동 결정)"
+---
+
+`docs/RELEASE-NOTES.md`의 내부 릴리즈 노트를 기반으로
+사용자 관점의 `docs/VERSION-HISTORY.md`를 생성/갱신합니다.
+버전: $ARGUMENTS (생략 시 변경 타입에 따라 자동 결정)
+
+## 수행 단계
+
+### 0. 권한 확인
+
+```bash
+REMOTE_URL=$(git remote get-url origin)
+GITEA_HOST=$(echo "$REMOTE_URL" | sed -E 's|^https?://([^/]+)/.*|\1|')
+REPO_PATH=$(echo "$REMOTE_URL" | grep -oE '[^/]+/[^/]+\.git$' | sed 's/.git$//')
+PERMISSIONS=$(curl -sf "https://${GITEA_HOST}/api/v1/repos/${REPO_PATH}" \
+  -H "Authorization: token ${GITEA_TOKEN}")
+IS_ADMIN=$(echo "$PERMISSIONS" | python3 -c "import sys,json; print(json.load(sys.stdin)['permissions']['admin'])")
+```
+
+- `IS_ADMIN`이 `False`이면: "버전 릴리즈는 프로젝트 관리자만 실행할 수 있습니다." 안내 후 종료
+- `GITEA_TOKEN` 미설정: 설정 안내 후 종료
+
+### 1. RELEASE-NOTES.md 분석
+
+`docs/RELEASE-NOTES.md`가 없으면 종료: "RELEASE-NOTES.md가 없습니다. 먼저 /mr로 릴리즈 노트를 생성하세요."
+
+```bash
+cat docs/RELEASE-NOTES.md
+```
+
+### 2. 수집 범위 결정
+
+- `docs/VERSION-HISTORY.md`가 있으면: 마지막 버전의 날짜를 확인
+- 해당 날짜 이후의 RELEASE-NOTES.md 항목을 수집
+- VERSION-HISTORY.md가 없으면: 전체 RELEASE-NOTES.md 항목 수집
+
+### 3. 버전 결정
+
+**인자가 있으면** ($ARGUMENTS): 해당 버전 사용
+
+**인자가 없으면** 자동 결정:
+- `feat` 포함 → minor 버전 올림 (x.Y.0)
+- `fix`만 → patch 버전 올림 (x.y.Z)
+- breaking change 포함 → major 버전 올림 (X.0.0)
+- 이전 버전이 없으면 `1.0.0`부터 시작
+
+### 4. 사용자 관점으로 재작성
+
+수집된 항목을 다음 섹션으로 재구성:
+
+| 섹션 | 포함 기준 |
+|------|----------|
+| **주요 변경** | 사용자가 눈에 띄게 느낄 수 있는 기능 (feat 중 UI/UX 영향 큰 것) |
+| **개선** | 성능/편의성 향상 (refactor, perf, 사소한 feat) |
+| **버그 수정** | 사용자 영향 있는 문제 해결 |
+| **보안** | 보안 관련 수정 (해당 시) |
+
+변환 규칙:
+- 기술 용어 → 사용자 언어로 재작성
+- 관련 항목 그룹핑 (여러 커밋이 하나의 기능이면 합침)
+- docs, test, chore, ci 등 사용자에게 보이지 않는 변경은 제외
+- 각 항목은 사용자가 "이게 뭐가 바뀐 거지?" 이해할 수 있는 수준으로
+
+### 5. 초안 표시 + 첨삭 확인
+
+초안을 표시하고 **AskUserQuestion**으로 확인:
+- **질문**: "VERSION-HISTORY.md 초안입니다. 수정할 내용이 있으면 알려주세요."
+- 옵션 1: 이대로 진행 (추천)
+- 옵션 2: 수정 (Other 입력)
+
+### 6. VERSION-HISTORY.md 갱신
+
+파일이 없으면 새로 생성:
+
+```markdown
+# Version History
+
+이 프로젝트는 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
+```
+
+새 버전을 기존 내용 위에 추가:
+
+```markdown
+## [1.2.0] - 2026-03-01
+
+### 주요 변경
+- **해역별 조업 현황 대시보드 추가**: 지도에서 해역을 선택하면 실시간 조업 통계를 확인할 수 있습니다
+
+### 개선
+- 지도 레이어 전환 속도 향상
+
+### 버그 수정
+- 야간 배치 실행 시 타임아웃 발생하던 문제 수정
+
+> 내부 릴리즈: 2026-02-28 ~ 2026-03-01 (3건)
+```
+
+마지막 줄에 참조한 내부 릴리즈 날짜 범위와 건수를 표시.
+
+### 7. 커밋
+
+```bash
+git add docs/VERSION-HISTORY.md
+git commit -m "docs: v$VERSION 릴리즈 노트 작성"
+git push
+```
+
+### 8. 결과 출력
+
+```
+✅ 버전 릴리즈 노트 작성 완료
+  버전: 1.2.0
+  파일: docs/VERSION-HISTORY.md
+  기반: RELEASE-NOTES.md (2026-02-28 ~ 2026-03-01, 3건)
+```
+
+## 필요 환경변수
+
+- `GITEA_TOKEN`: Gitea API 접근 토큰 (필수)
--- a/.gitignore
+++ b/.gitignore
@ -35,6 +35,14 @@ application-local.properties
 .env.*
 secrets/

+# === Frontend ===
+frontend/node_modules/
+frontend/node/
+frontend/dist/
+
+# === Generated static assets (built by frontend) ===
+src/main/resources/static/
+
 # === Claude Code (개인 설정) ===
 .claude/settings.local.json
 .claude/CLAUDE.local.md
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -1,53 +1,72 @@
-# 프로젝트 개요
+# SNP Connection Monitoring

- **타입**: Java + Spring Boot + Maven
- **JDK**: 17 (`.sdkmanrc` 참조)
- **프레임워크**: Spring Boot
- **빌드 도구**: Maven (Maven Wrapper 사용)
+API Gateway + 모니터링 통합 플랫폼. 모든 서비스 사용자가 모니터링 애플리케이션에 데이터를 요청할 때 API 인증키를 통해 인증하고, 모든 요청/응답 데이터를 추적/관리하는 서비스.
+
+## 기술 스택
+- Java 17, Spring Boot 3.2.1, Spring Data JPA
+- PostgreSQL (스키마: std_snp_connection)
+- Spring Security (JWT 기반 인증 예정)
+- WebFlux WebClient (Heartbeat, Gateway Proxy)
+- Springdoc OpenAPI 2.3.0 (Swagger)
+- Lombok
+- Frontend: React 19 + TypeScript + Vite + Tailwind CSS 4

 ## 빌드 및 실행

 ```bash
-# 빌드
-./mvnw clean compile
+# 프론트엔드 빌드 (별도)
+cd frontend && npm install && npm run build && cd ..

-# 패키징
+# 백엔드 빌드 (프론트엔드 자동 빌드 포함)
 ./mvnw clean package -DskipTests

-# 테스트
-./mvnw test
-
-# 특정 테스트 클래스 실행
-./mvnw test -Dtest=클래스명
-
 # 로컬 실행
 ./mvnw spring-boot:run

-# 린트 (Checkstyle 설정된 경우)
-./mvnw checkstyle:check
+# 테스트
+./mvnw test
+
+# 프론트엔드 개발 서버
+cd frontend && npm run dev
 ```

-## 프로젝트 구조
+**주의**: frontend-maven-plugin의 Node 호환성 문제로, 프론트엔드와 백엔드를 분리하여 빌드합니다.
+
+## 서버 설정
+- 포트: 8042
+- Context Path: /snp-connection
+- Swagger UI: http://localhost:8042/snp-connection/swagger-ui/index.html
+- 프론트엔드 개발 서버: http://localhost:5173/snp-connection/
+
+## 디렉토리 구조

 ```
-src/
-├── main/
-│   ├── java/
-│   │   └── com/gcsc/{프로젝트}/
-│   │       ├── config/          # 설정 클래스
-│   │       ├── controller/      # REST 컨트롤러
-│   │       ├── service/         # 비즈니스 로직
-│   │       ├── repository/      # 데이터 접근
-│   │       ├── domain/          # 엔티티
-│   │       ├── dto/             # 데이터 전송 객체
-│   │       ├── exception/       # 예외 처리
-│   │       └── util/            # 유틸리티
-│   └── resources/
-│       ├── application.yml      # 공통 설정
-│       ├── application-local.yml # 로컬 설정 (.gitignore)
-│       └── application-prod.yml  # 운영 설정
-└── test/
-    └── java/                    # 테스트 코드
+snp-connection-monitoring/
+├── pom.xml                            # Maven 설정 (frontend-maven-plugin 포함)
+├── frontend/                          # React + TypeScript 프론트엔드
+│   ├── package.json
+│   ├── vite.config.ts                 # Vite 빌드 설정 (output → ../src/main/resources/static)
+│   ├── tsconfig.json
+│   ├── index.html
+│   └── src/
+│       ├── main.tsx                   # React 엔트리 포인트
+│       ├── App.tsx                    # 루트 컴포넌트 (라우팅)
+│       ├── index.css                  # 글로벌 스타일 (Tailwind)
+│       ├── pages/                     # 페이지 컴포넌트
+│       ├── components/                # 재사용 가능 컴포넌트
+│       ├── hooks/                     # 커스텀 훅
+│       ├── services/                  # API 호출 모듈
+│       ├── store/                     # 상태 관리
+│       ├── types/                     # TypeScript 타입 정의
+│       └── utils/                     # 유틸리티 함수
+├── src/main/java/com/gcsc/connection/
+│   ├── SnpConnectionApplication.java  # 메인 애플리케이션
+│   ├── config/                        # 설정 클래스
+│   ├── common/                        # 공통 모듈 (ApiResponse, Exception)
+│   └── global/                        # 글로벌 컨트롤러 (WebViewController)
+└── src/main/resources/
+    ├── application.yml                # 공통 설정
+    └── static/                        # 프론트엔드 빌드 결과물 (자동 생성)
 ```

 ## 팀 규칙
@ -60,6 +79,5 @@ src/

 ## 의존성 관리

- Nexus 프록시 레포지토리를 통해 의존성 관리 (`.mvn/settings.xml`)
- 새 의존성 추가 시 `pom.xml`에 버전 명시
- Spring Boot BOM 범위 내 의존성은 버전 생략 가능
+- Maven: Nexus 프록시 레포지토리 (`.mvn/settings.xml`)
+- npm: Nexus npm 프록시 레지스트리 (`frontend/.npmrc`)
--- a/docs/RELEASE-NOTES.md
+++ b/docs/RELEASE-NOTES.md
@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/ko/1.0.0/).
+
+## [Unreleased]
+
+## [2026-04-07]
+
+### 추가
+
+- Spring Boot 3.2.1 백엔드 초기 구조 (com.gcsc.connection, 포트 8042, context /snp-connection)
+- React 19 + TypeScript + Vite 7 + Tailwind CSS 4 프론트엔드 통합
+- frontend-maven-plugin 기반 통합 빌드 설정
+- SPA fallback WebViewController, SecurityConfig, SwaggerConfig
+- 공통 모듈 (ApiResponse, GlobalExceptionHandler)
+- 파비콘 등록 (favicon_io_red)
+- 팀 워크플로우 v1.6.1 동기화
--- a/frontend/.editorconfig
+++ b/frontend/.editorconfig
@ -0,0 +1,33 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{java,kt}]
+indent_style = space
+indent_size = 4
+
+[*.{js,jsx,ts,tsx,json,yml,yaml,css,scss,html}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{sh,bash}]
+indent_style = space
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+
+[*.{gradle,groovy}]
+indent_style = space
+indent_size = 4
+
+[*.xml]
+indent_style = space
+indent_size = 4
--- a/frontend/.node-version
+++ b/frontend/.node-version
@ -0,0 +1 @@
+20
--- a/frontend/.npmrc
+++ b/frontend/.npmrc
@ -0,0 +1,5 @@
+# Nexus npm 프록시 레지스트리
+registry=https://nexus.gc-si.dev/repository/npm-public/
+
+# Nexus 인증
+//nexus.gc-si.dev/repository/npm-public/:_auth=YWRtaW46R2NzYyE4OTMy
--- a/frontend/.prettierrc
+++ b/frontend/.prettierrc
@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@ -0,0 +1,25 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['dist'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+    },
+  },
+);
--- a/frontend/index.html
+++ b/frontend/index.html
@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="ko">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" sizes="32x32" href="/snp-connection/favicon-32x32.png" />
+    <link rel="icon" type="image/png" sizes="16x16" href="/snp-connection/favicon-16x16.png" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/snp-connection/apple-touch-icon.png" />
+    <link rel="manifest" href="/snp-connection/site.webmanifest" />
+    <link rel="shortcut icon" href="/snp-connection/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SNP Connection Monitoring</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
--- a/frontend/package.json
+++ b/frontend/package.json
@ -0,0 +1,35 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css}\""
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.13.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "prettier": "^3.5.3",
+    "tailwindcss": "^4.1.18",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^7.3.1"
+  }
+}
--- a/frontend/public/android-chrome-192x192.png
+++ b/frontend/public/android-chrome-192x192.png
--- a/frontend/public/android-chrome-512x512.png
+++ b/frontend/public/android-chrome-512x512.png
--- a/frontend/public/apple-touch-icon.png
+++ b/frontend/public/apple-touch-icon.png
--- a/frontend/public/favicon-16x16.png
+++ b/frontend/public/favicon-16x16.png
--- a/frontend/public/favicon-32x32.png
+++ b/frontend/public/favicon-32x32.png
--- a/frontend/public/favicon.ico
+++ b/frontend/public/favicon.ico
--- a/frontend/public/site.webmanifest
+++ b/frontend/public/site.webmanifest
@ -0,0 +1,19 @@
+{
+  "name": "SNP Connection Monitoring",
+  "short_name": "SNP Connection",
+  "icons": [
+    {
+      "src": "/snp-connection/android-chrome-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/snp-connection/android-chrome-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@ -0,0 +1,26 @@
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
+
+const BASE_PATH = '/snp-connection';
+
+function App() {
+  return (
+    <BrowserRouter basename={BASE_PATH}>
+      <Routes>
+        <Route path="/" element={<Navigate to="/dashboard" replace />} />
+        <Route
+          path="/dashboard"
+          element={
+            <div className="flex min-h-screen items-center justify-center bg-gray-50">
+              <div className="text-center">
+                <h1 className="text-3xl font-bold text-gray-900">SNP Connection Monitoring</h1>
+                <p className="mt-2 text-gray-600">Dashboard - Coming Soon</p>
+              </div>
+            </div>
+          }
+        />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+
+export default App;
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@ -0,0 +1 @@
+@import 'tailwindcss';
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import './index.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
--- a/frontend/src/vite-env.d.ts
+++ b/frontend/src/vite-env.d.ts
@ -0,0 +1 @@
+/// <reference types="vite/client" />
--- a/frontend/tsconfig.app.json
+++ b/frontend/tsconfig.app.json
@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsBuildInfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
--- a/frontend/tsconfig.node.json
+++ b/frontend/tsconfig.node.json
@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsBuildInfo",
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@ -0,0 +1,21 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: {
+    port: 5173,
+    proxy: {
+      '/snp-connection/api': {
+        target: 'http://localhost:8042',
+        changeOrigin: true,
+      },
+    },
+  },
+  base: '/snp-connection/',
+  build: {
+    outDir: '../src/main/resources/static',
+    emptyOutDir: true,
+  },
+});
--- a/pom.xml
+++ b/pom.xml
@ -0,0 +1,183 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.2.1</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>com.gcsc</groupId>
+    <artifactId>snp-connection-monitoring</artifactId>
+    <version>1.0.0</version>
+    <name>SNP Connection Monitoring</name>
+    <description>API Gateway + Monitoring Platform for S&amp;P Connection Services</description>
+
+    <properties>
+        <java.version>17</java.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+
+        <!-- Dependency versions -->
+        <spring-boot.version>3.2.1</spring-boot.version>
+        <postgresql.version>42.7.6</postgresql.version>
+        <lombok.version>1.18.30</lombok.version>
+    </properties>
+
+    <dependencies>
+        <!-- Spring Boot Starter Web -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <!-- Spring Boot Starter Data JPA -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-jpa</artifactId>
+        </dependency>
+
+        <!-- Spring Boot Starter Security -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-security</artifactId>
+        </dependency>
+
+        <!-- Spring Boot Starter Validation -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+
+        <!-- PostgreSQL Driver -->
+        <dependency>
+            <groupId>org.postgresql</groupId>
+            <artifactId>postgresql</artifactId>
+            <version>${postgresql.version}</version>
+        </dependency>
+
+        <!-- WebClient for Heartbeat & Gateway proxy -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-webflux</artifactId>
+        </dependency>
+
+        <!-- Jackson for JSON processing -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+
+        <!-- Lombok -->
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <version>${lombok.version}</version>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- Spring Boot DevTools -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-devtools</artifactId>
+            <scope>runtime</scope>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- Spring Boot Actuator -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+
+        <!-- Springdoc OpenAPI (Swagger) -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.3.0</version>
+        </dependency>
+
+        <!-- Test Dependencies -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+                <version>${spring-boot.version}</version>
+                <configuration>
+                    <excludes>
+                        <exclude>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                        </exclude>
+                    </excludes>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>com.github.eirslett</groupId>
+                <artifactId>frontend-maven-plugin</artifactId>
+                <version>1.15.1</version>
+                <configuration>
+                    <workingDirectory>frontend</workingDirectory>
+                    <nodeVersion>v20.19.0</nodeVersion>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>install-node-and-npm</id>
+                        <goals><goal>install-node-and-npm</goal></goals>
+                    </execution>
+                    <execution>
+                        <id>npm-install</id>
+                        <goals><goal>npm</goal></goals>
+                        <configuration>
+                            <arguments>install</arguments>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>npm-build</id>
+                        <goals><goal>npm</goal></goals>
+                        <configuration>
+                            <arguments>run build</arguments>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.11.0</version>
+                <configuration>
+                    <source>17</source>
+                    <target>17</target>
+                    <encoding>UTF-8</encoding>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                            <version>${lombok.version}</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
--- a/src/main/java/com/gcsc/connection/SnpConnectionApplication.java
+++ b/src/main/java/com/gcsc/connection/SnpConnectionApplication.java
@ -0,0 +1,14 @@
+package com.gcsc.connection;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.scheduling.annotation.EnableScheduling;
+
+@SpringBootApplication
+@EnableScheduling
+public class SnpConnectionApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(SnpConnectionApplication.class, args);
+    }
+}
--- a/src/main/java/com/gcsc/connection/common/dto/ApiResponse.java
+++ b/src/main/java/com/gcsc/connection/common/dto/ApiResponse.java
@ -0,0 +1,37 @@
+package com.gcsc.connection.common.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class ApiResponse<T> {
+
+    private final boolean success;
+    private final String message;
+    private final T data;
+
+    public static <T> ApiResponse<T> ok(T data) {
+        return ApiResponse.<T>builder()
+            .success(true)
+            .data(data)
+            .build();
+    }
+
+    public static <T> ApiResponse<T> ok(T data, String message) {
+        return ApiResponse.<T>builder()
+            .success(true)
+            .message(message)
+            .data(data)
+            .build();
+    }
+
+    public static <T> ApiResponse<T> error(String message) {
+        return ApiResponse.<T>builder()
+            .success(false)
+            .message(message)
+            .build();
+    }
+}
--- a/src/main/java/com/gcsc/connection/common/exception/GlobalExceptionHandler.java
+++ b/src/main/java/com/gcsc/connection/common/exception/GlobalExceptionHandler.java
@ -0,0 +1,21 @@
+package com.gcsc.connection.common.exception;
+
+import com.gcsc.connection.common.dto.ApiResponse;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+@Slf4j
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ApiResponse<Void>> handleException(Exception e) {
+        log.error("Unhandled exception: {}", e.getMessage(), e);
+        return ResponseEntity
+            .status(HttpStatus.INTERNAL_SERVER_ERROR)
+            .body(ApiResponse.error(e.getMessage()));
+    }
+}
--- a/src/main/java/com/gcsc/connection/config/SecurityConfig.java
+++ b/src/main/java/com/gcsc/connection/config/SecurityConfig.java
@ -0,0 +1,26 @@
+package com.gcsc.connection.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
+import org.springframework.security.config.annotation.web.configurers.HeadersConfigurer;
+import org.springframework.security.web.SecurityFilterChain;
+
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        http
+            .csrf(AbstractHttpConfigurer::disable)
+            .headers(headers -> headers
+                .frameOptions(HeadersConfigurer.FrameOptionsConfig::sameOrigin))
+            .authorizeHttpRequests(auth -> auth
+                .anyRequest().permitAll());
+
+        return http.build();
+    }
+}
--- a/src/main/java/com/gcsc/connection/config/SwaggerConfig.java
+++ b/src/main/java/com/gcsc/connection/config/SwaggerConfig.java
@ -0,0 +1,19 @@
+package com.gcsc.connection.config;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class SwaggerConfig {
+
+    @Bean
+    public OpenAPI openAPI() {
+        return new OpenAPI()
+            .info(new Info()
+                .title("SNP Connection Monitoring API")
+                .description("API Gateway + Monitoring Platform for S&P Connection Services")
+                .version("1.0.0"));
+    }
+}
--- a/src/main/java/com/gcsc/connection/global/controller/WebViewController.java
+++ b/src/main/java/com/gcsc/connection/global/controller/WebViewController.java
@ -0,0 +1,21 @@
+package com.gcsc.connection.global.controller;
+
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+
+/**
+ * SPA(React) fallback router
+ *
+ * React Router handles client-side routing,
+ * so all frontend paths are forwarded to index.html.
+ */
+@Controller
+public class WebViewController {
+
+    @GetMapping({"/", "/login", "/dashboard", "/dashboard/**",
+                 "/monitoring/**", "/apikeys", "/apikeys/**",
+                 "/admin/**"})
+    public String forward() {
+        return "forward:/index.html";
+    }
+}
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@ -0,0 +1,60 @@
+spring:
+  application:
+    name: snp-connection-monitoring
+
+  # PostgreSQL Database Configuration
+  datasource:
+    url: jdbc:postgresql://211.208.115.83:5432/snpdb
+    username: snp
+    password: snp#8932
+    driver-class-name: org.postgresql.Driver
+    hikari:
+      maximum-pool-size: 10
+      minimum-idle: 5
+      connection-timeout: 30000
+
+  # JPA Configuration
+  jpa:
+    hibernate:
+      ddl-auto: validate
+    show-sql: false
+    properties:
+      hibernate:
+        dialect: org.hibernate.dialect.PostgreSQLDialect
+        format_sql: true
+        default_schema: std_snp_connection
+
+# Server Configuration
+server:
+  port: 8042
+  servlet:
+    context-path: /snp-connection
+
+# Actuator Configuration
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics
+  endpoint:
+    health:
+      show-details: always
+
+# Springdoc / Swagger UI
+springdoc:
+  swagger-ui:
+    deep-linking: true
+    display-request-duration: true
+
+# Logging Configuration
+logging:
+  level:
+    root: INFO
+    com.gcsc.connection: DEBUG
+
+# Custom Application Properties
+app:
+  environment: dev
+  heartbeat:
+    default-interval-seconds: 30
+    timeout-seconds: 5
--- a/src/test/java/com/gcsc/connection/SnpConnectionApplicationTest.java
+++ b/src/test/java/com/gcsc/connection/SnpConnectionApplicationTest.java
@ -0,0 +1,14 @@
+package com.gcsc.connection;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class SnpConnectionApplicationTest {
+
+    @Test
+    void contextLoads() {
+    }
+}
--- a/src/test/resources/application-test.yml
+++ b/src/test/resources/application-test.yml
@ -0,0 +1,13 @@
+spring:
+  datasource:
+    url: jdbc:h2:mem:testdb
+    driver-class-name: org.h2.Driver
+    username: sa
+    password:
+
+  jpa:
+    hibernate:
+      ddl-auto: create-drop
+    properties:
+      hibernate:
+        dialect: org.hibernate.dialect.H2Dialect
--- a/workflow-version.json
+++ b/workflow-version.json
@ -1,26 +1,7 @@
 {
-  "version": "1.0.0",
-  "updated": "2026-02-14",
-  "gitea_url": "http://211.208.115.83:3000",
-  "nexus_url": "http://211.208.115.83:9081",
-  "changes": [
-    {
-      "version": "1.0.0",
-      "date": "2026-02-14",
-      "description": "팀 워크플로우 초기 구성",
-      "items": [
-        "3계층 정책 강제 (프로젝트 deny + 서버 hooks + Branch Protection)",
-        "Java Maven/Gradle + React TS 템플릿",
-        "Nexus 자체 레포지토리 연동",
-        "Conventional Commits (한/영 혼용)",
-        "Git hooks: pre-commit(빌드검증), commit-msg(형식검증), post-checkout(hooksPath 자동설정)"
-      ],
-      "affected_files": [
-        ".claude/settings.json",
-        ".claude/rules/*",
-        ".claude/skills/*",
-        ".githooks/*"
-      ]
-    }
-  ]
+  "applied_global_version": "1.6.1",
+  "applied_date": "2026-04-07",
+  "project_type": "java-maven",
+  "gitea_url": "https://gitea.gc-si.dev",
+  "nexus_url": "https://nexus.gc-si.dev"
 }