Claude Code 워크숍 — 카카오임팩트 AX

Part 0

기본 개념 설명

클로드 코드를 이해하기 위한 기본 개념들을 설명합니다.

클로드 계정 하나, 두 가지 창구

클로드 계정 하나로 두 가지 방식으로 접근할 수 있어요. claude.ai는 채팅창에서 쓰는 웹 인터페이스고, 클로드 코드는 터미널에서 직접 클로드를 불러 쓰는 방식이에요. 같은 계정, 같은 모델이지만 사용하는 '창구'가 다른 거예요. 웹은 대화 중심, 코드는 파일과 코드 작업 중심이라고 생각하면 돼요.

IDE, Terminal, Claude Extension

IDE는 코드를 쓰는 편집기예요. VS Code가 대표적이고, 우리가 주로 쓰는 환경이에요. Terminal(터미널)은 컴퓨터에 명령을 직접 입력하는 창이고요. Claude Extension은 VS Code 안에 클로드를 붙여놓은 플러그인이에요. IDE 안에서 바로 클로드한테 물어보고 코드를 수정할 수 있어요.

Part 1

클로드 코드 세팅하기

설치부터 첫 대화까지, 단계별로 따라오세요.

Premium 플랜 안내. 이번 워크숍을 위해 전 크루에게 Claude Premium(Max) 플랜이 배정되었습니다. 마음껏 써보세요!

맥북에 설치하기

터미널 열기

Spotlight(Cmd + Space) → 'terminal' 검색

Claude Code 설치

아래 명령어를 복사해서 터미널에 붙여넣으세요.

curl -fsSL https://claude.ai/install.sh | bash

로그인

claude login → 브라우저에서 인증

VS Code 설치

code.visualstudio.com → Mac 버전 다운로드 → Applications 폴더로 드래그

Claude Extension 설치

VS Code → Extensions(Cmd+Shift+X) → "Claude" 검색 → Anthropic 제작 확인 → Install

VS Code에서 시작하기

작업 폴더 만들기

바탕화면에 workspace 폴더 → 그 안에 프로젝트 폴더 생성

VS Code에서 폴더 열기

File → Open Folder → 만든 폴더 선택

Claude 탭에서 대화 시작

왼쪽 사이드바 Claude 아이콘 클릭 → 바로 대화를 시작하세요!

설치 트러블슈팅

증상	해결
Extension이 안 보임	VS Code 재시작
`claude` 명령어가 안 됨	VS Code 완전히 종료 후 재시작
브라우저 로그인 후 반응 없음	브라우저에서 "허용" 클릭 확인
응답이 안 옴	Claude 구독 상태 확인
`git` 명령어가 안 됨	VS Code 완전히 종료 후 재시작 또는 재설치

막히면 손 들어주세요! 세팅 도우미 크루들이 도와드립니다.

Part 2

기본 사용법

슬래시 명령어, 단축키를 익혀봅시다.

핵심 슬래시 명령어

명령어	역할	언제?
`/init`	폴더 분석 → CLAUDE.md 자동 생성	새 프로젝트 시작
`/plan`	Plan Mode 진입 (읽기 전용)	큰 작업 전 검토
`/clear`	대화 기록 초기화	작업 완료 후
`/compact`	긴 대화 압축 → 토큰 절약	대화가 길어질 때
`/cost`	현재 세션 비용 확인	비용 모니터링
`/resume`	이전 세션 불러오기	/clear 후 돌아가고 싶을 때
`/memory`	자동 기억 확인/수정	Claude가 뭘 기억하는지
`/btw`	현재 작업 중단 없이 별도 질문/요청	작업 흐름을 끊지 않고 물어볼 때
`/help`	전체 명령어 보기	언제든지

키보드 단축키

단축키	기능
`Shift+Tab`	모드 전환
`Shift+Enter`	줄바꿈 (Enter는 전송)
`Ctrl+C`	작업 중단
`Esc`	현재 입력 취소
`Esc × 2`	직전 작업 되돌리기 (Claude 작업만)

