diff --git a/.claude/agents/explorer.md b/.claude/agents/explorer.md new file mode 100644 index 0000000..be33b64 --- /dev/null +++ b/.claude/agents/explorer.md @@ -0,0 +1,47 @@ +--- +name: explorer +description: 코드베이스 탐색 및 분석 에이전트. 3개 이상의 파일을 탐색하거나 프로젝트 구조를 파악할 때 사용한다. +model: sonnet +tools: Read, Glob, Grep +maxTurns: 12 +--- + +지정된 영역 내에서 코드베이스를 분석하고 구조화된 결과를 반환한다. +읽기 전용 — 파일을 수정하지 않는다. + +## 자율 범위 + +- 메인 세션이 지정한 **탐색 영역**(디렉토리 또는 파일 목록) 내에서 자유롭게 탐색 +- 영역 내 파일 간 의존성 추적, 임포트 체인 분석은 자율 수행 +- 탐색 영역 밖 파일은 임포트/참조 관계 확인 목적으로만 열람 가능 + +## 입력 (메인 세션이 제공) + +- **탐색 영역**: 디렉토리 경로 또는 파일 목록 +- **목적**: 분석 목적이나 답변할 질문 (구체적일수록 좋음) + +## 출력 형식 + +``` +## 분석 결과 + +### 구조 +- 핵심 파일/디렉토리 구성 (파일:라인 근거) + +### 발견사항 +- 목적에 대한 답변 (파일:라인 근거 포함) + +### 패턴 +- 코드 컨벤션, 반복 패턴, 아키텍처 특성 + +### 확신도 +- 각 발견사항별: 확정 / 추정(근거) / 판단불가(필요 정보) + +### 범위 외 참고 +- 탐색 영역 밖에서 발견된 관련 사항 (해당 시) +``` + +## 제약 + +- 파일 수정/생성 금지 +- 정보 부족 시 추측하지 않고 "판단불가 — [필요한 정보]"로 표시 diff --git a/.claude/agents/implementer.md b/.claude/agents/implementer.md new file mode 100644 index 0000000..6ac24b6 --- /dev/null +++ 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 자체 검증 수행 diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md new file mode 100644 index 0000000..e4763ac --- /dev/null +++ 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로만 기록 diff --git a/.claude/rules/release-notes-guide.md b/.claude/rules/release-notes-guide.md new file mode 100644 index 0000000..48bf706 --- /dev/null +++ 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이 아닌 **리포 단위 팀 권한** 기준 diff --git a/.claude/rules/subagent-policy.md b/.claude/rules/subagent-policy.md new file mode 100644 index 0000000..05164c5 --- /dev/null +++ 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)**: 계약은 고정, 내부 구현은 자율 → 중간 자율성 +- **같은 파일을 두 에이전트가 동시에 수정하지 않는다** +- **커밋/푸시는 반드시 메인 세션에서 수행** diff --git a/.claude/settings.json b/.claude/settings.json index b13b469..1eee08a 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,5 +1,8 @@ { "$schema": "https://json.schemastore.org/claude-code-settings.json", + "env": { + "CLAUDE_BOT_TOKEN": "4804f9f63e799e25d9a8b381e89c8bff11471b7a" + }, "permissions": { "allow": [ "Bash(npm run *)", diff --git a/.claude/skills/create-mr/SKILL.md b/.claude/skills/create-mr/SKILL.md index 741fbc2..71029c5 100644 --- 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)" --- diff --git a/.claude/skills/fix-issue/SKILL.md b/.claude/skills/fix-issue/SKILL.md index 70452ea..7868072 100644 --- 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: "" --- diff --git a/.claude/skills/init-project/SKILL.md b/.claude/skills/init-project/SKILL.md index 3f5d388..ec3da04 100644 --- 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]" --- @@ -46,7 +45,7 @@ curl -sf "${GITEA_URL}/gc/template-react-ts/raw/branch/develop/.editorconfig" ### 3. .claude/ 디렉토리 구성 이미 팀 표준 파일이 존재하면 건너뜀. 없는 경우 위의 URL 패턴으로 Gitea에서 다운로드: -- `.claude/settings.json` — 프로젝트 타입별 표준 권한 설정 + hooks 섹션 (4단계 참조) +- `.claude/settings.json` — 프로젝트 타입별 표준 권한 설정 + env(CLAUDE_BOT_TOKEN 등) + hooks 섹션 (4단계 참조) - `.claude/rules/` — 팀 규칙 파일 (team-policy, git-workflow, code-style, naming, testing) - `.claude/skills/` — 팀 스킬 (create-mr, fix-issue, sync-team-workflow, init-project) diff --git a/.claude/skills/mr/SKILL.md b/.claude/skills/mr/SKILL.md new file mode 100644 index 0000000..9ac5448 --- /dev/null +++ b/.claude/skills/mr/SKILL.md @@ -0,0 +1,242 @@ +--- +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 생성 권한이 필요합니다. 프로젝트 관리자에게 요청하세요." 안내 후 종료 + +### 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 생성만, 세부 옵션 지원 (상세 제어) diff --git a/.claude/skills/push/SKILL.md b/.claude/skills/push/SKILL.md new file mode 100644 index 0000000..7cbdceb --- /dev/null +++ b/.claude/skills/push/SKILL.md @@ -0,0 +1,111 @@ +--- +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 권한이 필요합니다. 프로젝트 관리자에게 요청하세요." 안내 후 종료 + +### 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(-) +``` diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md new file mode 100644 index 0000000..8369a99 --- /dev/null +++ b/.claude/skills/release/SKILL.md @@ -0,0 +1,196 @@ +--- +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`이면: "릴리즈는 프로젝트 관리자만 실행할 수 있습니다." 안내 후 종료 + +### 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 승인용 토큰 (선택, 없으면 자동 승인 건너뜀) diff --git a/.claude/skills/sync-team-workflow/SKILL.md b/.claude/skills/sync-team-workflow/SKILL.md index 930d04d..5c07617 100644 --- a/.claude/skills/sync-team-workflow/SKILL.md +++ b/.claude/skills/sync-team-workflow/SKILL.md @@ -1,7 +1,6 @@ --- name: sync-team-workflow description: 팀 글로벌 워크플로우를 현재 프로젝트에 동기화합니다 -allowed-tools: "Bash, Read, Write, Edit, Glob, Grep" --- 팀 글로벌 워크플로우의 최신 버전을 현재 프로젝트에 적용합니다. @@ -45,12 +44,22 @@ curl -sf "${GITEA_URL}/gc/template-react-ts/raw/branch/develop/.editorconfig" ``` .claude/rules/team-policy.md .claude/rules/git-workflow.md +.claude/rules/release-notes-guide.md +.claude/rules/subagent-policy.md .claude/rules/code-style.md (타입별) .claude/rules/naming.md (타입별) .claude/rules/testing.md (타입별) ``` +#### 4-1b. 에이전트 파일 (덮어쓰기) +``` +.claude/agents/explorer.md +.claude/agents/implementer.md +.claude/agents/reviewer.md +``` + #### 4-2. settings.json (부분 갱신) +- `env`: 글로벌 최신으로 교체 (CLAUDE_BOT_TOKEN 등 팀 공통 환경변수) - `deny` 목록: 글로벌 최신으로 교체 - `allow` 목록: 기존 사용자 커스텀 유지 + 글로벌 기본값 병합 - `hooks`: init-project SKILL.md의 hooks JSON 블록을 참조하여 교체 (없으면 추가) @@ -64,6 +73,10 @@ curl -sf "${GITEA_URL}/gc/template-react-ts/raw/branch/develop/.editorconfig" .claude/skills/fix-issue/SKILL.md .claude/skills/sync-team-workflow/SKILL.md .claude/skills/init-project/SKILL.md +.claude/skills/push/SKILL.md +.claude/skills/mr/SKILL.md +.claude/skills/release/SKILL.md +.claude/skills/version/SKILL.md ``` #### 4-4. Git Hooks (덮어쓰기 + 실행 권한) diff --git a/.claude/skills/version/SKILL.md b/.claude/skills/version/SKILL.md new file mode 100644 index 0000000..1358d53 --- /dev/null +++ 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 접근 토큰 (필수) diff --git a/.claude/workflow-version.json b/.claude/workflow-version.json index fb01d6e..53d92da 100644 --- a/.claude/workflow-version.json +++ b/.claude/workflow-version.json @@ -1,6 +1,6 @@ { - "applied_global_version": "1.2.0", - "applied_date": "2026-02-14", + "applied_global_version": "1.5.0", + "applied_date": "2026-03-01", "project_type": "react-ts", "gitea_url": "https://gitea.gc-si.dev" } diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml index 0fd405c..07319cb 100644 --- a/.gitea/workflows/deploy.yml +++ b/.gitea/workflows/deploy.yml @@ -15,7 +15,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: '20' + node-version: '24' - name: Configure npm registry run: | diff --git a/.githooks/commit-msg b/.githooks/commit-msg index 08dbad7..67be0a9 100755 --- a/.githooks/commit-msg +++ b/.githooks/commit-msg @@ -20,11 +20,14 @@ fi # Conventional Commits 정규식 # type(scope): subject # - type: feat|fix|docs|style|refactor|test|chore|ci|perf (필수) -# - scope: 영문, 숫자, 한글, 점, 밑줄, 하이픈 허용 (선택) -# - subject: 1~72자, 한/영 혼용 허용 (필수) +# - scope: 괄호 제외 모든 문자 허용 — 한/영/숫자/특수문자 (선택) +# - subject: 1자 이상 (길이는 바이트 기반 별도 검증) +PATTERN='^(feat|fix|docs|style|refactor|test|chore|ci|perf)(\([^)]+\))?: .+$' +MAX_SUBJECT_BYTES=200 # UTF-8 한글(3byte) 허용: 72문자 ≈ 최대 216byte + FIRST_LINE=$(head -1 "$COMMIT_MSG_FILE") -if ! echo "$FIRST_LINE" | grep -qE '^(feat|fix|docs|style|refactor|test|chore|ci|perf)(\([a-zA-Z0-9._-]+\)|(\([^)]+\)))?: .{1,72}$'; then +if ! echo "$FIRST_LINE" | grep -qE "$PATTERN"; then echo "" echo "╔══════════════════════════════════════════════════════════════╗" echo "║ 커밋 메시지가 Conventional Commits 형식에 맞지 않습니다 ║" @@ -56,3 +59,13 @@ if ! echo "$FIRST_LINE" | grep -qE '^(feat|fix|docs|style|refactor|test|chore|ci echo "" exit 1 fi + +# 길이 검증 (바이트 기반 — UTF-8 한글 허용) +MSG_LEN=$(echo -n "$FIRST_LINE" | wc -c | tr -d ' ') +if [ "$MSG_LEN" -gt "$MAX_SUBJECT_BYTES" ]; then + echo "" + echo " ✗ 커밋 메시지가 너무 깁니다 (${MSG_LEN}바이트, 최대 ${MAX_SUBJECT_BYTES})" + echo " 현재 메시지: $FIRST_LINE" + echo "" + exit 1 +fi diff --git a/.node-version b/.node-version index 209e3ef..a45fd52 100644 --- a/.node-version +++ b/.node-version @@ -1 +1 @@ -20 +24 diff --git a/docs/RELEASE-NOTES.md b/docs/RELEASE-NOTES.md new file mode 100644 index 0000000..686a323 --- /dev/null +++ b/docs/RELEASE-NOTES.md @@ -0,0 +1,26 @@ +# Release Notes + +이 문서는 [Keep a Changelog](https://keepachangelog.com/ko/1.0.0/) 형식을 따릅니다. + +## [Unreleased] + +## [2026-03-01] +### 추가 +- 프로젝트 초기 구성 (React 19 + TypeScript + Vite + Tailwind CSS v4) +- Google OAuth 인증 + 롤 기반 접근 제어 +- 가이드 콘텐츠 9개 섹션 (개발환경, Gitea, Git, Nexus, CI/CD, Claude Code, 릴리즈 등) +- 관리자 페이지 5개 (사용자, 롤, 권한, 가입설정, 통계) +- CI/CD 자동 배포 워크플로우 (Gitea Actions) +- 로그인 redirect 파라미터 처리 +- Nginx 프록시 인증 연동 +- 팀 워크플로우 v1.5.0 동기화 (스킬 8종, 에이전트 3종, 규칙) + +### 수정 +- Nexus 프록시 인증정보 추가 +- 파비콘 GC 아이콘 적용 및 페이지 타이틀 변경 +- 존재하지 않는 URL 접근 시 메인으로 리다이렉트 +- commit-msg hook 정규식 통일 +- settings.json에서 개인 토큰 분리 (settings.local.json으로 이동) + +### 변경 +- chat 봇 연동/디자인 시스템 섹션 임시 주석처리 diff --git a/src/content/ClaudeCodeSkills.tsx b/src/content/ClaudeCodeSkills.tsx new file mode 100644 index 0000000..5ecb01b --- /dev/null +++ b/src/content/ClaudeCodeSkills.tsx @@ -0,0 +1,198 @@ +import { Alert } from '../components/common/Alert'; +import { CodeBlock } from '../components/common/CodeBlock'; +import { StepGuide } from '../components/common/StepGuide'; + +const SKILLS = [ + { name: '/push', desc: '변경 확인 → 커밋 메시지 자동 제안 → 푸시', perm: 'push' }, + { name: '/mr', desc: '커밋 + 푸시 + MR 생성 + 릴리즈 노트 갱신 + 봇 승인/머지 선택', perm: 'push' }, + { name: '/release', desc: '릴리즈 노트 정리 + develop→main MR + 봇 승인/머지', perm: 'admin' }, + { name: '/version', desc: 'VERSION-HISTORY.md (SemVer) 생성', perm: 'admin' }, + { name: '/create-mr', desc: 'MR만 생성 (세부 옵션 지원)', perm: 'push' }, + { name: '/fix-issue', desc: 'Gitea 이슈 분석 + 수정 브랜치 생성', perm: 'push' }, + { name: '/init-project', desc: '팀 표준 워크플로우로 프로젝트 초기화', perm: '-' }, + { name: '/sync-team-workflow', desc: '워크플로우 버전 동기화', perm: '-' }, +]; + +export default function ClaudeCodeSkills() { + return ( +
+

