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

docs: 개발환경 가이드 v1.6.1 최신화 #24

병합
htlee feature/guide-v161-update 에서 develop 로 1 commits 를 머지했습니다 2026-03-08 13:21:40 +09:00
대화 0 커밋 1 파일 변경됨 3 +299 -141
3개의 변경된 파일과 299개의 추가작업 그리고 141개의 파일을 삭제
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
src/content/ClaudeCodeSkills.tsx
파일 보기

@ -57,73 +57,182 @@ export default function ClaudeCodeSkills() {
Gitea 리포 설정에서 확인할 수 있습니다. Gitea 리포 설정에서 확인할 수 있습니다.
</Alert> </Alert>
{/* 일상적인 개발 흐름 */} {/* 개발 프로세스 전체 흐름 */}
<h2 className="text-xl font-bold text-text-primary mt-10 mb-4">일상적인 개발 흐름</h2> <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">개발 프로세스 — 전체 흐름</h2>
<p className="text-text-secondary mb-4"> <p className="text-text-secondary mb-6">
Claude Code 스킬을 활용한 일반적인 개발 흐름입니다. 기능 개발부터 릴리즈까지, Claude Code 스킬을 활용한 전체 개발 흐름입니다.
</p> </p>
{/* 시각적 플로우 */}
<div className="bg-surface border border-border-default rounded-xl p-5 mb-8">
<div className="flex flex-wrap items-center gap-2 text-sm font-mono justify-center">
<span className="px-3 py-1.5 bg-accent/10 text-accent rounded-lg font-semibold">계획 수립</span>
<span className="text-text-muted">→</span>
<span className="px-3 py-1.5 bg-info/10 text-info rounded-lg font-semibold">브랜치 분리</span>
<span className="text-text-muted">→</span>
<span className="px-3 py-1.5 bg-success/10 text-success rounded-lg font-semibold">개발</span>
<span className="text-text-muted">→</span>
<span className="px-3 py-1.5 bg-warning/10 text-warning rounded-lg font-semibold">/push</span>
<span className="text-text-muted">→</span>
<span className="px-3 py-1.5 bg-info/10 text-info rounded-lg font-semibold">/mr</span>
<span className="text-text-muted">→</span>
<span className="px-3 py-1.5 bg-danger/10 text-danger rounded-lg font-semibold">/release</span>
</div>
</div>
<StepGuide <StepGuide
steps={[ steps={[
{ {
title: '코드 수정 후 푸시 — /push', title: '1. 계획 수립 — 플랜 모드',
content: ( content: (
<> <>
<p className="mb-2">작업 후 변경 사항을 확인하고 커밋+푸시합니다.</p> <p className="mb-2">복잡한 기능은 구현 전에 계획을 먼저 세웁니다. Claude Code가 코드베이스를 분석하고 구현 방향을 설계합니다.</p>
<CodeBlock <CodeBlock
language="text" language="text"
code={`/push code={`"사용자 인증 기능을 추가해줘"
# 변경 파일 목록 표시 → 커밋 메시지 자동 제안 # → Claude가 자동으로 플랜 모드 전환
# → 사용자 승인 후 커밋 + 푸시 # → 코드베이스 분석 → 구현 계획 작성
# → 사용자 승인 후 구현 시작`}
/push "feat(auth): 로그인 검증 로직 추가"
# 메시지를 직접 지정할 수도 있습니다`}
/> />
<p className="text-xs text-text-muted mt-1">3개 이상 파일 수정이 필요하거나, 아키텍처에 영향을 주는 변경은 자동으로 플랜 모드로 전환됩니다.</p>
</> </>
), ),
}, },
{ {
title: 'MR 생성 — /mr', title: '2. 브랜치 분리 — feature 브랜치 생성',
content: ( content: (
<> <>
<p className="mb-2">feature 브랜치에서 develop으로 MR을 생성합니다.</p> <p className="mb-2">develop에서 feature 브랜치를 생성하여 독립적으로 개발합니다.</p>
<CodeBlock <CodeBlock
language="text" language="bash"
code={`/mr code={`git checkout develop
# 1. 커밋되지 않은 변경이 있으면 커밋+푸시 git pull origin develop
# 2. 릴리즈 노트(RELEASE-NOTES.md) 자동 갱신 git checkout -b feature/ISSUE-42-user-auth`}
# 3. 사용자 첨삭 확인 후 Gitea MR 생성
# 4. 리뷰 대기 or 봇 승인+머지 선택`}
/> />
<p className="text-xs text-text-muted mt-1"> <p className="text-xs text-text-muted mt-1">
<code className="bg-bg-tertiary px-1 rounded">/mr</code>은{' '} 이슈 기반 개발 시 <code className="bg-bg-tertiary px-1 rounded">/fix-issue 42</code>를 사용하면
<code className="bg-bg-tertiary px-1 rounded">/push</code> + MR + 릴리즈 노트를 한 번에 처리합니다. 이슈 분석 + 브랜치 생성을 자동으로 처리합니다.
MR 생성 후 리뷰 대기 또는 claude-bot 자동 승인+머지를 선택할 수 있습니다.
</p> </p>
</> </>
), ),
}, },
{ {
title: '릴리즈 — /release (관리자)', title: '3. 개발 → /push',
content: ( content: (
<> <>
<p className="mb-2">develop → main 릴리즈 MR을 생성하고, 봇이 자동 승인합니다.</p> <p className="mb-2">코드 수정 후 <code className="bg-bg-tertiary px-1 rounded">/push</code>로 커밋+푸시합니다.</p>
<CodeBlock <CodeBlock
language="text" language="text"
code={`/release code={`/push
# 1. develop 동기화 확인 # 1. 팀 워크플로우 해시 체크 (불일치 시 자동 동기화)
# 2. 릴리즈 노트 [Unreleased] → [날짜] 전환 + 압축 # 2. 변경 파일 목록 + diff 요약 표시
# 3. develop→main MR 생성 # 3. Conventional Commits 형식 커밋 메시지 자동 제안
# 4. claude-bot 자동 승인 → 머지 → CI/CD 배포`} # 4. 사용자 승인 → commit + push`}
/> />
<Alert type="warning"> <Alert type="info">
<code className="bg-bg-tertiary px-1 rounded">/release</code>는 리포 <strong>admin</strong> 권한이 필요합니다. 여러 커밋을 쌓지 말고, 하나의 기능 단위로 커밋하세요.
<code className="bg-bg-tertiary px-1 rounded ml-1">/push</code>는 모든 변경을 단일 커밋으로 정리합니다.
</Alert> </Alert>
</> </>
), ),
}, },
{
title: '4. MR 생성 — /mr',
content: (
<>
<p className="mb-2">기능 완성 후 develop으로 MR(Merge Request)을 생성합니다.</p>
<CodeBlock
language="text"
code={`/mr
# 1. 커밋되지 않은 변경이 있으면 커밋+푸시
# 2. docs/RELEASE-NOTES.md [Unreleased] 자동 갱신
# 3. 릴리즈 노트 초안 확인 (사용자 첨삭 가능)
# 4. Gitea API로 MR 생성
# 5. 처리 방식 선택:
# - 리뷰 대기 (기본) → 리뷰어가 승인 후 머지
# - 봇 승인+머지 → claude-bot이 즉시 승인+머지`}
/>
</>
),
},
]} ]}
/> />
{/* 권한별 시나리오 */}
<h2 className="text-xl font-bold text-text-primary mt-10 mb-4">권한별 시나리오</h2>
<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
<div className="bg-surface border border-info/30 rounded-xl p-5">
<h4 className="font-semibold text-info mb-3 flex items-center gap-2">
<span className="px-2 py-0.5 bg-info/10 text-info rounded text-xs font-medium">push 권한</span>
개발자
</h4>
<div className="text-sm text-text-secondary space-y-2">
<p className="font-medium text-text-primary">사용 가능: /push, /mr, /create-mr, /fix-issue</p>
<div className="bg-bg-tertiary rounded-lg p-3 text-xs space-y-1.5">
<div className="flex items-center gap-2">
<span className="text-success">1.</span>
<span><code className="bg-surface px-1 rounded">/push</code> — 변경 커밋+푸시</span>
</div>
<div className="flex items-center gap-2">
<span className="text-success">2.</span>
<span><code className="bg-surface px-1 rounded">/mr</code> — develop으로 MR 생성</span>
</div>
<div className="flex items-center gap-2">
<span className="text-success">3.</span>
<span>&quot;리뷰 대기&quot; 선택 → 관리자에게 리뷰 요청</span>
</div>
<div className="flex items-center gap-2">
<span className="text-info">→</span>
<span>관리자가 Gitea에서 리뷰 + 승인 → 머지</span>
</div>
</div>
<Alert type="info">
<code className="bg-bg-tertiary px-1 rounded">/release</code>와 <code className="bg-bg-tertiary px-1 rounded">/version</code>은
admin 권한이 필요합니다. 관리자에게 요청하세요.
</Alert>
</div>
</div>
<div className="bg-surface border border-danger/30 rounded-xl p-5">
<h4 className="font-semibold text-danger mb-3 flex items-center gap-2">
<span className="px-2 py-0.5 bg-danger/10 text-danger rounded text-xs font-medium">admin 권한</span>
관리자
</h4>
<div className="text-sm text-text-secondary space-y-2">
<p className="font-medium text-text-primary">추가 사용: /release, /version</p>
<div className="bg-bg-tertiary rounded-lg p-3 text-xs space-y-1.5">
<div className="flex items-center gap-2">
<span className="text-success">1.</span>
<span><code className="bg-surface px-1 rounded">/push</code> → <code className="bg-surface px-1 rounded">/mr</code> → &quot;봇 승인+머지&quot; 선택</span>
</div>
<div className="flex items-center gap-2">
<span className="text-success">2.</span>
<span>feature 머지 완료 후, develop에서:</span>
</div>
<div className="flex items-center gap-2">
<span className="text-success">3.</span>
<span><code className="bg-surface px-1 rounded">/release</code> — develop→main 릴리즈 MR</span>
</div>
<div className="flex items-center gap-2 pl-4 text-text-muted">
<span>↳ 릴리즈 노트 날짜 전환 + 이전 넘버링 압축</span>
</div>
<div className="flex items-center gap-2 pl-4 text-text-muted">
<span>↳ claude-bot 자동 승인 → 머지 → CI/CD 배포</span>
</div>
<div className="flex items-center gap-2">
<span className="text-success">4.</span>
<span><code className="bg-surface px-1 rounded">/version</code> — VERSION-HISTORY.md 생성 (SemVer)</span>
</div>
</div>
</div>
</div>
</div>
<Alert type="info">
권한은 Gitea 리포지토리 단위로 관리됩니다. <strong>gc</strong> 조직 →{' '}
<strong>developers</strong> 팀 소속이면 push 권한이 자동 부여됩니다.
admin 권한은 프로젝트 관리자가 리포 설정에서 직접 부여합니다.
</Alert>
{/* 커스텀 에이전트 */} {/* 커스텀 에이전트 */}
<h2 className="text-xl font-bold text-text-primary mt-10 mb-4">커스텀 에이전트</h2> <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">커스텀 에이전트</h2>
<p className="text-text-secondary mb-4"> <p className="text-text-secondary mb-4">
@ -161,38 +270,32 @@ export default function ClaudeCodeSkills() {
</div> </div>
</div> </div>
{/* 사전 준비 */} {/* 시작하기 */}
<h2 className="text-xl font-bold text-text-primary mt-10 mb-4">사전 준비</h2> <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">시작하기</h2>
<p className="text-text-secondary mb-4"> <p className="text-text-secondary mb-4">
스킬을 사용하려면 다음이 필요합니다. Claude Code 스킬을 사용하려면 프로젝트에서 <code className="bg-bg-tertiary px-1 rounded">/init-project</code>를 한 번 실행하면 됩니다.
</p>
<div className="bg-surface border border-border-default rounded-xl p-5">
<div className="space-y-3 text-sm">
<div className="flex items-start gap-3">
<span className="px-2 py-0.5 bg-accent/10 text-accent rounded text-xs font-semibold mt-0.5">1</span>
<span className="text-text-secondary">Claude Code 설치: <code className="bg-bg-tertiary px-1 rounded">npm install -g @anthropic-ai/claude-code</code></span>
</div>
<div className="flex items-start gap-3">
<span className="px-2 py-0.5 bg-accent/10 text-accent rounded text-xs font-semibold mt-0.5">2</span>
<span className="text-text-secondary">프로젝트에서 <code className="bg-bg-tertiary px-1 rounded">claude</code> 실행 → <code className="bg-bg-tertiary px-1 rounded">/init-project</code></span>
</div>
<div className="flex items-start gap-3">
<span className="px-2 py-0.5 bg-accent/10 text-accent rounded text-xs font-semibold mt-0.5">3</span>
<span className="text-text-secondary">GITEA_TOKEN 설정 안내에 따라 토큰 입력 (→ <strong>초기 환경 설정</strong> 가이드 참고)</span>
</div>
</div>
</div>
<p className="text-xs text-text-muted mt-2">
<code className="bg-bg-tertiary px-1 rounded">CLAUDE_BOT_TOKEN</code>은{' '}
<code className="bg-bg-tertiary px-1 rounded">settings.json</code>에 팀 공통으로 포함되어 있어 별도 설정이 필요 없습니다.
팀 워크플로우(rules, skills, agents)는 <code className="bg-bg-tertiary px-1 rounded">/push</code> 실행 시 서버 해시 비교를 통해 자동 동기화됩니다.
</p> </p>
<ul className="space-y-2 text-text-secondary">
<li className="flex items-start gap-2">
<span className="text-accent mt-0.5">•</span>
<span>
<strong>GITEA_TOKEN</strong> 환경변수 설정 — <strong>초기 환경 설정</strong> 가이드의
&quot;Gitea API 토큰 설정&quot; 참고
</span>
</li>
<li className="flex items-start gap-2">
<span className="text-accent mt-0.5">•</span>
<span>
<strong>Claude Code 설치</strong> — <code className="bg-bg-tertiary px-1 rounded">npm install -g @anthropic-ai/claude-code</code>
</span>
</li>
<li className="flex items-start gap-2">
<span className="text-accent mt-0.5">•</span>
<span>
<strong>프로젝트 초기화</strong> — <code className="bg-bg-tertiary px-1 rounded">/init-project</code> 실행으로 팀 설정 자동 적용
</span>
</li>
</ul>
<Alert type="info">
<code className="bg-bg-tertiary px-1 rounded">GITEA_TOKEN</code>은{' '}
<code className="bg-bg-tertiary px-1 rounded">settings.json</code>의{' '}
<code className="bg-bg-tertiary px-1 rounded">env</code> 필드에서도 설정할 수 있습니다.
환경변수와 settings.json 모두 설정된 경우 환경변수가 우선합니다.
</Alert>
</div> </div>
); );
} }

90
src/content/InitialSetup.tsx
파일 보기

@ -195,51 +195,107 @@ claude --version`}
<h3 className="text-lg font-bold text-text-primary mt-8 mb-4"> <h3 className="text-lg font-bold text-text-primary mt-8 mb-4">
Gitea API 토큰 설정 Gitea API 토큰 설정
<span className="ml-2 px-2 py-0.5 bg-danger/10 text-danger rounded text-xs font-medium align-middle">필수</span>
</h3> </h3>
<p className="text-text-secondary mb-4"> <p className="text-text-secondary mb-4">
Claude Code 스킬(<code className="bg-bg-tertiary px-1 rounded">/push</code>,{' '} Claude Code 스킬(<code className="bg-bg-tertiary px-1 rounded">/push</code>,{' '}
<code className="bg-bg-tertiary px-1 rounded">/mr</code>,{' '} <code className="bg-bg-tertiary px-1 rounded">/mr</code>,{' '}
<code className="bg-bg-tertiary px-1 rounded">/release</code> 등)을 사용하려면 Gitea API 토큰이 필요합니다. <code className="bg-bg-tertiary px-1 rounded">/release</code> 등)과 Git push에 필요한 개인 토큰입니다.
</p> </p>
<StepGuide <StepGuide
steps={[ steps={[
{ {
title: 'Gitea에서 토큰 생성', title: '토큰 생성 페이지 접속',
content: ( content: (
<p> <p>
Gitea 접속 → 우측 상단 프로필 → <strong>설정</strong> → <strong>애플리케이션</strong> → <a href="https://gitea.gc-si.dev/user/settings/applications" target="_blank" rel="noopener noreferrer" className="text-accent hover:underline">
&quot;액세스 토큰 관리&quot; 섹션에서 토큰 이름을 입력하고 <strong>토큰 생성</strong>을 클릭합니다. gitea.gc-si.dev/user/settings/applications
</a>
{' '}접속 → &quot;Manage Access Tokens&quot; 섹션에서 <strong>&quot;Generate New Token&quot;</strong> 클릭
</p> </p>
), ),
}, },
{
title: '토큰 정보 입력',
content: (
<>
<p className="mb-3">
<strong>Token Name:</strong> <code className="bg-bg-tertiary px-1 rounded">claude-code</code> (자유롭게 지정)<br />
<strong>Repository and Organization Access:</strong> <em>All (public, private, and limited)</em>
</p>
<p className="mb-2 font-medium text-text-primary text-sm">Select permissions (아래 4개만 설정, 나머지는 No Access 유지):</p>
<div className="overflow-x-auto">
<table className="w-full bg-bg-tertiary rounded-lg overflow-hidden text-sm">
<thead>
<tr className="bg-surface">
<th className="text-left px-3 py-2 font-semibold text-text-primary">항목</th>
<th className="text-left px-3 py-2 font-semibold text-text-primary">권한</th>
<th className="text-left px-3 py-2 font-semibold text-text-primary">용도</th>
</tr>
</thead>
<tbody className="divide-y divide-border-subtle">
<tr><td className="px-3 py-2 font-mono text-xs">issue</td><td className="px-3 py-2">Read and Write</td><td className="px-3 py-2 text-text-muted">/fix-issue 이슈 조회/코멘트</td></tr>
<tr><td className="px-3 py-2 font-mono text-xs">organization</td><td className="px-3 py-2">Read</td><td className="px-3 py-2 text-text-muted">gc 조직 리포 접근</td></tr>
<tr><td className="px-3 py-2 font-mono text-xs">repository</td><td className="px-3 py-2">Read and Write</td><td className="px-3 py-2 text-text-muted">/push, /mr, /release API 호출</td></tr>
<tr><td className="px-3 py-2 font-mono text-xs">user</td><td className="px-3 py-2">Read</td><td className="px-3 py-2 text-text-muted">API 사용자 인증 확인</td></tr>
</tbody>
</table>
</div>
</>
),
},
{ {
title: '토큰 복사', title: '토큰 복사',
content: ( content: (
<Alert type="warning"> <Alert type="warning">
생성된 토큰은 <strong>한 번만 표시</strong>됩니다. 반드시 복사해서 안전한 곳에 저장하세요. <strong>&quot;Generate Token&quot;</strong> 클릭 후 표시되는 토큰은 <strong>한 번만 표시</strong>됩니다. 반드시 복사해서 안전한 곳에 저장하세요.
</Alert> </Alert>
), ),
}, },
{ {
title: '환경변수 등록', title: '토큰 등록',
content: ( content: (
<> <>
<CodeBlock <p className="text-text-secondary text-sm mb-3">두 가지 방법 중 하나를 선택하세요.</p>
language="bash" <div className="space-y-3">
filename="~/.zshrc" <div className="bg-bg-tertiary rounded-lg p-3">
code={`# Gitea API 토큰 (Claude Code 스킬 실행에 필요) <p className="text-xs font-semibold text-accent mb-1">방법 A: settings.local.json (권장 — Claude Code 사용 시)</p>
export GITEA_TOKEN="생성된_토큰_붙여넣기"`} <p className="text-xs text-text-muted mb-2">
/> <code className="bg-surface px-1 rounded">/init-project</code> 실행 시 토큰 입력 안내가 표시됩니다. 입력하면 자동 저장됩니다.
<CodeBlock language="bash" code="source ~/.zshrc" /> </p>
<CodeBlock
language="json"
filename=".claude/settings.local.json"
code={`{
"env": {
"GITEA_TOKEN": "생성된_토큰_붙여넣기"
}
}`}
/>
<p className="text-xs text-text-muted mt-1">이 파일은 .gitignore에 포함되어 리포에 커밋되지 않습니다.</p>
</div>
<div className="bg-bg-tertiary rounded-lg p-3">
<p className="text-xs font-semibold text-text-secondary mb-1">방법 B: 환경변수 (~/.zshrc)</p>
<CodeBlock
language="bash"
filename="~/.zshrc"
code={`export GITEA_TOKEN="생성된_토큰_붙여넣기"`}
/>
</div>
</div>
</> </>
), ),
}, },
]} ]}
/> />
<Alert type="info">
<code className="bg-bg-tertiary px-1 rounded">CLAUDE_BOT_TOKEN</code>은 프로젝트{' '} <div className="bg-accent-soft border border-accent/20 rounded-xl p-4 mt-4">
<code className="bg-bg-tertiary px-1 rounded">settings.json</code>에 팀 공통으로 포함되어 있어 별도 설정이 필요 없습니다. <h4 className="font-semibold text-accent text-sm mb-2">GITEA_TOKEN vs CLAUDE_BOT_TOKEN</h4>
</Alert> <ul className="text-xs text-text-secondary space-y-1">
<li><strong>GITEA_TOKEN</strong> (개인) — 각자 생성. <code className="bg-bg-tertiary px-1 rounded">/push</code>, <code className="bg-bg-tertiary px-1 rounded">/mr</code>, <code className="bg-bg-tertiary px-1 rounded">/release</code> 등 Git API 호출에 사용</li>
<li><strong>CLAUDE_BOT_TOKEN</strong> (팀 공용) — <code className="bg-bg-tertiary px-1 rounded">settings.json</code>에 포함되어 자동 적용. PR 자동 승인용 봇 계정 토큰. 별도 설정 불필요</li>
</ul>
</div>
</div> </div>
); );
} }

123
src/content/StartingProject.tsx
파일 보기

@ -81,9 +81,7 @@ export default function StartingProject() {
content: ( content: (
<p> <p>
Gitea → <strong>gc</strong> 조직 → <strong>새 저장소</strong>를 클릭합니다. Gitea → <strong>gc</strong> 조직 → <strong>새 저장소</strong>를 클릭합니다.
<strong> &quot;템플릿에서 생성&quot;</strong>에서 프로젝트 유형에 맞는 템플릿(<code className="bg-bg-tertiary px-1 rounded">template-java-maven</code>,{' '} <strong> &quot;템플릿에서 생성&quot;</strong>에서 프로젝트 유형에 맞는 템플릿을 선택하고 프로젝트 이름을 입력합니다.
<code className="bg-bg-tertiary px-1 rounded">template-java-gradle</code>,{' '}
<code className="bg-bg-tertiary px-1 rounded">template-react-ts</code>)을 선택하고 프로젝트 이름을 입력합니다.
</p> </p>
), ),
}, },
@ -98,55 +96,45 @@ cd 새-프로젝트명`}
), ),
}, },
{ {
title: 'Claude Code로 초기화 (Claude Code 사용 시)', title: '/init-project 실행',
content: ( content: (
<> <>
<p className="mb-2">
Claude Code를 사용한다면 세션에서 프로젝트 초기화 스킬을 실행합니다.
</p>
<CodeBlock <CodeBlock
language="bash" language="bash"
code={`claude code={`claude
# 세션 내에서 실행: # Claude Code 세션에서 실행:
/init-project`} /init-project`}
/> />
<div className="mt-3 bg-bg-tertiary rounded-lg p-3"> <div className="mt-3 bg-bg-tertiary rounded-lg p-3">
<p className="text-xs text-text-secondary mb-1"> <p className="text-xs font-semibold text-text-primary mb-2">/init-project가 한 번에 처리하는 작업:</p>
<strong className="text-text-primary">/init-project</strong>가 수행하는 작업:
</p>
<ul className="text-xs text-text-muted space-y-0.5 list-disc list-inside"> <ul className="text-xs text-text-muted space-y-0.5 list-disc list-inside">
<li>Git hooks 경로 설정 (<code>.githooks/</code>를 로컬 hooks로 연결)</li> <li>프로젝트 분석 (빌드 도구, 프레임워크, lint 자동 감지)</li>
<li>워크플로우 버전 검증 및 동기화</li> <li>CLAUDE.md 프로젝트 설명서 생성</li>
<li>CLAUDE.md 프로젝트 컨텍스트 확인</li> <li>settings.json 팀 표준 설정 다운로드</li>
<li>memory 디렉토리 초기화 (프로젝트 분석 기반)</li> <li><strong>GITEA_TOKEN 설정 안내</strong> (미설정 시 토큰 생성 가이드 표시 → settings.local.json 자동 저장)</li>
<li>hook 스크립트 생성 (<code>.claude/scripts/</code>)</li> <li>Git hooks 경로 설정 + pre-commit 빌드 검증</li>
<li>lint 도구 감지 + 설정 확인</li> <li>.gitignore에 팀 관리 경로 추가</li>
<li>memory 디렉토리 초기화</li>
<li><strong>팀 워크플로우 자동 동기화</strong> (서버에서 최신 rules, skills, agents, scripts 다운로드)</li>
</ul> </ul>
</div> </div>
<p className="mt-2 text-text-muted text-xs"> <Alert type="info">
Claude Code를 사용하지 않는 경우에도 Git hooks는 클론 시 포함되어 있으며,{' '} Claude Code를 사용하지 않는 경우:{' '}
<code className="bg-bg-tertiary px-1 rounded">git config core.hooksPath .githooks</code>로 <code className="bg-bg-tertiary px-1 rounded">git config core.hooksPath .githooks</code>로
수동 설정할 수 있습니다. Git hooks만 수동 설정할 수 있습니다.
</p> </Alert>
</> </>
), ),
}, },
{ {
title: 'develop 브랜치 생성', title: 'develop 브랜치 생성 + 첫 feature 시작',
content: ( content: (
<CodeBlock <CodeBlock
language="bash" language="bash"
code={`git checkout -b develop code={`git checkout -b develop
git push -u origin develop`} git push -u origin develop
/>
), git checkout -b feature/ISSUE-1-project-setup
},
{
title: '첫 feature 브랜치 시작',
content: (
<CodeBlock
language="bash"
code={`git checkout -b feature/ISSUE-1-project-setup
# 코딩 시작!`} # 코딩 시작!`}
/> />
), ),
@ -154,39 +142,48 @@ git push -u origin develop`}
]} ]}
/> />
{/* 템플릿 공통 파일 구조 */} {/* 프로젝트 파일 구조 */}
<h2 className="text-xl font-bold text-text-primary mt-10 mb-4">템플릿 공통 파일 구조</h2> <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">프로젝트 파일 구조</h2>
<p className="text-text-secondary mb-4"> <p className="text-text-secondary mb-4">
모든 프로젝트 템플릿에 포함되는 공통 파일입니다. 이 파일들은 Git에 커밋되어 팀 전체가 공유합니다. 팀 파일은 <strong>리포에 커밋되는 부트스트랩 파일</strong>과{' '}
<strong>로컬 전용 팀 관리 파일</strong>로 나뉩니다. 팀 관리 파일은 .gitignore에 포함되어 리포에 커밋되지 않으며,{' '}
<code className="bg-bg-tertiary px-1 rounded">/sync-team-workflow</code>가 서버에서 최신 버전을 자동으로 다운로드합니다.
</p> </p>
<div className="bg-surface border border-border-default rounded-xl p-5"> <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
<div className="font-mono text-sm space-y-1.5 text-text-secondary"> <div className="bg-surface border border-border-default rounded-xl p-5">
<div><span className="text-accent">.claude/</span></div> <h4 className="font-semibold text-accent text-sm mb-3">리포에 커밋 (부트스트랩)</h4>
<div className="pl-4"><span className="text-accent">rules/</span> — 팀 코딩 규칙 (code-style, git-workflow, naming, testing, team-policy, release-notes-guide, subagent-policy)</div> <div className="font-mono text-xs space-y-1.5 text-text-secondary">
<div className="pl-4"><span className="text-accent">skills/</span> — 팀 Claude 스킬 (push, mr, release, version, create-mr, fix-issue, init-project, sync-team-workflow)</div> <div><span className="text-accent">.claude/settings.json</span> — 팀 권한 + env</div>
<div className="pl-4"><span className="text-accent">agents/</span> — 커스텀 서브에이전트 (explorer, implementer, reviewer)</div> <div><span className="text-accent">.claude/workflow-version.json</span> — 버전 추적</div>
<div className="pl-4"><span className="text-accent">scripts/</span> — hook 스크립트 (on-pre-compact, on-post-compact, on-commit)</div> <div><span className="text-accent">.claude/skills/init-project/</span></div>
<div className="pl-4"><span className="text-accent">settings.json</span> — 팀 Claude 권한 정책 + env (GITEA_TOKEN 등)</div> <div><span className="text-accent">.claude/skills/sync-team-workflow/</span></div>
<div className="pl-4 text-text-muted italic">settings.local.json — 개인 확장 설정 (.gitignore에 포함, 각자 자유)</div> <div><span className="text-accent">.githooks/</span> — commit-msg, post-checkout, pre-commit</div>
<div className="mt-2"><span className="text-accent">.githooks/</span></div> <div><span className="text-accent">CLAUDE.md</span> — 프로젝트 설명서</div>
<div className="pl-4"><span className="text-accent">commit-msg</span> — Conventional Commits 검증 훅</div> <div><span className="text-accent">.editorconfig</span>, <span className="text-accent">.gitignore</span></div>
<div className="pl-4"><span className="text-accent">post-checkout</span> — 체크아웃 후 자동 실행</div> </div>
<div className="mt-2"><span className="text-accent">docs/</span></div> </div>
<div className="pl-4"><span className="text-accent">RELEASE-NOTES.md</span> — 릴리즈 노트 (keepachangelog, /mr에서 자동 갱신)</div> <div className="bg-surface border border-border-default rounded-xl p-5">
<div className="pl-4 text-text-muted italic">VERSION-HISTORY.md — 버전 히스토리 (SemVer, /version으로 생성)</div> <h4 className="font-semibold text-info text-sm mb-3">로컬 전용 (.gitignore, sync 관리)</h4>
<div className="mt-2"><span className="text-accent">.editorconfig</span> — 에디터 공통 설정</div> <div className="font-mono text-xs space-y-1.5 text-text-secondary">
<div><span className="text-accent">.gitignore</span> — Git 제외 패턴</div> <div><span className="text-info">.claude/rules/</span> — 팀 코딩 규칙 7종</div>
<div><span className="text-accent">CLAUDE.md</span> — 프로젝트 설명서</div> <div><span className="text-info">.claude/agents/</span> — 서브에이전트 3종</div>
<div><span className="text-accent">workflow-version.json</span> — 워크플로우 버전 추적</div> <div><span className="text-info">.claude/skills/push, mr, release...</span> — 스킬 6종</div>
<div><span className="text-info">.claude/scripts/</span> — hook 스크립트</div>
<div className="mt-2 text-text-muted italic">.claude/settings.local.json — 개인 설정 (GITEA_TOKEN 등)</div>
<div className="mt-2"><span className="text-info">docs/RELEASE-NOTES.md</span> — /mr에서 자동 갱신</div>
<div className="text-text-muted italic">docs/VERSION-HISTORY.md — /version으로 생성</div>
</div>
</div> </div>
</div> </div>
<div className="bg-accent-soft border border-accent/20 rounded-xl p-4 mt-4 mb-6"> <div className="bg-accent-soft border border-accent/20 rounded-xl p-4 mt-4 mb-6">
<h4 className="font-semibold text-accent text-sm mb-2">settings.json vs settings.local.json</h4> <h4 className="font-semibold text-accent text-sm mb-2">자동 동기화 (v1.6.1)</h4>
<ul className="text-xs text-text-secondary space-y-1"> <p className="text-xs text-text-secondary">
<li><code className="bg-bg-tertiary px-1 rounded">.claude/settings.json</code> — 팀 정책 (Git에 커밋). 팀 전체에 적용되는 권한과 규칙.</li> <code className="bg-bg-tertiary px-1 rounded">/push</code>, <code className="bg-bg-tertiary px-1 rounded">/mr</code>,{' '}
<li><code className="bg-bg-tertiary px-1 rounded">.claude/settings.local.json</code> — 개인 확장 (.gitignore). 팀 정책 위에 개인 설정 추가. 없어도 무방.</li> <code className="bg-bg-tertiary px-1 rounded">/release</code> 실행 시 로컬 팀 파일의 SHA256 해시를 서버와 비교합니다.
</ul> 불일치가 감지되면 자동으로 최신 파일을 다운로드합니다.
팀 관리 파일이 리포에 커밋되지 않으므로, 코드 롤백으로 워크플로우가 구버전으로 되돌아가는 문제가 없습니다.
</p>
</div> </div>
{/* 템플릿별 추가 파일 */} {/* 템플릿별 추가 파일 */}
@ -216,9 +213,11 @@ git push -u origin develop`}
</div> </div>
</div> </div>
<Alert type="info" title="워크플로우 업데이트"> <Alert type="info" title="워크플로우 자동 동기화">
팀 워크플로우가 업데이트되면 Claude Code 세션 시작 시 알림이 표시됩니다. 워크플로우가 업데이트되면 <code className="bg-bg-tertiary px-1 rounded">/push</code>,{' '}
<code className="bg-bg-tertiary px-1 rounded ml-1">/sync-team-workflow</code>를 실행하여 최신 규칙을 동기화하세요. <code className="bg-bg-tertiary px-1 rounded">/mr</code>,{' '}
<code className="bg-bg-tertiary px-1 rounded">/release</code> 실행 시 자동으로 최신 버전이 동기화됩니다.
별도로 <code className="bg-bg-tertiary px-1 rounded ml-1">/sync-team-workflow</code>를 수동 실행할 필요가 없습니다.
</Alert> </Alert>
{/* 프로젝트 구조 권장안 */} {/* 프로젝트 구조 권장안 */}