컨텍스트 관리 원칙

AI 모델은 대화를 '기억'하지 않아요. 매번 전체 내용을 다시 읽어요. 대화가 길어지면 느려지고 비용이 올라갑니다.

질문-답변 5쌍 이내

한 세션에서 작업을 마무리하세요

작업 완료 후 /clear

컨텍스트를 깨끗이 초기화하세요

50% 남으면 /compact

흐름을 이어가면서 토큰을 아끼세요

Part 3

Git 안전망

코드의 타임머신. 바이브코딩의 필수 안전장치.

왜 Git이 필요한가?

"보고서_최종.docx, 보고서_최최종.docx, 보고서_진짜최종.docx..." — Git은 이 문제를 해결해요. 게임의 세이브 포인트처럼, 큰 작업 전에 현재 상태를 저장해두면 언제든 돌아갈 수 있어요.

Git vs GitHub

Git

내 컴퓨터에서 변경 내역을 기록하는 로컬 도구

GitHub

코드를 온라인에 저장하고 공유하는 클라우드 저장소 (코드용 구글 드라이브)

핵심 명령어

명령어	설명	비유
`git add [파일]`	저장할 파일 선택	무대 위로 올리기
`git commit -m "메시지"`	선택한 파일 저장 + 메모	세이브 포인트
`git push`	내 컴퓨터 → GitHub 업로드	클라우드 백업
`git pull`	GitHub → 내 컴퓨터 다운로드	최신 버전 받기
`git clone [URL]`	GitHub 프로젝트 다운로드	복사해오기

초보자 전략. 혼자 작업할 때는 commit + push + pull 3개만 잘 써도 충분해요.

Claude Code와 함께 쓰기

자연어로 말하면 Git 명령어를 알아서 실행해줘요.

# 이렇게 말하면
"현재 상태 저장해줘"          → git add + commit + push
"오늘 작업 내용 커밋해줘"     → commit 메시지도 Claude가 작성
"아까 작업 전 상태로 돌아가줘"  → git reset 또는 checkout

실습 — GitHub 연결

GitHub에서 새 레포 만들기

github.com → New repository → 이름 입력 → Create

Claude에게 연결 요청

"내 GitHub 레포에 현재 폴더를 연결하고 첫 번째 커밋을 push해줘"

GitHub에서 확인

파일이 올라가 있으면 안전망 완성!

Part 4

CLAUDE.md 설정

새 직원에게 주는 업무 매뉴얼. Claude에게 주는 행동 지침.

CLAUDE.md란?

claude를 실행할 때마다 Claude는 자동으로 CLAUDE.md를 읽어요. 매번 같은 설명을 반복할 필요가 없어져요.

매장 업무 매뉴얼

"손님한테 존댓말 쓰기" / "냉장고 온도 건드리지 마"

CLAUDE.md

"항상 한국어로 답변" / "config.json은 수정 금지"

실제 사용 중인 CLAUDE.md 예시

# 나에 대해
- 이름: 민석 (업무 닉네임: 테일러)
- 소속: 카카오임팩트 테크 임팩트팀
- 배경: 컴퓨터공학 + 철학 복수전공. 기술 기획

# 글쓰기 & 문서화
- 블로그 포스트 작성 시 콜론(:) 사용 금지
  — 한국어 문장에서 콜론은 부자연스럽고 AI 생성 티가 남
- 자연스러운 줄글 선호. 과도한 불렛 포인트 지양
- 마크다운 기반 기록. 옵시디언 호환 마크다운으로 작성
- 파일명 규칙: YYYY-MM-DD-제목.md