Claude Code 활용

+

+ Claude Code 스킬을 활용하여 커밋, MR 생성, 릴리즈까지 개발 워크플로우를 자동화할 수 있습니다. +

+ + {/* 스킬 일람 */} +

스킬 일람

+
+ + + + + + + + + + {SKILLS.map((s) => ( + + + + + + ))} + +
스킬설명필요 권한
{s.name}{s.desc} + {s.perm === 'admin' ? ( + admin + ) : s.perm === 'push' ? ( + push + ) : ( + - + )} +
+
+ + push 권한은 팀원에게,{' '} + admin 권한은 리포지토리 관리자에게 부여됩니다. + Gitea 리포 설정에서 확인할 수 있습니다. + + + {/* 일상적인 개발 흐름 */} +

일상적인 개발 흐름

+

+ Claude Code 스킬을 활용한 일반적인 개발 흐름입니다. +

+ +

작업 후 변경 사항을 확인하고 커밋+푸시합니다.

+ + + ), + }, + { + title: 'MR 생성 — /mr', + content: ( + <> +

feature 브랜치에서 develop으로 MR을 생성합니다.

+ +

+ /mr은{' '} + /push + MR + 릴리즈 노트를 한 번에 처리합니다. + MR 생성 후 리뷰 대기 또는 claude-bot 자동 승인+머지를 선택할 수 있습니다. +

+ + ), + }, + { + title: '릴리즈 — /release (관리자)', + content: ( + <> +

develop → main 릴리즈 MR을 생성하고, 봇이 자동 승인합니다.

+ + + /release는 리포 admin 권한이 필요합니다. + + + ), + }, + ]} + /> + + {/* 커스텀 에이전트 */} +

