onboarding: Claude Code 환경 셋업

핵심: 처음 사용하는 사람이 Claude Code를 편하게 쓸 수 있도록 역할 확인 → 기본 정보 → CLAUDE.md 생성 → 세션/프로젝트 개념 → 출력 스타일 → 유용한 팁까지 안내한다.

실행 흐름 요약

상태 확인 → Step 1 직군 확인 → Step 2 기본 정보 수집 → Step 3 CLAUDE.md 생성
→ Step 4 세션/대화 개념 → Step 5 프로젝트 개념 → Step 6 output-style (비개발자만)
→ Step 7 유용한 팁 → 완료 + connector 안내

링크 출력 규칙: 모든 URL은 코드 블록 밖에서 마크다운 링크 형식 [텍스트](URL) 으로 표시한다. 코드 블록 안에 URL을 절대 넣지 않는다. 링크 닫는 괄호 ) 뒤에 반드시 공백을 한 칸 넣는다. 예: [페이지](URL) 에서 (O) / [페이지](URL)에서 (X)

기술 용어 변환 (비개발자 대상)

비개발자에게 설명할 때 아래 변환 테이블을 따른다. 개발자에게는 기술 용어를 그대로 사용한다.

기술 용어	비개발자에게 보이는 표현
세션 (session)	대화방 (채팅방)
cwd (현재 작업 디렉토리)	현재 폴더
터미널	명령어 입력 창
CLAUDE.md	Claude 메모장 (Claude가 매번 읽는 메모)
프로젝트	폴더 (서랍)
output-style	출력 스타일 (Claude가 대답하는 방식)
컨텍스트	대화 맥락
플러그인	확장 기능
MCP 서버	연결된 도구

---

상태 확인 및 분기

스킬이 시작되면 Read 도구로 ~/.claude/skills/smilegate-ai-tools/state.json 파일을 읽는다.

아래 2가지 케이스로 분기한다:

케이스 A: 파일 없음 또는 onboarding 키 없음 → 신규

처음 방문한 사용자다. Step 1부터 전체 흐름을 진행한다.

환영 인사를 출력한다:

안녕하세요! Claude Code 환경 셋업을 도와드릴게요.
몇 가지 질문에 답해주시면, 맞춤 설정을 해드릴게요.

케이스 B: onboarding.status = "completed" → 재방문

이미 온보딩을 완료한 사용자다.

케이스 B 진입 시, connector.status를 확인하여 추가 안내를 출력한다:

• connector.status === "partial": "일부 도구만 연결된 상태예요 ({connected_services} 연결됨, {failed_services} 미연결). /connector로 추가 연결할 수 있어요."
• connector.status === "error": "도구 연결에 문제가 있었어요. /connector로 다시 시도해보세요."
• connector.status === "completed" 또는 키 없음: 추가 안내 없이 기존 옵션 메뉴 표시.

AskUserQuestion으로 원하는 항목을 선택받는다:

• question: "이전에 온보딩을 완료하셨네요! 어떤 걸 도와드릴까요?"
• options:
  • {label: "세션/대화 다시 보기", description: "세션과 대화방 개념을 다시 설명해드려요"}
  • {label: "프로젝트 다시 보기", description: "프로젝트(폴더) 개념을 다시 설명해드려요"}
  • {label: "팁 다시 보기", description: "유용한 팁과 명령어를 다시 보여드려요"}
  • {label: "CLAUDE.md 다시 만들기", description: "Claude 메모장을 새로 만들어드려요"}
  • {label: "필요없어요", description: "온보딩을 종료합니다"}

선택에 따라 해당 Step만 출력하고 종료한다 (이후 Step은 진행하지 않는다):

• "세션/대화 다시 보기" → Step 4만 출력 후 종료
• "프로젝트 다시 보기" → Step 5만 출력 후 종료
• "팁 다시 보기" → Step 7만 출력 후 종료
• "CLAUDE.md 다시 만들기" → state.json에서 user_info와 role을 불러와 Step 3의 생성 로직을 실행한다 (Step 2 정보 수집은 건너뛴다). CLAUDE.md가 이미 있으면 Step 3의 "이미 있는 경우" 분기를 동일하게 따른다.
• "필요없어요" → 종료

---

Step 1: 직군 확인

사용자의 직군을 확인하여 개발자/비개발자를 분류한다.

AskUserQuestion으로 직군을 입력받는다:

• question: "어떤 직군이세요? (예: 기획, 마케팅, 백엔드 개발, QA 등)"
• options:
  • {label: "기획", description: "게임 기획, 서비스 기획 등"}
  • {label: "마케팅/운영", description: "마케팅, 사업, 운영 등"}
  • {label: "개발", description: "서버, 클라이언트, 웹, 데이터 등"}
  • {label: "디자인/아트", description: "UI, UX, 2D, 3D 등"}

사용자가 옵션을 선택하거나 Other로 직군을 입력하면, Claude가 내부적으로 개발자/비개발자를 분류한다. 의미 없는 입력(빈 값, 한 글자 등)이면 다시 질문한다.

개발자로 분류하는 키워드: 개발, 엔지니어, DevOps, SRE, QA, 테스트, 프론트엔드, 백엔드, 풀스택, 데이터 엔지니어, DBA, 인프라, 플랫폼, 보안, 시스템, 프로그래머

그 외 모든 직군은 비개발자로 분류한다: 기획, 마케팅, 디자인, PM, PO, 운영, 사업, 인사, 재무, CS, 데이터 분석 등

분류 결과를 사용자에게 직접 말하지 않는다. 내부적으로만 사용하여 이후 설명의 톤과 깊이를 조절한다.

---

Step 2: 기본 정보 수집

2회에 걸쳐 기본 정보를 수집한다.

2-1) 이름과 아이디

AskUserQuestion으로 입력받는다:

• question: "이름과 아이디(사번)를 알려주세요."
• options:
  • {label: "직접 입력하기", description: "예: 홍길동 / gildong (아이디 없으면 생략 가능)"}

2-2) 소속과 업무

AskUserQuestion으로 입력받는다:

• question: "소속과 주로 하시는 업무를 알려주세요."
• options:
  • {label: "직접 입력하기", description: "예: 데이터서비스개발팀 / 게임 기획"}

수집 정보 확인

수집한 정보를 요약하여 보여준다:

입력하신 정보를 정리했어요.

• 이름: {이름}
• 아이디: {아이디}
• 소속: {소속}
• 주요 업무: {업무}

AskUserQuestion으로 확인한다:

• question: "이 정보가 맞나요?"
• options:
  • {label: "맞아요", description: "다음 단계로 진행할게요"}
  • {label: "수정할래요", description: "수정할 부분을 알려주세요"}

"수정할래요" 선택 시: "어떤 부분을 수정하시겠어요?"라고 물은 뒤 해당 필드만 재입력받고 다시 확인한다. 아이디, 업무 등 선택 필드가 비어있으면 빈 문자열로 저장한다.

---

Step 3: CLAUDE.md 생성

조건 확인

현재 작업 디렉토리(cwd)에 CLAUDE.md 파일이 있는지 확인한다.

CLAUDE.md가 이미 있는 경우:

AskUserQuestion으로 선택받는다:

• question: "이 폴더에 CLAUDE.md가 이미 있어요. 사용자 정보를 추가할까요?"
• options:
  • {label: "추가할게요", description: "기존 내용은 유지하고, 사용자 정보 섹션을 추가해요"}
  • {label: "건너뛰기", description: "CLAUDE.md를 수정하지 않고 다음으로 넘어갈게요"}

"추가할게요" 선택 시:

1. 기존 CLAUDE.md를 Read 도구로 읽는다.
2. ## 사용자 정보 섹션이 이미 있으면 해당 섹션의 내용만 교체한다.
3. ## 응답 스타일 섹션이 이미 있으면 해당 섹션의 내용만 교체한다.
4. 두 섹션이 없으면 파일 끝에 추가한다.
5. 기존 내용(다른 섹션)은 절대 삭제하지 않는다. "건너뛰기" 선택 시: Step 4로 이동한다.

CLAUDE.md가 없는 경우: 바로 생성한다.

생성 내용

비개발자용 CLAUDE.md:

# 프로젝트 규칙

## 사용자 정보
- 이름: {이름}
- 아이디: {아이디}
- 소속: {소속}
- 주요 업무: {업무}

## 응답 스타일
- 항상 한국어로 대답해줘
- 개발적인 표현은 아주 쉽게 비유를 들어서 설명해줘
- 단계별로 차근차근 안내해줘

개발자용 CLAUDE.md:

# 프로젝트 규칙

## 사용자 정보
- 이름: {이름}
- 아이디: {아이디}
- 소속: {소속}
- 주요 업무: {업무}

## 응답 스타일
- 항상 한국어로 대답해줘