# 대화 스타일
- 한국어 반말로 대화. 친구처럼 편하게
- 간결하게. 장황한 설명 금지. 필요한 만큼만
- 단순 동의보다는 적절한 질문으로 사고 확장 유도
- 대안적 관점이나 놓친 부분이 있으면 짚어주기
- 학습에 도움 되는 설명은 환영하지만 매번 기초부터 설명할 필요 없음
- 감정/행동 묘사, 의미 없는 감탄사 금지

/init으로 자동 생성하기

터미널에서 /init을 실행하면 Claude가 프로젝트를 분석해서 CLAUDE.md를 자동으로 만들어줘요.

핵심 패턴. /init → commit → /clear → 다음 작업. 이 리듬을 반복하면 Claude가 항상 최신 맥락을 알고 있어요.

작성 원칙

구체적으로

"잘 만들어줘" (X)
"camelCase 파일명, 주석은 한국어로" (O)

200줄 이내

너무 길면 컨텍스트 낭비. 핵심만 간결하게.

금지사항 명시

"~하지 말 것" 형태가 효과적이에요.

Part 5

바이브코딩 5단계 사이클

기획 → 플랜 → 액션 → 확인 → 반복. 이 리듬으로 만들어보세요.

기획

GitHub 레포 생성 → Claude에게 기획 문서 초안 요청 → 직접 읽고 디테일 수정. 3일짜리 프로젝트라면 1~2일은 기획에 투자하세요.

플랜

기획 문서 바탕으로 페이즈별 작업 계획 생성. Plan Mode에서 방향을 확인하고 수정 요청.

액션 + 저장

코드 작성 → git commit push → /clear → /init → git commit push → 다음 작업. 큰 작업 전에 항상 "현재 상태 저장해줘"를 먼저.

확인

Claude에게 결과물 직접 확인 시키기. "만든 페이지를 열어서 잘 작동하는지 확인해줘. 에러가 있으면 알려줘."

수정 + 반복

문제 발견 → 작은 플랜 → 수정. 같은 문제를 3번 이상 고쳐도 안 되면, 과감히 세이브 포인트로 돌아가서 다시 시작.

나만의 도구 상상하기

워크시트에 적으면서 오늘 만들 것을 구체화해보세요.

1. 나는 어떤 일을 하는 사람인가요?

직업, 역할, 담당 사업

2. 필요한 것은 무엇인가요?

반복 업무, 찾기 어려운 정보, 있으면 좋겠다 싶은 도구

3. 뭘 만들어보고 싶나요?

KPI 대시보드, 리포트 생성기, 보고서 초안 등

4. 오늘 시도해볼 한 가지

가장 작게 시작할 수 있는 걸 골라보세요

Tip. 위에 적은 내용이 곧 Claude Code한테 처음 할 말이 돼요.
"나는 카카오임팩트에서 ○○ 사업을 담당하는 사람인데, ○○를 만들고 싶어. 계획을 먼저 세워봐."

핵심 능력 4가지

능력	의미
대상 정의	어떤 반복 업무를 맡길지 구체적으로 파악
프로세스 설명	입력 → 처리 → 출력 흐름을 AI에게 명확히 설명
반복 개선	한 번에 완벽하지 않아도 됨. 5~10번 수정이 정상
결과 검증	AI 결과물을 내 업무 지식으로 맞는지 확인

Part 6

연동과 주의 사항

토큰 관리부터 외부 서비스 연동까지.

토큰 사용량

코딩 작업은 토큰을 많이 소모해요. Premium 플랜을 사용하고 있으니 걱정 없이 써보세요. 리밋이 걸리면 잠시 쉬었다가 하면 돼요.

세션 관리

하나의 세션에서 너무 긴 작업을 할수록 토큰이 빨리 닳아요. 긴 대화를 하면 점점 앞의 말을 까먹는 거랑 같아요. /compact로 대화를 압축하거나, 새 터미널 창을 열어 새로 시작하면 돼요.

권한 부여

