gc-wing/.claude/skills/init-project/SKILL.md

name	description	argument-hint
init-project	팀 표준 워크플로우로 프로젝트를 초기화합니다	[project-type: java-maven|java-gradle|react-ts|auto]

팀 표준 워크플로우에 따라 프로젝트를 초기화합니다. 프로젝트 타입: $ARGUMENTS (기본: auto — 자동 감지)

프로젝트 타입 자동 감지

$ARGUMENTS가 "auto"이거나 비어있으면 다음 순서로 감지:

1. pom.xml 존재 → java-maven
2. build.gradle 또는 build.gradle.kts 존재 → java-gradle
3. package.json + tsconfig.json 존재 → react-ts
4. 감지 실패 → 사용자에게 타입 선택 요청

수행 단계

1. 프로젝트 분석

• 빌드 파일, 설정 파일, 디렉토리 구조 파악
• 사용 중인 프레임워크, 라이브러리 감지
• 기존 .claude/ 디렉토리 존재 여부 확인
• eslint, prettier, checkstyle, spotless 등 lint 도구 설치 여부 확인

2. CLAUDE.md 생성

프로젝트 루트에 CLAUDE.md를 생성하고 다음 내용 포함:

• 프로젝트 개요 (이름, 타입, 주요 기술 스택)
• 빌드/실행 명령어 (감지된 빌드 도구 기반)
• 테스트 실행 명령어
• lint 실행 명령어 (감지된 도구 기반)
• 프로젝트 디렉토리 구조 요약
• 팀 컨벤션 참조 (.claude/rules/ 안내)

Gitea 파일 다운로드 URL 패턴

⚠️ Gitea raw 파일은 반드시 web raw URL을 사용해야 합니다 (/api/v1/ 경로 사용 불가):

GITEA_URL="${GITEA_URL:-https://gitea.gc-si.dev}"
# common 파일: ${GITEA_URL}/gc/template-common/raw/branch/develop/<파일경로>
# 타입별 파일: ${GITEA_URL}/gc/template-<타입>/raw/branch/develop/<파일경로>
# 예시:
curl -sf "${GITEA_URL}/gc/template-common/raw/branch/develop/.claude/rules/team-policy.md"
curl -sf "${GITEA_URL}/gc/template-react-ts/raw/branch/develop/.editorconfig"

3. .claude/ 디렉토리 구성

이미 팀 표준 파일이 존재하면 건너뜀. 없는 경우 위의 URL 패턴으로 Gitea에서 다운로드:

• .claude/settings.json — 프로젝트 타입별 표준 권한 설정 + env(CLAUDE_BOT_TOKEN 등) + hooks 섹션 (4단계 참조)

⚠️ 팀 규칙(.claude/rules/), 에이전트(.claude/agents/), 스킬 6종, 스크립트는 12단계(sync-team-workflow)에서 자동 다운로드된다. 여기서는 settings.json만 설정한다.

3.5. Gitea 토큰 설정

CLAUDE_BOT_TOKEN (팀 공용): settings.json의 env 필드에 이미 포함되어 있음 (3단계에서 설정됨). 별도 조치 불필요.

GITEA_TOKEN (개인): /push, /mr, /release 등 Git 스킬에 필요한 개인 토큰.

# 현재 GITEA_TOKEN 설정 여부 확인
if [ -z "$GITEA_TOKEN" ]; then
  echo "GITEA_TOKEN 미설정"
fi

GITEA_TOKEN이 없는 경우, 다음 안내를 AskUserQuestion으로 표시:

질문: "GITEA_TOKEN이 설정되지 않았습니다. Gitea 개인 토큰을 생성하시겠습니까?"

• 옵션 1: 토큰 생성 안내 보기 (추천)
• 옵션 2: 이미 있음 (토큰 입력)
• 옵션 3: 나중에 하기

토큰 생성 안내 선택 시, 다음 내용을 표시:

📋 Gitea 토큰 생성 방법:

1. 브라우저에서 접속:
   https://gitea.gc-si.dev/user/settings/applications

2. "Manage Access Tokens" 섹션에서 "Generate New Token" 클릭

3. 입력:
   - Token Name: "claude-code" (자유롭게 지정)
   - Repository and Organization Access: ✅ All (public, private, and limited)

4. Select permissions (아래 4개만 설정, 나머지는 No Access 유지):

   ┌─────────────────┬──────────────────┬──────────────────────────────┐
   │ 항목             │ 권한             │ 용도                          │
   ├─────────────────┼──────────────────┼──────────────────────────────┤
   │ issue           │ Read and Write   │ /fix-issue 이슈 조회/코멘트   │
   │ organization    │ Read             │ gc 조직 리포 접근              │
   │ repository      │ Read and Write   │ /push, /mr, /release API 호출 │
   │ user            │ Read             │ API 사용자 인증 확인           │
   └─────────────────┴──────────────────┴──────────────────────────────┘

5. "Generate Token" 클릭 → ⚠️ 토큰이 한 번만 표시됩니다! 반드시 복사하세요.

표시 후 AskUserQuestion: "생성한 토큰을 입력하세요"

• 옵션 1: 토큰 입력 (Other로 입력)
• 옵션 2: 나중에 하기

토큰 입력 시:

1. Gitea API로 유효성 검증:

curl -sf "https://gitea.gc-si.dev/api/v1/user" \
  -H "Authorization: token <입력된 토큰>"

• 성공: ✅ <login> (<full_name>) 인증 확인 출력
• 실패: ❌ 토큰이 유효하지 않습니다. 다시 확인해주세요. 출력 → 재입력 요청

2. .claude/settings.local.json에 저장 (이 파일은 .gitignore에 포함, 리포 커밋 안됨):