위 내용 외에 불필요한 지시사항을 추가하지 않는다.

생성 후 안내

비개발자에게:

CLAUDE.md를 만들었어요!

이 파일은 Claude가 "내가 누구인지, 어떻게 말해줬으면 하는지" 기억하는 메모장이에요.
이 폴더에서 Claude를 시작하면 매번 이 메모를 자동으로 읽어요.
나중에 원하는 규칙이 생기면 이 파일에 추가하면 돼요.

개발자에게:

CLAUDE.md를 생성했습니다.
프로젝트 루트의 CLAUDE.md는 세션 시작 시 자동으로 로드됩니다.
필요한 규칙이 있으면 이 파일에 추가하세요.

---

Step 4: 세션/대화 개념

핵심 개념: 한 세션 = 한 대화방(채팅방)

비개발자용 설명

💬 세션 = 대화방

카카오톡 채팅방을 떠올려보세요.

• 새 대화 시작 = 새 채팅방을 여는 것
  → 명령어 입력 창에서 claude 를 입력하면 새 대화방이 열려요

• 대화방 여러 개 = 동시에 여러 주제로 대화
  → 명령어 입력 창을 여러 개 열면 각각 다른 대화방이에요 (서로 독립적)

• 대화방 나가기 = 대화 끝내기
  → Ctrl+D 를 누르면 현재 대화가 끝나요

• 이전 대화 이어가기 = 전에 하던 채팅 다시 열기
  → claude --resume 또는 대화 중에 /resume 을 입력하면
    이전 대화를 이어갈 수 있어요

개발자용 설명

세션

• 세션은 독립적인 대화 컨텍스트입니다
• 여러 터미널에서 별도 세션을 동시에 실행할 수 있습니다
• 세션 종료: Ctrl+D
• 이전 세션 이어가기: claude --resume 또는 /resume
• 새 세션: claude

---

Step 5: 프로젝트 개념

비개발자용 설명

📁 프로젝트 = 서랍장

서랍장을 떠올려보세요.

• 폴더 = 서랍 하나
  → 각 서랍에는 관련 파일들이 들어있어요

• Claude는 현재 열린 서랍만 봐요
  → 명령어 입력 창에서 어떤 폴더를 열고 claude 를 실행하면,
    Claude는 그 폴더 안의 파일만 볼 수 있어요

• CLAUDE.md = 서랍에 붙인 메모
  → 아까 만든 메모장 기억하시죠?
    폴더마다 다른 메모를 붙일 수 있어요.
    Claude는 대화를 시작할 때 이 메모를 매번 읽어요.

개발자용 설명

프로젝트

• cwd가 프로젝트 단위입니다
• 프로젝트 루트의 CLAUDE.md는 매 세션 시작 시 자동 로드됩니다
• 프로젝트마다 별도의 CLAUDE.md를 두어 프로젝트별 규칙을 설정할 수 있습니다

스코프(프로젝트 레벨/유저 레벨) 설명은 생략한다.

---

Step 6: output-style 설정 (비개발자만)

개발자는 이 Step을 건너뛴다. Step 5 이후 바로 Step 7로 이동한다.

비개발자에게 출력 스타일 설정을 안내한다:

🎓 출력 스타일 설정

Claude가 대답하는 방식을 바꿀 수 있어요.
더 자세하고 친절한 설명을 원하시면, 출력 스타일을 변경해보세요!

👉 /output-style 을 입력하고 Explanatory 를 선택하세요!

선택하면 Claude가 설명을 더 풍부하게 해줘요.

/output-style은 이 대화 안에서 바로 입력하면 된다. 설정을 바꾼 뒤 아래 질문에 답하면 다음 Step으로 자연스럽게 이어진다.

AskUserQuestion으로 확인한다:

• question: "출력 스타일을 설정하셨나요?"
• options:
  • {label: "설정했어요", description: "다음 단계로 넘어갈게요"}
  • {label: "나중에 할게요", description: "나중에 /output-style 로 언제든 설정할 수 있어요"}
  • {label: "이미 되어있어요", description: "다음 단계로 넘어갈게요"}

---

Step 7: 유용한 팁

비개발자와 개발자 공통으로 안내하되, 비개발자에게는 비유를 추가한다.

비개발자용

💡 알아두면 편한 팁

1. 이전 대화 이어가기
   → claude --resume 또는 대화 중에 /resume
   이전에 하던 대화를 다시 열 수 있어요 (채팅방 다시 열기!)

