2장. VS Code에서 첫 대화 나누기 — 설치, 필수 파일 8종, 첫 실습
이 챕터를 읽으면, VS Code에 Claude Code를 설치하고 첫 대화를 나눌 수 있다. 그리고 교사에게 필요한 파일 8종의 이름과 역할을 알 수 있다.
박선생님의 고민
박선생님은 마음을 먹었어요. "좋아, Claude Code를 설치해보자."
유튜브에서 설치 영상을 찾아봤어요. 영상에서는 까만 화면에 하얀 글씨가 빠르게 지나가고 있었어요. 영어로 된 명령어가 쏟아졌고, 영상 속 사람은 아무렇지 않게 타이핑하고 있었어요.
박선생님은 노트북을 닫았어요. "이건 나한테 무리인 것 같아..."
괜찮아요, 선생님. 저도 처음에 똑같았어요. 까만 화면만 보면 심장이 빨라졌거든요. 그런데 알고 나니까 별거 아니었어요. 정말이에요. 30분이면 끝나요.
김선생님 한마디
"터미널은 해커 도구가 아니에요. 카카오톡 같은 채팅창이에요. 카카오톡에서 친구한테 메시지 보내듯이, 터미널에서 컴퓨터한테 메시지를 보내는 거예요. 그리고 우리가 칠 명령어는 딱 하나.
claude."
이게 왜 되나요? — 터미널은 카카오톡이다
터미널 공포 해소하기
터미널이 무섭게 느껴지는 이유가 있어요. 까만 배경, 흰 글씨, 마우스 대신 키보드. 영화에서 해커들이 엄청 빠르게 타이핑하면서 "침입 성공!"이라고 외치는 장면. 그 이미지가 떠오르니까 무서운 거예요.
터미널의 본질은 아주 단순해요. 채팅창이에요.
카카오톡을 생각해보세요. 메시지를 입력하고 Enter를 누르면 상대방이 대답하죠? 터미널도 똑같아요. 글자를 입력하고 Enter를 누르면 컴퓨터가 대답해요. 상대방이 친구가 아니라 컴퓨터라는 것만 달라요.
"그래도 명령어를 많이 외워야 하는 거 아닌가요?"
아니에요. 우리가 터미널에서 할 일은 딱 하나예요. claude라고 입력하는 거예요. 이 한 단어만 치면 클로드코드가 켜져요. 그 다음부터는 한국어로 대화하면 돼요.
저도 6개월째 클로드코드를 쓰고 있지만, 터미널 명령어를 아는 건 claude 하나뿐이에요. 솔직히요.
VS Code가 뭔가요?
VS Code(Visual Studio Code)는 마이크로소프트가 만든 무료 프로그램이에요. 원래는 개발자들이 코드를 작성하는 도구인데, 우리는 딱 한 가지만 써요. 터미널.
고급 주방을 떠올려보세요. 오븐, 믹서, 그릴, 진공 포장기가 가득해요. 우리는 그 주방에 들어가서 전자레인지 하나만 쓰는 거예요. 주방 전체를 쓸 필요 없어요. 전자레인지(터미널) 하나면 충분해요.
VS Code를 쓰는 이유는 세 가지예요.
- 무료예요.
- 터미널이 내장되어 있어요. 별도 프로그램을 찾을 필요 없어요.
- 클로드코드가 만든 파일을 바로 확인할 수 있어요. 왼쪽에 폴더 목록, 가운데에 파일 내용, 아래에 터미널 — 한 화면에서 전부 해결돼요.
세 번째가 특히 중요해요. "퀴즈 만들어줘"라고 말하면, 아래 터미널에서 AI가 작업하는 모습이 보이고, 왼쪽에 새 파일이 생겨요. 클릭하면 가운데에 내용이 나타나요. 작업 과정과 결과를 한눈에 볼 수 있어요.
실습해보기 — 설치부터 첫 대화까지
자, 이제 실제로 해볼게요. 차근차근 따라오시면 30분이면 끝나요.
Step 0. 준비물 확인
- 컴퓨터: Windows 또는 Mac
- 인터넷 연결: 설치와 AI 대화에 필요
- Anthropic 계정: claude.ai에서 무료로 가입
- 시간: 약 30분
계정이 없다면 claude.ai에서 먼저 회원가입하세요. 이메일 주소만 있으면 돼요.
Step 1. VS Code 설치하기
VS Code가 이미 설치되어 있다면 건너뛰세요.
방법 A (Windows)
- 웹 브라우저에서 code.visualstudio.com 접속
- 파란색 "Download for Windows" 버튼 클릭
- 다운로드된 파일 실행 → "다음" 버튼만 계속 눌러서 설치 완료
- 바탕화면 VS Code 아이콘 더블클릭
방법 B (Mac)
- 웹 브라우저에서 code.visualstudio.com 접속
- "Download for macOS" 버튼 클릭
- 다운로드된 .zip 파일 더블클릭 → VS Code 앱이 나옴
- 이 앱을 "응용 프로그램" 폴더로 드래그
- 응용 프로그램에서 VS Code 실행
설치가 끝나면, VS Code를 열어보세요. 영어로 된 화면이 나와도 당황하지 마세요. 정상이에요. 우리는 이 프로그램의 기능을 하나만 쓸 거예요.
Step 2. 프로젝트 폴더 만들기
클로드코드에게 일을 시키려면, "사무실 문을 열어줘야" 해요. 조교가 출근하려면 사무실이 있어야 하잖아요. 그 사무실이 바로 프로젝트 폴더예요.
방법 A (Windows)
- 바탕화면에서 마우스 오른쪽 클릭 → "새로 만들기" → "폴더"
- 폴더 이름을
내-수업-프로젝트로 짓기 - VS Code에서 File → Open Folder → 방금 만든 폴더 선택
방법 B (Mac)
- Finder에서 "문서" 폴더로 이동
- 마우스 오른쪽 클릭 → "새 폴더" →
내-수업-프로젝트로 이름 짓기 - VS Code에서 File → Open Folder → 방금 만든 폴더 선택
VS Code 왼쪽에 폴더 이름이 나타나면 성공이에요.
Step 3. Node.js 확인하기
클로드코드를 설치하려면 Node.js라는 프로그램이 필요해요. 이미 설치되어 있을 수도 있어요.
Node.js는 뭔가요? AI 조교가 출근할 때 가져오는 "기본 도구 세트"예요. 볼펜과 메모장 없이는 조교도 일할 수 없듯이, Node.js 없이는 클로드코드도 실행되지 않아요. 한 번 설치하면 신경 쓸 일 없어요.
VS Code에서 터미널을 열어보세요.
- Windows: 상단 메뉴 Terminal → New Terminal (또는 Ctrl + `)
- Mac: 상단 메뉴 Terminal → New Terminal (또는 Cmd + `)
화면 아래에 터미널 창이 나타나요. 거기에 이렇게 입력하세요.
node --version
Enter를 누르면 결과가 나와요.
v18.0.0같은 숫자가 나오면 → 이미 설치되어 있어요. Step 4로 넘어가세요.- "command not found" 또는 에러가 나오면 → 설치가 필요해요.
Node.js 설치 (필요한 경우만)
- nodejs.org 접속
- LTS 버전 다운로드 (초록색 버튼)
- 설치 파일 실행 → "Next"만 계속 눌러서 완료
- VS Code를 완전히 닫았다가 다시 열기 (중요!)
- 터미널에서
node --version다시 입력해서 숫자 확인
Step 4. Claude Code 설치하기
드디어 클로드코드를 설치할 차례예요. 터미널에 아래 명령어를 입력하세요.
npm install -g @anthropic-ai/claude-code
Enter를 누르면 설치가 시작돼요. 글자가 빠르게 지나가도 당황하지 마세요. 정상이에요. 1~2분 정도 기다리면 돼요.
설치가 끝나면, 이제 claude라고 입력해보세요.
claude
처음 실행하면 Anthropic 계정으로 로그인하라는 안내가 나와요. 화면에 나오는 지시를 따라 로그인하세요. 웹 브라우저가 자동으로 열릴 거예요.
로그인이 끝나면 — 축하해요! 클로드코드가 켜졌어요. 이제부터 한국어로 대화하면 돼요.
자주 나오는 오류 3가지 해결
설치 과정에서 오류가 나올 수 있어요. 당황하지 마세요. 가장 흔한 세 가지만 알면 돼요.
오류 1: "npm: command not found" → Node.js가 설치되지 않았다는 뜻이에요. Step 3으로 돌아가세요.
오류 2: "EACCES: permission denied" (Mac에서 자주 발생)
→ 권한 문제예요. 명령어 앞에 sudo를 붙여보세요.
sudo npm install -g @anthropic-ai/claude-code
비밀번호를 물으면 Mac 로그인 비밀번호를 입력하세요. (입력할 때 화면에 아무것도 안 나타나는 게 정상이에요.)
오류 3: "network error" 또는 설치가 멈춤 → 인터넷 연결을 확인하세요. 학교 네트워크에서 차단될 수 있어요. 이 경우 개인 핫스팟으로 연결해보세요.
세 가지로 해결되지 않으면, 오류 메시지 전체를 복사해서 Claude Chat(claude.ai)에 붙여넣고 "이 오류 어떻게 해결해요?"라고 물어보세요. AI에게 AI 설치 도움을 받는 거예요. 실제로 잘 작동해요.
교사에게 필요한 파일 8종
클로드코드를 설치했으니, 이제 조교의 사무실을 세팅할 차례예요.
새 학기 첫날을 떠올려보세요. 담임이 교실에 준비하는 서류가 있잖아요. 출석부, 좌석표, 학급 규칙, 알림장 양식... 클로드코드에도 비슷한 서류 8장이 필요해요. 지금 다 외울 필요 없어요. 이름만 기억해두세요.
| 번호 | 파일명 | 역할 | 교사 비유 |
|---|---|---|---|
| 1 | CLAUDE.md | AI 조교에게 건네는 업무 메모 | 담임 교사의 학급 운영 메모 |
| 2 | .claude/settings.json | 조교의 권한 설정 | "이 서랍은 열어도 돼, 이건 안 돼" |
| 3 | .claude/settings.local.json | 내 컴퓨터만의 설정 | 담임 교사 개인 선호 (다른 교사와 공유 안 함) |
| 4 | rules/ 폴더 | 상황별 업무 규칙 | 수업자료 규칙, 행정문서 규칙 (분야별 교실 약속) |
| 5 | .claude/commands/ 폴더 | 단축 버튼 (Skills) | 자판기 버튼 — 누르면 정해진 결과가 나옴 |
| 6 | handoff.md | 업무 인수인계 문서 | 보충교사에게 남기는 "여기까지 했고, 이게 남았어요" |
| 7 | plan.md | 오늘의 작업 계획 | 수업 지도안 — 뭘 먼저 하고, 뭘 나중에 할지 |
| 8 | outputs/ 폴더 | 결과물 보관함 | 학생에게 나눠줄 인쇄물 모아두는 서류함 |
가장 중요한 건 1번 CLAUDE.md예요. 이건 Ch.3에서 직접 만들어볼 거예요.
파일 8종을 한 번에 다 만들 필요 없어요. 실제로는 이렇게 진행돼요.
| 시기 | 만드는 파일 | 이유 |
|---|---|---|
| 오늘 (Ch.2) | 프로젝트 폴더, outputs/ | 첫 실습에 필요 |
| 이번 주 (Ch.3) | CLAUDE.md, rules/ | 조교에게 업무 규칙 전달 |
| 다음 주 (Ch.4~) | plan.md, commands/ | 수업 자료 만들기 시작 |
| 필요할 때 (Ch.8~) | handoff.md, settings.json | 인수인계, 권한 설정 |
마치 새 학기에 서류를 한꺼번에 만드는 게 아니라, 필요할 때마다 하나씩 추가하는 것과 같아요.
.claude/ 폴더 구조 이해하기
클로드코드를 사용하면 .claude/라는 숨겨진 폴더가 생겨요. 이 폴더에는 두 종류가 있어요.
폴더와 서랍을 비유로 이해해볼게요. 학교에는 교무실 공용 서랍(모든 교사가 공유)과 교사별 개인 서랍이 있잖아요. .claude/ 폴더도 비슷해요.
| 폴더 위치 | 역할 | 비유 |
|---|---|---|
~/.claude/ (컴퓨터 전체) | 모든 프로젝트에서 공통으로 쓰는 설정 | 교무실 공용 서랍 — 모든 반에서 쓰는 학교 규칙 |
./.claude/ (프로젝트 폴더 안) | 이 프로젝트에서만 쓰는 설정 | 교실 개인 서랍 — 우리 반에만 해당하는 약속 |
~는 "내 컴퓨터 홈 폴더"라는 뜻이에요. ./는 "지금 열고 있는 프로젝트 폴더"라는 뜻이에요. 기호가 낯설어도 괜찮아요. "전체 설정"과 "프로젝트별 설정"이 분리되어 있다는 것만 기억하면 돼요.
settings.json의 우선순위도 알아두면 좋아요. 조직 관리자가 잠근 설정 > 프로젝트 설정 > 개인 설정 순서로 적용돼요. 학교에서 정한 교칙이 반별 약속보다 우선하는 것과 같아요. 나중에 "왜 내 설정이 안 먹히지?" 하는 순간이 오면 이 순서를 떠올리세요.
지금 다 만들 필요 없어요. 이 챕터에서는 이름만 기억하고, Ch.3에서 하나씩 직접 만들어볼 거예요. 마치 새 학기 첫날에 "올해는 이런 서류가 필요해요"라고 안내받는 것처럼, 지금은 목록만 확인하는 거예요.
첫 실습: "다음 주 수업 퀴즈 5문항 만들어줘"
드디어 클로드코드와 첫 대화를 나눠볼 거예요.
터미널에서 claude가 실행된 상태에서, 아래와 같이 입력하세요.
초등학교 4학년 영어, 다음 주 수업 퀴즈 5문항을 만들어줘.
선택지는 4개, 정답과 간단한 해설을 포함해줘.
결과를 quiz.md 파일로 저장해줘.
Enter를 누르세요. 클로드코드가 일하기 시작해요.
잠시 기다리면, 왼쪽 파일 목록에 quiz.md라는 파일이 나타나요. 클릭해보세요. 퀴즈 5문항이 선택지, 정답, 해설과 함께 만들어져 있을 거예요.
축하해요! 선생님이 방금 AI 조교에게 첫 업무를 시켰어요. 복사-붙여넣기 없이, 파일이 바로 만들어졌어요.
이 과정에서 느낀 차이를 정리하면 이래요.
| 이전 방식 (ChatGPT) | 지금 방식 (Claude Code) |
|---|---|
| "퀴즈 만들어줘" → 화면에 결과 표시 → 드래그 → 복사 → 한글 열기 → 붙여넣기 → 형식 맞추기 → 저장 | "퀴즈 만들어서 파일로 저장해줘" → 끝 |
| 소요 시간: 15~20분 | 소요 시간: 1~2분 |
| 복사 과정에서 형식 깨짐 | 원본 형식 그대로 유지 |
결과가 마음에 안 드는 부분이 있으면, 바로 이어서 말하면 돼요.
3번 문항의 난이도를 좀 낮춰줘. 우리 반 수준에 안 맞아.
클로드코드가 파일을 수정해줄 거예요. 대화하듯이 자연스럽게.
@파일명과 #메모 기능
두 가지 편리한 기능을 알아두세요.
@파일명: 특정 파일을 대화에 불러올 때 써요.
@quiz.md 이 퀴즈를 상/중/하 세 수준으로 나눠줘.
@를 붙이면 클로드코드가 해당 파일을 읽고 참조해요. 파일을 복사해서 붙여넣을 필요 없이, 이름만 적으면 돼요.
#메모: 짧은 메모를 남길 때 써요.
#우리반특성 상위권 5명은 영어 영재반, 하위권 3명은 기초 수준
이 메모는 현재 대화에서 참고 정보로 사용돼요.
두 기능 모두 지금 완벽히 익힐 필요 없어요. "이런 게 있구나" 정도면 충분해요. 쓰면서 익숙해질 거예요.
오해 바로잡기
"터미널은 위험한 곳이다" → "카카오톡과 같은 채팅창이다"
이 오해를 바로잡아야 해요. 터미널은 위험한 해킹 도구가 아니에요.
카카오톡에서 이상한 메시지를 보내도 상대방이 "무슨 말인지 모르겠어요"라고 하듯이, 터미널에서 엉뚱한 걸 입력해도 컴퓨터가 "그런 명령어 없어요"라고 대답할 뿐이에요. 컴퓨터가 고장나지 않아요.
클로드코드에는 안전장치가 있어요. 파일을 삭제하거나 중요한 변경을 할 때는 "이걸 정말 실행할까요?"라고 물어봐요. 선생님이 "예"라고 승인하기 전까지는 아무 일도 일어나지 않아요.
터미널 = 채팅창. 이 한 줄만 기억하세요.
이번 주 딱 한 가지
VS Code를 설치하고, claude를 입력해서 첫 대화를 나눠보세요.
"다음 주 수업 퀴즈 5문항 만들어줘"를 직접 해보세요. 파일이 만들어지는 순간, "아, 이게 다른 거구나"를 체감하실 거예요. 10분이면 돼요.
핵심 3가지
이 챕터의 핵심:
- 터미널은 채팅창이다. 카카오톡에서 친구에게 메시지 보내듯, 터미널에서 컴퓨터에게 메시지를 보내는 것. 외울 명령어는
claude하나. - 교사에게 필요한 파일 8종이 있다. CLAUDE.md(업무 메모), settings.json(권한), settings.local.json(개인 설정), rules/(규칙), commands/(단축 버튼), handoff.md(인수인계), plan.md(계획), outputs/(결과물). 지금은 이름만 기억.
- VS Code + Claude Code = 30분 설치, 한국어로 대화. 코딩 몰라도 "퀴즈 만들어서 파일로 저장해줘"가 한 문장으로 끝난다.
참고 출처
- VS Code 공식 사이트: code.visualstudio.com
- Node.js 공식 사이트: nodejs.org
- Claude Code 공식 설치 문서: docs.anthropic.com
- Anthropic, Claude Code 공식 가이드