{
  "env": {
    "GITEA_TOKEN": "<입력된 토큰>"
  }
}

기존 settings.local.json이 있으면 env.GITEA_TOKEN만 추가/갱신.

나중에 하기 선택 시: 경고 표시 후 다음 단계로 진행:

⚠️ GITEA_TOKEN 없이는 /push, /mr, /release 스킬을 사용할 수 없습니다.
   나중에 토큰을 생성하면 .claude/settings.local.json에 다음을 추가하세요:
   { "env": { "GITEA_TOKEN": "your-token-here" } }

4. Hook 스크립트 설정

⚠️ .claude/scripts/ 스크립트 파일은 12단계(sync-team-workflow)에서 서버로부터 자동 다운로드된다. 여기서는 settings.json에 hooks 섹션만 설정한다.

.claude/settings.json에 hooks 섹션이 없으면 추가 (기존 settings.json의 내용에 병합):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/scripts/on-post-compact.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/scripts/on-pre-compact.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/scripts/on-commit.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

5. Git Hooks 설정

git config core.hooksPath .githooks

.githooks/ 디렉토리에 실행 권한 부여:

chmod +x .githooks/*

pre-commit 훅 검증: .githooks/pre-commit을 실행하여 빌드 검증이 정상 동작하는지 확인. 에러 발생 시 (예: 모노레포가 아닌 특수 구조, 빌드 명령 불일치 등):

1. 프로젝트에 맞게 .githooks/pre-commit을 커스텀 수정
2. .claude/workflow-version.json에 "custom_pre_commit": true 추가
3. 이후 /sync-team-workflow 실행 시 pre-commit은 덮어쓰지 않고 보존됨 (commit-msg, post-checkout은 항상 팀 표준으로 동기화)

6. 프로젝트 타입별 추가 설정

java-maven

• .sdkmanrc 생성 (java=17.0.18-amzn 또는 프로젝트에 맞는 버전)
• .mvn/settings.xml Nexus 미러 설정 확인
• mvn compile 빌드 성공 확인

java-gradle

• .sdkmanrc 생성
• gradle.properties.example Nexus 설정 확인
• ./gradlew compileJava 빌드 성공 확인

react-ts

• .node-version 생성 (프로젝트에 맞는 Node 버전)
• .npmrc Nexus 레지스트리 설정 확인
• npm install && npm run build 성공 확인

7. .gitignore 확인

다음 항목이 .gitignore에 포함되어 있는지 확인하고, 없으면 추가:

.claude/settings.local.json
.claude/CLAUDE.local.md
.env
.env.*
*.local

팀 워크플로우 관리 경로 (sync로 생성/관리되는 파일, 리포에 커밋하지 않음):

# Team workflow (managed by /sync-team-workflow)
.claude/rules/
.claude/agents/
.claude/skills/push/
.claude/skills/mr/
.claude/skills/create-mr/
.claude/skills/release/
.claude/skills/version/
.claude/skills/fix-issue/
.claude/scripts/

8. Git exclude 설정

.git/info/exclude 파일을 읽고, 기존 내용을 보존하면서 하단에 추가:

# Claude Code 워크플로우 (로컬 전용)
docs/CHANGELOG.md
*.tmp

9. Memory 초기화

프로젝트 memory 디렉토리의 위치를 확인하고 (보통 ~/.claude/projects/<project-hash>/memory/) 다음 파일들을 생성:

• memory/MEMORY.md — 프로젝트 분석 결과 기반 핵심 요약 (200줄 이내)
  • 현재 상태, 프로젝트 개요, 기술 스택, 주요 패키지 구조, 상세 참조 링크
• memory/project-snapshot.md — 디렉토리 구조, 패키지 구성, 주요 의존성, API 엔드포인트
• memory/project-history.md — "초기 팀 워크플로우 구성" 항목으로 시작
• memory/api-types.md — 주요 인터페이스/DTO/Entity 타입 요약
• memory/decisions.md — 빈 템플릿 (# 의사결정 기록)
• memory/debugging.md — 빈 템플릿 (# 디버깅 경험 & 패턴)

10. Lint 도구 확인

• TypeScript: eslint, prettier 설치 여부 확인. 미설치 시 사용자에게 설치 제안
• Java: checkstyle, spotless 등 설정 확인
• CLAUDE.md에 lint 실행 명령어가 이미 기록되었는지 확인

11. workflow-version.json 생성

Gitea API로 최신 팀 워크플로우 버전을 조회:

curl -sf --max-time 5 "https://gitea.gc-si.dev/gc/template-common/raw/branch/develop/workflow-version.json"

조회 성공 시 해당 version 값 사용, 실패 시 "1.0.0" 기본값 사용.

.claude/workflow-version.json 파일 생성:

{
  "applied_global_version": "<조회된 버전>",
  "applied_date": "<현재날짜>",
  "project_type": "<감지된타입>",
  "gitea_url": "https://gitea.gc-si.dev"
}

12. 팀 워크플로우 최신화

/sync-team-workflow를 자동으로 1회 실행하여 최신 팀 파일(rules, agents, skills 6종, scripts, hooks)을 서버에서 다운로드하고 로컬에 적용한다.

이 단계에서 .claude/rules/, .claude/agents/, .claude/skills/push/ 등 팀 관리 파일이 생성된다. (이 파일들은 7단계에서 .gitignore에 추가되었으므로 리포에 커밋되지 않음)

13. 검증 및 요약

• 생성/수정된 파일 목록 출력
• git config core.hooksPath 확인
• 빌드 명령 실행 가능 확인
• Hook 스크립트 실행 권한 확인
• 다음 단계 안내:
  • 개발 시작, 첫 커밋 방법
  • 범용 스킬: /api-registry, /changelog, /swagger-spec