docs: 개발환경 가이드 v1.6.1 기준 최신화

- InitialSetup: GITEA_TOKEN 생성 가이드 강화 (권한 테이블, settings.local.json)
- StartingProject: init-project 중심 간소화, 파일 구조 2분할 (커밋/로컬), 자동 동기화 안내
- ClaudeCodeSkills: 개발 프로세스 전체 흐름 + 권한별 시나리오 (개발자/관리자)

src/content/ClaudeCodeSkills.tsx

@@ -57,73 +57,182 @@ export default function ClaudeCodeSkills() {
         Gitea 리포 설정에서 확인할 수 있습니다.
       </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>
+
+      {/* 시각적 플로우 */}
+      <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
         steps={[
           {
-            title: '코드 수정 후 푸시 — /push',
+            title: '1. 계획 수립 — 플랜 모드',
             content: (
               <>
-                <p className="mb-2">작업 후 변경 사항을 확인하고 커밋+푸시합니다.</p>
+                <p className="mb-2">복잡한 기능은 구현 전에 계획을 먼저 세웁니다. Claude Code가 코드베이스를 분석하고 구현 방향을 설계합니다.</p>
                 <CodeBlock
                   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: (
               <>
-                <p className="mb-2">feature 브랜치에서 develop으로 MR을 생성합니다.</p>
+                <p className="mb-2">develop에서 feature 브랜치를 생성하여 독립적으로 개발합니다.</p>
+                <CodeBlock
+                  language="bash"
+                  code={`git checkout develop
+git pull origin develop
+git checkout -b feature/ISSUE-42-user-auth`}
+                />
+                <p className="text-xs text-text-muted mt-1">
+                  이슈 기반 개발 시 <code className="bg-bg-tertiary px-1 rounded">/fix-issue 42</code>를 사용하면
+                  이슈 분석 + 브랜치 생성을 자동으로 처리합니다.
+                </p>
+              </>
+            ),
+          },
+          {
+            title: '3. 개발 → /push',
+            content: (
+              <>
+                <p className="mb-2">코드 수정 후 <code className="bg-bg-tertiary px-1 rounded">/push</code>로 커밋+푸시합니다.</p>
+                <CodeBlock
+                  language="text"
+                  code={`/push
+# 1. 팀 워크플로우 해시 체크 (불일치 시 자동 동기화)
+# 2. 변경 파일 목록 + diff 요약 표시
+# 3. Conventional Commits 형식 커밋 메시지 자동 제안
+# 4. 사용자 승인 → commit + push`}
+                />
+                <Alert type="info">
+                  여러 커밋을 쌓지 말고, 하나의 기능 단위로 커밋하세요.
+                  <code className="bg-bg-tertiary px-1 rounded ml-1">/push</code>는 모든 변경을 단일 커밋으로 정리합니다.
+                </Alert>
+              </>
+            ),
+          },
+          {
+            title: '4. MR 생성 — /mr',
+            content: (
+              <>
+                <p className="mb-2">기능 완성 후 develop으로 MR(Merge Request)을 생성합니다.</p>
                 <CodeBlock
                   language="text"
                   code={`/mr
 # 1. 커밋되지 않은 변경이 있으면 커밋+푸시
-# 2. 릴리즈 노트(RELEASE-NOTES.md) 자동 갱신
+# 2. docs/RELEASE-NOTES.md [Unreleased] 자동 갱신
-# 3. 사용자 첨삭 확인 후 Gitea MR 생성
+# 3. 릴리즈 노트 초안 확인 (사용자 첨삭 가능)
-# 4. 리뷰 대기 or 봇 승인+머지 선택`}
+# 4. Gitea API로 MR 생성
+# 5. 처리 방식 선택:
+#    - 리뷰 대기 (기본) → 리뷰어가 승인 후 머지
+#    - 봇 승인+머지 → claude-bot이 즉시 승인+머지`}
                 />
-                <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">/push</code> + MR + 릴리즈 노트를 한 번에 처리합니다.
-                  MR 생성 후 리뷰 대기 또는 claude-bot 자동 승인+머지를 선택할 수 있습니다.
-                </p>
-              </>
-            ),
-          },
-          {
-            title: '릴리즈 — /release (관리자)',
-            content: (
-              <>
-                <p className="mb-2">develop → main 릴리즈 MR을 생성하고, 봇이 자동 승인합니다.</p>
-                <CodeBlock
-                  language="text"
-                  code={`/release
-# 1. develop 동기화 확인
-# 2. 릴리즈 노트 [Unreleased] → [날짜] 전환 + 압축
-# 3. develop→main MR 생성
-# 4. claude-bot 자동 승인 → 머지 → CI/CD 배포`}
-                />
-                <Alert type="warning">
-                  <code className="bg-bg-tertiary px-1 rounded">/release</code>는 리포 <strong>admin</strong> 권한이 필요합니다.
-                </Alert>
               </>
             ),
           },
         ]}
       />
 
+      {/* 권한별 시나리오 */}
+      <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>
       <p className="text-text-secondary mb-4">
@@ -161,38 +270,32 @@ export default function ClaudeCodeSkills() {
         </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">
-        스킬을 사용하려면 다음이 필요합니다.
+        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>
-      <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>
   );
 }

src/content/InitialSetup.tsx

@@ -195,51 +195,107 @@ claude --version`}
 
       <h3 className="text-lg font-bold text-text-primary mt-8 mb-4">
         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>
       <p className="text-text-secondary mb-4">
         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">/release</code> 등)을 사용하려면 Gitea API 토큰이 필요합니다.
+        <code className="bg-bg-tertiary px-1 rounded">/release</code> 등)과 Git push에 필요한 개인 토큰입니다.
       </p>
       <StepGuide
         steps={[
           {
-            title: 'Gitea에서 토큰 생성',
+            title: '토큰 생성 페이지 접속',
             content: (
               <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>
             ),
           },
+          {
+            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: '토큰 복사',
             content: (
               <Alert type="warning">
-                생성된 토큰은 <strong>한 번만 표시</strong>됩니다. 반드시 복사해서 안전한 곳에 저장하세요.
+                <strong>&quot;Generate Token&quot;</strong> 클릭 후 표시되는 토큰은 <strong>한 번만 표시</strong>됩니다. 반드시 복사해서 안전한 곳에 저장하세요.
               </Alert>
             ),
           },
           {
-            title: '환경변수 등록',
+            title: '토큰 등록',
             content: (
               <>
+                <p className="text-text-secondary text-sm mb-3">두 가지 방법 중 하나를 선택하세요.</p>
+                <div className="space-y-3">
+                  <div className="bg-bg-tertiary rounded-lg p-3">
+                    <p className="text-xs font-semibold text-accent mb-1">방법 A: settings.local.json (권장 — Claude Code 사용 시)</p>
+                    <p className="text-xs text-text-muted mb-2">
+                      <code className="bg-surface px-1 rounded">/init-project</code> 실행 시 토큰 입력 안내가 표시됩니다. 입력하면 자동 저장됩니다.
+                    </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={`# Gitea API 토큰 (Claude Code 스킬 실행에 필요)
+                      code={`export GITEA_TOKEN="생성된_토큰_붙여넣기"`}
-export GITEA_TOKEN="생성된_토큰_붙여넣기"`}
                     />
-                <CodeBlock language="bash" code="source ~/.zshrc" />
+                  </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>
   );
 }

src/content/StartingProject.tsx

@@ -81,9 +81,7 @@ export default function StartingProject() {
             content: (
               <p>
                 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>
             ),
           },
@@ -98,55 +96,45 @@ cd 새-프로젝트명`}
             ),
           },
           {
-            title: 'Claude Code로 초기화 (Claude Code 사용 시)',
+            title: '/init-project 실행',
             content: (
               <>
-                <p className="mb-2">
-                  Claude Code를 사용한다면 세션에서 프로젝트 초기화 스킬을 실행합니다.
-                </p>
                 <CodeBlock
                   language="bash"
                   code={`claude
-# 세션 내에서 실행:
+# Claude Code 세션에서 실행:
 /init-project`}
                 />
                 <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">
-                    <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>
                 </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>로
-                  수동 설정할 수 있습니다.
+                  Git hooks만 수동 설정할 수 있습니다.
-                </p>
+                </Alert>
               </>
             ),
           },
           {
-            title: 'develop 브랜치 생성',
+            title: 'develop 브랜치 생성 + 첫 feature 시작',
             content: (
               <CodeBlock
                 language="bash"
                 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">
-        모든 프로젝트 템플릿에 포함되는 공통 파일입니다. 이 파일들은 Git에 커밋되어 팀 전체가 공유합니다.
+        팀 파일은 <strong>리포에 커밋되는 부트스트랩 파일</strong>과{' '}
+        <strong>로컬 전용 팀 관리 파일</strong>로 나뉩니다. 팀 관리 파일은 .gitignore에 포함되어 리포에 커밋되지 않으며,{' '}
+        <code className="bg-bg-tertiary px-1 rounded">/sync-team-workflow</code>가 서버에서 최신 버전을 자동으로 다운로드합니다.
       </p>
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
         <div className="bg-surface border border-border-default rounded-xl p-5">
-        <div className="font-mono text-sm space-y-1.5 text-text-secondary">
+          <h4 className="font-semibold text-accent text-sm mb-3">리포에 커밋 (부트스트랩)</h4>
-          <div><span className="text-accent">.claude/</span></div>
+          <div className="font-mono text-xs space-y-1.5 text-text-secondary">
-          <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><span className="text-accent">.claude/settings.json</span> — 팀 권한 + env</div>
-          <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/workflow-version.json</span> — 버전 추적</div>
-          <div className="pl-4"><span className="text-accent">agents/</span> — 커스텀 서브에이전트 (explorer, implementer, reviewer)</div>
+            <div><span className="text-accent">.claude/skills/init-project/</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/sync-team-workflow/</span></div>
-          <div className="pl-4"><span className="text-accent">settings.json</span> — 팀 Claude 권한 정책 + env (GITEA_TOKEN 등)</div>
+            <div><span className="text-accent">.githooks/</span> — commit-msg, post-checkout, pre-commit</div>
-          <div className="pl-4 text-text-muted italic">settings.local.json — 개인 확장 설정 (.gitignore에 포함, 각자 자유)</div>
-          <div className="mt-2"><span className="text-accent">.githooks/</span></div>
-          <div className="pl-4"><span className="text-accent">commit-msg</span> — Conventional Commits 검증 훅</div>
-          <div className="pl-4"><span className="text-accent">post-checkout</span> — 체크아웃 후 자동 실행</div>
-          <div className="mt-2"><span className="text-accent">docs/</span></div>
-          <div className="pl-4"><span className="text-accent">RELEASE-NOTES.md</span> — 릴리즈 노트 (keepachangelog, /mr에서 자동 갱신)</div>
-          <div className="pl-4 text-text-muted italic">VERSION-HISTORY.md — 버전 히스토리 (SemVer, /version으로 생성)</div>
-          <div className="mt-2"><span className="text-accent">.editorconfig</span> — 에디터 공통 설정</div>
-          <div><span className="text-accent">.gitignore</span> — Git 제외 패턴</div>
             <div><span className="text-accent">CLAUDE.md</span> — 프로젝트 설명서</div>
-          <div><span className="text-accent">workflow-version.json</span> — 워크플로우 버전 추적</div>
+            <div><span className="text-accent">.editorconfig</span>, <span className="text-accent">.gitignore</span></div>
+          </div>
+        </div>
+        <div className="bg-surface border border-border-default rounded-xl p-5">
+          <h4 className="font-semibold text-info text-sm mb-3">로컬 전용 (.gitignore, sync 관리)</h4>
+          <div className="font-mono text-xs space-y-1.5 text-text-secondary">
+            <div><span className="text-info">.claude/rules/</span> — 팀 코딩 규칙 7종</div>
+            <div><span className="text-info">.claude/agents/</span> — 서브에이전트 3종</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 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>
 
       {/* 템플릿별 추가 파일 */}
@@ -216,9 +213,11 @@ git push -u origin develop`}
         </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>
 
       {/* 프로젝트 구조 권장안 */}