커스텀 에이전트

+

+ 팀 워크플로우에는 특화된 서브에이전트 3종이 포함되어 있습니다. + .claude/agents/ 디렉토리에 배치되며,{' '} + /init-project로 자동 설정됩니다. +

+
+
+

explorer

+

코드베이스 탐색/분석 에이전트

+
    +
  • 읽기 전용 (코드 수정 불가)
    • +
  • 높은 자율성
    • +
  • 모델: Sonnet
    • +
+
+
+

implementer

+

모듈 단위 구현 에이전트

+
    +
  • 계약 기반 구현
    • +
  • 중간 자율성
    • +
  • 모델: Sonnet
    • +
+
+
+

reviewer

+

코드 리뷰/품질 검증 에이전트

+
    +
  • 체크리스트 기반 검증
    • +
  • 높은 자율성
    • +
  • 모델: Sonnet
    • +
+
+
+ + {/* 사전 준비 */} +

사전 준비

+

+ 스킬을 사용하려면 다음이 필요합니다. +

+
    +
  • + • + + GITEA_TOKEN 환경변수 설정 — 초기 환경 설정 가이드의 + "Gitea API 토큰 설정" 참고 + +
    • +
  • + • + + Claude Code 설치 — npm install -g @anthropic-ai/claude-code + +
    • +
  • + • + + 프로젝트 초기화 — /init-project 실행으로 팀 설정 자동 적용 + +
    • +
