From 15352c2049d83db5cab16e1c2a5f7647889ca0ab Mon Sep 17 00:00:00 2001 From: htlee Date: Mon, 23 Mar 2026 13:52:35 +0900 Subject: [PATCH] =?UTF-8?q?chore:=20=ED=8C=80=20=EC=9B=8C=ED=81=AC?= =?UTF-8?q?=ED=94=8C=EB=A1=9C=EC=9A=B0=20=EB=B6=80=ED=8A=B8=EC=8A=A4?= =?UTF-8?q?=ED=8A=B8=EB=9E=A9=20-=20.claude/skills/init-project/SKILL.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/skills/init-project/SKILL.md | 295 +++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 .claude/skills/init-project/SKILL.md diff --git a/.claude/skills/init-project/SKILL.md b/.claude/skills/init-project/SKILL.md new file mode 100644 index 0000000..d0df8e5 --- /dev/null +++ b/.claude/skills/init-project/SKILL.md @@ -0,0 +1,295 @@ +--- +name: init-project +description: 팀 표준 워크플로우로 프로젝트를 초기화합니다 +argument-hint: "[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/` 경로 사용 불가): +```bash +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 스킬에 필요한 개인 토큰. + +```bash +# 현재 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로 유효성 검증: +```bash +curl -sf "https://gitea.gc-si.dev/api/v1/user" \ + -H "Authorization: token <입력된 토큰>" +``` +- 성공: `✅ () 인증 확인` 출력 +- 실패: `❌ 토큰이 유효하지 않습니다. 다시 확인해주세요.` 출력 → 재입력 요청 + +2. `.claude/settings.local.json`에 저장 (이 파일은 .gitignore에 포함, 리포 커밋 안됨): +```json +{ + "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의 내용에 병합): + +```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 설정 +```bash +git config core.hooksPath .githooks +``` +`.githooks/` 디렉토리에 실행 권한 부여: +```bash +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` 파일을 읽고, 기존 내용을 보존하면서 하단에 추가: + +```gitignore + +# Claude Code 워크플로우 (로컬 전용) +docs/CHANGELOG.md +*.tmp +``` + +### 9. Memory 초기화 +프로젝트 memory 디렉토리의 위치를 확인하고 (보통 `~/.claude/projects//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로 최신 팀 워크플로우 버전을 조회: +```bash +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` 파일 생성: +```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`