문제: Claude Code 설정이 없거나 부족한 프로젝트에서 처음부터 수동 설정은 번거로움
해결: 프로젝트 분석 → 언어/구조에 맞는 초기 설정 자동 생성
결과: CLAUDE.md, .claude/, hooks, permissions 등 한 번에 설정

수행 작업

1단계: 마스터 가이드 참조

반드시 다음 문서를 먼저 읽습니다:

.claude/docs/CLAUDE-CODE-MASTERY.md           # 목차 및 핵심 개념
.claude/docs/mastery/01-settings-guide.md     # 설정 요소별 상세 가이드
.claude/docs/mastery/02-language-templates.md # 언어별 설정 템플릿
.claude/docs/mastery/03-project-structures.md # 프로젝트 구조별 가이드

필요한 내용에 따라 해당 파일을 참조합니다.

2단계: 프로젝트 분석

# 분석 대상
1. package.json → 패키지 매니저, 스크립트 확인
2. 폴더 구조 → 모노레포 여부, 모듈 구조
3. 기존 .claude/ → 이미 설정된 항목 확인
4. tsconfig.json → TypeScript 설정
5. .eslintrc / biome.json → 린트 설정
6. .prettierrc → 포맷터 설정

3단계: 기술 스택 파악

항목	확인 방법
패키지 매니저	lockfile 확인 (pnpm-lock.yaml, package-lock.json, bun.lockb)
언어	tsconfig.json 유무, 파일 확장자
프레임워크	package.json dependencies
모노레포	pnpm-workspace.yaml, turbo.json, lerna.json
테스트 도구	vitest, jest, mocha 등

4단계: 설정 규모 결정

## 규모 결정 기준

### Minimal (소규모, 1-3명)
- 단일 패키지
- 간단한 프로젝트

### Standard (중규모, 4-10명)
- 모노레포 또는 복잡한 단일 패키지
- 여러 개발자 협업

### Full (대규모, 10명+)
- 대규모 모노레포
- 여러 도메인
- 외부 시스템 연동 필요

5단계: 파일 생성

5.1 CLAUDE.md 생성 (항상)

# Development Workflow

## 패키지 관리
- **항상 `{detected_package_manager}` 사용**

## 개발 순서
1. 변경 사항 작성
2. 타입체크: `{typecheck_command}`
3. 테스트: `{test_command}`
4. 린트: `{lint_command}`
5. 빌드: `{build_command}`

## 코딩 컨벤션
- `type` 선호, `interface` 자제
- **`enum` 절대 금지** → 문자열 리터럴 유니온 사용
- Zod 스키마로 타입 정의

## 프로젝트 구조
{detected_structure}

## 금지 사항
- ❌ console.log 대신 logger 사용
- ❌ any 타입 사용 금지

5.2 settings.local.json 생성 (항상)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "{format_command} || true"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash({package_manager} run:*)",
      "Bash({package_manager} build:*)",
      "Bash({package_manager} test:*)",
      "Bash({package_manager} lint:*)",
      "Bash({package_manager} typecheck:*)"
    ],
    "deny": [],
    "ask": []
  }
}

5.3 Commands 생성 (Standard, Full)

.claude/commands/ 폴더에 다음 파일 생성:

commit-push-pr.md - 커밋 → 푸시 → PR
typecheck-all.md - 전체 타입체크
test-module.md - 모듈별 테스트
lint-fix.md - 린트 자동 수정
build-all.md - 전체 빌드

5.4 Agents 생성 (Standard, Full)

.claude/agents/ 폴더에 다음 파일 생성:

build-validator.md - 빌드 검증
code-reviewer.md - 코드 리뷰
test-runner.md - 테스트 실행 분석
api-doc-generator.md - API 문서 생성

5.5 Skills 생성 (Standard, Full) - 하이브리드 방식

.claude/skills/ 폴더에 3단계로 스킬을 생성합니다.

1단계: 공통 스킬 (항상 생성)

스킬	용도
`{project}-architecture`	전체 아키텍처, 폴더 구조, 의존성 방향
`{project}-testing`	테스트 패턴, 단위/통합 테스트, 실행 방법

2단계: 프로젝트 유형 감지

# 프로젝트 구조 분석
if modules/ or domains/ exist → Hexagonal/DDD
if packages/ or apps/ exist → Monorepo
if components/ or pages/ exist → Frontend
if controllers/ or routes/ exist → MVC Backend
if services/ exist → Microservices
if src/ only → Library/Simple

3단계: 유형별 스킬 제안 (사용자 확인)

Hexagonal/DDD 프로젝트:

감지	제안 스킬
`modules/{name}/`	`{project}-{name}` (도메인별)
MongoDB 사용	`{project}-database`
Fastify/Express	`{project}-api-conventions`
Zod 사용	`{project}-validation`

모노레포:

감지	제안 스킬
`packages/{name}/`	`{project}-{name}` (패키지별)
`apps/{name}/`	`{project}-{name}-app`
공통 설정	`{project}-shared`

프론트엔드:

감지	제안 스킬
`components/`	`{project}-components`
`pages/` or `routes/`	`{project}-routing`
`hooks/`	`{project}-hooks`
`stores/` or `context/`	`{project}-state`

MVC 백엔드:

감지	제안 스킬
`controllers/`	`{project}-controllers`
`models/`	`{project}-models`
`routes/`	`{project}-api-conventions`
`middleware/`	`{project}-middleware`

마이크로서비스:

감지	제안 스킬
`services/{name}/`	`{project}-{name}` (서비스별)
Docker 사용	`{project}-deployment`
메시지 큐	`{project}-messaging`

라이브러리:

감지	제안 스킬
`src/`	`{project}-api`
`examples/`	`{project}-examples`

사용자 확인 (AskUserQuestion)

프로젝트 유형: Hexagonal/DDD (modules/ 감지)

다음 스킬을 생성할까요?

공통 스킬 (자동 생성):
 ✅ {project}-architecture
 ✅ {project}-testing

프로젝트별 스킬 (선택):
 [x] {project}-auth (modules/auth/)
 [x] {project}-user (modules/user/)
 [x] {project}-transaction (modules/transaction/)
 [ ] {project}-marketing (선택 해제 가능)
 [x] {project}-database (MongoDB 감지)
 [x] {project}-api-conventions (Fastify 감지)

스킬 템플릿

---
name: {project}-{name}
description: {name} 관련 작업 시 적용. Use when working with {keywords}.
---

# {Name} Skill

## 개요
[자동 분석된 설명]

## 핵심 파일
[해당 영역의 주요 파일 경로]

## 핵심 규칙
[코드베이스에서 추출한 패턴]

## 자주 사용하는 명령어
[관련 테스트/빌드 명령어]

5.6 MCP 서버 연결 (Standard, Full) - 선택적

중요: MCP 서버는 보안상 사용자가 명시적으로 선택해야 합니다.

"Use third party MCP servers at your own risk" - Anthropic

의존성 분석 후 추천

프로젝트 의존성(package.json, requirements.txt 등)을 분석하여 관련 MCP 서버를 추천합니다.

감지된 의존성	추천 MCP 서버
mongoose, mongodb	MongoDB MCP
pg, postgres	PostgreSQL MCP
stripe	Stripe MCP
@sentry/*	Sentry MCP
redis, ioredis	Redis MCP

상세 추천 전략: .claude/docs/mastery/01-settings-guide.md 참조

사용자 선택 (AskUserQuestion)

MCP 서버 연결 여부를 사용자에게 질문합니다:

프로젝트 분석 결과, 다음 MCP 서버를 추천합니다:

협업 도구 (선택):
[ ] GitHub - PR/이슈 관리
[ ] Linear - 이슈 트래킹
[ ] Jira - 프로젝트 관리

의존성 감지 (선택):
[x] MongoDB (mongoose 감지됨)
[ ] Redis (ioredis 감지됨)

기타:
[ ] 건너뛰기 - MCP 연결 안 함

.mcp.json 생성 (선택한 서버만)

사용자가 선택한 서버만 포함합니다:

{
  "mcpServers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-mongodb"],
      "env": {
        "MONGODB_URI": "${MONGODB_URI}"
      }
    }
  }
}

MCP 서버 CLI 명령어

# CLI로 직접 추가
claude mcp add github

# 상태 확인
claude
/mcp

5.7 GitHub Action 생성 (Full만)

.github/workflows/claude-docs-update.yml 생성

6단계: 기존 설정과 병합

이미 존재하는 파일은 덮어쓰지 않음
새로운 항목만 추가하거나 사용자에게 확인 요청

결과 출력

✅ Claude Code 설정 완료!

📁 생성된 파일:
- CLAUDE.md ✅
- .claude/settings.local.json ✅
- .claude/commands/ (5개) ✅
- .claude/agents/ (4개) ✅
- .claude/skills/ (4개) ✅
- .mcp.json (선택 시)
- .github/workflows/claude-docs-update.yml ✅

📊 설정 규모: {minimal|standard|full}
🔧 기술 스택: {detected_stack}

🎯 다음 단계:
1. CLAUDE.md 내용 확인 및 수정
2. /learn-claude-code 로 사용법 학습
3. /upgrade-claude-code 로 최신 트렌드 확인

주의사항

기존 파일이 있으면 백업 후 병합을 시도합니다
package.json이 없으면 기본 npm 설정으로 생성합니다
커스텀 설정이 필요하면 생성 후 수동으로 수정하세요

에러 처리

마스터 가이드를 찾을 수 없는 경우

⚠️ 마스터 가이드 문서를 찾을 수 없습니다.

해결 방법:
1. bkit-starter 저장소에서 .claude/docs/ 폴더를 복사하세요
2. 최소 설정으로 진행하려면: /setup-claude-code minimal

프로젝트 유형 감지 실패 시

⚠️ 프로젝트 유형을 감지할 수 없습니다.

확인할 사항:
- package.json, tsconfig.json 등 설정 파일이 있는지 확인
- 프로젝트 루트 디렉토리에서 실행했는지 확인

수동 지정하려면:
→ /setup-claude-code minimal (최소 설정)
→ /setup-claude-code standard (표준 설정)
→ /setup-claude-code full (전체 설정)

파일 생성 실패 시

⚠️ 파일 생성에 실패했습니다: {파일명}

확인할 사항:
- 쓰기 권한이 있는지 확인
- 디스크 공간이 충분한지 확인

수동 생성하려면:
→ 01-settings-guide.md의 해당 섹션 참조하여 직접 생성

참고 문서

.claude/docs/CLAUDE-CODE-MASTERY.md
.claude/docs/mastery/01-settings-guide.md (MCP 추천 전략 포함)

setup-claude-code

Claude Code 프로젝트 설정 생성

사용법

왜 이 커맨드가 필요한가?