+ + GITEA_TOKEN은{' '} + settings.json의{' '} + env 필드에서도 설정할 수 있습니다. + 환경변수와 settings.json 모두 설정된 경우 환경변수가 우선합니다. + +
+ ); +} diff --git a/src/content/GitWorkflow.tsx b/src/content/GitWorkflow.tsx index 09acc25..22fffe6 100644 --- a/src/content/GitWorkflow.tsx +++ b/src/content/GitWorkflow.tsx @@ -144,11 +144,25 @@ git commit -m "feat(auth): 로그인 폼 UI 구현 (#42)"`} { title: '푸시 및 MR 생성', content: ( - +

수동 방식:

+ + /> +
+

Claude Code 사용 시 (권장)

+ +

+ 자세한 내용은 Claude Code 활용 가이드를 참고하세요. +

+
+ ), }, { diff --git a/src/content/InitialSetup.tsx b/src/content/InitialSetup.tsx index 6385c72..7dadc14 100644 --- a/src/content/InitialSetup.tsx +++ b/src/content/InitialSetup.tsx @@ -192,6 +192,54 @@ claude --version`} Claude Code 사용을 위해 팀 관리자에게 API 키를 요청하세요. + +

+ Gitea API 토큰 설정 +

+

+ Claude Code 스킬(/push,{' '} + /mr,{' '} + /release 등)을 사용하려면 Gitea API 토큰이 필요합니다. +