Claude Code는 파일을 읽거나 수정하기 전에 항상 먼저 물어봐요. 접근을 열어두는 건 문을 열 수 있는 권한을 주는 거고, 문을 열기 전에 항상 노크를 해요. 허락하지 않으면 절대 멋대로 열고 들어오지 않아요.

'연동'이란?

두 서비스가 서로 데이터를 주고받을 수 있게 이어주는 거예요. 연동 방식에는 크게 API와 MCP가 있어요.

API 연동

두 프로그램이 대화할 때 쓰는 약속된 창구. "이 주소로 요청을 보내면 이 형식으로 데이터를 돌려줄게" 라는 규칙.

MCP 연동

AI가 외부 서비스를 직접 도구처럼 쓸 수 있게 해주는 연결 규약. "노션에 정리해줘" 하면 직접 노션 페이지를 만들어줘요.

CLI 도구 연동

Google, GitHub 같은 서비스들은 터미널에서도 쓸 수 있게 전용 CLI 도구를 제공해요. gcloud, gh, gws 같은 것들이에요.

한 번 연동(로그인/인증)만 해두면, 그 다음부터는 터미널에서 바로 기능을 쓸 수 있어요. 클로드 코드는 이런 CLI 도구들을 직접 실행할 수 있어서, 자연어로 말하면 알맞은 명령어를 조합해서 실행해줘요. 각 CLI의 명령어를 외울 필요 없이, 클로드가 번역사 역할을 해주는 거예요.

연결 가능한 서비스들

서비스	연동 방식	할 수 있는 것
Notion	MCP	페이지 읽기/생성/업데이트
Google Sheets	MCP	스프레드시트 읽기/쓰기
Slack	MCP	메시지 자동 전송
GitHub	CLI (gh)	PR 생성, 코드 리뷰
Google Drive	CLI (gws)	파일 조회, 권한 관리
Playwright	MCP	브라우저 자동 테스트
Supabase / SQLite	연동	DB 조회 및 관리
Vercel / Render	CLI	웹사이트 배포

Part 7

Gen AI 기반 개발의 흐름

단순히 "잘 물어보는 것"에서 "AI가 스스로 더 많이 할 수 있도록 설계하는 것"으로.

2024

프롬프트 엔지니어링

AI한테 어떻게 잘 말할지에 집중. 같은 질문도 표현에 따라 결과가 크게 달랐어요.

2025

컨텍스트 엔지니어링

AI에게 얼마나 풍부한 맥락을 주느냐가 핵심. 시스템 프롬프트, 메모리, RAG가 주목받기 시작.

2026

에이전틱 엔지니어링

AI가 직접 도구를 쓰고 판단하고 행동. 사람은 흐름을 설계하고 AI가 자율 실행.

'하네스(harness)'는 AI라는 강한 힘을 잘 묶어서 원하는 방향으로 이끄는 것에 비유한 표현이에요. Claude Code도 이 흐름 위에 있어요.

앞으로

앞으로의 계획

워크숍 이후, 이렇게 진행됩니다.

4월

도구 전환 안정화

슬랙, 드라이브, Gmail 전환 마무리. 새 환경에 적응하기.

4월 말~

AI Show & Tell

크루가 직접 AI 활용 사례를 공유하는 시간. 지원자를 모집합니다!

5~6월

AI 에이전트 구축

AI 인터뷰어로 각 팀의 업무 흐름을 파악하고, 정리된 데이터 위에 AI 에이전트 구축.

하반기

AI와 함께 일하는 재단!

하루 여유 시간을 갖고 더 많은 임팩트를 만드는, AI와 일하는 재단!

Show & Tell #1 지원자 모집 중! AI로 해본 것, 뭐든 좋아요. 편하게 DM 주세요.

FAQ

자주 묻는 질문

궁금한 점들을 모았어요.

Homebrew, Git, npm이 뭔가요?

