From 7b439a3203735cc8ec5f8fc7df4042f0824a4aad Mon Sep 17 00:00:00 2001 From: htlee Date: Sun, 15 Feb 2026 19:35:35 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EC=84=B9?= =?UTF-8?q?=EC=85=98=20=EC=88=9C=EC=84=9C=20=EC=9E=AC=EB=B0=B0=EC=B9=98=20?= =?UTF-8?q?=EB=B0=8F=20=EC=BD=98=ED=85=90=EC=B8=A0=20=EA=B0=9C=EC=84=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 학습 흐름에 맞게 사이드바/CONTENT_MAP 순서 재배치 - InitialSetup: 팀 필수 vs 권장 도구 구분, 대안 도구 안내 - NexusUsage: 팀 정책 vs 개인 로컬 설정 분리, 인증 경고 강화 - StartingProject: /init-project 수행 내용 상세화, settings.json vs local 설명 Co-Authored-By: Claude Sonnet 4.5 --- src/content/InitialSetup.tsx | 47 ++++++++++++++++++++++++----- src/content/NexusUsage.tsx | 52 ++++++++++++++++++++++++--------- src/content/StartingProject.tsx | 44 +++++++++++++++++++++------- src/pages/GuidePage.tsx | 6 ++-- src/utils/navigation.ts | 6 ++-- 5 files changed, 117 insertions(+), 38 deletions(-) diff --git a/src/content/InitialSetup.tsx b/src/content/InitialSetup.tsx index 6abfd3f..6385c72 100644 --- a/src/content/InitialSetup.tsx +++ b/src/content/InitialSetup.tsx @@ -8,10 +8,23 @@ export default function InitialSetup() {

초기 환경 설정

개발을 시작하기 전 필요한 도구와 설정을 안내합니다. + SSH 키와 Git 설정은 팀 필수이며, 런타임 관리 도구는 권장 사항입니다.

+ {/* 팀 필수 설정 구분 */} +
+

팀 필수 vs 권장 도구

+
    +
  • 필수 — SSH 키 등록, Git 설정 (@gcsc.co.kr 이메일)
    • +
  • 권장 — JDK/Node.js 버전 관리 도구, Claude Code (아래 안내는 권장 도구 예시이며, 동일 역할의 다른 도구 사용 가능)
    • +
+
+ {/* SSH 키 생성 */} -

1. SSH 키 생성 및 등록

+

+ 1. SSH 키 생성 및 등록 + 필수 +

Gitea에 SSH로 접근하려면 SSH 키가 필요합니다.

@@ -52,7 +65,10 @@ export default function InitialSetup() { /> {/* Git 설정 */} -

2. Git 기본 설정

+

+ 2. Git 기본 설정 + 필수 +

{/* SDKMAN */} -

3. SDKMAN! (JDK 관리)

+

+ 3. JDK 버전 관리 + 권장 +

- Java 프로젝트를 위해 SDKMAN!으로 JDK를 관리합니다. + Java 프로젝트는 프로젝트별로 JDK 버전이 다를 수 있습니다. + 아래는 SDKMAN!을 사용한 예시이며, jenv, asdf 등 다른 버전 관리 도구를 사용해도 됩니다. + 프로젝트의 .sdkmanrc에 지정된 버전만 맞추면 됩니다.

{/* fnm */} -

4. fnm (Node.js 관리)

+

+ 4. Node.js 버전 관리 + 권장 +

- 프론트엔드 프로젝트를 위해 fnm으로 Node.js를 관리합니다. + 프론트엔드 프로젝트는 Node.js 버전 관리가 필요합니다. + 아래는 fnm을 사용한 예시이며, nvm, asdf 등 다른 도구를 사용해도 됩니다. + 프로젝트의 .node-version에 지정된 버전만 맞추면 됩니다.

{/* Claude Code */} -

5. Claude Code 설치

+

+ 5. Claude Code 설치 + 권장 +

- AI 기반 코딩 어시스턴트로 개발 생산성을 높입니다. + AI 기반 코딩 어시스턴트입니다. + 팀 프로젝트 템플릿에 Claude Code 워크플로우 설정이 포함되어 있어, + 설치하면 팀 규칙과 스킬이 자동으로 적용됩니다.

Nexus 사용법

- Maven, Gradle, npm 프록시 설정 방법과 프라이빗 패키지 배포 가이드입니다. + Maven, Gradle, npm 의존성을 팀 Nexus 프록시를 통해 관리하는 방법을 안내합니다.

nexus.gc-si.dev — 웹 UI에서 저장소 목록과 패키지를 확인할 수 있습니다. + {/* 팀 정책 vs 개인 설정 구분 */} +
+

팀 정책 vs 개인 로컬 설정

+
    +
  • 팀 정책 — 모든 팀 프로젝트는 Nexus를 프록시로 사용합니다. 레지스트리 URL은 프로젝트에 포함됩니다.
    • +
  • 개인 설정 — 인증 정보(username/password)는 각자 홈 디렉토리 또는 환경변수에 설정합니다. 프로젝트에 포함하지 마세요.
    • +
+
+ {/* Maven */}

Maven 프록시 설정

-

- Maven 프로젝트에서 Nexus를 프록시로 사용하려면 ~/.m2/settings.xml을 설정합니다. +

+ 팀 프로젝트 템플릿에 Nexus 미러 URL이 포함되어 있습니다. + 인증 정보만 각자 로컬에 설정하면 됩니다. +

+

+ 아래 파일은 개인 홈 디렉토리에 생성합니다. Git에 커밋하지 마세요.

@@ -41,12 +54,13 @@ export default function NexusUsage() { {/* Gradle */}

Gradle 프록시 설정

-

- build.gradle의 repositories 블록에 Nexus를 추가합니다. +

+ build.gradle의 repositories 블록은 프로젝트에 포함(팀 설정)되며, + 인증 정보는 환경변수 또는 개인 로컬 파일에서 읽습니다.

- 인증 정보는 ~/.gradle/gradle.properties에 nexusUsername/nexusPassword로 설정할 수도 있습니다. + 인증 정보는 ~/.gradle/gradle.properties(개인 로컬 파일)에{' '} + nexusUsername/nexusPassword로 + 설정하거나, 환경변수로 설정합니다. {/* npm */}

npm 프록시 설정

- 프로젝트 루트의 .npmrc 파일에 Nexus 레지스트리를 설정합니다. + 프로젝트 .npmrc에는 레지스트리 URL만 포함합니다. + 인증 토큰은 환경변수 또는 글로벌 ~/.npmrc에 설정합니다.

+ `} + /> - _auth 값을 .npmrc에 직접 하드코딩하지 마세요. 환경변수 또는 ~/.npmrc(글로벌)에 설정하고, 프로젝트 .npmrc는 레지스트리 URL만 포함합니다. + _auth 값을 프로젝트{' '} + .npmrc에 직접 하드코딩하지 마세요. + 인증 정보는 반드시 개인 ~/.npmrc 또는 환경변수에 설정합니다. + 인증 토큰은 팀 관리자에게 문의하세요. {/* 패키지 배포 */} @@ -86,7 +110,7 @@ always-auth=true`}

Maven 배포

nexus @@ -103,7 +127,7 @@ always-auth=true`}

npm 배포

프로젝트 시작하기

팀 템플릿을 사용해 새 프로젝트를 빠르게 시작하는 방법을 안내합니다. + 템플릿에서 클론하면 팀 워크플로우가 자동으로 적용됩니다.

{/* 템플릿 비교 */} @@ -80,7 +81,7 @@ export default function StartingProject() { content: (

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

@@ -97,18 +98,32 @@ cd 새-프로젝트명`} ), }, { - title: 'Claude Code로 초기화', + title: 'Claude Code로 초기화 (Claude Code 사용 시)', content: ( <> -

Claude Code 세션에서 프로젝트 초기화 스킬을 실행합니다.

+

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

+
+

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

+
    +
  • Git hooks 경로 설정 (.githooks/를 로컬 hooks로 연결)
    • +
  • 워크플로우 버전 검증 및 동기화
    • +
  • CLAUDE.md 프로젝트 컨텍스트 확인
    • +
+

- 이 명령은 팀 워크플로우 규칙, Git hooks, Claude 설정 파일을 자동으로 구성합니다. + Claude Code를 사용하지 않는 경우에도 Git hooks는 클론 시 포함되어 있으며,{' '} + git config core.hooksPath .githooks로 + 수동 설정할 수 있습니다.

), @@ -139,14 +154,15 @@ git push -u origin develop`} {/* 템플릿 공통 파일 구조 */}

템플릿 공통 파일 구조

- 모든 프로젝트 템플릿에 포함되는 공통 파일입니다. + 모든 프로젝트 템플릿에 포함되는 공통 파일입니다. 이 파일들은 Git에 커밋되어 팀 전체가 공유합니다.

.claude/
-
rules/ — 팀 규칙 (code-style, git-workflow, naming, testing, team-policy)
-
skills/ — Claude 스킬 (create-mr, fix-issue, init-project, sync-team-workflow)
-
settings.json — Claude 권한 설정
+
rules/ — 팀 코딩 규칙 (code-style, git-workflow, naming, testing, team-policy)
+
skills/ — 팀 Claude 스킬 (create-mr, fix-issue, init-project, sync-team-workflow)
+
settings.json — 팀 Claude 권한 정책 (Git에 커밋됨)
+
settings.local.json — 개인 확장 설정 (.gitignore에 포함, 각자 자유)
.githooks/
commit-msg — Conventional Commits 검증 훅
post-checkout — 체크아웃 후 자동 실행
@@ -157,6 +173,14 @@ git push -u origin develop`}
+
+

settings.json vs settings.local.json

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

템플릿별 추가 파일

@@ -178,14 +202,14 @@ git push -u origin develop`}

template-react-ts

.node-version — Node.js 버전
-
.npmrc — npm 레지스트리
+
.npmrc — npm 레지스트리 (URL만)
.prettierrc — 코드 포매터
- 팀 워크플로우가 업데이트되면 세션 시작 시 알림이 표시됩니다. + 팀 워크플로우가 업데이트되면 Claude Code 세션 시작 시 알림이 표시됩니다. /sync-team-workflow를 실행하여 최신 규칙을 동기화하세요. diff --git a/src/pages/GuidePage.tsx b/src/pages/GuidePage.tsx index 5cd2ab1..046574d 100644 --- a/src/pages/GuidePage.tsx +++ b/src/pages/GuidePage.tsx @@ -6,12 +6,12 @@ const CONTENT_MAP: Record '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() { diff --git a/src/utils/navigation.ts b/src/utils/navigation.ts index 6139a68..197f5da 100644 --- 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[] = [