+ + Gitea 접속 → 우측 상단 프로필 → 설정 → 애플리케이션 → + "액세스 토큰 관리" 섹션에서 토큰 이름을 입력하고 토큰 생성을 클릭합니다. +

+ ), + }, + { + title: '토큰 복사', + content: ( + + 생성된 토큰은 한 번만 표시됩니다. 반드시 복사해서 안전한 곳에 저장하세요. + + ), + }, + { + title: '환경변수 등록', + content: ( + <> + + + + ), + }, + ]} + /> + + CLAUDE_BOT_TOKEN은 프로젝트{' '} + settings.json에 팀 공통으로 포함되어 있어 별도 설정이 필요 없습니다. + ); } diff --git a/src/content/ReleaseManagement.tsx b/src/content/ReleaseManagement.tsx new file mode 100644 index 0000000..1c152d7 --- /dev/null +++ b/src/content/ReleaseManagement.tsx @@ -0,0 +1,158 @@ +import { Alert } from '../components/common/Alert'; +import { CodeBlock } from '../components/common/CodeBlock'; +import { StepGuide } from '../components/common/StepGuide'; + +export default function ReleaseManagement() { + return ( +
+

릴리즈 관리

+

+ 팀은 2계층 릴리즈 노트 체계를 사용합니다. Claude Code 스킬이 대부분의 작성과 관리를 자동화합니다. +

+ + {/* 2계층 릴리즈 노트 */} +

2계층 릴리즈 노트

+
+
+
+ Tier 1 +

RELEASE-NOTES.md

+
+
    +
  • Keep a Changelog 형식
    • +
  • 날짜 + 순번 버저닝 ([2026-03-01])
    • +
  • /mr에서 [Unreleased] 자동 갱신
    • +
  • /release에서 날짜 전환 + 압축
    • +
  • 개발자 관점의 변경 이력
    • +
+
+
+
+ Tier 2 +

VERSION-HISTORY.md

+
+
    +
  • Semantic Versioning (v1.0.0)
    • +
  • RELEASE-NOTES.md 기반 생성
    • +
  • /version 스킬로 수동 생성
    • +
  • 사용자/고객 관점의 버전 히스토리
    • +
  • 릴리즈 마일스톤 기록
    • +
+
+
+ + {/* RELEASE-NOTES.md 형식 */} +

RELEASE-NOTES.md 형식

+

+ + Keep a Changelog + 형식을 따릅니다. +

+ + + {/* 자동 관리 흐름 */} +

자동 관리 흐름

+ + /mr 실행 시 커밋 메시지를 분석하여{' '} + [Unreleased] 섹션에 자동 추가합니다. + 사용자에게 첨삭 확인을 거친 후 커밋됩니다. +

+ ), + }, + { + title: '/release — 날짜 전환 + 압축', + content: ( + <> +

+ /release 실행 시{' '} + [Unreleased]를{' '} + [2026-03-01] 형태로 전환합니다. + 이전 날짜의 넘버링된 릴리즈는 자동 압축됩니다. +

+

+ 예: [2026-02-28.1] +{' '} + [2026-02-28.2] →{' '} + [2026-02-28] +

+ + ), + }, + { + title: '/version — VERSION-HISTORY.md 생성', + content: ( +

+ RELEASE-NOTES.md를 기반으로 Semantic Versioning 형태의{' '} + VERSION-HISTORY.md를 생성합니다. + 사용자 관점의 변경 이력을 정리하며, 관리자(admin 권한)만 실행할 수 있습니다. +

+ ), + }, + ]} + /> + + 릴리즈 노트는 /mr,{' '} + /release 스킬이 자동 관리합니다. + 직접 편집은 각 스킬의 첨삭 확인 단계에서 가능합니다. + + + {/* 날짜 넘버링 규칙 */} +