Homebrew는 맥에서 프로그램을 설치할 때 쓰는 패키지 관리자예요. 앱스토어처럼 명령어 한 줄로 도구들을 설치할 수 있게 해줘요.

Git은 코드의 변경 이력을 기록하는 버전 관리 도구예요. "버전1, 버전2, 최종, 진짜최종"을 체계적으로 관리해주는 시스템이에요.

npm은 Node.js 기반 프로그램들을 설치하고 관리하는 도구예요.

환경 변수와 API 키가 뭔가요?

환경 변수는 컴퓨터 전체에서 쓸 수 있는 '메모장' 같은 거예요. API 키처럼 여러 프로그램에서 반복해서 필요한 값을 한 번만 저장해두면 어디서든 불러쓸 수 있어요.

API 키는 절대 코드 파일 안에 직접 써넣거나 깃허브에 올리면 안 돼요. 환경 변수로 분리해서 코드는 공유해도 키는 내 컴퓨터 안에만 있는 구조를 만드는 거예요.

CLI가 뭔가요?

우리가 보통 쓰는 인터페이스는 아이콘과 버튼이 있는 GUI(그래픽 유저 인터페이스)예요. CLI(커맨드 라인 인터페이스)는 터미널 창에서 명령어를 입력하는 방식이에요.

CLI가 어려운 이유는 정해진 명령어를 입력하지 않으면 튕겨나기 때문이에요. 하지만 클로드 코드는 LLM을 터미널에서 쓸 수 있게 만들어준 것이라, 자연어로 말해도 동작해요. 심지어 오타를 내도요!

Claude vs Claude Code 차이가 뭔가요?

Claude는 Anthropic의 LLM 모델 (AI 두뇌)이에요. Claude Code는 Claude 모델 + 실행 가능한 도구들이에요.

Claude는 카톡 상담사처럼 대화만 하지만, Claude Code는 직접 방문한 전문가처럼 파일도 만들고 명령도 실행해요.

Claude Desktop과 Claude Code는 다른 건가요?

Claude Code는 개발자 대상 터미널 CLI, Claude Desktop은 비개발자 대상 통합 앱이에요. 기저 모델은 동일하지만 시스템 프롬프트와 도구가 달라서 체감 성능이 달라요.

최근에는 Claude Desktop 안에 Code 탭이 통합되어서 GUI에서도 Claude Code 기능을 쓸 수 있어요.

터미널이 뭔가요?

버튼 없이 명령어를 직접 입력하는 창이에요. GUI(그래픽 인터페이스)가 터치스크린 키오스크라면, 터미널은 직원에게 직접 말로 주문하는 거예요.

Claude Code 사용 시 터미널 명령어를 외울 필요 없어요. 한국어로 원하는 것을 설명하면 됩니다.

IDE(VS Code)와 터미널의 관계는?

IDE는 코드를 보고 편집하는 작업 공간이고, 터미널은 컴퓨터에 명령하는 창이에요. VS Code 안에 터미널이 내장되어 있어서 하나의 화면에서 모든 작업을 할 수 있어요.

비개발자에게는 VS Code를 열어서 파일 변경을 눈으로 확인하는 것을 추천해요.

바이브코딩에서 기술 부채는 어떻게 관리하나요?

AI 코드 품질은 천차만별이에요. 장기 운영 시 수정 포인트 불명, 보안 취약, 업그레이드 난이 등의 리스크가 있어요.

Git으로 버전 관리를 하고, CLAUDE.md로 규칙을 명시하는 것이 기본적인 대응이에요. 큰 프로젝트라면 코드 리뷰 과정을 거치는 게 좋아요.

포포는 어떤 프로젝트인가요?

포포는 카카오임팩트의 업무용 AI 프로젝트입니다. Claude를 기반으로 재단 업무에 맞게 커스터마이징한 AI 어시스턴트예요. 사용자 지정 스킬을 통해 재단 업무에 특화된 도움을 받을 수 있습니다.