Merge pull request 'docs: 가이드 섹션 순서 재배치 및 콘텐츠 개선' (#6) from develop into main

Reviewed-on: #6

src/content/InitialSetup.tsx

@@ -8,10 +8,23 @@ export default function InitialSetup() {
       <h1 className="text-3xl font-bold text-text-primary mb-2">초기 환경 설정</h1>
       <p className="text-text-secondary mb-8">
         개발을 시작하기 전 필요한 도구와 설정을 안내합니다.
+        SSH 키와 Git 설정은 팀 필수이며, 런타임 관리 도구는 권장 사항입니다.
       </p>
 
+      {/* 팀 필수 설정 구분 */}
+      <div className="bg-accent-soft border border-accent/20 rounded-xl p-4 mb-8">
+        <h3 className="font-semibold text-accent text-sm mb-2">팀 필수 vs 권장 도구</h3>
+        <ul className="text-sm text-text-secondary space-y-1">
+          <li><span className="text-danger font-medium">필수</span> — SSH 키 등록, Git 설정 (@gcsc.co.kr 이메일)</li>
+          <li><span className="text-info font-medium">권장</span> — JDK/Node.js 버전 관리 도구, Claude Code (아래 안내는 권장 도구 예시이며, 동일 역할의 다른 도구 사용 가능)</li>
+        </ul>
+      </div>
+
       {/* SSH 키 생성 */}
-      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">1. SSH 키 생성 및 등록</h2>
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">
+        1. SSH 키 생성 및 등록
+        <span className="ml-2 px-2 py-0.5 bg-danger/10 text-danger rounded text-xs font-medium align-middle">필수</span>
+      </h2>
       <p className="text-text-secondary mb-4">
         Gitea에 SSH로 접근하려면 SSH 키가 필요합니다.
       </p>
@@ -52,7 +65,10 @@ export default function InitialSetup() {
       />
 
       {/* Git 설정 */}
-      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">2. Git 기본 설정</h2>
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">
+        2. Git 기본 설정
+        <span className="ml-2 px-2 py-0.5 bg-danger/10 text-danger rounded text-xs font-medium align-middle">필수</span>
+      </h2>
       <CodeBlock
         language="bash"
         filename="~/.gitconfig"
@@ -66,9 +82,14 @@ git config --global core.autocrlf input`}
       </Alert>
 
       {/* SDKMAN */}
-      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">3. SDKMAN! (JDK 관리)</h2>
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">
+        3. JDK 버전 관리
+        <span className="ml-2 px-2 py-0.5 bg-info/10 text-info rounded text-xs font-medium align-middle">권장</span>
+      </h2>
       <p className="text-text-secondary mb-4">
-        Java 프로젝트를 위해 SDKMAN!으로 JDK를 관리합니다.
+        Java 프로젝트는 프로젝트별로 JDK 버전이 다를 수 있습니다.
+        아래는 <strong>SDKMAN!</strong>을 사용한 예시이며, jenv, asdf 등 다른 버전 관리 도구를 사용해도 됩니다.
+        프로젝트의 <code className="bg-bg-tertiary px-1 rounded">.sdkmanrc</code>에 지정된 버전만 맞추면 됩니다.
       </p>
       <StepGuide
         steps={[
@@ -112,9 +133,14 @@ sdk use java 17.0.18-amzn`}
       />
 
       {/* fnm */}
-      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">4. fnm (Node.js 관리)</h2>
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">
+        4. Node.js 버전 관리
+        <span className="ml-2 px-2 py-0.5 bg-info/10 text-info rounded text-xs font-medium align-middle">권장</span>
+      </h2>
       <p className="text-text-secondary mb-4">
-        프론트엔드 프로젝트를 위해 fnm으로 Node.js를 관리합니다.
+        프론트엔드 프로젝트는 Node.js 버전 관리가 필요합니다.
+        아래는 <strong>fnm</strong>을 사용한 예시이며, nvm, asdf 등 다른 도구를 사용해도 됩니다.
+        프로젝트의 <code className="bg-bg-tertiary px-1 rounded">.node-version</code>에 지정된 버전만 맞추면 됩니다.
       </p>
       <StepGuide
         steps={[
@@ -149,9 +175,14 @@ node --version`}
       />
 
       {/* Claude Code */}
-      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">5. Claude Code 설치</h2>
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">
+        5. Claude Code 설치
+        <span className="ml-2 px-2 py-0.5 bg-info/10 text-info rounded text-xs font-medium align-middle">권장</span>
+      </h2>
       <p className="text-text-secondary mb-4">
-        AI 기반 코딩 어시스턴트로 개발 생산성을 높입니다.
+        AI 기반 코딩 어시스턴트입니다.
+        팀 프로젝트 템플릿에 Claude Code 워크플로우 설정이 포함되어 있어,
+        설치하면 팀 규칙과 스킬이 자동으로 적용됩니다.
       </p>
       <CodeBlock
         language="bash"

src/content/NexusUsage.tsx

@@ -6,21 +6,34 @@ export default function NexusUsage() {
     <div className="max-w-4xl mx-auto py-12 px-6">
       <h1 className="text-3xl font-bold text-text-primary mb-2">Nexus 사용법</h1>
       <p className="text-text-secondary mb-8">
-        Maven, Gradle, npm 프록시 설정 방법과 프라이빗 패키지 배포 가이드입니다.
+        Maven, Gradle, npm 의존성을 팀 Nexus 프록시를 통해 관리하는 방법을 안내합니다.
       </p>
 
       <Alert type="info" title="Nexus 주소">
         <strong>nexus.gc-si.dev</strong> — 웹 UI에서 저장소 목록과 패키지를 확인할 수 있습니다.
       </Alert>
 
+      {/* 팀 정책 vs 개인 설정 구분 */}
+      <div className="bg-accent-soft border border-accent/20 rounded-xl p-4 mt-6 mb-8">
+        <h3 className="font-semibold text-accent text-sm mb-2">팀 정책 vs 개인 로컬 설정</h3>
+        <ul className="text-sm text-text-secondary space-y-1">
+          <li><span className="text-accent font-medium">팀 정책</span> — 모든 팀 프로젝트는 Nexus를 프록시로 사용합니다. 레지스트리 URL은 프로젝트에 포함됩니다.</li>
+          <li><span className="text-text-muted font-medium">개인 설정</span> — 인증 정보(username/password)는 각자 홈 디렉토리 또는 환경변수에 설정합니다. 프로젝트에 포함하지 마세요.</li>
+        </ul>
+      </div>
+
       {/* Maven */}
       <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">Maven 프록시 설정</h2>
-      <p className="text-text-secondary mb-4">
-        Maven 프로젝트에서 Nexus를 프록시로 사용하려면 <code className="bg-bg-tertiary px-1 rounded">~/.m2/settings.xml</code>을 설정합니다.
+      <p className="text-text-secondary mb-2">
+        팀 프로젝트 템플릿에 Nexus 미러 URL이 포함되어 있습니다.
+        인증 정보만 각자 로컬에 설정하면 됩니다.
+      </p>
+      <p className="text-xs text-text-muted mb-4">
+        아래 파일은 개인 홈 디렉토리에 생성합니다. Git에 커밋하지 마세요.
       </p>
       <CodeBlock
         language="xml"
-        filename="~/.m2/settings.xml"
+        filename="~/.m2/settings.xml (개인 로컬 파일)"
         code={`<settings>
   <mirrors>
     <mirror>
@@ -41,12 +54,13 @@ export default function NexusUsage() {
 
       {/* Gradle */}
       <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">Gradle 프록시 설정</h2>
-      <p className="text-text-secondary mb-4">
-        <code className="bg-bg-tertiary px-1 rounded">build.gradle</code>의 repositories 블록에 Nexus를 추가합니다.
+      <p className="text-text-secondary mb-2">
+        <code className="bg-bg-tertiary px-1 rounded">build.gradle</code>의 repositories 블록은 프로젝트에 포함(팀 설정)되며,
+        인증 정보는 환경변수 또는 개인 로컬 파일에서 읽습니다.
       </p>
       <CodeBlock
         language="groovy"
-        filename="build.gradle"
+        filename="build.gradle (프로젝트에 포함)"
         code={`repositories {
     maven {
         url 'https://nexus.gc-si.dev/repository/maven-public/'
@@ -58,23 +72,33 @@ export default function NexusUsage() {
 }`}
       />
       <Alert type="info">
-        인증 정보는 <code className="bg-bg-tertiary px-1 rounded">~/.gradle/gradle.properties</code>에 <code className="bg-bg-tertiary px-1 rounded">nexusUsername</code>/<code className="bg-bg-tertiary px-1 rounded">nexusPassword</code>로 설정할 수도 있습니다.
+        인증 정보는 <code className="bg-bg-tertiary px-1 rounded">~/.gradle/gradle.properties</code>(개인 로컬 파일)에{' '}
+        <code className="bg-bg-tertiary px-1 rounded">nexusUsername</code>/<code className="bg-bg-tertiary px-1 rounded">nexusPassword</code>로
+        설정하거나, 환경변수로 설정합니다.
       </Alert>
 
       {/* npm */}
       <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">npm 프록시 설정</h2>
       <p className="text-text-secondary mb-4">
-        프로젝트 루트의 <code className="bg-bg-tertiary px-1 rounded">.npmrc</code> 파일에 Nexus 레지스트리를 설정합니다.
+        프로젝트 <code className="bg-bg-tertiary px-1 rounded">.npmrc</code>에는 레지스트리 URL만 포함합니다.
+        인증 토큰은 환경변수 또는 글로벌 <code className="bg-bg-tertiary px-1 rounded">~/.npmrc</code>에 설정합니다.
       </p>
       <CodeBlock
         language="ini"
-        filename=".npmrc"
+        filename=".npmrc (프로젝트에 포함 — URL만)"
         code={`registry=https://nexus.gc-si.dev/repository/npm-public/
-//nexus.gc-si.dev/repository/npm-public/:_auth=\${NPM_AUTH_TOKEN}
 always-auth=true`}
       />
+      <CodeBlock
+        language="ini"
+        filename="~/.npmrc (개인 로컬 파일 — 인증)"
+        code={`//nexus.gc-si.dev/repository/npm-public/:_auth=<Base64 인코딩된 인증 토큰>`}
+      />
       <Alert type="warning" title="보안 주의">
-        <code className="bg-bg-tertiary px-1 rounded">_auth</code> 값을 <code className="bg-bg-tertiary px-1 rounded">.npmrc</code>에 직접 하드코딩하지 마세요. 환경변수 또는 <code className="bg-bg-tertiary px-1 rounded">~/.npmrc</code>(글로벌)에 설정하고, 프로젝트 <code className="bg-bg-tertiary px-1 rounded">.npmrc</code>는 레지스트리 URL만 포함합니다.
+        <code className="bg-bg-tertiary px-1 rounded">_auth</code> 값을 프로젝트{' '}
+        <code className="bg-bg-tertiary px-1 rounded">.npmrc</code>에 직접 하드코딩하지 마세요.
+        인증 정보는 반드시 개인 <code className="bg-bg-tertiary px-1 rounded">~/.npmrc</code> 또는 환경변수에 설정합니다.
+        인증 토큰은 팀 관리자에게 문의하세요.
       </Alert>
 
       {/* 패키지 배포 */}
@@ -86,7 +110,7 @@ always-auth=true`}
       <h3 className="text-lg font-semibold text-text-primary mt-6 mb-3">Maven 배포</h3>
       <CodeBlock
         language="xml"
-        filename="pom.xml"
+        filename="pom.xml (프로젝트에 포함)"
         code={`<distributionManagement>
   <repository>
     <id>nexus</id>
@@ -103,7 +127,7 @@ always-auth=true`}
       <h3 className="text-lg font-semibold text-text-primary mt-6 mb-3">npm 배포</h3>
       <CodeBlock
         language="json"
-        filename="package.json"
+        filename="package.json (프로젝트에 포함)"
         code={`{
   "publishConfig": {
     "registry": "https://nexus.gc-si.dev/repository/npm-hosted/"

src/content/StartingProject.tsx

@@ -8,6 +8,7 @@ export default function StartingProject() {
       <h1 className="text-3xl font-bold text-text-primary mb-2">프로젝트 시작하기</h1>
       <p className="text-text-secondary mb-8">
         팀 템플릿을 사용해 새 프로젝트를 빠르게 시작하는 방법을 안내합니다.
+        템플릿에서 클론하면 팀 워크플로우가 자동으로 적용됩니다.
       </p>
 
       {/* 템플릿 비교 */}
@@ -80,7 +81,7 @@ export default function StartingProject() {
             content: (
               <p>
                 Gitea → <strong>gc</strong> 조직 → <strong>새 저장소</strong>를 클릭합니다.
-                <strong> "템플릿에서 생성"</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-maven</code>,{' '}
                 <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>
@@ -97,18 +98,32 @@ cd 새-프로젝트명`}
             ),
           },
           {
-            title: 'Claude Code로 초기화',
+            title: 'Claude Code로 초기화 (Claude Code 사용 시)',
             content: (
               <>
-                <p className="mb-2">Claude Code 세션에서 프로젝트 초기화 스킬을 실행합니다.</p>
+                <p className="mb-2">
+                  Claude Code를 사용한다면 세션에서 프로젝트 초기화 스킬을 실행합니다.
+                </p>
                 <CodeBlock
                   language="bash"
                   code={`claude
 # 세션 내에서 실행:
 /init-project`}
                 />
+                <div className="mt-3 bg-bg-tertiary rounded-lg p-3">
+                  <p className="text-xs text-text-secondary mb-1">
+                    <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>워크플로우 버전 검증 및 동기화</li>
+                    <li>CLAUDE.md 프로젝트 컨텍스트 확인</li>
+                  </ul>
+                </div>
                 <p className="mt-2 text-text-muted text-xs">
-                  이 명령은 팀 워크플로우 규칙, Git hooks, Claude 설정 파일을 자동으로 구성합니다.
+                  Claude Code를 사용하지 않는 경우에도 Git hooks는 클론 시 포함되어 있으며,{' '}
+                  <code className="bg-bg-tertiary px-1 rounded">git config core.hooksPath .githooks</code>로
+                  수동 설정할 수 있습니다.
                 </p>
               </>
             ),
@@ -139,14 +154,15 @@ git push -u origin develop`}
       {/* 템플릿 공통 파일 구조 */}
       <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">템플릿 공통 파일 구조</h2>
       <p className="text-text-secondary mb-4">
-        모든 프로젝트 템플릿에 포함되는 공통 파일입니다.
+        모든 프로젝트 템플릿에 포함되는 공통 파일입니다. 이 파일들은 Git에 커밋되어 팀 전체가 공유합니다.
       </p>
       <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">
           <div><span className="text-accent">.claude/</span></div>
-          <div className="pl-4"><span className="text-accent">rules/</span> — 팀 규칙 (code-style, git-workflow, naming, testing, team-policy)</div>
-          <div className="pl-4"><span className="text-accent">skills/</span> — Claude 스킬 (create-mr, fix-issue, init-project, sync-team-workflow)</div>
-          <div className="pl-4"><span className="text-accent">settings.json</span> — Claude 권한 설정</div>
+          <div className="pl-4"><span className="text-accent">rules/</span> — 팀 코딩 규칙 (code-style, git-workflow, naming, testing, team-policy)</div>
+          <div className="pl-4"><span className="text-accent">skills/</span> — 팀 Claude 스킬 (create-mr, fix-issue, init-project, sync-team-workflow)</div>
+          <div className="pl-4"><span className="text-accent">settings.json</span> — 팀 Claude 권한 정책 (Git에 커밋됨)</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>
@@ -157,6 +173,14 @@ git push -u origin develop`}
         </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>
+        <ul className="text-xs text-text-secondary space-y-1">
+          <li><code className="bg-bg-tertiary px-1 rounded">.claude/settings.json</code> — 팀 정책 (Git에 커밋). 팀 전체에 적용되는 권한과 규칙.</li>
+          <li><code className="bg-bg-tertiary px-1 rounded">.claude/settings.local.json</code> — 개인 확장 (.gitignore). 팀 정책 위에 개인 설정 추가. 없어도 무방.</li>
+        </ul>
+      </div>
+
       {/* 템플릿별 추가 파일 */}
       <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">템플릿별 추가 파일</h2>
       <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
@@ -178,14 +202,14 @@ git push -u origin develop`}
           <h4 className="font-semibold text-text-primary text-sm mb-2">template-react-ts</h4>
           <div className="font-mono text-xs space-y-1 text-text-secondary">
             <div><code className="bg-bg-tertiary px-1 rounded">.node-version</code> — Node.js 버전</div>
-            <div><code className="bg-bg-tertiary px-1 rounded">.npmrc</code> — npm 레지스트리</div>
+            <div><code className="bg-bg-tertiary px-1 rounded">.npmrc</code> — npm 레지스트리 (URL만)</div>
             <div><code className="bg-bg-tertiary px-1 rounded">.prettierrc</code> — 코드 포매터</div>
           </div>
         </div>
       </div>
 
       <Alert type="info" title="워크플로우 업데이트">
-        팀 워크플로우가 업데이트되면 세션 시작 시 알림이 표시됩니다.
+        팀 워크플로우가 업데이트되면 Claude Code 세션 시작 시 알림이 표시됩니다.
         <code className="bg-bg-tertiary px-1 rounded ml-1">/sync-team-workflow</code>를 실행하여 최신 규칙을 동기화하세요.
       </Alert>
 

src/pages/GuidePage.tsx

@@ -6,12 +6,12 @@ const CONTENT_MAP: Record<string, React.LazyExoticComponent<React.ComponentType>
   'env-intro': lazy(() => import('../content/DevEnvIntro')),
   'initial-setup': lazy(() => import('../content/InitialSetup')),
   'gitea-usage': lazy(() => import('../content/GiteaUsage')),
-  'nexus-usage': lazy(() => import('../content/NexusUsage')),
   'git-workflow': lazy(() => import('../content/GitWorkflow')),
-  'chat-bot': lazy(() => import('../content/ChatBotIntegration')),
   'starting-project': lazy(() => import('../content/StartingProject')),
-  'design-system': lazy(() => import('../content/DesignSystem')),
+  'nexus-usage': lazy(() => import('../content/NexusUsage')),
   'ci-cd': lazy(() => import('../content/CiCdGuide')),
+  'chat-bot': lazy(() => import('../content/ChatBotIntegration')),
+  'design-system': lazy(() => import('../content/DesignSystem')),
 };
 
 export function GuidePage() {

src/utils/navigation.ts

@@ -4,12 +4,12 @@ export const DEV_NAV: NavItem[] = [
   { path: '/dev/env-intro', label: '개발환경 소개' },
   { path: '/dev/initial-setup', label: '초기 환경 설정' },
   { path: '/dev/gitea-usage', label: 'Gitea 사용법' },
-  { path: '/dev/nexus-usage', label: 'Nexus 사용법' },
   { path: '/dev/git-workflow', label: 'Git 워크플로우' },
-  { path: '/dev/chat-bot', label: 'Chat 봇 연동' },
   { path: '/dev/starting-project', label: '프로젝트 시작하기' },
-  { path: '/dev/design-system', 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: '디자인 시스템' },
 ];
 
 export const ADMIN_NAV: NavItem[] = [