날짜 넘버링 규칙

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
상황버전설명
당일 첫 릴리즈[2026-03-01]순번 없음
당일 두 번째[2026-03-01.2].2 부터 순번 부여
다음날 릴리즈 시[2026-03-02]이전 넘버링 자동 압축 → [2026-03-01]
+
+
+ ); +} diff --git a/src/content/StartingProject.tsx b/src/content/StartingProject.tsx index 8e8f7c9..b0532da 100644 --- a/src/content/StartingProject.tsx +++ b/src/content/StartingProject.tsx @@ -118,6 +118,9 @@ cd 새-프로젝트명`}
  • Git hooks 경로 설정 (.githooks/를 로컬 hooks로 연결)
  • 워크플로우 버전 검증 및 동기화
  • CLAUDE.md 프로젝트 컨텍스트 확인
    • +
  • memory 디렉토리 초기화 (프로젝트 분석 기반)
    • +
  • hook 스크립트 생성 (.claude/scripts/)
    • +
  • lint 도구 감지 + 설정 확인

    • @@ -159,13 +162,18 @@ git push -u origin develop`}

    .claude/
    -
    rules/ — 팀 코딩 규칙 (code-style, git-workflow, naming, testing, team-policy)
    -
    skills/ — 팀 Claude 스킬 (create-mr, fix-issue, init-project, sync-team-workflow)
    -
    settings.json — 팀 Claude 권한 정책 (Git에 커밋됨)
    +
    rules/ — 팀 코딩 규칙 (code-style, git-workflow, naming, testing, team-policy, release-notes-guide, subagent-policy)
    +
    skills/ — 팀 Claude 스킬 (push, mr, release, version, create-mr, fix-issue, init-project, sync-team-workflow)
    +
    agents/ — 커스텀 서브에이전트 (explorer, implementer, reviewer)
    +
    scripts/ — hook 스크립트 (on-pre-compact, on-post-compact, on-commit)
    +
    settings.json — 팀 Claude 권한 정책 + env (GITEA_TOKEN 등)
    settings.local.json — 개인 확장 설정 (.gitignore에 포함, 각자 자유)
    .githooks/
    commit-msg — Conventional Commits 검증 훅
    post-checkout — 체크아웃 후 자동 실행
    +
    docs/
    +
    RELEASE-NOTES.md — 릴리즈 노트 (keepachangelog, /mr에서 자동 갱신)
    +
    VERSION-HISTORY.md — 버전 히스토리 (SemVer, /version으로 생성)
    .editorconfig — 에디터 공통 설정
    .gitignore — Git 제외 패턴
    CLAUDE.md — 프로젝트 설명서
    diff --git a/src/pages/GuidePage.tsx b/src/pages/GuidePage.tsx index 046574d..3918bf4 100644 --- a/src/pages/GuidePage.tsx +++ b/src/pages/GuidePage.tsx @@ -10,8 +10,10 @@ const CONTENT_MAP: Record 'starting-project': lazy(() => import('../content/StartingProject')), 'nexus-usage': lazy(() => import('../content/NexusUsage')), 'ci-cd': lazy(() => import('../content/CiCdGuide')), - 'chat-bot': lazy(() => import('../content/ChatBotIntegration')), - 'design-system': lazy(() => import('../content/DesignSystem')), + 'claude-code': lazy(() => import('../content/ClaudeCodeSkills')), + 'release-mgmt': lazy(() => import('../content/ReleaseManagement')), + // 'chat-bot': lazy(() => import('../content/ChatBotIntegration')), + // 'design-system': lazy(() => import('../content/DesignSystem')), }; export function GuidePage() { diff --git a/src/utils/navigation.ts b/src/utils/navigation.ts index 6789177..2c94772 100644 --- a/src/utils/navigation.ts +++ b/src/utils/navigation.ts @@ -8,8 +8,10 @@ export const DEV_NAV: NavItem[] = [ { path: '/dev/starting-project', label: '프로젝트 시작하기' }, { path: '/dev/nexus-usage', label: 'Nexus 사용법' }, { path: '/dev/ci-cd', label: 'CI/CD 자동 배포' }, - { path: '/dev/chat-bot', label: 'Chat 봇 연동' }, - { path: '/dev/design-system', label: '디자인 시스템' }, + { path: '/dev/claude-code', label: 'Claude Code 활용' }, + { path: '/dev/release-mgmt', label: '릴리즈 관리' }, + // { path: '/dev/chat-bot', label: 'Chat 봇 연동' }, + // { path: '/dev/design-system', label: '디자인 시스템' }, ]; export const ADMIN_NAV: NavItem[] = [