docs: 가이드 섹션 순서 재배치 및 콘텐츠 개선

- 학습 흐름에 맞게 사이드바/CONTENT_MAP 순서 재배치 - InitialSetup: 팀 필수 vs 권장 도구 구분, 대안 도구 안내 - NexusUsage: 팀 정책 vs 개인 로컬 설정 분리, 인증 경고 강화 - StartingProject: /init-project 수행 내용 상세화, settings.json vs local 설명 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-15 19:35:35 +09:00 · 2026-02-15 19:35:35 +09:00 · 7b439a3203
--- a/src/content/InitialSetup.tsx
+++ b/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"
--- a/src/content/NexusUsage.tsx
+++ b/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/"
--- a/src/content/StartingProject.tsx
+++ b/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>

--- a/src/pages/GuidePage.tsx
+++ b/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() {
--- a/src/utils/navigation.ts
+++ b/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[] = [