From 56fdc38f7b86acc3287fb80c5656760bf6cc57bb Mon Sep 17 00:00:00 2001 From: htlee Date: Sun, 8 Mar 2026 13:21:23 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B0=9C=EB=B0=9C=ED=99=98=EA=B2=BD=20?= =?UTF-8?q?=EA=B0=80=EC=9D=B4=EB=93=9C=20v1.6.1=20=EA=B8=B0=EC=A4=80=20?= =?UTF-8?q?=EC=B5=9C=EC=8B=A0=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - InitialSetup: GITEA_TOKEN 생성 가이드 강화 (권한 테이블, settings.local.json) - StartingProject: init-project 중심 간소화, 파일 구조 2분할 (커밋/로컬), 자동 동기화 안내 - ClaudeCodeSkills: 개발 프로세스 전체 흐름 + 권한별 시나리오 (개발자/관리자) --- src/content/ClaudeCodeSkills.tsx | 227 ++++++++++++++++++++++--------- src/content/InitialSetup.tsx | 90 +++++++++--- src/content/StartingProject.tsx | 123 +++++++++-------- 3 files changed, 299 insertions(+), 141 deletions(-) diff --git a/src/content/ClaudeCodeSkills.tsx b/src/content/ClaudeCodeSkills.tsx index 5ecb01b..a8b9bde 100644 --- a/src/content/ClaudeCodeSkills.tsx +++ b/src/content/ClaudeCodeSkills.tsx @@ -57,73 +57,182 @@ export default function ClaudeCodeSkills() { Gitea 리포 설정에서 확인할 수 있습니다. - {/* 일상적인 개발 흐름 */} -

일상적인 개발 흐름

-

- Claude Code 스킬을 활용한 일반적인 개발 흐름입니다. + {/* 개발 프로세스 전체 흐름 */} +

개발 프로세스 — 전체 흐름

+

+ 기능 개발부터 릴리즈까지, Claude Code 스킬을 활용한 전체 개발 흐름입니다.

+ + {/* 시각적 플로우 */} +
+
+ 계획 수립 + → + 브랜치 분리 + → + 개발 + → + /push + → + /mr + → + /release +
+
+ -

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

+

복잡한 기능은 구현 전에 계획을 먼저 세웁니다. Claude Code가 코드베이스를 분석하고 구현 방향을 설계합니다.

+

3개 이상 파일 수정이 필요하거나, 아키텍처에 영향을 주는 변경은 자동으로 플랜 모드로 전환됩니다.

), }, { - title: 'MR 생성 — /mr', + title: '2. 브랜치 분리 — feature 브랜치 생성', content: ( <> -

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

+

develop에서 feature 브랜치를 생성하여 독립적으로 개발합니다.

- /mr은{' '} - /push + MR + 릴리즈 노트를 한 번에 처리합니다. - MR 생성 후 리뷰 대기 또는 claude-bot 자동 승인+머지를 선택할 수 있습니다. + 이슈 기반 개발 시 /fix-issue 42를 사용하면 + 이슈 분석 + 브랜치 생성을 자동으로 처리합니다.

), }, { - title: '릴리즈 — /release (관리자)', + title: '3. 개발 → /push', content: ( <> -

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

+

코드 수정 후 /push로 커밋+푸시합니다.

- - /release는 리포 admin 권한이 필요합니다. + + 여러 커밋을 쌓지 말고, 하나의 기능 단위로 커밋하세요. + /push는 모든 변경을 단일 커밋으로 정리합니다. ), }, + { + title: '4. MR 생성 — /mr', + content: ( + <> +

기능 완성 후 develop으로 MR(Merge Request)을 생성합니다.

+ + + ), + }, ]} /> + {/* 권한별 시나리오 */} +

권한별 시나리오

+
+
+

+ push 권한 + 개발자 +

+
+

사용 가능: /push, /mr, /create-mr, /fix-issue

+
+
+ 1. + /push — 변경 커밋+푸시 +
+
+ 2. + /mr — develop으로 MR 생성 +
+
+ 3. + "리뷰 대기" 선택 → 관리자에게 리뷰 요청 +
+
+ → + 관리자가 Gitea에서 리뷰 + 승인 → 머지 +
+
+ + /release와 /version은 + admin 권한이 필요합니다. 관리자에게 요청하세요. + +
+
+
+

+ admin 권한 + 관리자 +

+
+

추가 사용: /release, /version

+
+
+ 1. + /push → /mr → "봇 승인+머지" 선택 +
+
+ 2. + feature 머지 완료 후, develop에서: +
+
+ 3. + /release — develop→main 릴리즈 MR +
+
+ ↳ 릴리즈 노트 날짜 전환 + 이전 넘버링 압축 +
+
+ ↳ claude-bot 자동 승인 → 머지 → CI/CD 배포 +
+
+ 4. + /version — VERSION-HISTORY.md 생성 (SemVer) +
+
+
+
+
+ + + 권한은 Gitea 리포지토리 단위로 관리됩니다. gc 조직 →{' '} + developers 팀 소속이면 push 권한이 자동 부여됩니다. + admin 권한은 프로젝트 관리자가 리포 설정에서 직접 부여합니다. + + {/* 커스텀 에이전트 */}