2. 파일 참조하기
   → @파일이름
   대화 중에 @를 붙여 파일 이름을 쓰면,
   Claude가 그 파일 내용을 읽어서 참고해요

3. 이미지 분석하기
   → 이미지 파일을 명령어 입력 창에 드래그앤드롭
   스크린샷이나 사진을 끌어다 놓으면 Claude가 분석해줘요

4. 빠른 명령어
   → /help : 도움말 보기
   → /clear : 대화 내용 정리하기
   → /compact : 대화 요약하기 (대화가 길어졌을 때)

5. 동시에 여러 대화
   → 명령어 입력 창을 여러 개 열면 각각 다른 대화를 할 수 있어요
     (카카오톡 채팅방 여러 개 동시에 열어놓는 것처럼!)

개발자용

💡 유용한 팁

1. 이전 세션 이어가기: claude --resume 또는 /resume
2. 파일 참조: @파일이름 (대화 중 파일 컨텍스트 추가)
3. 이미지 분석: 터미널에 이미지 드래그앤드롭
4. 빠른 명령어: /help, /clear, /compact
5. 멀티 세션: 여러 터미널에서 동시 실행 가능

---

완료 + 다음 단계

state.json 업데이트

Step 7까지 완료되면 ~/.claude/skills/smilegate-ai-tools/state.json 파일을 업데이트한다. 파일이나 디렉토리가 없으면 새로 생성한다.

파일이 이미 존재하면 기존 내용을 보존하고 onboarding 키만 업데이트한다.

{
  "onboarding": {
    "status": "completed",
    "role": "{developer 또는 non-developer}",
    "job_title": "{입력받은 직군}",
    "user_info": {
      "name": "{이름}",
      "id": "{아이디}",
      "team": "{소속}",
      "work": "{업무}"
    },
    "claude_md_created": true,
    "completed_at": "{현재 ISO 8601 시각}"
  }
}

• claude_md_created: CLAUDE.md를 생성했으면 true, 건너뛰었으면 false

skill-creator 플러그인 설치

state.json 업데이트 후, skill-creator 플러그인 설치를 시도하고 결과를 내부적으로 기억한다.

claude plugin list 2>&1 | grep -q "skill-creator"

• 이미 설치됨 (exit 0) → skill_creator_status = "already_installed". 설치 명령 실행하지 않는다.
• 미설치 (exit 1) → 아래 명령 실행:

  claude plugin install skill-creator@claude-plugins-official 2>&1
  

  • 성공 → skill_creator_status = "newly_installed"
  • 실패 → skill_creator_status = "failed". 조용히 무시하고 진행.

설치 후 플러그인이 활성화되려면 Claude Code 재시작이 필요하다. 단, connector 이후 재시작 안내가 이미 있으므로 별도 재시작을 요구하지 않는다.

완료 메시지 및 다음 단계 안내

비개발자용:

🎉 환경 셋업이 완료되었어요!

지금까지 한 일:
• Claude 메모장(CLAUDE.md) 만들기
• 대화방(세션), 폴더(프로젝트) 개념 익히기
• 출력 스타일 설정
• 유용한 팁 확인
{skill_creator_status == "newly_installed" 인 경우만: • 스킬 만들기 도구 설치}

다음으로 업무 도구를 연결해볼까요?
Slack, Jira, Confluence 같은 도구를 Claude에 연결하면
업무 자동화가 가능해져요.

개발자용:

🎉 환경 셋업 완료!

설치된 것들: CLAUDE.md{skill_creator_status == "newly_installed" 인 경우만: , skill-creator 플러그인}

다음으로 업무 도구를 연결하시겠습니까?
Slack, Jira, Confluence 등을 Claude Code에 연결하면
업무 자동화가 가능합니다.

AskUserQuestion으로 선택받는다:

• question: "업무 도구를 연결할까요?"
• options:
  • {label: "좋아요, 연결할래요", description: "/connector 로 도구 연결을 시작합니다"}
  • {label: "나중에 할게요", description: "나중에 /connector 로 언제든 연결할 수 있어요"}

"좋아요, 연결할래요" 선택 시:

좋아요! 도구 연결을 시작할게요.
아래 명령어를 그대로 입력해주세요:

> /connector

"나중에 할게요" 선택 시:

알겠어요! 나중에 도구를 연결하고 싶으면
/connector 라고 말하면 돼요.

그럼 Claude Code를 즐겁게 사용하세요! 🎉