커스텀 에이전트

@@ -161,38 +270,32 @@ export default function ClaudeCodeSkills() { - {/* 사전 준비 */} -

사전 준비

+ {/* 시작하기 */} +

시작하기

- 스킬을 사용하려면 다음이 필요합니다. + Claude Code 스킬을 사용하려면 프로젝트에서 /init-project를 한 번 실행하면 됩니다. +

+
+
+
+ 1 + Claude Code 설치: npm install -g @anthropic-ai/claude-code +
+
+ 2 + 프로젝트에서 claude 실행 → /init-project +
+
+ 3 + GITEA_TOKEN 설정 안내에 따라 토큰 입력 (→ 초기 환경 설정 가이드 참고) +
+
+
+

+ CLAUDE_BOT_TOKEN은{' '} + settings.json에 팀 공통으로 포함되어 있어 별도 설정이 필요 없습니다. + 팀 워크플로우(rules, skills, agents)는 /push 실행 시 서버 해시 비교를 통해 자동 동기화됩니다.

-
    -
  • - • - - 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/InitialSetup.tsx b/src/content/InitialSetup.tsx index 7dadc14..245f139 100644 --- a/src/content/InitialSetup.tsx +++ b/src/content/InitialSetup.tsx @@ -195,51 +195,107 @@ claude --version`}

Gitea API 토큰 설정 + 필수

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

- Gitea 접속 → 우측 상단 프로필 → 설정 → 애플리케이션 → - "액세스 토큰 관리" 섹션에서 토큰 이름을 입력하고 토큰 생성을 클릭합니다. + + gitea.gc-si.dev/user/settings/applications + + {' '}접속 → "Manage Access Tokens" 섹션에서 "Generate New Token" 클릭

), }, + { + title: '토큰 정보 입력', + content: ( + <> +

+ Token Name: claude-code (자유롭게 지정)
+ Repository and Organization Access: All (public, private, and limited) +

+

Select permissions (아래 4개만 설정, 나머지는 No Access 유지):

+
+ + + + + + + + + + + + + + +
항목권한용도
issueRead and Write/fix-issue 이슈 조회/코멘트
organizationReadgc 조직 리포 접근
repositoryRead and Write/push, /mr, /release API 호출
userReadAPI 사용자 인증 확인
+
+ + ), + }, { title: '토큰 복사', content: ( - 생성된 토큰은 한 번만 표시됩니다. 반드시 복사해서 안전한 곳에 저장하세요. + "Generate Token" 클릭 후 표시되는 토큰은 한 번만 표시됩니다. 반드시 복사해서 안전한 곳에 저장하세요. ), }, { - title: '환경변수 등록', + title: '토큰 등록', content: ( <> - - +

두 가지 방법 중 하나를 선택하세요.

+
+
+

방법 A: settings.local.json (권장 — Claude Code 사용 시)

+

+ /init-project 실행 시 토큰 입력 안내가 표시됩니다. 입력하면 자동 저장됩니다. +

+ +

이 파일은 .gitignore에 포함되어 리포에 커밋되지 않습니다.

+
+
+

방법 B: 환경변수 (~/.zshrc)

+ +
+
), }, ]} /> - - CLAUDE_BOT_TOKEN은 프로젝트{' '} - settings.json에 팀 공통으로 포함되어 있어 별도 설정이 필요 없습니다. - + +
+

GITEA_TOKEN vs CLAUDE_BOT_TOKEN

+
    +
  • GITEA_TOKEN (개인) — 각자 생성. /push, /mr, /release 등 Git API 호출에 사용
    • +
  • CLAUDE_BOT_TOKEN (팀 공용) — settings.json에 포함되어 자동 적용. PR 자동 승인용 봇 계정 토큰. 별도 설정 불필요
    • +
+
); } diff --git a/src/content/StartingProject.tsx b/src/content/StartingProject.tsx index b0532da..aa8d556 100644 --- a/src/content/StartingProject.tsx +++ b/src/content/StartingProject.tsx @@ -81,9 +81,7 @@ export default function StartingProject() { content: (

Gitea → gc 조직 → 새 저장소를 클릭합니다. - "템플릿에서 생성"에서 프로젝트 유형에 맞는 템플릿(template-java-maven,{' '} - template-java-gradle,{' '} - template-react-ts)을 선택하고 프로젝트 이름을 입력합니다. + "템플릿에서 생성"에서 프로젝트 유형에 맞는 템플릿을 선택하고 프로젝트 이름을 입력합니다.

), }, @@ -98,55 +96,45 @@ cd 새-프로젝트명`} ), }, { - title: 'Claude Code로 초기화 (Claude Code 사용 시)', + title: '/init-project 실행', content: ( <> -

- Claude Code를 사용한다면 세션에서 프로젝트 초기화 스킬을 실행합니다. -

-

- /init-project가 수행하는 작업: -

+

/init-project가 한 번에 처리하는 작업:

    -
  • Git hooks 경로 설정 (.githooks/를 로컬 hooks로 연결)
    • -
  • 워크플로우 버전 검증 및 동기화
    • -
  • CLAUDE.md 프로젝트 컨텍스트 확인
    • -
  • memory 디렉토리 초기화 (프로젝트 분석 기반)
    • -
  • hook 스크립트 생성 (.claude/scripts/)
    • -
  • lint 도구 감지 + 설정 확인
    • +
  • 프로젝트 분석 (빌드 도구, 프레임워크, lint 자동 감지)
    • +
  • CLAUDE.md 프로젝트 설명서 생성
    • +
  • settings.json 팀 표준 설정 다운로드
    • +
  • GITEA_TOKEN 설정 안내 (미설정 시 토큰 생성 가이드 표시 → settings.local.json 자동 저장)
    • +
  • Git hooks 경로 설정 + pre-commit 빌드 검증
    • +
  • .gitignore에 팀 관리 경로 추가
    • +
  • memory 디렉토리 초기화
    • +
  • 팀 워크플로우 자동 동기화 (서버에서 최신 rules, skills, agents, scripts 다운로드)
-

- Claude Code를 사용하지 않는 경우에도 Git hooks는 클론 시 포함되어 있으며,{' '} + + Claude Code를 사용하지 않는 경우:{' '} git config core.hooksPath .githooks로 - 수동 설정할 수 있습니다. -

+ Git hooks만 수동 설정할 수 있습니다. + ), }, { - title: 'develop 브랜치 생성', + title: 'develop 브랜치 생성 + 첫 feature 시작', content: ( - ), - }, - { - title: '첫 feature 브랜치 시작', - content: ( - ), @@ -154,39 +142,48 @@ git push -u origin develop`} ]} /> - {/* 템플릿 공통 파일 구조 */} -

템플릿 공통 파일 구조

+ {/* 프로젝트 파일 구조 */} +

프로젝트 파일 구조

- 모든 프로젝트 템플릿에 포함되는 공통 파일입니다. 이 파일들은 Git에 커밋되어 팀 전체가 공유합니다. + 팀 파일은 리포에 커밋되는 부트스트랩 파일과{' '} + 로컬 전용 팀 관리 파일로 나뉩니다. 팀 관리 파일은 .gitignore에 포함되어 리포에 커밋되지 않으며,{' '} + /sync-team-workflow가 서버에서 최신 버전을 자동으로 다운로드합니다.

-
-
-
.claude/
-
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 — 프로젝트 설명서
-
workflow-version.json — 워크플로우 버전 추적
+
+
+

리포에 커밋 (부트스트랩)

+
+
.claude/settings.json — 팀 권한 + env
+
.claude/workflow-version.json — 버전 추적
+
.claude/skills/init-project/
+
.claude/skills/sync-team-workflow/
+
.githooks/ — commit-msg, post-checkout, pre-commit
+
CLAUDE.md — 프로젝트 설명서
+
.editorconfig, .gitignore
+
+
+
+

로컬 전용 (.gitignore, sync 관리)

+
+
.claude/rules/ — 팀 코딩 규칙 7종
+
.claude/agents/ — 서브에이전트 3종
+
.claude/skills/push, mr, release... — 스킬 6종
+
.claude/scripts/ — hook 스크립트
+
.claude/settings.local.json — 개인 설정 (GITEA_TOKEN 등)
+
docs/RELEASE-NOTES.md — /mr에서 자동 갱신
+
docs/VERSION-HISTORY.md — /version으로 생성
+
-

settings.json vs settings.local.json

-
    -
  • .claude/settings.json — 팀 정책 (Git에 커밋). 팀 전체에 적용되는 권한과 규칙.
    • -
  • .claude/settings.local.json — 개인 확장 (.gitignore). 팀 정책 위에 개인 설정 추가. 없어도 무방.
    • -
+

자동 동기화 (v1.6.1)

+

+ /push, /mr,{' '} + /release 실행 시 로컬 팀 파일의 SHA256 해시를 서버와 비교합니다. + 불일치가 감지되면 자동으로 최신 파일을 다운로드합니다. + 팀 관리 파일이 리포에 커밋되지 않으므로, 코드 롤백으로 워크플로우가 구버전으로 되돌아가는 문제가 없습니다. +

{/* 템플릿별 추가 파일 */} @@ -216,9 +213,11 @@ git push -u origin develop`}
- - 팀 워크플로우가 업데이트되면 Claude Code 세션 시작 시 알림이 표시됩니다. - /sync-team-workflow를 실행하여 최신 규칙을 동기화하세요. + + 워크플로우가 업데이트되면 /push,{' '} + /mr,{' '} + /release 실행 시 자동으로 최신 버전이 동기화됩니다. + 별도로 /sync-team-workflow를 수동 실행할 필요가 없습니다. {/* 프로젝트 구조 권장안 */}